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

## 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

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: BYK

AGENTS.md

@@ -77,6 +77,7 @@ If you pass a self-hosted Sentry URL as a command argument (e.g., an issue or ev
 | `SENTRY_FORCE_ENV_TOKEN` | Force env token over stored OAuth token |
 | `SENTRY_ORG` | Default organization slug |
 | `SENTRY_PROJECT` | Default project slug (supports `org/project` format) |
+| `NODE_EXTRA_CA_CERTS` | Path to PEM file with additional CA certificates (for corporate proxies) |
 <!-- GENERATED:END self-hosted-env-vars -->
 
 See [Configuration](./configuration/) for the full environment variable reference.

docs/src/content/docs/self-hosted.md

@@ -362,6 +362,10 @@ const SELF_HOSTED_TABLE_ENTRIES: readonly [string, string][] = [
   ["SENTRY_FORCE_ENV_TOKEN", "Force env token over stored OAuth token"],
   ["SENTRY_ORG", "Default organization slug"],
   ["SENTRY_PROJECT", "Default project slug (supports `org/project` format)"],
+  [
+    "NODE_EXTRA_CA_CERTS",
+    "Path to PEM file with additional CA certificates (for corporate proxies)",
+  ],
 ];
 
 /**

script/generate-docs-sections.ts

@@ -3,26 +3,31 @@
  *
  * View and manage persistent CLI default settings.
  *
- * Supports four defaults:
+ * Supports these defaults:
  * - `org` / `organization` — default organization slug
  * - `project` — default project slug
  * - `telemetry` — telemetry preference (on/off)
  * - `url` — Sentry instance URL (for self-hosted)
+ * - `ca-cert` — path to PEM file with custom CA certificates
  */
 
+import { resolve } from "node:path";
 import type { SentryContext } from "../../context.js";
 import { buildCommand } from "../../lib/command.js";
 import { normalizeUrl } from "../../lib/constants.js";
+import { readCaCertFile } from "../../lib/custom-ca.js";
 import { parseCustomHeaders } from "../../lib/custom-headers.js";
 import {
   clearAllDefaults,
   type DefaultsState,
   getAllDefaults,
+  getDefaultCaCert,
   getDefaultHeaders,
   getDefaultOrganization,
   getDefaultProject,
   getDefaultUrl,
   getTelemetryPreference,
+  setDefaultCaCert,
   setDefaultHeaders,
   setDefaultOrganization,
   setDefaultProject,
@@ -47,7 +52,13 @@ import { computeTelemetryEffective } from "../../lib/telemetry.js";
 // ---------------------------------------------------------------------------
 
 /** Canonical key names matching DefaultsState fields */
-type DefaultKey = "organization" | "project" | "telemetry" | "url" | "headers";
+type DefaultKey =
+  | "organization"
+  | "project"
+  | "telemetry"
+  | "url"
+  | "headers"
+  | "ca-cert";
 
 /** Handler for reading, writing, and clearing a single default */
 type DefaultHandler = {
@@ -131,6 +142,25 @@ const DEFAULTS_REGISTRY: Record<DefaultKey, DefaultHandler> = {
     },
     clear: () => setDefaultHeaders(null),
   },
+  "ca-cert": {
+    get: getDefaultCaCert,
+    set: (value) => {
+      const trimmed = value.trim();
+      if (!trimmed) {
+        throw new ValidationError(
+          "CA certificate path cannot be empty.",
+          "ca-cert"
+        );
+      }
+      const resolved = resolve(trimmed);
+      const result = readCaCertFile(resolved);
+      if (!result.ok) {
+        throw new ValidationError(result.reason, "ca-cert");
+      }
+      setDefaultCaCert(resolved);
+    },
+    clear: () => setDefaultCaCert(null),
+  },
 };
 
 // ---------------------------------------------------------------------------
@@ -140,6 +170,9 @@ const DEFAULTS_REGISTRY: Record<DefaultKey, DefaultHandler> = {
 /** Shorthand aliases for canonical keys (e.g., "org" → "organization") */
 const KEY_ALIASES: Partial<Record<string, DefaultKey>> = {
   org: "organization",
+  ca: "ca-cert",
+  cert: "ca-cert",
+  "ca-certs": "ca-cert",
 };
 
 /** Resolve a user-provided key string to a canonical key, or null if unknown */
@@ -196,6 +229,7 @@ export const defaultsCommand = buildCommand({
       "sentry cli defaults telemetry off      # Disable telemetry\n" +
       "sentry cli defaults url https://...    # Set Sentry URL (self-hosted)\n" +
       "sentry cli defaults headers 'X-IAP: t'  # Set custom headers (self-hosted)\n" +
+      "sentry cli defaults ca-cert /path/to/ca.pem  # Trust a custom CA certificate\n" +
       "sentry cli defaults org --clear        # Clear a specific default\n" +
       "sentry cli defaults --clear --yes      # Clear all defaults\n" +
       "```\n\n" +
@@ -206,7 +240,8 @@ export const defaultsCommand = buildCommand({
       "| `project` | Default project slug |\n" +
       "| `telemetry` | Telemetry preference (on/off, yes/no, true/false, 1/0) |\n" +
       "| `url` | Sentry instance URL (for self-hosted installations) |\n" +
-      "| `headers` | Custom HTTP headers for self-hosted proxies (semicolon-separated `Name: Value`) |",
+      "| `headers` | Custom HTTP headers for self-hosted proxies (semicolon-separated `Name: Value`) |\n" +
+      "| `ca-cert` | Path to PEM file with custom CA certificates (for corporate proxies) |",
   },
   output: {
     human: formatDefaultsResult,
@@ -260,7 +295,7 @@ export const defaultsCommand = buildCommand({
         guardNonInteractive(flags);
         if (!isConfirmationBypassed(flags)) {
           const confirmed = await log.prompt(
-            "This will clear all defaults (organization, project, telemetry, URL, headers). Continue?",
+            "This will clear all defaults (organization, project, telemetry, URL, headers, ca-cert). Continue?",
             { type: "confirm" }
           );
           if (confirmed !== true) {