fix(tls): support custom CA certificates for corporate proxies (CLI-1K6)

[BYK]

Summary

• Add custom CA certificate support so the CLI works behind corporate TLS-intercepting proxies (CLI-1K6)
• Bun's fetch() doesn't honor NODE_EXTRA_CA_CERTS natively — we now read it and pass CA certs via Bun's fetch({ tls: { ca } }) option
• On Node 24+, call tls.setDefaultCACertificates() to inject CAs into the process-wide trust store
• Add sentry cli defaults ca-cert for persistent CA registration that also silences the SaaS security warning

Details

Root cause

Users behind corporate TLS proxies (Zscaler, Netskope, Palo Alto) get Error: unable to get local issuer certificate because Bun uses BoringSSL with Mozilla's compiled-in CA bundle and doesn't read NODE_EXTRA_CA_CERTS or the OS certificate store.

Fix

New src/lib/custom-ca.ts module reads CA certs from (in priority order):

1. sentry cli defaults ca-cert (stored in SQLite)
2. NODE_EXTRA_CA_CERTS env var

Custom CAs are concatenated with tls.rootCertificates (Mozilla's built-in bundle) to preserve additive semantics — only adding CAs, never replacing the default bundle.

Runtime behavior:

Runtime	Mechanism
Bun (compiled binary)	fetch({ tls: { ca: combined } }) — Bun-specific option
Node 24+ (npm)	tls.setDefaultCACertificates([...rootCerts, custom]) — process-wide
Node 22 (npm)	NODE_EXTRA_CA_CERTS handled natively by Node; defaults ca-cert requires Node 24+

PEM validation logic is shared via readCaCertFile() — used by both the eager validation in sentry cli defaults ca-cert and the lazy loading at fetch time.

Security model

When custom CAs come from env vars (not stored defaults) AND the target is *.sentry.io, a one-time log.warn() fires. This creates a forensic trail in CI logs — an attacker who can set env vars in a CI step could inject a rogue CA + proxy to intercept tokens. sentry cli defaults ca-cert silences the warning (user has acknowledged). See plan file for the full threat model discussion.

Error handling improvements

• TLS cert errors are detected by pattern (walking error.cause chain with cycle detection for Node.js's TypeError: fetch failed wrapper) and wrapped in ApiError
• buildTlsErrorDetail() is shared between both fetch paths and branches on whether custom CAs are already loaded
• TLS errors are not retried (deterministic)
• Only CA trust errors are matched (not CERT_HAS_EXPIRED or hostname mismatches which need different guidance)

Changes

File	Change
src/lib/custom-ca.ts	New — CA loading, readCaCertFile, buildTlsErrorDetail, isTlsCertError, Node 24+ injection, SaaS warning
src/lib/sentry-client.ts	Wire custom TLS into fetchWithTimeout, TLS error handling
src/lib/oauth.ts	Wire custom TLS into OAuth fetch, TLS error handling
src/lib/db/defaults.ts	Add defaults.ca-cert key
src/commands/cli/defaults.ts	Add ca-cert handler with aliases, eager PEM validation
src/lib/formatters/human.ts	Add "ca-cert": "CA Certificate" to defaults display
src/lib/env-registry.ts	Register NODE_EXTRA_CA_CERTS
script/generate-docs-sections.ts	Add env var to self-hosted docs table
test/lib/custom-ca.test.ts	New — 24 tests

Fixes CLI-1K6

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://cli.sentry.dev/_preview/pr-901/
Built to branch gh-pages at 2026-05-01 18:45 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[github-actions]

Codecov Results 📊

✅ 6521 passed | Total: 6521 | Pass Rate: 100% | Execution Time: 0ms

📊 Comparison with Base Branch

Metric	Change
Total Tests	📈 +24
Passed Tests	📈 +24
Failed Tests	—
Skipped Tests	—

All tests are passing successfully.

❌ Patch coverage is 72.22%. Project has 13305 uncovered lines.
✅ Project coverage is 76.05%. Comparing base (base) to head (head).

Files with missing lines (5)

File	Patch %	Lines
src/lib/custom-ca.ts	79.73%	⚠️ 30 Missing
src/commands/cli/defaults.ts	41.67%	⚠️ 14 Missing
src/lib/oauth.ts	52.17%	⚠️ 11 Missing
src/lib/sentry-client.ts	47.06%	⚠️ 9 Missing
src/lib/db/defaults.ts	92.31%	⚠️ 1 Missing

Coverage diff

@@            Coverage Diff             @@
##          main       #PR       +/-##
==========================================
+ Coverage    75.99%    76.05%    +0.06%
==========================================
  Files          295       296        +1
  Lines        55386     55555      +169
  Branches         0         0         —
==========================================
+ Hits         42090     42250      +160
- Misses       13296     13305        +9
- Partials         0         0         —

---

Generated by Codecov Action

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 1e6603a. Configure here.}