From 018a67dbd6c3bc7a1d53f23a5d38f07e79f626ac Mon Sep 17 00:00:00 2001
From: Deva Annamaraju <yansh2017@gmail.com>
Date: Mon, 25 May 2026 23:20:48 +0530
Subject: [PATCH 1/2] fix cursor vpn auth diagnostics

---
 README.md                                 |  23 +
 packages/cli/src/cursor.test.ts           | 109 ++++-
 packages/cli/src/cursor.ts                |  87 ++++
 packages/registry/src/cursor-auth.test.ts | 116 ++++-
 packages/registry/src/cursor-auth.ts      | 538 +++++++++++++++++++++-
 packages/registry/src/index.ts            |   8 +
 6 files changed, 854 insertions(+), 27 deletions(-)

diff --git a/README.md b/README.md
index d415f39..d0c48a4 100644
--- a/README.md
+++ b/README.md
@@ -196,6 +196,7 @@ Use these commands to manage Cursor authentication and the local cache that Toke
 tokenleak cursor login --name work
 tokenleak cursor status
 tokenleak cursor accounts --json
+tokenleak cursor doctor
 tokenleak cursor switch work
 tokenleak cursor logout --name work
 tokenleak cursor logout --all --purge-cache
@@ -238,6 +239,28 @@ bun packages/cli/dist/cli.js --provider cursor --format json
 - If `cursor status` is valid but `--list-providers` still shows Cursor as unavailable, run `tokenleak --provider cursor` once to sync the cache, then rerun `--list-providers`.
 - Cursor session tokens are stored in plaintext at `~/.config/tokenleak/cursor-credentials.json` (or under `TOKENLEAK_CURSOR_DIR`) with local-only file permissions.
 
+#### Corporate VPN / protected network
+
+If `tokenleak cursor login` works off VPN but fails on a company protected VPN with a connection, proxy, or certificate error, run the token-free doctor first:
+
+```bash
+tokenleak cursor doctor
+```
+
+For managed proxy networks, pass a Cursor-specific proxy or use your standard shell proxy variables:
+
+```bash
+TOKENLEAK_CURSOR_PROXY=http://proxy.company:8080 tokenleak cursor doctor
+```
+
+For TLS inspection networks, export the company root CA as a PEM file and point Tokenleak at it:
+
+```bash
+TOKENLEAK_CURSOR_CA_FILE=/path/company-root-ca.pem tokenleak cursor doctor --with-token
+```
+
+Tokenleak also honors `HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`, and `TOKENLEAK_CURSOR_TIMEOUT_MS` for Cursor API requests. `tokenleak cursor doctor --insecure-skip-tls-verify` exists only to prove that TLS inspection is the failure mode; do not use it for normal login or sync.
+
 ### Date filtering
 
 By default, Tokenleak shows the last **90 days** of usage.
diff --git a/packages/cli/src/cursor.test.ts b/packages/cli/src/cursor.test.ts
index 780f6e1..3c8eb82 100644
--- a/packages/cli/src/cursor.test.ts
+++ b/packages/cli/src/cursor.test.ts
@@ -9,6 +9,7 @@ import {
   loadCursorCredentialsStore,
   removeAllCursorAccounts,
   resetCursorProviderState,
+  runCursorCommand,
   saveCursorCredentials,
   setActiveCursorAccount,
   shouldSyncCursorForRun,
@@ -24,21 +25,47 @@ const SAMPLE_CSV = [
 ].join('\n');
 
 describe('cursor auth and sync helpers', () => {
-  const originalCursorDir = process.env['TOKENLEAK_CURSOR_DIR'];
   const originalFetch = globalThis.fetch;
+  const originalEnv = { ...process.env };
   let tempRoot = '';
 
   beforeEach(() => {
     tempRoot = mkdtempSync(join(tmpdir(), 'tokenleak-cursor-'));
     process.env['TOKENLEAK_CURSOR_DIR'] = tempRoot;
+    for (const key of [
+      'TOKENLEAK_CURSOR_PROXY',
+      'TOKENLEAK_CURSOR_CA_FILE',
+      'TOKENLEAK_CURSOR_TIMEOUT_MS',
+      'HTTPS_PROXY',
+      'https_proxy',
+      'HTTP_PROXY',
+      'http_proxy',
+      'NO_PROXY',
+      'no_proxy',
+    ]) {
+      delete process.env[key];
+    }
     globalThis.fetch = originalFetch;
   });
 
   afterEach(() => {
-    if (originalCursorDir === undefined) {
-      delete process.env['TOKENLEAK_CURSOR_DIR'];
-    } else {
-      process.env['TOKENLEAK_CURSOR_DIR'] = originalCursorDir;
+    for (const key of [
+      'TOKENLEAK_CURSOR_DIR',
+      'TOKENLEAK_CURSOR_PROXY',
+      'TOKENLEAK_CURSOR_CA_FILE',
+      'TOKENLEAK_CURSOR_TIMEOUT_MS',
+      'HTTPS_PROXY',
+      'https_proxy',
+      'HTTP_PROXY',
+      'http_proxy',
+      'NO_PROXY',
+      'no_proxy',
+    ]) {
+      if (originalEnv[key] === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = originalEnv[key];
+      }
     }
     globalThis.fetch = originalFetch;
     rmSync(tempRoot, { recursive: true, force: true });
@@ -168,4 +195,76 @@ describe('cursor auth and sync helpers', () => {
     expect(existsSync(join(getCursorCacheDir(), 'usage.csv'))).toBe(false);
     expect(listCursorAccounts()).toEqual([]);
   });
+
+  test('cursor help includes doctor diagnostics', async () => {
+    let output = '';
+    const originalWrite = process.stdout.write;
+    process.stdout.write = ((chunk: string | Uint8Array) => {
+      output += String(chunk);
+      return true;
+    }) as typeof process.stdout.write;
+
+    try {
+      await runCursorCommand(['--help']);
+    } finally {
+      process.stdout.write = originalWrite;
+    }
+
+    expect(output).toContain('tokenleak cursor doctor [--name <label>] [--with-token] [--insecure-skip-tls-verify]');
+  });
+
+  test('cursor doctor redacts proxy credentials and saved token details', async () => {
+    process.env['TOKENLEAK_CURSOR_PROXY'] = 'http://user:secret@proxy.company:8080';
+    saveCursorCredentials('user-work::super-secret-token', 'work');
+    globalThis.fetch = (async (url, init) => {
+      const cookie = String((init?.headers as Record<string, string> | undefined)?.['Cookie'] ?? '');
+      const hasToken = cookie.includes('super-secret-token');
+      if (String(url).includes('/api/usage-summary')) {
+        if (!hasToken) {
+          return new Response(JSON.stringify({ error: 'not_authenticated' }), { status: 401 });
+        }
+        return new Response(JSON.stringify({
+          billingCycleStart: '2026-03-01',
+          billingCycleEnd: '2026-03-31',
+          membershipType: 'pro',
+        }), { status: 200 });
+      }
+      if (!hasToken) {
+        return new Response('', { status: 307, headers: { location: 'https://api.workos.com' } });
+      }
+      return new Response(SAMPLE_CSV, { status: 200 });
+    }) as typeof fetch;
+
+    let output = '';
+    const originalWrite = process.stdout.write;
+    process.stdout.write = ((chunk: string | Uint8Array) => {
+      output += String(chunk);
+      return true;
+    }) as typeof process.stdout.write;
+
+    try {
+      await runCursorCommand(['doctor', '--name', 'work', '--with-token']);
+    } finally {
+      process.stdout.write = originalWrite;
+    }
+
+    expect(output).toContain('Cursor network doctor');
+    expect(output).toContain('Proxy: http://***:***@proxy.company:8080');
+    expect(output).toContain('Token check: enabled');
+    expect(output).not.toContain('super-secret-token');
+    expect(output).not.toContain('user:secret');
+    expect(output).not.toContain('Set-Cookie');
+  });
+
+  test('cursor login network errors point to doctor and Cursor network env vars', async () => {
+    globalThis.fetch = (async () => {
+      throw new Error('self signed certificate in certificate chain');
+    }) as typeof fetch;
+
+    await expect(validateCursorSession('token-123')).resolves.toMatchObject({
+      valid: false,
+      reason: 'network',
+      error: expect.stringContaining('TOKENLEAK_CURSOR_CA_FILE'),
+    });
+  });
 });
diff --git a/packages/cli/src/cursor.ts b/packages/cli/src/cursor.ts
index bcf5737..d48c7f3 100644
--- a/packages/cli/src/cursor.ts
+++ b/packages/cli/src/cursor.ts
@@ -1,5 +1,6 @@
 import {
   CursorAuthError,
+  diagnoseCursorConnection,
   getActiveCursorCredentials,
   getCursorCacheDir,
   getCursorCredentialsFor,
@@ -19,6 +20,8 @@ import {
   type CursorAccountInfo,
   type CursorCredentials,
   type CursorCredentialsStore,
+  type CursorDiagnosticCheck,
+  type CursorDiagnosticResult,
   type SyncCursorResult,
   type ValidateCursorSessionResult,
 } from '@tokenleak/registry';
@@ -43,11 +46,14 @@ export {
   shouldSyncCursorForRun,
   syncCursorCache,
   validateCursorSession,
+  diagnoseCursorConnection,
 };
 export type {
   CursorAccountInfo,
   CursorCredentials,
   CursorCredentialsStore,
+  CursorDiagnosticCheck,
+  CursorDiagnosticResult,
   SyncCursorResult,
   ValidateCursorSessionResult,
 };
@@ -118,6 +124,7 @@ export function buildCursorHelpText(): string {
     'Usage:',
     '  tokenleak cursor login [--name <label>]',
     '  tokenleak cursor status [--name <label>]',
+    '  tokenleak cursor doctor [--name <label>] [--with-token] [--insecure-skip-tls-verify]',
     '  tokenleak cursor accounts [--json]',
     '  tokenleak cursor switch <name-or-id>',
     '  tokenleak cursor logout [--name <label> | --all] [--purge-cache]',
@@ -126,12 +133,40 @@ export function buildCursorHelpText(): string {
     'Notes:',
     '  Session tokens come from https://www.cursor.com/settings',
     '  Session tokens are stored in plaintext with local-only file permissions.',
+    '  For protected VPN/proxy networks, run: tokenleak cursor doctor',
     `  Credentials: ${getCursorCredentialsPath()}`,
     `  Cache: ${getCursorCacheDir()}`,
     '',
   ].join('\n');
 }
 
+function formatDiagnosticCheck(check: CursorDiagnosticCheck): string {
+  const prefix = check.ok ? '[ok]' : '[fail]';
+  const status = check.status === undefined ? '' : ` HTTP ${check.status}`;
+  const kind = check.kind ? ` ${check.kind}` : '';
+  const hint = check.hint ? `\n       Hint: ${check.hint}` : '';
+  return `  ${prefix} ${check.name}${status}${kind}: ${check.message}${hint}`;
+}
+
+function printCursorDoctorResult(result: CursorDiagnosticResult, tokenEnabled: boolean): void {
+  process.stdout.write('Cursor network doctor\n');
+  process.stdout.write(`Timeout: ${result.network.timeoutMs}ms\n`);
+  process.stdout.write(`Proxy: ${result.network.proxy ?? 'not configured'}\n`);
+  if (result.network.proxySource) {
+    process.stdout.write(`Proxy source: ${result.network.proxySource}\n`);
+  }
+  if (result.network.noProxyMatched) {
+    process.stdout.write('Proxy bypass: matched NO_PROXY/no_proxy\n');
+  }
+  process.stdout.write(`CA file: ${result.network.caFile ?? 'not configured'}\n`);
+  process.stdout.write(`TLS verification: ${result.network.tlsVerification}\n`);
+  process.stdout.write(`Token check: ${tokenEnabled ? 'enabled' : 'disabled'}\n`);
+  process.stdout.write('Checks:\n');
+  for (const check of result.checks) {
+    process.stdout.write(`${formatDiagnosticCheck(check)}\n`);
+  }
+}
+
 function printCursorAccounts(json: boolean): void {
   const accounts = listCursorAccounts();
   if (json) {
@@ -193,6 +228,27 @@ async function runCursorStatus(name?: string): Promise<void> {
   }
 }
 
+async function runCursorDoctor(options: {
+  name?: string;
+  withToken: boolean;
+  insecureSkipTlsVerify: boolean;
+}): Promise<void> {
+  let credentials: CursorCredentials | null = null;
+  if (options.withToken) {
+    credentials = options.name ? getCursorCredentialsFor(options.name) : getActiveCursorCredentials();
+    if (!credentials) {
+      throw new TokenleakError(options.name ? `Account not found: ${options.name}` : 'No saved Cursor accounts');
+    }
+  }
+
+  const result = await diagnoseCursorConnection({
+    credentials,
+    includeToken: options.withToken,
+    insecureSkipTlsVerify: options.insecureSkipTlsVerify,
+  });
+  printCursorDoctorResult(result, options.withToken);
+}
+
 function runCursorLogout(name: string | undefined, all: boolean, purgeCache: boolean): void {
   if (all) {
     removeAllCursorAccounts(purgeCache);
@@ -278,6 +334,37 @@ export async function runCursorCommand(argv: string[]): Promise<void> {
     return;
   }
 
+  if (command === 'doctor') {
+    let name: string | undefined;
+    let withToken = false;
+    let insecureSkipTlsVerify = false;
+    for (let index = 1; index < argv.length; ) {
+      const arg = argv[index]!;
+      if (arg === '--name') {
+        [name, index] = parseNameFlag(argv, index);
+        continue;
+      }
+      if (arg === '--with-token') {
+        withToken = true;
+        index += 1;
+        continue;
+      }
+      if (arg === '--insecure-skip-tls-verify') {
+        insecureSkipTlsVerify = true;
+        index += 1;
+        continue;
+      }
+      throw new TokenleakError(`Unknown cursor doctor flag "${arg}"`);
+    }
+
+    try {
+      await runCursorDoctor({ name, withToken, insecureSkipTlsVerify });
+    } catch (error: unknown) {
+      wrapCursorError(error);
+    }
+    return;
+  }
+
   if (command === 'accounts') {
     if (argv.length > 2 || (argv[1] && argv[1] !== '--json')) {
       throw new TokenleakError(`Unknown cursor flag "${argv[1]}"`);
diff --git a/packages/registry/src/cursor-auth.test.ts b/packages/registry/src/cursor-auth.test.ts
index 0f51b6d..66c7fea 100644
--- a/packages/registry/src/cursor-auth.test.ts
+++ b/packages/registry/src/cursor-auth.test.ts
@@ -3,9 +3,12 @@ import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import {
+  classifyCursorNetworkError,
+  diagnoseCursorConnection,
   getCursorCacheDir,
   removeAllCursorAccounts,
   resolveCursorSetupStatus,
+  resolveCursorNetworkSettings,
   saveCursorCredentials,
   validateCursorSession,
 } from './cursor-auth';
@@ -17,21 +20,47 @@ const SAMPLE_CSV = [
 ].join('\n');
 
 describe('resolveCursorSetupStatus', () => {
-  const originalCursorDir = process.env['TOKENLEAK_CURSOR_DIR'];
   const originalFetch = globalThis.fetch;
+  const originalEnv = { ...process.env };
   let tempRoot = '';
 
   beforeEach(() => {
     tempRoot = mkdtempSync(join(tmpdir(), 'tokenleak-cursor-status-'));
     process.env['TOKENLEAK_CURSOR_DIR'] = tempRoot;
+    for (const key of [
+      'TOKENLEAK_CURSOR_PROXY',
+      'TOKENLEAK_CURSOR_CA_FILE',
+      'TOKENLEAK_CURSOR_TIMEOUT_MS',
+      'HTTPS_PROXY',
+      'https_proxy',
+      'HTTP_PROXY',
+      'http_proxy',
+      'NO_PROXY',
+      'no_proxy',
+    ]) {
+      delete process.env[key];
+    }
     globalThis.fetch = originalFetch;
   });
 
   afterEach(() => {
-    if (originalCursorDir === undefined) {
-      delete process.env['TOKENLEAK_CURSOR_DIR'];
-    } else {
-      process.env['TOKENLEAK_CURSOR_DIR'] = originalCursorDir;
+    for (const key of [
+      'TOKENLEAK_CURSOR_DIR',
+      'TOKENLEAK_CURSOR_PROXY',
+      'TOKENLEAK_CURSOR_CA_FILE',
+      'TOKENLEAK_CURSOR_TIMEOUT_MS',
+      'HTTPS_PROXY',
+      'https_proxy',
+      'HTTP_PROXY',
+      'http_proxy',
+      'NO_PROXY',
+      'no_proxy',
+    ]) {
+      if (originalEnv[key] === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = originalEnv[key];
+      }
     }
     globalThis.fetch = originalFetch;
     rmSync(tempRoot, { recursive: true, force: true });
@@ -135,4 +164,81 @@ describe('resolveCursorSetupStatus', () => {
     expect(existsSync(join(getCursorCacheDir(), 'usage.csv'))).toBe(false);
     expect(existsSync(join(getCursorCacheDir(), 'archive'))).toBe(false);
   });
+
+  test('resolves Cursor proxy settings and honors NO_PROXY for Cursor hosts', () => {
+    process.env['TOKENLEAK_CURSOR_PROXY'] = 'http://user:secret@proxy.company:8080';
+    process.env['HTTPS_PROXY'] = 'http://fallback.company:8080';
+
+    expect(resolveCursorNetworkSettings('https://cursor.com/api/usage-summary')).toMatchObject({
+      proxy: 'http://user:secret@proxy.company:8080',
+      proxySource: 'TOKENLEAK_CURSOR_PROXY',
+      noProxyMatched: false,
+    });
+
+    process.env['NO_PROXY'] = '.cursor.com,localhost';
+    expect(resolveCursorNetworkSettings('https://www.cursor.com/settings')).toMatchObject({
+      proxy: undefined,
+      proxySource: undefined,
+      noProxyMatched: true,
+    });
+  });
+
+  test('resolves Cursor CA file and timeout settings for fetch', () => {
+    const caPath = join(tempRoot, 'company-root-ca.pem');
+    writeFileSync(caPath, '-----BEGIN CERTIFICATE-----\nfake\n-----END CERTIFICATE-----\n');
+    process.env['TOKENLEAK_CURSOR_CA_FILE'] = caPath;
+    process.env['TOKENLEAK_CURSOR_TIMEOUT_MS'] = '45000';
+
+    const settings = resolveCursorNetworkSettings('https://cursor.com/api/usage-summary');
+
+    expect(settings.timeoutMs).toBe(45000);
+    expect(settings.caFile).toBe(caPath);
+    expect(settings.tls?.ca).toContain('BEGIN CERTIFICATE');
+  });
+
+  test('classifies DNS, TLS, proxy, and timeout network errors', () => {
+    expect(classifyCursorNetworkError(new Error('getaddrinfo ENOTFOUND cursor.com')).kind).toBe('dns');
+    expect(classifyCursorNetworkError(new Error('self signed certificate in certificate chain')).kind).toBe('tls');
+    expect(classifyCursorNetworkError(new Error('Proxy CONNECT aborted while tunneling')).kind).toBe('proxy');
+
+    const aborted = new Error('aborted');
+    aborted.name = 'AbortError';
+    expect(classifyCursorNetworkError(aborted).kind).toBe('timeout');
+  });
+
+  test('diagnoses Cursor reachability without leaking token or proxy secrets', async () => {
+    process.env['TOKENLEAK_CURSOR_PROXY'] = 'http://user:secret@proxy.company:8080';
+    saveCursorCredentials('user-work::super-secret-token', 'work');
+    const cookies: string[] = [];
+
+    globalThis.fetch = (async (url, init) => {
+      cookies.push(String((init?.headers as Record<string, string> | undefined)?.['Cookie'] ?? ''));
+      const hasToken = cookies.at(-1)?.includes('super-secret-token') ?? false;
+      if (String(url).includes('/api/usage-summary')) {
+        if (!hasToken) {
+          return new Response(JSON.stringify({ error: 'not_authenticated' }), { status: 401 });
+        }
+        return new Response(JSON.stringify({
+          billingCycleStart: '2026-03-01',
+          billingCycleEnd: '2026-03-31',
+          membershipType: 'pro',
+        }), { status: 200 });
+      }
+      if (!hasToken) {
+        return new Response('', { status: 307, headers: { location: 'https://api.workos.com' } });
+      }
+      return new Response(SAMPLE_CSV, { status: 200 });
+    }) as typeof fetch;
+
+    const result = await diagnoseCursorConnection({
+      credentials: { sessionToken: 'user-work::super-secret-token' },
+      includeToken: true,
+    });
+
+    expect(result.network.proxy).toBe('http://***:***@proxy.company:8080');
+    expect(result.checks.every((check) => check.ok)).toBe(true);
+    expect(JSON.stringify(result)).not.toContain('super-secret-token');
+    expect(JSON.stringify(result)).not.toContain('user:secret');
+    expect(cookies.some((cookie) => cookie.includes('super-secret-token'))).toBe(true);
+  });
 });
diff --git a/packages/registry/src/cursor-auth.ts b/packages/registry/src/cursor-auth.ts
index ee6d23b..b5befd0 100644
--- a/packages/registry/src/cursor-auth.ts
+++ b/packages/registry/src/cursor-auth.ts
@@ -17,6 +17,7 @@ import { basename, dirname, join } from 'node:path';
 const CURSOR_USAGE_CSV_ENDPOINT =
   'https://cursor.com/api/dashboard/export-usage-events-csv?strategy=tokens';
 const CURSOR_USAGE_SUMMARY_ENDPOINT = 'https://cursor.com/api/usage-summary';
+const DEFAULT_CURSOR_FETCH_TIMEOUT_MS = 10_000;
 
 export type CursorFailureReason =
   | 'auth'
@@ -91,6 +92,69 @@ export interface CursorSetupStatus {
   activeAccountLabel?: string;
 }
 
+export type CursorNetworkFailureKind =
+  | 'dns'
+  | 'timeout'
+  | 'proxy'
+  | 'tls'
+  | 'http_auth'
+  | 'api'
+  | 'parse'
+  | 'redirect'
+  | 'unknown';
+
+export interface CursorNetworkClassification {
+  kind: CursorNetworkFailureKind;
+  message: string;
+  hint?: string;
+}
+
+export interface CursorNetworkSettings {
+  timeoutMs: number;
+  proxy?: string;
+  proxySource?: string;
+  proxyDisplay?: string;
+  noProxyMatched: boolean;
+  caFile?: string;
+  tls?: {
+    ca?: string;
+    rejectUnauthorized?: boolean;
+  };
+}
+
+export interface CursorDiagnosticCheck {
+  name: string;
+  ok: boolean;
+  message: string;
+  status?: number;
+  kind?: CursorNetworkFailureKind;
+  hint?: string;
+}
+
+export interface CursorDiagnosticResult {
+  network: {
+    timeoutMs: number;
+    proxy?: string;
+    proxySource?: string;
+    noProxyMatched: boolean;
+    caFile?: string;
+    tlsVerification: 'enabled' | 'disabled';
+  };
+  checks: CursorDiagnosticCheck[];
+}
+
+interface CursorNetworkOverrides {
+  insecureSkipTlsVerify?: boolean;
+}
+
+type CursorFetchInit = RequestInit & {
+  proxy?: string;
+  tls?: {
+    ca?: string;
+    rejectUnauthorized?: boolean;
+  };
+};
+
 function getCursorRootDir(): string {
   return process.env['TOKENLEAK_CURSOR_DIR'] ?? join(homedir(), '.config', 'tokenleak');
 }
@@ -103,6 +167,248 @@ export function getCursorCacheDir(): string {
   return join(getCursorRootDir(), 'cursor-cache');
 }
 
+function envValue(name: string): string | undefined {
+  const value = process.env[name]?.trim();
+  return value ? value : undefined;
+}
+
+function parseCursorTimeoutMs(): number {
+  const raw = envValue('TOKENLEAK_CURSOR_TIMEOUT_MS');
+  if (!raw) {
+    return DEFAULT_CURSOR_FETCH_TIMEOUT_MS;
+  }
+
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_CURSOR_FETCH_TIMEOUT_MS;
+}
+
+function splitNoProxyHostPort(entry: string): { host: string; port?: string } {
+  const trimmed = entry.trim().toLowerCase();
+  if (!trimmed) {
+    return { host: '' };
+  }
+
+  if (trimmed.startsWith('[')) {
+    const end = trimmed.indexOf(']');
+    if (end >= 0) {
+      const host = trimmed.slice(1, end);
+      const port = trimmed.slice(end + 1).replace(/^:/, '') || undefined;
+      return { host, port };
+    }
+  }
+
+  const colonIndex = trimmed.lastIndexOf(':');
+  if (colonIndex > 0 && trimmed.indexOf(':') === colonIndex) {
+    return {
+      host: trimmed.slice(0, colonIndex),
+      port: trimmed.slice(colonIndex + 1) || undefined,
+    };
+  }
+
+  return { host: trimmed };
+}
+
+function noProxyMatches(url: string, noProxy?: string): boolean {
+  if (!noProxy?.trim()) {
+    return false;
+  }
+
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return false;
+  }
+
+  const host = parsed.hostname.toLowerCase();
+  const port = parsed.port || (parsed.protocol === 'https:' ? '443' : '80');
+  for (const entry of noProxy.split(',')) {
+    const { host: entryHost, port: entryPort } = splitNoProxyHostPort(entry);
+    if (!entryHost) {
+      continue;
+    }
+
+    if (entryHost === '*') {
+      return true;
+    }
+
+    if (entryPort && entryPort !== port) {
+      continue;
+    }
+
+    if (entryHost.startsWith('*.')) {
+      const suffix = entryHost.slice(1);
+      if (host.endsWith(suffix)) {
+        return true;
+      }
+      continue;
+    }
+
+    if (entryHost.startsWith('.')) {
+      const bare = entryHost.slice(1);
+      if (host === bare || host.endsWith(entryHost)) {
+        return true;
+      }
+      continue;
+    }
+
+    if (host === entryHost || host.endsWith(`.${entryHost}`)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function getProxyCandidate(): { proxy?: string; source?: string } {
+  for (const name of [
+    'TOKENLEAK_CURSOR_PROXY',
+    'HTTPS_PROXY',
+    'https_proxy',
+    'HTTP_PROXY',
+    'http_proxy',
+  ]) {
+    const proxy = envValue(name);
+    if (proxy) {
+      return { proxy, source: name };
+    }
+  }
+
+  return {};
+}
+
+function redactProxy(proxy: string): string {
+  try {
+    const parsed = new URL(proxy);
+    if (parsed.username || parsed.password) {
+      parsed.username = '***';
+      parsed.password = parsed.password ? '***' : '';
+    }
+    const redacted = parsed.toString();
+    return parsed.pathname === '/' && !proxy.endsWith('/') ? redacted.slice(0, -1) : redacted;
+  } catch {
+    return proxy.replace(/\/\/([^:@/\s]+):([^@/\s]+)@/, '//***:***@');
+  }
+}
+
+export function resolveCursorNetworkSettings(
+  url: string,
+  overrides: CursorNetworkOverrides = {},
+): CursorNetworkSettings {
+  const noProxy = envValue('NO_PROXY') ?? envValue('no_proxy');
+  const noProxyMatched = noProxyMatches(url, noProxy);
+  const candidate = noProxyMatched ? {} : getProxyCandidate();
+  const caFile = envValue('TOKENLEAK_CURSOR_CA_FILE');
+  const tls: CursorNetworkSettings['tls'] = {};
+
+  if (caFile) {
+    tls.ca = readFileSync(caFile, 'utf8');
+  }
+
+  if (overrides.insecureSkipTlsVerify) {
+    tls.rejectUnauthorized = false;
+  }
+
+  return {
+    timeoutMs: parseCursorTimeoutMs(),
+    proxy: candidate.proxy,
+    proxySource: candidate.source,
+    proxyDisplay: candidate.proxy ? redactProxy(candidate.proxy) : undefined,
+    noProxyMatched,
+    caFile,
+    tls: Object.keys(tls).length > 0 ? tls : undefined,
+  };
+}
+
+export function classifyCursorNetworkError(error: unknown): CursorNetworkClassification {
+  const message = error instanceof Error ? error.message : String(error);
+  const name = error instanceof Error ? error.name : '';
+  const code = typeof error === 'object' && error !== null && 'code' in error
+    ? String((error as { code?: unknown }).code)
+    : '';
+  const haystack = `${name} ${code} ${message}`.toLowerCase();
+
+  if (
+    haystack.includes('enotfound') ||
+    haystack.includes('eai_again') ||
+    haystack.includes('getaddrinfo') ||
+    haystack.includes('dns')
+  ) {
+    return {
+      kind: 'dns',
+      message,
+      hint: 'Check DNS/VPN routing for cursor.com and run `tokenleak cursor doctor`.',
+    };
+  }
+
+  if (
+    haystack.includes('proxy') ||
+    haystack.includes('tunnel') ||
+    haystack.includes('connect aborted') ||
+    haystack.includes('407')
+  ) {
+    return {
+      kind: 'proxy',
+      message,
+      hint: 'Set TOKENLEAK_CURSOR_PROXY or your HTTPS_PROXY/HTTP_PROXY value, then run `tokenleak cursor doctor`.',
+    };
+  }
+
+  if (name === 'AbortError' || haystack.includes('abort') || haystack.includes('timeout')) {
+    return {
+      kind: 'timeout',
+      message,
+      hint: 'Try increasing TOKENLEAK_CURSOR_TIMEOUT_MS and run `tokenleak cursor doctor`.',
+    };
+  }
+
+  if (
+    haystack.includes('certificate') ||
+    haystack.includes('cert_') ||
+    haystack.includes('self signed') ||
+    haystack.includes('unable_to_verify') ||
+    haystack.includes('unable to verify') ||
+    haystack.includes('tls') ||
+    haystack.includes('ssl')
+  ) {
+    return {
+      kind: 'tls',
+      message,
+      hint: 'Export your company root CA as PEM and set TOKENLEAK_CURSOR_CA_FILE, then run `tokenleak cursor doctor`.',
+    };
+  }
+
+  return {
+    kind: 'unknown',
+    message,
+    hint: 'Run `tokenleak cursor doctor` to collect network diagnostics.',
+  };
+}
+
+function formatNetworkError(error: unknown): string {
+  const classification = classifyCursorNetworkError(error);
+  const prefix = classification.kind === 'unknown'
+    ? 'Failed to connect'
+    : `Failed to connect (${classification.kind})`;
+  return `${prefix}: ${classification.message}. ${classification.hint}`;
+}
+
+function buildFetchInit(
+  url: string,
+  init: RequestInit,
+  overrides: CursorNetworkOverrides = {},
+): { init: CursorFetchInit; settings: CursorNetworkSettings } {
+  const settings = resolveCursorNetworkSettings(url, overrides);
+  const fetchInit: CursorFetchInit = { ...init };
+  if (settings.proxy) {
+    fetchInit.proxy = settings.proxy;
+  }
+  if (settings.tls) {
+    fetchInit.tls = settings.tls;
+  }
+  return { init: fetchInit, settings };
+}
+
 function ensureDir(dirPath: string, mode?: number): void {
   if (!existsSync(dirPath)) {
     mkdirSync(dirPath, { recursive: true });
@@ -124,25 +430,22 @@ function atomicWriteFile(path: string, contents: string, mode?: number): void {
   renameSync(tempPath, path);
 }
 
-const CURSOR_FETCH_TIMEOUT_MS = 10_000;
-
-async function fetchWithTimeout(url: string, init: RequestInit): Promise<Response> {
+async function fetchWithTimeout(
+  url: string,
+  init: RequestInit,
+  overrides: CursorNetworkOverrides = {},
+): Promise<Response> {
+  const { init: fetchInit, settings } = buildFetchInit(url, init, overrides);
   const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), CURSOR_FETCH_TIMEOUT_MS);
+  const timeout = setTimeout(() => controller.abort(), settings.timeoutMs);
 
   try {
     return await fetch(url, {
-      ...init,
+      ...fetchInit,
       signal: controller.signal,
     });
   } catch (error: unknown) {
-    if (error instanceof Error && error.name === 'AbortError') {
-      throw new CursorAuthError(
-        `Failed to connect: request timed out after ${CURSOR_FETCH_TIMEOUT_MS}ms`,
-        'network',
-      );
-    }
-    throw error;
+    throw new CursorAuthError(formatNetworkError(error), 'network');
   } finally {
     clearTimeout(timeout);
   }
@@ -515,7 +818,9 @@ export async function validateCursorSession(sessionToken: string): Promise<Valid
   } catch (error: unknown) {
     return {
       valid: false,
-      error: `Failed to connect: ${error instanceof Error ? error.message : String(error)}`,
+      error: error instanceof CursorAuthError
+        ? error.message
+        : formatNetworkError(error),
       reason: 'network',
     };
   }
@@ -573,10 +878,7 @@ async function fetchCursorUsageCsv(sessionToken: string): Promise<string> {
     if (error instanceof CursorAuthError) {
       throw error;
     }
-    throw new CursorAuthError(
-      `Failed to connect: ${error instanceof Error ? error.message : String(error)}`,
-      'network',
-    );
+    throw new CursorAuthError(formatNetworkError(error), 'network');
   }
 
   if (response.status === 401 || response.status === 403) {
@@ -598,6 +900,208 @@ async function fetchCursorUsageCsv(sessionToken: string): Promise<string> {
   return text;
 }
 
+async function runDiagnosticFetch(
+  name: string,
+  url: string,
+  init: RequestInit,
+  evaluate: (response: Response) => Promise<CursorDiagnosticCheck>,
+  overrides: CursorNetworkOverrides,
+): Promise<CursorDiagnosticCheck> {
+  try {
+    const response = await fetchWithTimeout(url, init, overrides);
+    return await evaluate(response);
+  } catch (error: unknown) {
+    const classification = error instanceof CursorAuthError
+      ? classifyCursorNetworkError(error.message)
+      : classifyCursorNetworkError(error);
+    return {
+      name,
+      ok: false,
+      message: classification.message,
+      kind: classification.kind,
+      hint: classification.hint,
+    };
+  }
+}
+
+export async function diagnoseCursorConnection(options: {
+  credentials?: Pick<CursorCredentials, 'sessionToken'> | null;
+  includeToken?: boolean;
+  insecureSkipTlsVerify?: boolean;
+} = {}): Promise<CursorDiagnosticResult> {
+  const overrides = { insecureSkipTlsVerify: options.insecureSkipTlsVerify };
+  const settings = resolveCursorNetworkSettings(CURSOR_USAGE_SUMMARY_ENDPOINT, overrides);
+  const checks: CursorDiagnosticCheck[] = [];
+
+  checks.push(await runDiagnosticFetch(
+    'usage-summary-baseline',
+    CURSOR_USAGE_SUMMARY_ENDPOINT,
+    {
+      headers: { Accept: 'application/json' },
+      redirect: 'manual',
+    },
+    async (response) => {
+      const ok = response.status === 401 || response.status === 403;
+      return {
+        name: 'usage-summary-baseline',
+        ok,
+        status: response.status,
+        message: ok
+          ? `Cursor usage summary is reachable (${response.status} unauthenticated response expected).`
+          : `Unexpected usage summary status ${response.status}.`,
+        kind: ok ? undefined : (response.status === 407 ? 'http_auth' : 'api'),
+        hint: ok ? undefined : 'Run `tokenleak cursor doctor --with-token` after confirming VPN/proxy settings.',
+      };
+    },
+    overrides,
+  ));
+
+  checks.push(await runDiagnosticFetch(
+    'usage-csv-baseline',
+    CURSOR_USAGE_CSV_ENDPOINT,
+    {
+      headers: { Accept: '*/*' },
+      redirect: 'manual',
+    },
+    async (response) => {
+      const ok = response.status === 307 || response.status === 401 || response.status === 403;
+      return {
+        name: 'usage-csv-baseline',
+        ok,
+        status: response.status,
+        message: ok
+          ? `Cursor CSV endpoint is reachable (${response.status} unauthenticated response expected).`
+          : `Unexpected Cursor CSV status ${response.status}.`,
+        kind: ok ? undefined : (response.status === 407 ? 'http_auth' : 'api'),
+        hint: ok ? undefined : 'Confirm the VPN allows cursor.com and api.workos.com.',
+      };
+    },
+    overrides,
+  ));
+
+  if (options.includeToken) {
+    const credentials = options.credentials;
+    if (!credentials?.sessionToken) {
+      checks.push({
+        name: 'token',
+        ok: false,
+        message: 'No saved Cursor token was available for token checks.',
+        kind: 'unknown',
+        hint: "Run 'tokenleak cursor login --name <label>' or pass --name for a saved account.",
+      });
+    } else {
+      checks.push(await runDiagnosticFetch(
+        'usage-summary-token',
+        CURSOR_USAGE_SUMMARY_ENDPOINT,
+        {
+          headers: buildCursorHeaders(credentials.sessionToken),
+        },
+        async (response) => {
+          if (response.status === 401 || response.status === 403) {
+            return {
+              name: 'usage-summary-token',
+              ok: false,
+              status: response.status,
+              message: 'Saved Cursor token was rejected.',
+              kind: 'http_auth',
+              hint: "Copy a fresh WorkosCursorSessionToken and run 'tokenleak cursor login' again.",
+            };
+          }
+          if (!response.ok) {
+            return {
+              name: 'usage-summary-token',
+              ok: false,
+              status: response.status,
+              message: `Cursor usage summary returned status ${response.status}.`,
+              kind: response.status === 407 ? 'http_auth' : 'api',
+              hint: 'Run token-free doctor checks to separate network and auth failures.',
+            };
+          }
+          try {
+            const payload = await response.json() as Record<string, unknown>;
+            const valid = typeof payload['billingCycleStart'] === 'string'
+              && typeof payload['billingCycleEnd'] === 'string';
+            return {
+              name: 'usage-summary-token',
+              ok: valid,
+              status: response.status,
+              message: valid
+                ? 'Saved Cursor token can read the usage summary.'
+                : 'Usage summary response did not match the expected JSON shape.',
+              kind: valid ? undefined : 'parse',
+              hint: valid ? undefined : 'Cursor may have changed the usage summary response format.',
+            };
+          } catch (error: unknown) {
+            return {
+              name: 'usage-summary-token',
+              ok: false,
+              status: response.status,
+              message: `Failed to parse usage summary JSON: ${error instanceof Error ? error.message : String(error)}`,
+              kind: 'parse',
+            };
+          }
+        },
+        overrides,
+      ));
+
+      checks.push(await runDiagnosticFetch(
+        'usage-csv-token',
+        CURSOR_USAGE_CSV_ENDPOINT,
+        {
+          headers: buildCursorHeaders(credentials.sessionToken),
+        },
+        async (response) => {
+          if (response.status === 401 || response.status === 403) {
+            return {
+              name: 'usage-csv-token',
+              ok: false,
+              status: response.status,
+              message: 'Saved Cursor token was rejected by the CSV endpoint.',
+              kind: 'http_auth',
+              hint: "Copy a fresh WorkosCursorSessionToken and run 'tokenleak cursor login' again.",
+            };
+          }
+          if (!response.ok) {
+            return {
+              name: 'usage-csv-token',
+              ok: false,
+              status: response.status,
+              message: `Cursor CSV endpoint returned status ${response.status}.`,
+              kind: response.status === 407 ? 'http_auth' : 'api',
+            };
+          }
+
+          const text = await response.text();
+          const ok = text.startsWith('Date,');
+          return {
+            name: 'usage-csv-token',
+            ok,
+            status: response.status,
+            message: ok
+              ? 'Saved Cursor token can read the usage CSV.'
+              : 'Cursor CSV response did not start with the expected header.',
+            kind: ok ? undefined : 'parse',
+            hint: ok ? undefined : 'The response may be an HTML login page or a changed API format.',
+          };
+        },
+        overrides,
+      ));
+    }
+  }
+
+  return {
+    network: {
+      timeoutMs: settings.timeoutMs,
+      proxy: settings.proxyDisplay,
+      proxySource: settings.proxySource,
+      noProxyMatched: settings.noProxyMatched,
+      caFile: settings.caFile,
+      tlsVerification: options.insecureSkipTlsVerify ? 'disabled' : 'enabled',
+    },
+    checks,
+  };
+}
+
 export async function syncCursorCache(): Promise<SyncCursorResult> {
   const store = loadCursorCredentialsStore();
   if (!store || Object.keys(store.accounts).length === 0) {
diff --git a/packages/registry/src/index.ts b/packages/registry/src/index.ts
index c0177da..9e34443 100644
--- a/packages/registry/src/index.ts
+++ b/packages/registry/src/index.ts
@@ -39,7 +39,9 @@ export {
   PiProvider,
 } from './providers/index';
 export {
+  classifyCursorNetworkError,
   CursorAuthError,
+  diagnoseCursorConnection,
   getActiveCursorCredentials,
   getCursorCacheDir,
   getCursorCredentialsFor,
@@ -53,6 +55,7 @@ export {
   removeCursorAccount,
   resetCursorProviderState,
   resolveCursorSetupStatus,
+  resolveCursorNetworkSettings,
   saveCursorCredentials,
   saveCursorCredentialsStore,
   setActiveCursorAccount,
@@ -64,7 +67,12 @@ export type {
   CursorAccountInfo,
   CursorCredentials,
   CursorCredentialsStore,
+  CursorDiagnosticCheck,
+  CursorDiagnosticResult,
   CursorFailureReason,
+  CursorNetworkClassification,
+  CursorNetworkFailureKind,
+  CursorNetworkSettings,
   CursorSetupState,
   CursorSetupStatus,
   SyncCursorResult,

From e9fdf6607367f237817a43733d17ccddd9fd02dd Mon Sep 17 00:00:00 2001
From: Deva Annamaraju <yansh2017@gmail.com>
Date: Mon, 25 May 2026 23:40:58 +0530
Subject: [PATCH 2/2] fix cursor doctor ca diagnostics

---
 packages/cli/src/cursor.test.ts           | 23 ++++++++++++
 packages/registry/src/cursor-auth.test.ts | 24 ++++++++++++
 packages/registry/src/cursor-auth.ts      | 46 ++++++++++++++++++-----
 3 files changed, 84 insertions(+), 9 deletions(-)

diff --git a/packages/cli/src/cursor.test.ts b/packages/cli/src/cursor.test.ts
index 3c8eb82..304b0d5 100644
--- a/packages/cli/src/cursor.test.ts
+++ b/packages/cli/src/cursor.test.ts
@@ -267,4 +267,27 @@ describe('cursor auth and sync helpers', () => {
       error: expect.stringContaining('TOKENLEAK_CURSOR_CA_FILE'),
     });
   });
+
+  test('cursor doctor reports a missing CA file without crashing', async () => {
+    const missingCaPath = join(tempRoot, 'missing-company-root-ca.pem');
+    process.env['TOKENLEAK_CURSOR_CA_FILE'] = missingCaPath;
+    let output = '';
+    const originalWrite = process.stdout.write;
+    process.stdout.write = ((chunk: string | Uint8Array) => {
+      output += String(chunk);
+      return true;
+    }) as typeof process.stdout.write;
+
+    try {
+      await runCursorCommand(['doctor']);
+    } finally {
+      process.stdout.write = originalWrite;
+    }
+
+    expect(output).toContain('Cursor network doctor');
+    expect(output).toContain('CA file:');
+    expect(output).toContain(missingCaPath);
+    expect(output).toContain('[fail] ca-file');
+    expect(output).toContain('TOKENLEAK_CURSOR_CA_FILE');
+  });
 });
diff --git a/packages/registry/src/cursor-auth.test.ts b/packages/registry/src/cursor-auth.test.ts
index 66c7fea..25c682e 100644
--- a/packages/registry/src/cursor-auth.test.ts
+++ b/packages/registry/src/cursor-auth.test.ts
@@ -241,4 +241,28 @@ describe('resolveCursorSetupStatus', () => {
     expect(JSON.stringify(result)).not.toContain('user:secret');
     expect(cookies.some((cookie) => cookie.includes('super-secret-token'))).toBe(true);
   });
+
+  test('diagnoses a missing Cursor CA file instead of throwing', async () => {
+    const missingCaPath = join(tempRoot, 'missing-company-root-ca.pem');
+    process.env['TOKENLEAK_CURSOR_CA_FILE'] = missingCaPath;
+    let called = false;
+    globalThis.fetch = (async () => {
+      called = true;
+      return new Response('unexpected', { status: 200 });
+    }) as typeof fetch;
+
+    const result = await diagnoseCursorConnection();
+
+    expect(called).toBe(false);
+    expect(result.network.caFile).toBe(missingCaPath);
+    expect(result.checks).toEqual([
+      expect.objectContaining({
+        name: 'ca-file',
+        ok: false,
+        kind: 'tls',
+        message: expect.stringContaining('missing-company-root-ca.pem'),
+        hint: expect.stringContaining('TOKENLEAK_CURSOR_CA_FILE'),
+      }),
+    ]);
+  });
 });
diff --git a/packages/registry/src/cursor-auth.ts b/packages/registry/src/cursor-auth.ts
index b5befd0..7056972 100644
--- a/packages/registry/src/cursor-auth.ts
+++ b/packages/registry/src/cursor-auth.ts
@@ -116,6 +116,7 @@ export interface CursorNetworkSettings {
   proxyDisplay?: string;
   noProxyMatched: boolean;
   caFile?: string;
+  caFileError?: string;
   tls?: {
     ca?: string;
     rejectUnauthorized?: boolean;
@@ -300,9 +301,14 @@ export function resolveCursorNetworkSettings(
   const candidate = noProxyMatched ? {} : getProxyCandidate();
   const caFile = envValue('TOKENLEAK_CURSOR_CA_FILE');
   const tls: CursorNetworkSettings['tls'] = {};
+  let caFileError: string | undefined;
 
   if (caFile) {
-    tls.ca = readFileSync(caFile, 'utf8');
+    try {
+      tls.ca = readFileSync(caFile, 'utf8');
+    } catch (error: unknown) {
+      caFileError = error instanceof Error ? error.message : String(error);
+    }
   }
 
   if (overrides.insecureSkipTlsVerify) {
@@ -316,6 +322,7 @@ export function resolveCursorNetworkSettings(
     proxyDisplay: candidate.proxy ? redactProxy(candidate.proxy) : undefined,
     noProxyMatched,
     caFile,
+    caFileError,
     tls: Object.keys(tls).length > 0 ? tls : undefined,
   };
 }
@@ -399,6 +406,13 @@ function buildFetchInit(
   overrides: CursorNetworkOverrides = {},
 ): { init: CursorFetchInit; settings: CursorNetworkSettings } {
   const settings = resolveCursorNetworkSettings(url, overrides);
+  if (settings.caFileError) {
+    throw new CursorAuthError(
+      `Failed to read TOKENLEAK_CURSOR_CA_FILE (${settings.caFile}): ${settings.caFileError}. Check the file path or export the company root CA as a readable PEM file.`,
+      'network',
+    );
+  }
+
   const fetchInit: CursorFetchInit = { ...init };
   if (settings.proxy) {
     fetchInit.proxy = settings.proxy;
@@ -932,6 +946,27 @@ export async function diagnoseCursorConnection(options: {
   const overrides = { insecureSkipTlsVerify: options.insecureSkipTlsVerify };
   const settings = resolveCursorNetworkSettings(CURSOR_USAGE_SUMMARY_ENDPOINT, overrides);
   const checks: CursorDiagnosticCheck[] = [];
+  const network = {
+    timeoutMs: settings.timeoutMs,
+    proxy: settings.proxyDisplay,
+    proxySource: settings.proxySource,
+    noProxyMatched: settings.noProxyMatched,
+    caFile: settings.caFile,
+    tlsVerification: options.insecureSkipTlsVerify ? 'disabled' as const : 'enabled' as const,
+  };
+
+  if (settings.caFileError) {
+    return {
+      network,
+      checks: [{
+        name: 'ca-file',
+        ok: false,
+        message: `Could not read TOKENLEAK_CURSOR_CA_FILE (${settings.caFile}): ${settings.caFileError}`,
+        kind: 'tls',
+        hint: 'Check that TOKENLEAK_CURSOR_CA_FILE points to a readable PEM file, or unset it and rerun `tokenleak cursor doctor`.',
+      }],
+    };
+  }
 
   checks.push(await runDiagnosticFetch(
     'usage-summary-baseline',
@@ -1090,14 +1125,7 @@ export async function diagnoseCursorConnection(options: {
   }
 
   return {
-    network: {
-      timeoutMs: settings.timeoutMs,
-      proxy: settings.proxyDisplay,
-      proxySource: settings.proxySource,
-      noProxyMatched: settings.noProxyMatched,
-      caFile: settings.caFile,
-      tlsVerification: options.insecureSkipTlsVerify ? 'disabled' : 'enabled',
-    },
+    network,
     checks,
   };
 }