Corporate proxy support + network errors that tell you what happened

[jpbelmo]

The CLI's first-run audit found its most likely abandonment point, and it's not detection: it's login behind a corporate proxy. Exactly our primary user (a developer on managed IT, NDA repo) is the one most likely to hit it.

Today:

• src/http-client.ts uses bare fetch, and Node's fetch ignores HTTP_PROXY/HTTPS_PROXY env vars entirely. Behind a mandatory proxy, every request fails at connect.
• TLS-intercepting proxies (corporate CA) work only if the user already knows about NODE_EXTRA_CA_CERTS, which our docs never mention.
• Every network failure (proxy, DNS, TLS interception, refused connection) collapses into the same message: Could not reach <host>. The cause is discarded on purpose so we never leak token material into errors, and that constraint stays. But cause-free means undiagnosable.

The work, likely 2-3 PRs:

1. Honor HTTP_PROXY/HTTPS_PROXY/NO_PROXY via undici's ProxyAgent (no new dependency: undici ships inside Node). Login/submit only; scan has no network by design and never will.
2. Differentiated error messages that name the failure class without echoing anything sensitive: "connection refused", "could not verify TLS certificate (corporate proxy? see docs)", "proxy required". Stack traces stay banned; token material stays out.
3. A short docs/corporate-networks.md: proxy env vars, NODE_EXTRA_CA_CERTS, and the submit visibility-probe edge where a captive proxy answers 200 for everything.

Touches network code, so the privacy gate and reviewer pass apply, and test/privacy/zero-network.test.ts must stay green (the proxy agent may only exist inside the login/submit allowlist). @rudi193-cmd this smells like your kind of plumbing if you want it; open to anyone otherwise, pick a slice and comment.

[rudi193-cmd]

Claiming slice 1: honor HTTP_PROXY / HTTPS_PROXY / NO_PROXY for the login/submit path only.

Looked at the current client before writing anything:

• Every outbound call already funnels through src/http-client.ts (postJson, postRawJson, pollJson, postJsonStatusOnly, headRequest, getJson). Node's global fetch is used bare; the catch {} on connect failures is where the cause is discarded, so a mandatory proxy looks identical to DNS/TLS/refused.
• test/privacy/zero-network.test.ts allowlists only http-client.ts, login.ts, and submit.ts. The proxy agent has to live inside http-client.ts — importing undici (or node:http/node:https) from login/submit/scan would fail that static check, and scan must keep zero network.
• headRequest / getJson are fail-open (null on any error). They still need the dispatcher so a visibility probe or version check can actually reach the host behind a proxy; they should stay fail-open, not grow new error strings. Slice 2 is the thrown NetworkError path.

Plan for the first PR, nothing else:

1. One dispatcher for the module, built from env via undici's EnvHttpProxyAgent (ships with Node; no new package). Attach it as dispatcher on every fetch in this file. Empty proxy env → same as today (no agent).
2. Tests that: with HTTP_PROXY set, fetch is invoked with a dispatcher; with it unset, it isn't; test/privacy/zero-network.test.ts stays green; scan still never constructs an agent.
3. No error-string rewrite and no new doc file in this PR. Those are slices 2 and 3, after this lands so the failure classes are real instead of guessed.

Will open that PR after this comment, unless someone wants a different split.

[jpbelmo]

Claim yours, and the analysis is exactly right: single dispatcher inside http-client.ts, the allowlist forces that shape, headRequest/getJson stay fail-open, slices 2-3 wait for real failure classes. One correction, and the mistake is mine in the issue body: on Node 20/22, undici's classes are NOT importable without adding the package. It ships inside Node but doesn't expose ProxyAgent/EnvHttpProxyAgent, and Node's native env-proxy flag only exists in 24, above our floor. I checked on 22.5.1 before writing this.

So slice 1 needs the repo's written-justification ritual for a new dependency, and this one clears the bar honestly: undici is the reference fetch implementation maintained by the Node.js core team, the exact code already running inside every supported Node, zero install scripts. Pin an exact version, paste the justification block in the PR body, and the rest of your plan stands as written. The alternative (hand-rolling CONNECT tunneling over node:http) is more security-sensitive code for less correctness, so don't.

Same design, one honest dependency. Go.

[rudi193-cmd]

Slice 1 is up: #84

Pinned undici@6.28.0 (exact) with the written justification in the PR body. EnvHttpProxyAgent only when a proxy env var is set; import confined to http-client.ts. Slices 2–3 stay out.

[rudi193-cmd]

Claiming slices 2 and 3 (jpbelmo on #84: whenever).

Slice 2 — thrown NetworkError path only (postJson / postRawJson / pollJson / postJsonStatusOnly catch). Classify from error.code / cause.code (and 407), never from error.message / headers / body:

• TLS/cert codes → could not verify TLS certificate (corporate proxy? see docs/corporate-networks.md)
• ECONNREFUSED with no proxy env → proxy required (mandatory-proxy networks look like refused-on-connect)
• ECONNREFUSED with proxy env set, or UND_ERR_PROXY / HTTP 407 → connection refused / proxy required as fits
• anything else stays Could not reach <host>.

headRequest / getJson stay fail-open. Stack traces stay banned.

Slice 3 — docs/corporate-networks.md: proxy env vars, NODE_EXTRA_CA_CERTS, and the submit visibility-probe edge where a captive proxy answers 200 for everything.

Landing on #84 so it sits on the dispatcher that makes these classes real.