feat(net): support a custom corporate root CA for all outbound connections (#134)

## What / why

Corporate and TLS-inspection networks terminate TLS with a private root
CA that
is not in the public trust store, so every outbound HTTPS connection
Driven
makes fails behind them. This adds an optional **`custom_root_ca_path`**
global
setting (a PEM file that may hold multiple certs) whose certificates are
added
to the system trust store for **all** outbound HTTP clients. Empty/unset
= system
trust only (unchanged behaviour). Implements item 14 ("Corporate CA
pinning") of
the V2 backlog, #34 (which DESIGN s5.8.7 had deferred).

## Trust semantics (the security boundary)

- **Additive, and that is the whole security boundary.** The CA is
*added* on top
of the OS/enterprise native roots via `add_root_certificate`; it never
replaces
them. Source-verified in both reqwest versions in the tree: 0.12
populates one
`RootCertStore` with native + custom roots
(`async_impl/client.rs:687-714`);
  0.13 (the updater plugin) uses
`rustls_platform_verifier::Verifier::new_with_extra_roots(extra,
platform)`
(`async_impl/client.rs:756-769`). Because it is purely additive,
*failing to
apply the CA can only make a connection stricter, never weaker* - so the
security boundary is entirely "additive + no verification bypass",
nothing else.
- **No verification bypass anywhere.** No `danger_accept_invalid_certs`,
no
`tls_built_in_root_certs(false)` / `tls_certs_only`, no
hostname-verification
disable. Grep-verified; the one helper crate (`driven-tls`) documents
this as a
  locked invariant at the call site.
- **A configured-but-bad PEM fails the client build** (missing /
unreadable /
unparseable / zero certs). This is a UX/correctness choice, not the
security
boundary (additive trust cannot fail *open*): we would rather surface a
broken
corporate-CA config than silently make requests the proxy will reject
anyway.
Save-time validation (below) stops a broken path being persisted in the
first
place. Note the best-effort paths (telemetry ping, Google userinfo, and
the
updater when AppState is unavailable) deliberately *proceed without* on
a load
error / missing state rather than hard-fail - they cannot weaken trust,
so this
  is a functionality edge case, not a fail-open.

## The one shared helper + the 10 outbound sites

New leaf crate **`driven-tls`** (depends only on `reqwest` +
`thiserror`) hosts
`apply_custom_ca(builder, &CustomCaConfig)` plus `load_certificates` /
`validate_ca_file`. It is a leaf because `driven-drive` is itself a leaf
that
`driven-core` depends on, so no pre-existing crate could host a helper
reachable
by all HTTP-using crates without a cycle.

The 9 reqwest build sites from the seams audit, each threaded via
constructor/param
following that crate's existing config style:

| # | Site | How it gets the CA |
|---|------|--------------------|
| 1 | captive-portal probe (`driven-net`) | `ReqwestBackend::new(ca)`
stores it; rebuilt on pool teardown |
| 2 | per-service probe (`driven-net`) | same |
| 3 | OAuth refresh client (`driven-drive` token_store) |
`from_stored_refresh_token(.., &ca)` |
| 4 | OAuth PKCE consent exchange (`driven-drive` oauth) |
`run_pkce_loopback_flow(.., &ca)` |
| 5 | Drive metadata client (`driven-drive`) |
`with_default_clients(tokens, &ca)` / `new(.., &ca)` |
| 6 | Drive stream client (`driven-drive`) | same |
| 7 | telemetry sink (`src-tauri`) | `HttpTelemetrySink::new(ca)`,
resolved once at boot |
| 8 | Google userinfo fetch (`src-tauri` accounts) | loaded per
add-account command |
| 9 | GitHub-releases update check (`src-tauri` settings) | loaded per
check/list command |

Plus a **10th** path the seams list did not cover and the advisor
flagged as the
one that matters most in a TLS-inspecting environment:
**tauri-plugin-updater's
own download client** (the signed manifest + binary fetch). The plugin
is on
reqwest **0.13** (workspace + `driven-tls` are 0.12), so it is wired
through the
plugin's `configure_client` hook using an aliased 0.13 `reqwest_updater`
dep
(already in the tree via the plugin) - the fallible PEM parse happens
first in
`run_check` (fail-closed), then the pre-parsed certs are added inside
the
infallible closure.

A hidden-constructor grep (`Client::new()` / `reqwest::get` /
`Client::default()`)
found no other outbound clients.

## Restart vs hot-reload

Applied **when each client is built**. Long-lived clients (Drive
metadata/stream,
OAuth refresh, network probes, telemetry sink) are built once at account
assembly
/ boot, so a CA change takes effect when the account is next assembled -
in
practice an **app restart** (the live `reconfigure_all` path only
re-applies
pacer/gates, it does not rebuild these clients). The per-operation
clients (OAuth
consent, userinfo, releases check, updater) rebuild each call and pick
up the
current setting on next use. The UI caption states "applies to new
connections
after an app restart".

## Settings UI + validation

- `GlobalSettings.custom_root_ca_path: Option<PathBuf>` (storage
`#[serde(default)]`
  for back-compat), DTO + patch (double-option) + TS mirrors.
- New `validate_custom_ca(path)` IPC command parses the PEM and returns
the cert
count or a parse error, for inline save-time feedback. `update_settings`
also
validates on save, so a broken path cannot be persisted; a blank path
clears
  the setting.
- Rules-tab input with live cert-count / error feedback.

Reviewer note: `validate_custom_ca` (and the build-time re-read) read a
plain,
user-typed **persisted** path rather than going through the app's
dialog-token
confinement model. This is intentional and low-risk: a CA path is an
inherently
user-supplied setting, and the command returns only a cert count / parse
status,
never file contents.

## Tests

- `driven-tls`: unit tests for `apply_custom_ca` / `validate_ca_file` -
valid
single cert, multi-cert bundle, garbage (-> `NoCertificates`), missing
(->
`Read`), corrupt-body PEM, and the `None` no-op. (Additivity itself
rests on the
reqwest source read above - it needs a live handshake to test, so it is
  asserted by source + the locked invariant comment, not a unit test.)
- `driven-drive`: fail-closed wiring test (bad CA -> refresh-client
build fails).
- `src-tauri`: `normalize_ca_path`, `storage::Global` serde back-compat
(pre-field
blob -> `None`), and the `validate_custom_ca` command (cert count /
blank /
  garbage).
- UI: three Settings.vue vitest cases (valid -> validate+save+count,
invalid ->
  no save + error, clear -> null patch).
- Gates: `cargo fmt --check`, `clippy --workspace --all-targets -D
warnings`,
per-crate `cargo test` (driven-tls/net/drive/app), `cargo check
--workspace`;
`pnpm lint` (0 errors), `vue-tsc`, `prettier --check`, `vitest` (265
pass).

Part of #34 (does not close the tracking epic).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: pmaxhogan

Cargo.lock

@@ -8,6 +8,7 @@ members = [
     "crates/driven-vss",
     "crates/driven-vss-helper",
     "crates/driven-net",
+    "crates/driven-tls",
     "crates/driven-cli",
     "crates/driven-test-fixtures",
     "crates/driven-chaos",

Cargo.toml

@@ -33,6 +33,7 @@ use driven_drive::google::oauth::{run_pkce_loopback_flow, OAuthProgress};
 use driven_drive::google::token_store::{KeyringTokenStore, RefreshingTokenSource};
 use driven_drive::google::{md5_hex, parse_installed_client_config, GoogleDriveStore, UploadBytes};
 use driven_drive::remote_store::{RemoteStore, UploadBody};
+use driven_drive::CustomCaConfig;
 
 /// The public installed-app client id (SPEC s4; M4 brief). Used when neither
 /// `--client-id`, the env var, nor `client_secret.json` supplies one.
@@ -265,6 +266,7 @@ async fn run_auth(args: AuthArgs) -> anyhow::Result<()> {
         &creds.client_secret,
         open_system_browser,
         tx,
+        &cli_custom_ca(),
     )
     .await?;
 
@@ -399,19 +401,51 @@ fn build_store(account: &str, creds: &ClientCreds) -> anyhow::Result<GoogleDrive
             "no refresh token stored for account '{account}'; run `driven-cli auth --account {account}` first"
         )
     })?;
+    let ca = cli_custom_ca();
     let token_source = RefreshingTokenSource::from_stored_refresh_token(
         refresh_token,
         creds.client_id.clone(),
         creds.client_secret.clone(),
+        &ca,
     )?
     .with_store(store);
-    GoogleDriveStore::with_default_clients(token_source)
+    GoogleDriveStore::with_default_clients(token_source, &ca)
+}
+
+/// Issue #34: the dev/e2e CLI reads its custom root CA (if any) from the
+/// `DRIVEN_CUSTOM_CA_PATH` env var so it can run behind the same corporate
+/// TLS-inspecting proxy the desktop app supports via its settings. Unset =
+/// system trust only (unchanged behaviour).
+fn cli_custom_ca() -> CustomCaConfig {
+    match std::env::var_os("DRIVEN_CUSTOM_CA_PATH") {
+        Some(v) if !v.is_empty() => CustomCaConfig::from_path(Some(PathBuf::from(v))),
+        _ => CustomCaConfig::none(),
+    }
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
 
+    #[test]
+    fn cli_custom_ca_reads_the_env_var() {
+        // Issue #34: the dev CLI resolves its custom root CA from
+        // DRIVEN_CUSTOM_CA_PATH (unset / blank = system trust only). No other
+        // test touches this env var, so the set/remove here does not race.
+        std::env::remove_var("DRIVEN_CUSTOM_CA_PATH");
+        assert!(!cli_custom_ca().is_enabled(), "unset = system trust only");
+
+        std::env::set_var("DRIVEN_CUSTOM_CA_PATH", "");
+        assert!(!cli_custom_ca().is_enabled(), "blank = system trust only");
+
+        std::env::set_var("DRIVEN_CUSTOM_CA_PATH", "/etc/corp/ca.pem");
+        let ca = cli_custom_ca();
+        assert!(ca.is_enabled());
+        assert_eq!(ca.path(), Some(Path::new("/etc/corp/ca.pem")));
+
+        std::env::remove_var("DRIVEN_CUSTOM_CA_PATH");
+    }
+
     #[test]
     fn resolve_creds_prefers_explicit_args() {
         let creds = resolve_creds(

crates/driven-cli/src/main.rs

@@ -29,6 +29,10 @@ uuid.workspace = true
 oauth2.workspace = true
 keyring.workspace = true
 reqwest.workspace = true
+# Issue #34 corporate CA pinning: threads a user-configured custom root CA into
+# the Drive metadata/stream clients, the OAuth refresh client, and the PKCE
+# consent-exchange client (additive; see driven-tls).
+driven-tls = { path = "../driven-tls" }
 url.workspace = true
 hex.workspace = true
 # Direct deps (not yet in workspace.dependencies). parking_lot for an

crates/driven-drive/Cargo.toml

@@ -49,6 +49,7 @@ use std::time::Duration;
 
 use async_trait::async_trait;
 use bytes::Bytes;
+use driven_tls::CustomCaConfig;
 use futures::Stream;
 use serde::Deserialize;
 use tokio::io::{AsyncRead, ReadBuf};
@@ -532,12 +533,14 @@ impl GoogleDriveStore {
     /// flows over (the caller builds it with the DESIGN s5.8.4 metadata
     /// timeouts). A second, no-overall-timeout streaming client is derived
     /// for the resumable chunk PUT + download paths.
-    pub fn new(http: reqwest::Client, tokens: RefreshingTokenSource) -> Self {
+    pub fn new(http: reqwest::Client, tokens: RefreshingTokenSource, ca: &CustomCaConfig) -> Self {
         let _ = TARGET;
-        // The streaming client mirrors `http`'s TLS/proxy config but drops
-        // the overall request cap; if the dedicated build fails we fall back
-        // to the provided client (correctness over a missing idle timeout).
-        let http_stream = build_stream_client().unwrap_or_else(|e| {
+        // The streaming client mirrors `http`'s TLS/proxy config (including the
+        // issue #34 custom root CA via `ca`) but drops the overall request cap;
+        // if the dedicated build fails we fall back to the provided client
+        // (correctness over a missing idle timeout - `http` already carries the
+        // same additive CA trust).
+        let http_stream = build_stream_client(ca).unwrap_or_else(|e| {
             warn!(
                 target: TARGET,
                 error = %e,
@@ -557,9 +560,12 @@ impl GoogleDriveStore {
     /// clients (DESIGN s5.8.4 timeouts) from a [`RefreshingTokenSource`].
     /// Convenience for the CLI / e2e paths that do not already hold a tuned
     /// client.
-    pub fn with_default_clients(tokens: RefreshingTokenSource) -> anyhow::Result<Self> {
-        let http = build_meta_client()?;
-        let http_stream = build_stream_client()?;
+    pub fn with_default_clients(
+        tokens: RefreshingTokenSource,
+        ca: &CustomCaConfig,
+    ) -> anyhow::Result<Self> {
+        let http = build_meta_client(ca)?;
+        let http_stream = build_stream_client(ca)?;
         Ok(Self {
             http,
             http_stream,
@@ -1621,26 +1627,31 @@ impl GoogleDriveStore {
 // Free helpers.
 // ---------------------------------------------------------------------------
 
-/// Builds the metadata Drive client with the DESIGN s5.8.4 timeouts.
-pub(crate) fn build_meta_client() -> anyhow::Result<reqwest::Client> {
-    reqwest::Client::builder()
+/// Builds the metadata Drive client with the DESIGN s5.8.4 timeouts. `ca` adds
+/// the user's custom root CA (issue #34) additively; fail-closed if it cannot be
+/// loaded.
+pub(crate) fn build_meta_client(ca: &CustomCaConfig) -> anyhow::Result<reqwest::Client> {
+    let builder = reqwest::Client::builder()
         .connect_timeout(CONNECT_TIMEOUT)
         .timeout(META_TOTAL_TIMEOUT)
         .read_timeout(STREAM_IDLE_TIMEOUT)
         .pool_max_idle_per_host(4)
-        .pool_idle_timeout(Duration::from_secs(90))
+        .pool_idle_timeout(Duration::from_secs(90));
+    driven_tls::apply_custom_ca(builder, ca)?
         .build()
         .map_err(|e| anyhow::anyhow!("drive: failed to build metadata client: {e}"))
 }
 
 /// Builds the streaming Drive client (resumable chunk PUT + download): no
 /// overall request cap, only the per-byte idle timeout (DESIGN s5.8.4 `*`).
-pub(crate) fn build_stream_client() -> anyhow::Result<reqwest::Client> {
-    reqwest::Client::builder()
+/// `ca` adds the user's custom root CA (issue #34) additively; fail-closed.
+pub(crate) fn build_stream_client(ca: &CustomCaConfig) -> anyhow::Result<reqwest::Client> {
+    let builder = reqwest::Client::builder()
         .connect_timeout(CONNECT_TIMEOUT)
         .read_timeout(STREAM_IDLE_TIMEOUT)
         .pool_max_idle_per_host(4)
-        .pool_idle_timeout(Duration::from_secs(90))
+        .pool_idle_timeout(Duration::from_secs(90));
+    driven_tls::apply_custom_ca(builder, ca)?
         .build()
         .map_err(|e| anyhow::anyhow!("drive: failed to build streaming client: {e}"))
 }
@@ -1861,6 +1872,47 @@ pub(crate) fn clone_kind(kind: &ResumableKind) -> ResumableKind {
 mod tests {
     use super::*;
 
+    #[test]
+    fn google_store_new_builds_a_stream_client_with_the_ca() {
+        // Issue #34: `GoogleDriveStore::new` derives its streaming client via
+        // `build_stream_client(ca)` (here `none`, offline). Covers the ctor +
+        // stream-client build path without a network/keychain dependency.
+        let tokens = crate::google::oauth::Tokens {
+            access_token: String::new(),
+            refresh_token: "rt".to_string(),
+            expires_at: 0,
+        };
+        let http = build_meta_client(&CustomCaConfig::none()).expect("meta client");
+        let source = RefreshingTokenSource::new(tokens, http, "cid", "secret");
+        let store = GoogleDriveStore::new(
+            build_meta_client(&CustomCaConfig::none()).expect("meta client"),
+            source,
+            &CustomCaConfig::none(),
+        );
+        // The streaming client is a distinct, usable handle (no panic on build).
+        let _ = store.http_stream();
+    }
+
+    #[test]
+    fn drive_clients_apply_custom_ca_fail_closed() {
+        // Issue #34: the Drive metadata + stream clients add the custom CA
+        // additively and fail closed on a bad one; `None` builds normally.
+        let none = CustomCaConfig::none();
+        assert!(build_meta_client(&none).is_ok(), "no-CA meta client builds");
+        assert!(
+            build_stream_client(&none).is_ok(),
+            "no-CA stream client builds"
+        );
+        let bad = CustomCaConfig::from_path(Some(std::path::PathBuf::from(
+            "/driven/no/such/drive-ca.pem",
+        )));
+        assert!(build_meta_client(&bad).is_err(), "bad CA fails meta build");
+        assert!(
+            build_stream_client(&bad).is_err(),
+            "bad CA fails stream build"
+        );
+    }
+
     #[test]
     fn rfc3339_parses_to_unix_ms() {
         // 2024-01-01T00:00:00Z == 1704067200000 ms.

crates/driven-drive/src/google/mod.rs

@@ -24,6 +24,7 @@
 use std::net::{Ipv4Addr, Ipv6Addr, SocketAddr};
 use std::time::Duration;
 
+use driven_tls::CustomCaConfig;
 use oauth2::basic::BasicClient;
 use oauth2::{
     AuthUrl, AuthorizationCode, ClientId, ClientSecret, CsrfToken, PkceCodeChallenge, RedirectUrl,
@@ -116,6 +117,7 @@ pub async fn run_pkce_loopback_flow(
     client_secret: &str,
     open_browser: impl FnOnce(&str) -> anyhow::Result<()>,
     progress_tx: Sender<OAuthProgress>,
+    ca: &CustomCaConfig,
 ) -> anyhow::Result<Tokens> {
     let (listener_v4, listener_v6, port) = bind_dual_loopback().await?;
     // The redirect URI we register with Google MUST be one literal string and
@@ -130,11 +132,13 @@ pub async fn run_pkce_loopback_flow(
     // SPEC s4 / oauth2 v5 upgrade notes) with bounded connect/total timeouts
     // (DESIGN s5.8.4; codex V-A1) so a hung token endpoint cannot stall the
     // code exchange indefinitely.
-    let http = reqwest::Client::builder()
+    let http_builder = reqwest::Client::builder()
         .redirect(reqwest::redirect::Policy::none())
         .connect_timeout(EXCHANGE_CONNECT_TIMEOUT)
-        .timeout(EXCHANGE_TOTAL_TIMEOUT)
-        .build()?;
+        .timeout(EXCHANGE_TOTAL_TIMEOUT);
+    // Issue #34: add the user's custom root CA additively (fail-closed) so the
+    // token exchange works behind a corporate TLS-inspecting proxy.
+    let http = driven_tls::apply_custom_ca(http_builder, ca)?.build()?;
 
     let client = BasicClient::new(ClientId::new(client_id.to_string()))
         .set_client_secret(ClientSecret::new(client_secret.to_string()))

crates/driven-drive/src/google/oauth.rs

@@ -34,6 +34,7 @@
 use std::sync::Arc;
 use std::time::Duration;
 
+use driven_tls::CustomCaConfig;
 use keyring::Entry;
 use serde::Deserialize;
 use tokio::sync::Mutex;
@@ -324,8 +325,9 @@ impl RefreshingTokenSource {
         refresh_token: impl Into<String>,
         client_id: impl Into<String>,
         client_secret: impl Into<String>,
+        ca: &CustomCaConfig,
     ) -> anyhow::Result<Self> {
-        let http = build_refresh_client()?;
+        let http = build_refresh_client(ca)?;
         let tokens = Tokens {
             access_token: String::new(),
             refresh_token: refresh_token.into(),
@@ -473,11 +475,15 @@ fn now_unix() -> i64 {
 /// time keeps a hung token endpoint from wedging every Drive request (the
 /// refresh holds the token mutex across the await); disabling redirects keeps
 /// the credential-bearing client from being steered to an attacker endpoint.
-fn build_refresh_client() -> anyhow::Result<reqwest::Client> {
-    reqwest::Client::builder()
+fn build_refresh_client(ca: &CustomCaConfig) -> anyhow::Result<reqwest::Client> {
+    let builder = reqwest::Client::builder()
         .connect_timeout(REFRESH_CONNECT_TIMEOUT)
         .timeout(REFRESH_TOTAL_TIMEOUT)
-        .redirect(reqwest::redirect::Policy::none())
+        .redirect(reqwest::redirect::Policy::none());
+    // Issue #34: add the user's custom root CA additively; fail-closed if a
+    // configured CA cannot be loaded (a corporate proxy would break the refresh
+    // otherwise, and silently ignoring the CA is never correct).
+    driven_tls::apply_custom_ca(builder, ca)?
         .build()
         .map_err(|e| anyhow::anyhow!("drive: failed to build OAuth refresh client: {e}"))
 }
@@ -591,18 +597,31 @@ mod tests {
         // V-A1: the refresh client must build with timeouts + redirect::none.
         // Building it is offline (no network); a failure would be a TLS-init
         // bug, so this is a real assertion, not a skip.
-        let client = build_refresh_client();
+        let client = build_refresh_client(&CustomCaConfig::none());
         assert!(
             client.is_ok(),
             "refresh client must build offline: {:?}",
             client.err()
         );
     }
 
+    #[test]
+    fn refresh_client_fails_closed_with_a_bad_ca() {
+        // Issue #34: a configured-but-unloadable custom CA must FAIL the client
+        // build (fail-closed), not silently fall back to system-trust-only. This
+        // is the representative wiring assertion for the driven-tls threading.
+        let missing = std::path::PathBuf::from("/driven/no/such/ca-bundle.pem");
+        let ca = CustomCaConfig::from_path(Some(missing));
+        assert!(
+            build_refresh_client(&ca).is_err(),
+            "a missing custom CA file must fail the refresh-client build"
+        );
+    }
+
     #[test]
     fn with_store_wires_the_keychain_store() {
         // C-P2-4 / V-A3: with_store attaches a store; without it, none.
-        let http = build_refresh_client().unwrap();
+        let http = build_refresh_client(&CustomCaConfig::none()).unwrap();
         let tokens = Tokens {
             access_token: String::new(),
             refresh_token: "rt".to_string(),

crates/driven-drive/src/google/token_store.rs

@@ -14,3 +14,9 @@
 pub mod fake;
 pub mod google;
 pub mod remote_store;
+
+// Issue #34: re-export the custom-root-CA config type so callers that already
+// depend on `driven-drive` (the CLI, the google_e2e integration test) can name
+// it without a separate `driven-tls` dependency. `apply_custom_ca` /
+// `validate_ca_file` live in `driven_tls` for the crates that build clients.
+pub use driven_tls::CustomCaConfig;

crates/driven-drive/src/lib.rs

@@ -85,14 +85,16 @@ fn e2e_creds(test_name: &str) -> Option<E2eCreds> {
 /// child folder id the scenario should operate under (ROADMAP M4: "each test
 /// uses a UUID-named child folder under the dest folder and cleans up").
 async fn setup_store(creds: &E2eCreds) -> (GoogleDriveStore, String) {
+    let ca = driven_drive::CustomCaConfig::none();
     let token_source = RefreshingTokenSource::from_stored_refresh_token(
         creds.refresh_token.clone(),
         creds.client_id.clone(),
         creds.client_secret.clone(),
+        &ca,
     )
     .expect("build refreshing token source");
     let store =
-        GoogleDriveStore::with_default_clients(token_source).expect("build GoogleDriveStore");
+        GoogleDriveStore::with_default_clients(token_source, &ca).expect("build GoogleDriveStore");
 
     // Each test operates inside a fresh UUID-named child folder so concurrent
     // runs never collide and cleanup is a single trash of that subtree