fix(http): name corporate-network transport failures (#433)

DOCUMENTATION.md

@@ -1535,6 +1535,25 @@ The full list is the [exit-code table](#exit-codes). On every path the same info
 | `14`                  | Client too old — the backend requires a newer CLI (HTTP 426 `CLIENT_TOO_OLD`); upgrade to proceed |
 | `129` / `130` / `143` | Interrupted by a signal (SIGHUP / SIGINT / SIGTERM) — `128 + signal number`                       |
 
+### Corporate TLS inspection and proxy block pages
+
+If every command exits `10` with a message naming `NODE_EXTRA_CA_CERTS`, the
+machine does not trust the certificate chain presented by the network. Node's
+default trust store is its bundled Mozilla roots plus any PEM bundle named by
+`NODE_EXTRA_CA_CERTS`; it does not read the operating-system store. Point that
+variable at the corporate root CA (for example
+`NODE_EXTRA_CA_CERTS=/path/to/corporate-root-ca.pem`). Never set
+`NODE_TLS_REJECT_UNAUTHORIZED=0` — it disables certificate checks for requests
+that carry the API key.
+
+If a proxy, firewall, or captive portal answers with an HTML `4xx` page, the CLI
+reports `UNAVAILABLE` with `details.reason: "not_testsprite"`, plus the status,
+content type, and page title, instead of mapping the status to an API verdict
+such as `AUTH_FORBIDDEN`. Ask IT to allow the API host, and set `HTTPS_PROXY` /
+`HTTP_PROXY` when the network requires an explicit proxy. A JSON API error
+envelope still maps by status; `408`, `429`, and `5xx` keep their existing retry
+behavior.
+
 ### Exit 7 on `test plan generate` — timeout or unsupported?
 
 Exit `7` is a shared bucket, and on this command it has three producers. The

src/commands/doctor.test.ts

@@ -397,6 +397,75 @@ describe('runDoctor — failing checks exit non-zero', () => {
     expect(capture.stdout.join('\n')).toContain('GET /me failed (NOT_FOUND)');
   });
 
+  it('a TLS trust failure names NODE_EXTRA_CA_CERTS and does not blame tunnels', async () => {
+    writeProfile('default', { apiKey: 'sk-user-abc' }, { path: credentialsPath });
+    const { capture, deps } = makeCapture();
+    const fetchImpl = vi.fn(async () => {
+      const cause = Object.assign(new Error('self-signed certificate in certificate chain'), {
+        code: 'SELF_SIGNED_CERT_IN_CHAIN',
+      });
+      throw new TypeError('fetch failed', { cause });
+    }) as unknown as DoctorDeps['fetchImpl'];
+    const rejection = await runDoctor(
+      { profile: 'default', output: 'text', debug: false },
+      { ...healthyDeps(credentialsPath, { fetchImpl }), ...deps },
+    ).catch((error: unknown) => error);
+
+    expect(rejection).toBeInstanceOf(CLIError);
+    const out = capture.stdout.join('\n');
+    expect(out).toContain('GET /me failed:');
+    expect(out).toContain('NODE_EXTRA_CA_CERTS');
+    expect(out).toContain('skipped; the connectivity check did not reach TestSprite');
+    expect(out).not.toContain('not available on this endpoint');
+    // Connectivity failed: the tunnel probe must not fire a second doomed request.
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+  });
+
+  it('an unclassified fetch rejection does not blame the tunnel endpoint', async () => {
+    writeProfile('default', { apiKey: 'sk-user-abc' }, { path: credentialsPath });
+    const { capture, deps } = makeCapture();
+    const fetchImpl = vi.fn(async () => {
+      const cause = Object.assign(new Error('connect EUNKNOWN'), { code: 'EUNKNOWN' });
+      throw new TypeError('fetch failed', { cause });
+    }) as unknown as DoctorDeps['fetchImpl'];
+    const rejection = await runDoctor(
+      { profile: 'default', output: 'text', debug: false },
+      { ...healthyDeps(credentialsPath, { fetchImpl }), ...deps },
+    ).catch((error: unknown) => error);
+
+    expect(rejection).toBeInstanceOf(CLIError);
+    const out = capture.stdout.join('\n');
+    expect(out).toContain('GET /me failed (UNAVAILABLE)');
+    expect(out).toContain('skipped; the connectivity check did not reach TestSprite');
+    expect(out).not.toContain('not available on this endpoint');
+    // Four connectivity attempts and no fifth tunnel probe.
+    expect(fetchImpl).toHaveBeenCalledTimes(4);
+  });
+
+  it('an HTML 403 block page is not reported as a rejected API key', async () => {
+    writeProfile('default', { apiKey: 'sk-user-abc' }, { path: credentialsPath });
+    const { capture, deps } = makeCapture();
+    const fetchImpl = vi.fn(
+      async () =>
+        new Response(
+          '<!doctype html><html><head><title>Website blocked by your organization</title></head></html>',
+          { status: 403, headers: { 'content-type': 'text/html; charset=utf-8' } },
+        ),
+    ) as unknown as DoctorDeps['fetchImpl'];
+    const rejection = await runDoctor(
+      { profile: 'default', output: 'text', debug: false },
+      { ...healthyDeps(credentialsPath, { fetchImpl }), ...deps },
+    ).catch((error: unknown) => error);
+
+    expect(rejection).toBeInstanceOf(CLIError);
+    const out = capture.stdout.join('\n');
+    expect(out).not.toContain('API key rejected');
+    expect(out).toContain('Website blocked by your organization');
+    expect(out).toContain('skipped; the connectivity check did not reach TestSprite');
+    expect(out).not.toContain('not available on this endpoint');
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+  });
+
   it('an excluded in-range Node runtime fails the Node.js check', async () => {
     writeProfile('default', { apiKey: 'sk-user-abc' }, { path: credentialsPath });
     const { capture, deps } = makeCapture();

src/commands/doctor.ts

@@ -33,6 +33,7 @@ import {
   CLIError,
   InterruptError,
   RequestTimeoutError,
+  TransportError,
   localValidationError,
 } from '../lib/errors.js';
 import type { FetchImpl } from '../lib/http.js';
@@ -43,6 +44,7 @@ import { GLOBAL_OPTS_HINT, Output, resolveOutputMode, type OutputMode } from '..
 import type { MeIdentityWire } from '../lib/response-schemas.js';
 import { ME_IDENTITY_SCHEMA } from '../lib/response-schemas.js';
 import { isVerifySkillInstalled } from '../lib/skill-nudge.js';
+import { isTransportFailure } from '../lib/transport-failure.js';
 import { emitV3RoutingAdvisory, routingLabel } from '../lib/v3-advisory.js';
 import { VERSION } from '../version.js';
 import { SUPPORTED_NODE_RANGE, shouldRejectNodeVersion } from '../version-guard.js';
@@ -175,6 +177,7 @@ export async function runDoctor(opts: CommonOptions, deps: DoctorDeps = {}): Pro
       hasKey,
       endpointOk: endpointCheck.status === 'ok',
       config,
+      reachedApi: connectivity.reachedApi,
     }),
   );
 
@@ -292,13 +295,25 @@ async function checkConnectivity(
   v3Enabled?: boolean;
   organizations?: CliOrgSummary[];
   org?: CliOrgBinding;
+  /** False when the request never produced an answer from the API. */
+  reachedApi: boolean;
 }> {
   const name = 'Connectivity';
-  if (opts.dryRun) return { check: { name, status: 'warn', detail: 'skipped under --dry-run' } };
+  if (opts.dryRun)
+    return {
+      check: { name, status: 'warn', detail: 'skipped under --dry-run' },
+      reachedApi: false,
+    };
   if (!ctx.hasKey)
-    return { check: { name, status: 'warn', detail: 'skipped; no API key to test with' } };
+    return {
+      check: { name, status: 'warn', detail: 'skipped; no API key to test with' },
+      reachedApi: false,
+    };
   if (!ctx.endpointOk)
-    return { check: { name, status: 'warn', detail: 'skipped; endpoint URL is invalid' } };
+    return {
+      check: { name, status: 'warn', detail: 'skipped; endpoint URL is invalid' },
+      reachedApi: false,
+    };
 
   try {
     const client = makeHttpClient(opts, {
@@ -316,6 +331,7 @@ async function checkConnectivity(
       v3Enabled: me.v3Enabled,
       organizations: me.organizations,
       org: me.org,
+      reachedApi: true,
     };
   } catch (error) {
     if (error instanceof InterruptError) throw error;
@@ -325,16 +341,37 @@ async function checkConnectivity(
         error.code === 'AUTH_INVALID' ||
         error.code === 'AUTH_FORBIDDEN'
       ) {
-        return { check: { name, status: 'fail', detail: `API key rejected (${error.code})` } };
+        return {
+          check: { name, status: 'fail', detail: `API key rejected (${error.code})` },
+          reachedApi: true,
+        };
+      }
+      // A named transport failure never reached the API (TLS interception, DNS,
+      // refused port, proxy block page). Print its actual cause instead of a
+      // bare UNAVAILABLE code, and let the tunnel check know not to blame the
+      // endpoint for a request that never arrived.
+      if (isTransportFailure(error)) {
+        return {
+          check: { name, status: 'fail', detail: `GET /me failed: ${error.message}` },
+          reachedApi: false,
+        };
       }
-      return { check: { name, status: 'fail', detail: `GET /me failed (${error.code})` } };
+      return {
+        check: { name, status: 'fail', detail: `GET /me failed (${error.code})` },
+        // A fetch rejection is a TransportError with no HTTP status. Local
+        // validation errors (e.g. a malformed key) are not transport failures:
+        // rerunning the tunnel check surfaces the same local error instead of
+        // hiding it behind a skip. An edge 502/504 carries its status.
+        reachedApi: !(error instanceof TransportError) || error.httpStatus !== undefined,
+      };
     }
     return {
       check: {
         name,
         status: 'fail',
         detail: `GET /me failed (${error instanceof Error ? error.message : String(error)})`,
       },
+      reachedApi: false,
     };
   }
 }
@@ -357,12 +394,21 @@ async function checkConnectivity(
 async function checkLocalTunnel(
   opts: CommonOptions,
   deps: DoctorDeps,
-  ctx: { hasKey: boolean; endpointOk: boolean; config: Config },
+  ctx: { hasKey: boolean; endpointOk: boolean; config: Config; reachedApi: boolean },
 ): Promise<DoctorCheck> {
   const name = 'Local tunnel';
   if (opts.dryRun) return { name, status: 'warn', detail: 'skipped under --dry-run' };
   if (!ctx.hasKey) return { name, status: 'warn', detail: 'skipped; no API key to test with' };
   if (!ctx.endpointOk) return { name, status: 'warn', detail: 'skipped; endpoint URL is invalid' };
+  // If GET /me never reached the API, this probe cannot reach it either. The
+  // old fall-through blamed the endpoint for not supporting tunnels — a
+  // misleading diagnosis of a TLS/DNS/proxy failure. Say what happened instead.
+  if (!ctx.reachedApi)
+    return {
+      name,
+      status: 'warn',
+      detail: 'skipped; the connectivity check did not reach TestSprite',
+    };
 
   const controller = new AbortController();
   const shutdownSignal = deps.shutdownSignal ?? globalShutdown.signal;

src/lib/errors.ts

@@ -418,16 +418,34 @@ export function localValidationError(
  * Network/transport failure not associated with a server envelope. Treated
  * as `UNAVAILABLE` for exit-code purposes per design §8.2.
  */
+export interface TransportErrorOptions {
+  /** Cause-specific remediation; falls back to the generic availability text. */
+  nextAction?: string;
+  /**
+   * Machine-readable cause, e.g. `{ reason: 'tls_untrusted', cause:
+   * 'UNABLE_TO_VERIFY_LEAF_SIGNATURE' }`. Every transport failure names what
+   * went wrong so `--output json` consumers and `doctor` can tell a TLS trust
+   * problem from a DNS typo or a proxy block page.
+   */
+  details?: Record<string, unknown>;
+  /** HTTP status when a response did arrive (e.g. an edge 502/504). */
+  httpStatus?: number;
+}
+
 export class TransportError extends ApiError {
-  constructor(message: string, requestId = 'local') {
-    super({
-      code: 'UNAVAILABLE',
-      message,
-      nextAction:
-        'Service is temporarily unavailable. The CLI retries with exponential backoff; if this persists, report it.',
-      requestId,
-      details: {},
-    });
+  constructor(message: string, requestId = 'local', options: TransportErrorOptions = {}) {
+    super(
+      {
+        code: 'UNAVAILABLE',
+        message,
+        nextAction:
+          options.nextAction ??
+          'Service is temporarily unavailable. The CLI retries with exponential backoff; if this persists, report it.',
+        requestId,
+        details: options.details ?? {},
+      },
+      options.httpStatus,
+    );
     this.name = 'TransportError';
   }
 }