feat(net): SOCKS5 and PAC proxy support for all outbound connections (#145)

Adds proxy support to every outbound HTTP client, completing the
corporate-network story started by the custom-CA work (#134) through the
same `driven-tls` seam.

## Modes (KV-stored `global` settings, serde-default - NO migration)
- **system** (default): unchanged - reqwest env-proxy pickup (DESIGN
5.8.7).
- **none**: explicit `.no_proxy()` everywhere - bypasses env proxies
too.
- **manual**: one proxy URL (`http://`, `https://`, `socks5://`,
`socks5h://` - socks5h resolves DNS proxy-side); reqwest `socks` feature
enabled on both workspace reqwest 0.12 and the updater's reqwest 0.13.
- **pac**: PAC file URL or local path, compiled with an embedded
pure-Rust JS engine (boa 0.20), evaluated per-URL via `Proxy::custom`
with a 256-entry per-HOST LRU. Standard helpers implemented
(isPlainHostName, dnsDomainIs, localHostOrDomainIs, dnsDomainLevels,
shExpMatch, dnsResolve, isResolvable, myIpAddress, isInNet); date/time
predicates (weekdayRange/dateRange/timeRange) are defined-but-false
stubs.

## Semantics + documented caveats
- CONFIG failures fail closed at settings-save AND client build (bad
URL, unfetchable/uncompilable PAC): clients are never built silently
unproxied. A corrupt stored mode string degrades to `system` (the
historical default).
- RUNTIME PAC eval errors (e.g. a DNS failure mid-eval) log a warning
and go direct for that request - browser-standard PAC failure behavior.
- The PAC realm is pure ECMAScript (no fetch/fs/process); DNS via the
helpers only. There is deliberately NO JS execution watchdog yet
(admin-configured input; LRU bounds eval count) - future hardening if
untrusted PAC ever becomes possible. DNS helpers use OS-resolver
timeouts.
- Cache keys on host only: a PAC branching on scheme/path gets the
per-host decision (endorsed pragmatic subset).
- Updater: PAC evaluates per-URL there too via a version-neutral engine
handle; CA certs + proxy fold into ONE configure_client closure (the
plugin keeps only the last).
- CLI: env proxy + `DRIVEN_PROXY_URL` (manual) only; PAC unsupported
there.
- deny.toml: `paste` (RUSTSEC-2024-0436, unmaintained build-time
proc-macro via boa) ignored with justification; `lru` at 0.16.3+ (clears
RUSTSEC-2026-0002).
- New IPC `validate_proxy` + Settings UI proxy section (mode select,
conditional inputs, inline validation), localized, vitest mount
coverage.

Refs #34

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

https://claude.ai/code/session_01QZQVP2tUuTLh8oL31D8heC

Author: pmaxhogan

Cargo.lock

@@ -66,6 +66,11 @@ reqwest = { version = "0.12", default-features = false, features = [
     "rustls-tls-native-roots",
     "http2",
     "stream",
+    # Issue #34 (SOCKS5 + PAC proxy support): the `socks` feature enables
+    # `socks5://` and `socks5h://` proxy URLs on `reqwest::Proxy` (the `h`
+    # variant does proxy-side DNS). Off by default; required for manual SOCKS5
+    # proxies and any PAC decision that returns a SOCKS proxy.
+    "socks",
 ] }
 # M3 encryption (DESIGN s7): XChaCha20-Poly1305 STREAM for content +
 # single-shot for filenames; BIP39 recovery phrase over the master key;

Cargo.toml

@@ -33,7 +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;
+use driven_drive::{CustomCaConfig, ProxyConfig};
 
 /// The public installed-app client id (SPEC s4; M4 brief). Used when neither
 /// `--client-id`, the env var, nor `client_secret.json` supplies one.
@@ -272,6 +272,7 @@ async fn run_auth(args: AuthArgs) -> anyhow::Result<()> {
         open_system_browser,
         tx,
         &cli_custom_ca(),
+        &cli_proxy(),
     )
     .await?;
 
@@ -414,14 +415,16 @@ fn build_store(account: &str, creds: &ClientCreds) -> anyhow::Result<GoogleDrive
         )
     })?;
     let ca = cli_custom_ca();
+    let proxy = cli_proxy();
     let token_source = RefreshingTokenSource::from_stored_refresh_token(
         refresh_token,
         creds.client_id.clone(),
         creds.client_secret.clone(),
         &ca,
+        &proxy,
     )?
     .with_store(store);
-    GoogleDriveStore::with_default_clients(token_source, &ca)
+    GoogleDriveStore::with_default_clients(token_source, &ca, &proxy)
 }
 
 /// Issue #34: the dev/e2e CLI reads its custom root CA (if any) from the
@@ -435,6 +438,18 @@ fn cli_custom_ca() -> CustomCaConfig {
     }
 }
 
+/// Issue #34: the dev/e2e CLI resolves its proxy from `DRIVEN_PROXY_URL` (an
+/// `http`/`https`/`socks5`/`socks5h` URL). Unset = `System` mode, which honours
+/// the standard `HTTP_PROXY`/`HTTPS_PROXY` env vars. PAC auto-config is a
+/// desktop-app-only feature (it needs an async fetch); the dev CLI supports only
+/// the env + manual forms. An invalid URL fails closed at client-build time.
+fn cli_proxy() -> ProxyConfig {
+    match std::env::var("DRIVEN_PROXY_URL") {
+        Ok(url) if !url.trim().is_empty() => ProxyConfig::Manual(url.trim().to_string()),
+        _ => ProxyConfig::system(),
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

crates/driven-cli/src/main.rs

@@ -49,7 +49,7 @@ use std::time::Duration;
 
 use async_trait::async_trait;
 use bytes::Bytes;
-use driven_tls::CustomCaConfig;
+use driven_tls::{CustomCaConfig, ProxyConfig};
 use futures::Stream;
 use serde::Deserialize;
 use tokio::io::{AsyncRead, ReadBuf};
@@ -557,14 +557,19 @@ 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, ca: &CustomCaConfig) -> Self {
+    pub fn new(
+        http: reqwest::Client,
+        tokens: RefreshingTokenSource,
+        ca: &CustomCaConfig,
+        proxy: &ProxyConfig,
+    ) -> Self {
         let _ = TARGET;
         // 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| {
+        // issue #34 custom root CA via `ca` and proxy via `proxy`) 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 + proxy).
+        let http_stream = build_stream_client(ca, proxy).unwrap_or_else(|e| {
             warn!(
                 target: TARGET,
                 error = %e,
@@ -587,9 +592,10 @@ impl GoogleDriveStore {
     pub fn with_default_clients(
         tokens: RefreshingTokenSource,
         ca: &CustomCaConfig,
+        proxy: &ProxyConfig,
     ) -> anyhow::Result<Self> {
-        let http = build_meta_client(ca)?;
-        let http_stream = build_stream_client(ca)?;
+        let http = build_meta_client(ca, proxy)?;
+        let http_stream = build_stream_client(ca, proxy)?;
         Ok(Self {
             http,
             http_stream,
@@ -1708,28 +1714,36 @@ impl GoogleDriveStore {
 /// 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> {
+pub(crate) fn build_meta_client(
+    ca: &CustomCaConfig,
+    proxy: &ProxyConfig,
+) -> 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));
-    driven_tls::apply_custom_ca(builder, ca)?
+    let builder = driven_tls::apply_custom_ca(builder, ca)?;
+    driven_tls::apply_proxy(builder, proxy)?
         .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 `*`).
 /// `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> {
+pub(crate) fn build_stream_client(
+    ca: &CustomCaConfig,
+    proxy: &ProxyConfig,
+) -> 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));
-    driven_tls::apply_custom_ca(builder, ca)?
+    let builder = driven_tls::apply_custom_ca(builder, ca)?;
+    driven_tls::apply_proxy(builder, proxy)?
         .build()
         .map_err(|e| anyhow::anyhow!("drive: failed to build streaming client: {e}"))
 }
@@ -1960,12 +1974,15 @@ mod tests {
             refresh_token: "rt".to_string(),
             expires_at: 0,
         };
-        let http = build_meta_client(&CustomCaConfig::none()).expect("meta client");
+        let http = build_meta_client(&CustomCaConfig::none(), &ProxyConfig::system())
+            .expect("meta client");
         let source = RefreshingTokenSource::new(tokens, http, "cid", "secret");
         let store = GoogleDriveStore::new(
-            build_meta_client(&CustomCaConfig::none()).expect("meta client"),
+            build_meta_client(&CustomCaConfig::none(), &ProxyConfig::system())
+                .expect("meta client"),
             source,
             &CustomCaConfig::none(),
+            &ProxyConfig::system(),
         );
         // The streaming client is a distinct, usable handle (no panic on build).
         let _ = store.http_stream();
@@ -1976,21 +1993,43 @@ mod tests {
         // 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");
+        let sys = ProxyConfig::system();
+        assert!(
+            build_meta_client(&none, &sys).is_ok(),
+            "no-CA meta client builds"
+        );
         assert!(
-            build_stream_client(&none).is_ok(),
+            build_stream_client(&none, &sys).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(),
+            build_meta_client(&bad, &sys).is_err(),
+            "bad CA fails meta build"
+        );
+        assert!(
+            build_stream_client(&bad, &sys).is_err(),
             "bad CA fails stream build"
         );
     }
 
+    #[test]
+    fn drive_clients_apply_proxy_fail_closed() {
+        // Issue #34: a bad proxy URL fails the Drive client builds closed.
+        let none = CustomCaConfig::none();
+        let bad = ProxyConfig::Manual("ftp://nope:21".to_string());
+        assert!(
+            build_meta_client(&none, &bad).is_err(),
+            "bad proxy fails meta"
+        );
+        assert!(
+            build_stream_client(&none, &bad).is_err(),
+            "bad proxy fails stream"
+        );
+    }
+
     #[test]
     fn rfc3339_parses_to_unix_ms() {
         // 2024-01-01T00:00:00Z == 1704067200000 ms.

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

@@ -24,7 +24,7 @@
 use std::net::{Ipv4Addr, Ipv6Addr, SocketAddr};
 use std::time::Duration;
 
-use driven_tls::CustomCaConfig;
+use driven_tls::{CustomCaConfig, ProxyConfig};
 use oauth2::basic::BasicClient;
 use oauth2::{
     AuthUrl, AuthorizationCode, ClientId, ClientSecret, CsrfToken, PkceCodeChallenge, RedirectUrl,
@@ -118,6 +118,7 @@ pub async fn run_pkce_loopback_flow(
     open_browser: impl FnOnce(&str) -> anyhow::Result<()>,
     progress_tx: Sender<OAuthProgress>,
     ca: &CustomCaConfig,
+    proxy: &ProxyConfig,
 ) -> 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
@@ -136,9 +137,11 @@ pub async fn run_pkce_loopback_flow(
         .redirect(reqwest::redirect::Policy::none())
         .connect_timeout(EXCHANGE_CONNECT_TIMEOUT)
         .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()?;
+    // Issue #34: add the user's custom root CA additively then the configured
+    // proxy (fail-closed) so the token exchange works behind a corporate
+    // TLS-inspecting proxy or an explicit SOCKS/PAC proxy.
+    let http_builder = driven_tls::apply_custom_ca(http_builder, ca)?;
+    let http = driven_tls::apply_proxy(http_builder, proxy)?.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,7 +34,7 @@
 use std::sync::Arc;
 use std::time::Duration;
 
-use driven_tls::CustomCaConfig;
+use driven_tls::{CustomCaConfig, ProxyConfig};
 use keyring::Entry;
 use serde::Deserialize;
 use tokio::sync::Mutex;
@@ -326,8 +326,9 @@ impl RefreshingTokenSource {
         client_id: impl Into<String>,
         client_secret: impl Into<String>,
         ca: &CustomCaConfig,
+        proxy: &ProxyConfig,
     ) -> anyhow::Result<Self> {
-        let http = build_refresh_client(ca)?;
+        let http = build_refresh_client(ca, proxy)?;
         let tokens = Tokens {
             access_token: String::new(),
             refresh_token: refresh_token.into(),
@@ -475,15 +476,20 @@ 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(ca: &CustomCaConfig) -> anyhow::Result<reqwest::Client> {
+fn build_refresh_client(
+    ca: &CustomCaConfig,
+    proxy: &ProxyConfig,
+) -> anyhow::Result<reqwest::Client> {
     let builder = reqwest::Client::builder()
         .connect_timeout(REFRESH_CONNECT_TIMEOUT)
         .timeout(REFRESH_TOTAL_TIMEOUT)
         .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)?
+    // Issue #34: add the user's custom root CA additively then the configured
+    // proxy; fail-closed if either cannot be applied (a corporate proxy would
+    // break the refresh otherwise, and silently ignoring the CA/proxy is never
+    // correct).
+    let builder = driven_tls::apply_custom_ca(builder, ca)?;
+    driven_tls::apply_proxy(builder, proxy)?
         .build()
         .map_err(|e| anyhow::anyhow!("drive: failed to build OAuth refresh client: {e}"))
 }
@@ -597,7 +603,7 @@ 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(&CustomCaConfig::none());
+        let client = build_refresh_client(&CustomCaConfig::none(), &ProxyConfig::system());
         assert!(
             client.is_ok(),
             "refresh client must build offline: {:?}",
@@ -613,15 +619,26 @@ mod tests {
         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(),
+            build_refresh_client(&ca, &ProxyConfig::system()).is_err(),
             "a missing custom CA file must fail the refresh-client build"
         );
     }
 
+    #[test]
+    fn refresh_client_fails_closed_with_a_bad_proxy() {
+        // Issue #34: a configured-but-invalid proxy URL must FAIL the refresh
+        // client build closed, never building an unproxied credential client.
+        let bad = ProxyConfig::Manual("ftp://nope:21".to_string());
+        assert!(
+            build_refresh_client(&CustomCaConfig::none(), &bad).is_err(),
+            "an invalid proxy URL 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(&CustomCaConfig::none()).unwrap();
+        let http = build_refresh_client(&CustomCaConfig::none(), &ProxyConfig::system()).unwrap();
         let tokens = Tokens {
             access_token: String::new(),
             refresh_token: "rt".to_string(),

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

@@ -20,3 +20,6 @@ pub mod remote_store;
 // 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;
+// Issue #34: likewise re-export the proxy config type (SOCKS5 + PAC support) so
+// the same callers can name it without a direct `driven-tls` dependency.
+pub use driven_tls::ProxyConfig;

crates/driven-drive/src/lib.rs

@@ -97,15 +97,17 @@ async fn setup_store(
     drive_context: &DriveContext,
 ) -> (GoogleDriveStore, String) {
     let ca = driven_drive::CustomCaConfig::none();
+    let proxy = driven_drive::ProxyConfig::system();
     let token_source = RefreshingTokenSource::from_stored_refresh_token(
         creds.refresh_token.clone(),
         creds.client_id.clone(),
         creds.client_secret.clone(),
         &ca,
+        &proxy,
     )
     .expect("build refreshing token source");
-    let store =
-        GoogleDriveStore::with_default_clients(token_source, &ca).expect("build GoogleDriveStore");
+    let store = GoogleDriveStore::with_default_clients(token_source, &ca, &proxy)
+        .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