feat(metrics): add opt-in TLS and mTLS support

crates/openshell-core/src/config.rs

@@ -230,6 +230,13 @@ pub struct Config {
     /// When `None`, the dedicated metrics listener is disabled.
     pub metrics_bind_address: Option<SocketAddr>,
 
+    /// TLS configuration for the dedicated metrics listener.
+    ///
+    /// When `None`, the metrics listener retains its plaintext HTTP behavior.
+    /// This configuration is intentionally separate from [`Self::tls`] so
+    /// metrics clients can use their own client CA trust boundary.
+    pub metrics_tls: Option<MetricsTlsConfig>,
+
     /// Log level (trace, debug, info, warn, error).
     pub log_level: String,
 
@@ -399,6 +406,27 @@ pub struct TlsConfig {
     pub external_server_names: Vec<String>,
 }
 
+/// TLS configuration for the dedicated metrics listener.
+///
+/// Unlike [`TlsConfig`], metrics TLS does not support external certificates
+/// or SNI routing. The metrics listener has one narrow HTTPS/mTLS contract
+/// with an optional, metrics-specific client CA.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct MetricsTlsConfig {
+    /// Path to the TLS certificate file served by the metrics listener.
+    pub cert_path: PathBuf,
+
+    /// Path to the TLS private key file served by the metrics listener.
+    pub key_path: PathBuf,
+
+    /// Path to the CA certificate file used to verify metrics clients.
+    pub client_ca_path: Option<PathBuf>,
+
+    /// Whether metrics clients must present a certificate trusted by
+    /// [`Self::client_ca_path`].
+    pub require_client_auth: bool,
+}
+
 /// OIDC (`OpenID` Connect) configuration for JWT-based authentication.
 ///
 /// When configured, the server validates `authorization: Bearer <JWT>`
@@ -929,6 +957,7 @@ impl Config {
             bind_address: default_bind_address(),
             health_bind_address: None,
             metrics_bind_address: None,
+            metrics_tls: None,
             log_level: default_log_level(),
             policy_validation_failure_mode: PolicyValidationFailureMode::default(),
             config_delivery_mode: ConfigDeliveryMode::default(),
@@ -981,6 +1010,13 @@ impl Config {
         self
     }
 
+    /// Create a new configuration with TLS for the dedicated metrics listener.
+    #[must_use]
+    pub fn with_metrics_tls(mut self, tls: MetricsTlsConfig) -> Self {
+        self.metrics_tls = Some(tls);
+        self
+    }
+
     /// Create a new configuration with the given log level.
     #[must_use]
     pub fn with_log_level(mut self, level: impl Into<String>) -> Self {
@@ -1223,12 +1259,12 @@ mod tests {
     use super::{
         AppArmorProfile, Config, ConfigDeliveryMode, DEFAULT_SERVICE_ROUTING_DOMAIN,
         GatewayInterceptorBindingPolicy, GatewayInterceptorConfig, GatewayInterceptorFailurePolicy,
-        GatewayJwtConfig, GatewayProviderProfileSourceConfig, ImagePullPolicy,
+        GatewayJwtConfig, GatewayProviderProfileSourceConfig, ImagePullPolicy, MetricsTlsConfig,
         PolicyValidationFailureMode, UpstreamProxyConfig, default_sandbox_pids_limit,
         normalize_compute_driver_name,
     };
-    use std::net::SocketAddr;
     use std::time::Duration;
+    use std::{net::SocketAddr, path::PathBuf};
 
     #[test]
     fn policy_validation_failure_mode_is_secure_by_default() {
@@ -1727,6 +1763,23 @@ mod tests {
         assert_eq!(cfg.health_bind_address, Some(addr));
     }
 
+    #[test]
+    fn metrics_tls_is_disabled_by_default_and_can_be_configured() {
+        assert!(Config::new(None).metrics_tls.is_none());
+
+        let tls = MetricsTlsConfig {
+            cert_path: PathBuf::from("/etc/openshell-metrics/tls.crt"),
+            key_path: PathBuf::from("/etc/openshell-metrics/tls.key"),
+            client_ca_path: Some(PathBuf::from("/etc/openshell-metrics/ca.crt")),
+            require_client_auth: true,
+        };
+
+        assert_eq!(
+            Config::new(None).with_metrics_tls(tls.clone()).metrics_tls,
+            Some(tls)
+        );
+    }
+
     #[test]
     fn supervisor_image_tag_prefers_explicit_build_tags() {
         use super::resolve_supervisor_image_tag;

crates/openshell-core/src/lib.rs

@@ -71,8 +71,8 @@ pub use config::{
     AppArmorProfile, Config, GatewayAuthConfig, GatewayInterceptorBindingOverride,
     GatewayInterceptorBindingPolicy, GatewayInterceptorConfig, GatewayInterceptorFailurePolicy,
     GatewayInterceptorPhaseConfig, GatewayJwtConfig, GatewayProviderProfileSourceConfig,
-    ImagePullPolicy, MtlsAuthConfig, OidcConfig, PolicyValidationFailureMode, TlsConfig,
-    UpstreamProxyConfig,
+    ImagePullPolicy, MetricsTlsConfig, MtlsAuthConfig, OidcConfig, PolicyValidationFailureMode,
+    TlsConfig, UpstreamProxyConfig,
 };
 pub use dynamic_string_allowlist::DynamicStringAllowlist;
 pub use error::{ComputeDriverError, Error, Result};

crates/openshell-server/src/cli.rs

@@ -104,6 +104,29 @@ struct RunArgs {
     #[arg(long, default_value_t = 0, env = "OPENSHELL_METRICS_PORT")]
     metrics_port: u16,
 
+    /// Path to the TLS certificate served by the metrics listener.
+    #[arg(long, env = "OPENSHELL_METRICS_TLS_CERT")]
+    metrics_tls_cert: Option<PathBuf>,
+
+    /// Path to the TLS private key served by the metrics listener.
+    #[arg(long, env = "OPENSHELL_METRICS_TLS_KEY")]
+    metrics_tls_key: Option<PathBuf>,
+
+    /// Path to the CA certificate used to verify metrics clients.
+    #[arg(long, env = "OPENSHELL_METRICS_TLS_CLIENT_CA")]
+    metrics_tls_client_ca: Option<PathBuf>,
+
+    /// Require metrics clients to present a certificate trusted by the metrics client CA.
+    #[arg(
+        long,
+        env = "OPENSHELL_METRICS_REQUIRE_CLIENT_AUTH",
+        num_args = 0..=1,
+        default_missing_value = "true",
+        require_equals = true,
+        value_parser = clap::value_parser!(bool)
+    )]
+    metrics_require_client_auth: Option<bool>,
+
     /// Log level (trace, debug, info, warn, error).
     #[arg(long, default_value = "info", env = "OPENSHELL_LOG_LEVEL")]
     log_level: String,
@@ -521,6 +544,12 @@ fn prepare_server_config_with_drivers(
         "metrics_port",
         || file_gateway.and_then(|g| g.metrics_bind_address),
     );
+    let metrics_tls = resolve_metrics_tls(args)?;
+    if metrics_tls.is_some() && metrics_bind.is_none() {
+        return Err(miette::miette!(
+            "metrics TLS requires an enabled metrics listener; set --metrics-port or metrics_bind_address"
+        ));
+    }
 
     if let Some(addr) = health_bind {
         if args.port == addr.port() {
@@ -549,6 +578,9 @@ fn prepare_server_config_with_drivers(
         }
         config = config.with_metrics_bind_address(addr);
     }
+    if let Some(tls) = metrics_tls {
+        config = config.with_metrics_tls(tls);
+    }
 
     config = config
         .with_database_url(db_url)
@@ -1077,6 +1109,7 @@ fn validate_preflight_semantics(
             "an explicit --tls-client-ca requires --tls-cert and --tls-key"
         ));
     }
+    let metrics_tls = resolve_metrics_tls(args)?;
     if !args.disable_tls
         && let Some(tls) = gateway.tls.as_ref()
     {
@@ -1118,6 +1151,11 @@ fn validate_preflight_semantics(
         "metrics_port",
         || gateway.metrics_bind_address,
     );
+    if metrics_tls.is_some() && metrics_bind.is_none() {
+        return Err(miette::miette!(
+            "metrics TLS requires an enabled metrics listener"
+        ));
+    }
     if health_bind.is_some_and(|address| address.port() == args.port)
         || metrics_bind.is_some_and(|address| address.port() == args.port)
         || health_bind
@@ -1212,6 +1250,43 @@ fn resolve_aux_listener(
     }
 }
 
+/// Resolve the optional TLS configuration for the dedicated metrics listener.
+///
+/// A metrics TLS configuration is activated by any metrics TLS input. It is
+/// deliberately independent from the gateway listener TLS settings so the
+/// metrics client CA remains a separate trust boundary.
+fn resolve_metrics_tls(args: &RunArgs) -> Result<Option<openshell_core::MetricsTlsConfig>> {
+    let configured = args.metrics_tls_cert.is_some()
+        || args.metrics_tls_key.is_some()
+        || args.metrics_tls_client_ca.is_some()
+        || args.metrics_require_client_auth == Some(true);
+    if !configured {
+        return Ok(None);
+    }
+
+    let cert_path = args
+        .metrics_tls_cert
+        .clone()
+        .ok_or_else(|| miette::miette!("metrics TLS requires --metrics-tls-cert"))?;
+    let key_path = args
+        .metrics_tls_key
+        .clone()
+        .ok_or_else(|| miette::miette!("metrics TLS requires --metrics-tls-key"))?;
+    let require_client_auth = args.metrics_require_client_auth.unwrap_or(false);
+    if require_client_auth && args.metrics_tls_client_ca.is_none() {
+        return Err(miette::miette!(
+            "--metrics-require-client-auth requires --metrics-tls-client-ca"
+        ));
+    }
+
+    Ok(Some(openshell_core::MetricsTlsConfig {
+        cert_path,
+        key_path,
+        client_ca_path: args.metrics_tls_client_ca.clone(),
+        require_client_auth,
+    }))
+}
+
 /// Apply gateway-wide values from `[openshell.gateway]` onto `RunArgs` for
 /// every argument that is still sourced from clap's built-in default.
 ///
@@ -1289,6 +1364,21 @@ fn merge_file_into_args(args: &mut RunArgs, file: &GatewayFileSection, matches:
             args.tls_client_ca.clone_from(&tls.client_ca_path);
         }
     }
+    // Dedicated metrics listener TLS fields.
+    if let Some(tls) = &file.metrics_tls {
+        if args.metrics_tls_cert.is_none() && arg_defaulted(matches, "metrics_tls_cert") {
+            args.metrics_tls_cert = Some(tls.cert_path.clone());
+        }
+        if args.metrics_tls_key.is_none() && arg_defaulted(matches, "metrics_tls_key") {
+            args.metrics_tls_key = Some(tls.key_path.clone());
+        }
+        if args.metrics_tls_client_ca.is_none() && arg_defaulted(matches, "metrics_tls_client_ca") {
+            args.metrics_tls_client_ca.clone_from(&tls.client_ca_path);
+        }
+        if arg_defaulted(matches, "metrics_require_client_auth") {
+            args.metrics_require_client_auth = Some(tls.require_client_auth);
+        }
+    }
     // OIDC fields
     if let Some(oidc) = &file.oidc {
         if args.oidc_issuer.is_none() && arg_defaulted(matches, "oidc_issuer") {
@@ -1418,6 +1508,7 @@ mod tests {
     use crate::test_environment::Environment;
     use clap::Parser;
     use std::net::{IpAddr, Ipv4Addr};
+    use std::path::PathBuf;
     use std::sync::atomic::{AtomicUsize, Ordering};
 
     static REGISTRY_DETECTION_CALLS: AtomicUsize = AtomicUsize::new(0);
@@ -2703,7 +2794,7 @@ mod tests {
     //
     // by exercising each combination on representative gateway fields.
 
-    use super::{ConfigFile, merge_file_into_args};
+    use super::{ConfigFile, merge_file_into_args, resolve_metrics_tls};
     use clap::FromArgMatches;
 
     fn parse_with_args(argv: &[&str]) -> (super::RunArgs, clap::ArgMatches) {
@@ -2716,6 +2807,105 @@ mod tests {
         toml::from_str(toml).expect("valid TOML in test fixture")
     }
 
+    #[test]
+    fn metrics_tls_file_values_merge_into_runtime_configuration() {
+        Environment::new()
+            .remove("OPENSHELL_METRICS_TLS_CERT")
+            .remove("OPENSHELL_METRICS_TLS_KEY")
+            .remove("OPENSHELL_METRICS_TLS_CLIENT_CA")
+            .remove("OPENSHELL_METRICS_REQUIRE_CLIENT_AUTH")
+            .run(|| {
+                let (mut args, matches) = parse_with_args(&[
+                    "openshell-gateway",
+                    "--db-url",
+                    "sqlite::memory:",
+                    "--metrics-port",
+                    "9090",
+                ]);
+                let file = config_file_from_toml(
+                    r#"
+[openshell.gateway.metrics_tls]
+cert_path = "/metrics/tls.crt"
+key_path = "/metrics/tls.key"
+client_ca_path = "/metrics/ca.crt"
+require_client_auth = true
+"#,
+                );
+
+                merge_file_into_args(&mut args, &file.openshell.gateway, &matches);
+                let tls = resolve_metrics_tls(&args)
+                    .expect("valid metrics TLS configuration")
+                    .expect("metrics TLS is configured");
+
+                assert_eq!(tls.cert_path, PathBuf::from("/metrics/tls.crt"));
+                assert_eq!(tls.key_path, PathBuf::from("/metrics/tls.key"));
+                assert_eq!(tls.client_ca_path, Some(PathBuf::from("/metrics/ca.crt")));
+                assert!(tls.require_client_auth);
+            });
+    }
+
+    #[test]
+    fn explicit_metrics_client_auth_value_overrides_file_value() {
+        Environment::new()
+            .remove("OPENSHELL_METRICS_TLS_CERT")
+            .remove("OPENSHELL_METRICS_TLS_KEY")
+            .remove("OPENSHELL_METRICS_TLS_CLIENT_CA")
+            .remove("OPENSHELL_METRICS_REQUIRE_CLIENT_AUTH")
+            .run(|| {
+                let (mut args, matches) = parse_with_args(&[
+                    "openshell-gateway",
+                    "--db-url",
+                    "sqlite::memory:",
+                    "--metrics-port",
+                    "9090",
+                    "--metrics-require-client-auth=false",
+                ]);
+                let file = config_file_from_toml(
+                    r#"
+[openshell.gateway.metrics_tls]
+cert_path = "/metrics/tls.crt"
+key_path = "/metrics/tls.key"
+client_ca_path = "/metrics/ca.crt"
+require_client_auth = true
+"#,
+                );
+
+                merge_file_into_args(&mut args, &file.openshell.gateway, &matches);
+                let tls = resolve_metrics_tls(&args)
+                    .expect("valid metrics TLS configuration")
+                    .expect("metrics TLS is configured");
+
+                assert!(!tls.require_client_auth);
+            });
+    }
+
+    #[test]
+    fn metrics_client_auth_requires_a_metrics_client_ca() {
+        Environment::new()
+            .remove("OPENSHELL_METRICS_TLS_CERT")
+            .remove("OPENSHELL_METRICS_TLS_KEY")
+            .remove("OPENSHELL_METRICS_TLS_CLIENT_CA")
+            .remove("OPENSHELL_METRICS_REQUIRE_CLIENT_AUTH")
+            .run(|| {
+                let (args, _) = parse_with_args(&[
+                    "openshell-gateway",
+                    "--metrics-tls-cert",
+                    "/metrics/tls.crt",
+                    "--metrics-tls-key",
+                    "/metrics/tls.key",
+                    "--metrics-require-client-auth",
+                ]);
+
+                let error =
+                    resolve_metrics_tls(&args).expect_err("client auth without a CA must fail");
+                assert!(
+                    error
+                        .to_string()
+                        .contains("--metrics-require-client-auth requires --metrics-tls-client-ca")
+                );
+            });
+    }
+
     #[test]
     fn rejects_legacy_drivers_flag() {
         let error = command()
@@ -2755,7 +2945,7 @@ mod tests {
 
                 assert_eq!(
                     super::resolve_config_path(&args).unwrap(),
-                    Some(std::path::PathBuf::from("/tmp/missing.toml"))
+                    Some(PathBuf::from("/tmp/missing.toml"))
                 );
             });
     }