feat: add mTLS support for model providers

Adds mutual TLS (mTLS) authentication support for model provider
connections, allowing Codex to connect to endpoints requiring
client certificates. The implementation uses rustls exclusively -
native-tls is not supported due to Cargo's feature unification causing
both TLS backends to be linked when any dependency enables native-tls.

Configuration is done via TOML for each model provider:
```toml
[model-providers.my-provider]
base_url = "https://example.com"
tls.ca-certificate = "/path/to/ca.pem"
tls.client-certificate = "/path/to/client.pem"
tls.client-private-key = "/path/to/key.pem"
```

Paths can be absolute or relative to `~/.codex/`. All three TLS fields
are optional - omit CA certificate to use system roots, omit client
cert/key for server-only TLS.

The implementation gracefully falls back to a non-TLS client if certificate
loading fails (with error logging), ensuring connectivity isn't completely
broken by misconfigured certificates. This matches the previous behavior on
reqwest builder failures.

Author: asm89

codex-rs/core/src/client.rs

@@ -42,7 +42,7 @@ use crate::client_common::Prompt;
 use crate::client_common::ResponseEvent;
 use crate::client_common::ResponseStream;
 use crate::config::Config;
-use crate::default_client::build_reqwest_client;
+use crate::default_client::build_reqwest_client_for_provider;
 use crate::error::CodexErr;
 use crate::error::Result;
 use crate::flags::CODEX_RS_SSE_FIXTURE;
@@ -168,7 +168,8 @@ impl ModelClient {
                 .provider
                 .to_api_provider(auth.as_ref().map(|a| a.mode))?;
             let api_auth = auth_provider_from_auth(auth.clone(), &self.provider).await?;
-            let transport = ReqwestTransport::new(build_reqwest_client());
+            let transport =
+                ReqwestTransport::new(build_reqwest_client_for_provider(&self.provider));
             let (request_telemetry, sse_telemetry) = self.build_streaming_telemetry();
             let client = ApiChatClient::new(transport, api_provider, api_auth)
                 .with_telemetry(Some(request_telemetry), Some(sse_telemetry));
@@ -253,7 +254,8 @@ impl ModelClient {
                 .provider
                 .to_api_provider(auth.as_ref().map(|a| a.mode))?;
             let api_auth = auth_provider_from_auth(auth.clone(), &self.provider).await?;
-            let transport = ReqwestTransport::new(build_reqwest_client());
+            let transport =
+                ReqwestTransport::new(build_reqwest_client_for_provider(&self.provider));
             let (request_telemetry, sse_telemetry) = self.build_streaming_telemetry();
             let client = ApiResponsesClient::new(transport, api_provider, api_auth)
                 .with_telemetry(Some(request_telemetry), Some(sse_telemetry));
@@ -337,7 +339,7 @@ impl ModelClient {
             .provider
             .to_api_provider(auth.as_ref().map(|a| a.mode))?;
         let api_auth = auth_provider_from_auth(auth.clone(), &self.provider).await?;
-        let transport = ReqwestTransport::new(build_reqwest_client());
+        let transport = ReqwestTransport::new(build_reqwest_client_for_provider(&self.provider));
         let request_telemetry = self.build_request_telemetry();
         let client = ApiCompactClient::new(transport, api_provider, api_auth)
             .with_telemetry(Some(request_telemetry));

codex-rs/core/src/config/mod.rs

@@ -2895,6 +2895,7 @@ model_verbosity = "high"
             stream_max_retries: Some(10),
             stream_idle_timeout_ms: Some(300_000),
             requires_openai_auth: false,
+            tls: None,
         };
         let model_provider_map = {
             let mut model_provider_map = built_in_model_providers();

codex-rs/core/src/default_client.rs

@@ -1,3 +1,5 @@
+use crate::model_provider_info::ModelProviderInfo;
+use crate::model_provider_info::ModelProviderTlsConfig;
 use crate::spawn::CODEX_SANDBOX_ENV_VAR;
 use http::Error as HttpError;
 use reqwest::IntoUrl;
@@ -8,10 +10,22 @@ use reqwest::header::HeaderValue;
 use serde::Serialize;
 use std::collections::HashMap;
 use std::fmt::Display;
+use std::path::PathBuf;
 use std::sync::LazyLock;
 use std::sync::Mutex;
 use std::sync::OnceLock;
 
+/// TLS configuration for HTTP clients
+#[derive(Debug, Clone)]
+pub struct TlsConfig {
+    /// Path to a custom CA certificate (PEM format)
+    pub ca_certificate: Option<PathBuf>,
+    /// Path to the client certificate (PEM format) for mutual TLS
+    pub client_certificate: Option<PathBuf>,
+    /// Path to the client private key (PEM format) for mutual TLS
+    pub client_private_key: Option<PathBuf>,
+}
+
 /// Set this to add a suffix to the User-Agent string.
 ///
 /// It is not ideal that we're using a global singleton for this.
@@ -130,7 +144,7 @@ impl CodexRequestBuilder {
             }
             Err(error) => {
                 let status = error.status();
-                tracing::debug!(
+                tracing::error!(
                     method = %self.method,
                     url = %self.url,
                     status = status.map(|s| s.as_u16()),
@@ -262,22 +276,170 @@ pub fn create_client() -> CodexHttpClient {
     CodexHttpClient::new(inner)
 }
 
+/// Create an HTTP client with optional TLS configuration.
+/// Optionally configure TLS/mTLS settings via the `tls_config` parameter.
+pub fn create_configured_client(tls_config: Option<&TlsConfig>) -> CodexHttpClient {
+    let inner = build_configured_reqwest_client(tls_config);
+    CodexHttpClient::new(inner)
+}
+
 pub fn build_reqwest_client() -> reqwest::Client {
+    build_configured_reqwest_client(None)
+}
+
+/// Build a reqwest client configured for a specific model provider.
+/// This extracts TLS configuration from the provider if present.
+pub fn build_reqwest_client_for_provider(provider: &ModelProviderInfo) -> reqwest::Client {
+    let tls_config = provider
+        .tls
+        .as_ref()
+        .map(ModelProviderTlsConfig::to_tls_config);
+    build_configured_reqwest_client(tls_config.as_ref())
+}
+
+pub fn build_configured_reqwest_client(tls_config: Option<&TlsConfig>) -> reqwest::Client {
+    let builder = create_base_client_builder();
+
+    // Apply TLS configuration if provided
+    let builder = if let Some(tls) = tls_config {
+        match apply_tls_config(builder, tls) {
+            Ok(configured_builder) => configured_builder,
+            Err(e) => {
+                tracing::error!("Failed to apply TLS configuration: {}", e);
+                // Fall back to base builder without TLS
+                create_base_client_builder()
+            }
+        }
+    } else {
+        builder
+    };
+
+    builder.build().unwrap_or_else(|_| reqwest::Client::new())
+}
+
+/// Create the base HTTP client builder with standard configuration.
+fn create_base_client_builder() -> reqwest::ClientBuilder {
     use reqwest::header::HeaderMap;
 
     let mut headers = HeaderMap::new();
     headers.insert("originator", originator().header_value.clone());
     let ua = get_codex_user_agent();
 
     let mut builder = reqwest::Client::builder()
-        // Set UA via dedicated helper to avoid header validation pitfalls
         .user_agent(ua)
         .default_headers(headers);
+
     if is_sandboxed() {
         builder = builder.no_proxy();
     }
 
-    builder.build().unwrap_or_else(|_| reqwest::Client::new())
+    builder
+}
+
+/// Apply TLS configuration to a reqwest ClientBuilder.
+/// Paths are resolved relative to ~/.codex/ if they're not absolute.
+fn apply_tls_config(
+    mut builder: reqwest::ClientBuilder,
+    tls: &TlsConfig,
+) -> Result<reqwest::ClientBuilder, String> {
+    use reqwest::Certificate;
+    use reqwest::Identity;
+
+    // Add custom CA certificate if provided
+    if let Some(ca_path) = &tls.ca_certificate {
+        let resolved_path = resolve_cert_path(ca_path);
+        let cert_pem = std::fs::read(&resolved_path).map_err(|e| {
+            format!(
+                "Failed to read CA certificate from {}: {}",
+                resolved_path.display(),
+                e
+            )
+        })?;
+
+        let certificate = Certificate::from_pem(&cert_pem).map_err(|e| {
+            format!(
+                "Failed to parse CA certificate from {}: {}",
+                resolved_path.display(),
+                e
+            )
+        })?;
+
+        // Disable built-in root certificates and use only our custom CA
+        builder = builder
+            .tls_built_in_root_certs(false)
+            .add_root_certificate(certificate);
+    }
+
+    // Configure client certificate and private key for mTLS
+    match (&tls.client_certificate, &tls.client_private_key) {
+        (Some(cert_path), Some(key_path)) => {
+            let cert_resolved = resolve_cert_path(cert_path);
+            let key_resolved = resolve_cert_path(key_path);
+
+            // Read cert and key files
+            let cert_pem = std::fs::read(&cert_resolved).map_err(|e| {
+                format!(
+                    "Failed to read client certificate from {}: {}",
+                    cert_resolved.display(),
+                    e
+                )
+            })?;
+            let key_pem = std::fs::read(&key_resolved).map_err(|e| {
+                format!(
+                    "Failed to read client private key from {}: {}",
+                    key_resolved.display(),
+                    e
+                )
+            })?;
+
+            // For rustls, Identity::from_pem() accepts combined cert+key PEM data
+            let mut combined_pem = cert_pem;
+            combined_pem.extend_from_slice(&key_pem);
+
+            let identity = Identity::from_pem(&combined_pem).map_err(|e| {
+                format!(
+                    "Failed to create client identity from {} and {}: {}",
+                    cert_resolved.display(),
+                    key_resolved.display(),
+                    e
+                )
+            })?;
+
+            builder = builder.identity(identity).https_only(true);
+        }
+        (Some(_), None) | (None, Some(_)) => {
+            return Err(
+                "client_certificate and client_private_key must both be provided for mTLS"
+                    .to_string(),
+            );
+        }
+        (None, None) => {
+            // No client certificate configured
+        }
+    }
+
+    Ok(builder)
+}
+
+/// Resolve certificate paths relative to ~/.codex/ if they're not absolute.
+fn resolve_cert_path(path: &PathBuf) -> PathBuf {
+    if path.is_absolute() {
+        path.clone()
+    } else {
+        // Resolve relative to $CODEX_HOME (defaults to ~/.codex)
+        let codex_home = std::env::var("CODEX_HOME")
+            .ok()
+            .and_then(|s| {
+                if s.is_empty() {
+                    None
+                } else {
+                    Some(PathBuf::from(s))
+                }
+            })
+            .or_else(|| dirs::home_dir().map(|home| home.join(".codex")))
+            .unwrap_or_else(|| PathBuf::from(".codex"));
+        codex_home.join(path)
+    }
 }
 
 fn is_sandboxed() -> bool {

codex-rs/core/src/model_provider_info.rs

@@ -16,6 +16,7 @@ use serde::Deserialize;
 use serde::Serialize;
 use std::collections::HashMap;
 use std::env::VarError;
+use std::path::PathBuf;
 use std::time::Duration;
 
 use crate::error::EnvVarError;
@@ -44,6 +45,36 @@ pub enum WireApi {
     Chat,
 }
 
+/// TLS configuration for mutual TLS (mTLS) authentication with model providers.
+#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub struct ModelProviderTlsConfig {
+    /// Path to a custom CA certificate (PEM format) to trust when connecting to this provider.
+    /// Relative paths are resolved against `~/.codex/`.
+    pub ca_certificate: Option<PathBuf>,
+
+    /// Path to the client certificate (PEM format) for mutual TLS authentication.
+    /// Must be provided together with `client_private_key`.
+    /// Relative paths are resolved against `~/.codex/`.
+    pub client_certificate: Option<PathBuf>,
+
+    /// Path to the client private key (PEM format) for mutual TLS authentication.
+    /// Must be provided together with `client_certificate`.
+    /// Relative paths are resolved against `~/.codex/`.
+    pub client_private_key: Option<PathBuf>,
+}
+
+impl ModelProviderTlsConfig {
+    /// Convert to the default_client TlsConfig type
+    pub fn to_tls_config(&self) -> crate::default_client::TlsConfig {
+        crate::default_client::TlsConfig {
+            ca_certificate: self.ca_certificate.clone(),
+            client_certificate: self.client_certificate.clone(),
+            client_private_key: self.client_private_key.clone(),
+        }
+    }
+}
+
 /// Serializable representation of a provider definition.
 #[derive(Debug, Clone, Deserialize, Serialize, PartialEq)]
 pub struct ModelProviderInfo {
@@ -96,6 +127,10 @@ pub struct ModelProviderInfo {
     /// and API key (if needed) comes from the "env_key" environment variable.
     #[serde(default)]
     pub requires_openai_auth: bool,
+
+    /// TLS configuration for mutual TLS (mTLS) authentication and custom CA certificates.
+    #[serde(default)]
+    pub tls: Option<ModelProviderTlsConfig>,
 }
 
 impl ModelProviderInfo {
@@ -263,6 +298,7 @@ pub fn built_in_model_providers() -> HashMap<String, ModelProviderInfo> {
                 stream_max_retries: None,
                 stream_idle_timeout_ms: None,
                 requires_openai_auth: true,
+                tls: None,
             },
         ),
         (
@@ -314,6 +350,7 @@ pub fn create_oss_provider_with_base_url(base_url: &str, wire_api: WireApi) -> M
         stream_max_retries: None,
         stream_idle_timeout_ms: None,
         requires_openai_auth: false,
+        tls: None,
     }
 }
 
@@ -342,6 +379,7 @@ base_url = "http://localhost:11434/v1"
             stream_max_retries: None,
             stream_idle_timeout_ms: None,
             requires_openai_auth: false,
+            tls: None,
         };
 
         let provider: ModelProviderInfo = toml::from_str(azure_provider_toml).unwrap();
@@ -372,6 +410,7 @@ query_params = { api-version = "2025-04-01-preview" }
             stream_max_retries: None,
             stream_idle_timeout_ms: None,
             requires_openai_auth: false,
+            tls: None,
         };
 
         let provider: ModelProviderInfo = toml::from_str(azure_provider_toml).unwrap();
@@ -405,6 +444,7 @@ env_http_headers = { "X-Example-Env-Header" = "EXAMPLE_ENV_VAR" }
             stream_max_retries: None,
             stream_idle_timeout_ms: None,
             requires_openai_auth: false,
+            tls: None,
         };
 
         let provider: ModelProviderInfo = toml::from_str(azure_provider_toml).unwrap();
@@ -436,6 +476,7 @@ env_http_headers = { "X-Example-Env-Header" = "EXAMPLE_ENV_VAR" }
                 stream_max_retries: None,
                 stream_idle_timeout_ms: None,
                 requires_openai_auth: false,
+                tls: None,
             };
             let api = provider.to_api_provider(None).expect("api provider");
             assert!(
@@ -458,6 +499,7 @@ env_http_headers = { "X-Example-Env-Header" = "EXAMPLE_ENV_VAR" }
             stream_max_retries: None,
             stream_idle_timeout_ms: None,
             requires_openai_auth: false,
+            tls: None,
         };
         let named_api = named_provider.to_api_provider(None).expect("api provider");
         assert!(named_api.is_azure_responses_endpoint());
@@ -482,6 +524,7 @@ env_http_headers = { "X-Example-Env-Header" = "EXAMPLE_ENV_VAR" }
                 stream_max_retries: None,
                 stream_idle_timeout_ms: None,
                 requires_openai_auth: false,
+                tls: None,
             };
             let api = provider.to_api_provider(None).expect("api provider");
             assert!(

codex-rs/core/src/openai_models/models_manager.rs

@@ -128,6 +128,7 @@ mod tests {
             stream_max_retries: Some(0),
             stream_idle_timeout_ms: Some(5_000),
             requires_openai_auth: false,
+            tls: None,
         }
     }
 

codex-rs/core/tests/chat_completions_payload.rs

@@ -56,6 +56,7 @@ async fn run_request(input: Vec<ResponseItem>) -> Value {
         stream_max_retries: Some(0),
         stream_idle_timeout_ms: Some(5_000),
         requires_openai_auth: false,
+        tls: None,
     };
 
     let codex_home = match TempDir::new() {