fix(run): mount Sidecar CA material through the sandbox mask

Author: luca-iachini

crates/firma-run/src/backend/linux_bwrap/mount.rs

@@ -17,6 +17,7 @@ use crate::backend::{
 use crate::config::MountSpec;
 use crate::error::RunError;
 use firma_config_loader::{CONFIG_DIR_NAME, CONFIG_FILE_NAME};
+use firma_runtime_state::RunEntryLayout;
 
 const BWRAP_ROOTFS_MODE_ENV: &str = "FIRMA_RUN_BWRAP_ROOTFS_MODE";
 const BWRAP_RUNTIME_HOME_ENV: &str = "FIRMA_RUN_BWRAP_RUNTIME_HOME";
@@ -215,14 +216,22 @@ impl BwrapMountPlan {
                         handle.runtime_dir.display()
                     ),
                 })?;
+        // Derived from the runtime layout rather than the launch environment:
+        // an operator-supplied `SSL_CERT_FILE` could otherwise aim the CA bind
+        // at a signing key elsewhere in the control-plane runtime.
+        let run_entry = runtime_layout.run_entry_layout(&handle.identity.sandbox_id);
+        let runtime_paths = PlanRuntimePaths {
+            control_plane: &control_plane_runtime,
+            sandbox: &sandbox_runtime,
+            run_entry: &run_entry,
+        };
         let mounts = validate_mounts(handle, &control_plane_runtime, &sandbox_runtime)?;
         let mut plan = Self::empty();
         append_filesystem_layout(
             &mut plan,
             handle,
             &mounts,
-            &control_plane_runtime,
-            &sandbox_runtime,
+            &runtime_paths,
             launch,
             hardening,
         )?;
@@ -373,8 +382,7 @@ fn append_filesystem_layout(
     plan: &mut BwrapMountPlan,
     handle: &SandboxHandle,
     mounts: &[ValidatedMount],
-    control_plane_runtime: &Path,
-    sandbox_runtime: &Path,
+    runtime_paths: &PlanRuntimePaths<'_>,
     launch: &LaunchSpec,
     hardening: &BwrapHardening,
 ) -> Result<(), RunError> {
@@ -417,17 +425,36 @@ fn append_filesystem_layout(
         .collect::<Vec<_>>();
     project_mount_aliases(&mut plan.config_seals, &overlay_specs, masked);
 
-    mask_control_plane_runtime(plan, mounts, control_plane_runtime, sandbox_runtime, launch)?;
+    mask_control_plane_runtime(
+        plan,
+        mounts,
+        runtime_paths.control_plane,
+        runtime_paths.sandbox,
+        launch,
+    )?;
+    mount_ca_material(plan, runtime_paths.run_entry);
     Ok(())
 }
 
+/// Host paths that anchor one sandbox filesystem plan.
+struct PlanRuntimePaths<'a> {
+    /// Canonical control-plane runtime root (`FIRMA_STATE_DIR`).
+    control_plane: &'a Path,
+    /// Canonical private runtime for the sandbox being planned.
+    sandbox: &'a Path,
+    /// Layout of this run's entry inside the control-plane runtime.
+    run_entry: &'a RunEntryLayout,
+}
+
 /// Hide host-side Firma runtime state from the wrapped process tree.
 ///
 /// The read-only host-root bind prevents mutation but not disclosure. The
 /// runtime root contains per-run Sidecar and Authority sockets, configuration,
 /// metadata, signing keys, and capability seeds, none of which the wrapped
 /// process needs. The sandbox-local bwrap runtime remains available separately
-/// because the proxy bridge and egress guard require its sockets.
+/// because the proxy bridge and egress guard require its sockets, and
+/// [`mount_ca_material`] mounts the Sidecar's public CA material back over
+/// this mask.
 fn mask_control_plane_runtime(
     plan: &mut BwrapMountPlan,
     mounts: &[ValidatedMount],
@@ -473,6 +500,37 @@ fn mask_control_plane_runtime(
     Ok(())
 }
 
+/// Mount the Sidecar's public CA material through the control-plane mask.
+///
+/// [`mask_control_plane_runtime`] tmpfs-masks the whole control-plane runtime,
+/// but the launch environment points `SSL_CERT_FILE`, `CURL_CA_BUNDLE`,
+/// `REQUESTS_CA_BUNDLE`, `NODE_EXTRA_CA_CERTS`, and `GIT_SSL_CAINFO` at CA
+/// files inside it. Without this restoration the wrapped process opens an
+/// unreadable trust store, silently falls back to the system roots, and every
+/// MITM-intercepted handshake fails with `certificate signed by unknown
+/// authority`.
+///
+/// Each file is bound individually and read-only. Binding
+/// [`RunEntryLayout::ca_dir`] as a directory would also expose
+/// [`RunEntryLayout::ca_key`] and let the wrapped process mint certificates
+/// trusted by anything configured to trust the Sidecar CA.
+///
+/// Missing files are skipped: with HTTPS MITM disabled no CA is generated, and
+/// the bundle exists only under `ca_trust_mode = "append_system_roots"`.
+fn mount_ca_material(plan: &mut BwrapMountPlan, run_entry: &RunEntryLayout) {
+    for source in [run_entry.ca_cert(), run_entry.ca_bundle()] {
+        if !source.is_file() {
+            continue;
+        }
+        plan.sandbox_runtime.bind(
+            BwrapPlanRole::SandboxInfrastructure,
+            source.clone(),
+            source,
+            BwrapBindMode::ReadOnly,
+        );
+    }
+}
+
 /// Resolves every prepared mount to the exact host source that will be emitted
 /// and enforces the source, target, and placement constraints associated with
 /// its authority.
@@ -1380,6 +1438,165 @@ mod tests {
         );
     }
 
+    /// Sandbox handle with no mounts, used by the CA restoration tests.
+    #[cfg(target_os = "linux")]
+    fn handle_with(
+        runtime_dir: std::path::PathBuf,
+        identity: crate::identity::RunIdentity,
+    ) -> crate::backend::SandboxHandle {
+        crate::backend::SandboxHandle {
+            backend: crate::backend::BackendKind::Bwrap,
+            runtime_dir,
+            identity,
+            mounts: vec![],
+            network_policy: crate::config::NetworkPolicy {
+                enforce_network_namespace: false,
+                fail_closed: true,
+            },
+        }
+    }
+
+    #[test]
+    #[cfg(target_os = "linux")]
+    fn filesystem_layout_restores_public_ca_material_over_control_plane_mask() {
+        // The control-plane mask hides the whole runtime root, but the launch
+        // environment aims `SSL_CERT_FILE` and friends at the run entry's CA.
+        // Each public file must be restored individually and after the mask;
+        // the signing key must stay hidden, so the CA directory is never bound
+        // as a whole.
+        let temp = tempfile::tempdir().expect("tempdir");
+        let cwd = temp.path().join("workspace");
+        std::fs::create_dir_all(&cwd).expect("mkdir workspace");
+        let runtime_dir = temp.path().join("runtime");
+        std::fs::create_dir_all(&runtime_dir).expect("mkdir runtime");
+
+        let identity =
+            crate::identity::RunIdentity::new(crate::identity::test_agent_id(), "generic");
+        let control_plane = temp.path().join("control-plane");
+        let runtime_layout = firma_runtime_state::RuntimeLayout::from_root(control_plane.clone());
+        let run_entry = runtime_layout.run_entry_layout(&identity.sandbox_id);
+        std::fs::create_dir_all(run_entry.ca_dir()).expect("mkdir CA dir");
+        for path in [
+            run_entry.ca_cert(),
+            run_entry.ca_bundle(),
+            run_entry.ca_key(),
+        ] {
+            std::fs::write(&path, "").expect("write CA material");
+        }
+
+        let handle = handle_with(runtime_dir, identity);
+        let launch = launch_with_cwd_and_config(cwd, None);
+        let hardening = super::BwrapHardening::from_env(&launch.env);
+
+        let plan = super::BwrapMountPlan::build(&runtime_layout, &handle, &launch, &hardening)
+            .expect("build mount plan");
+
+        let rendered = rendered_plan(plan);
+        let mask = rendered
+            .iter()
+            .position(|arg| arg == &canonical(&control_plane))
+            .expect("control-plane runtime masked");
+        for public in [run_entry.ca_cert(), run_entry.ca_bundle()] {
+            let path = public.display().to_string();
+            let bind = rendered
+                .windows(3)
+                .position(|win| win[0] == "--ro-bind" && win[1] == path && win[2] == path)
+                .unwrap_or_else(|| panic!("{path} bound read-only through the mask"));
+            assert!(
+                mask < bind,
+                "{path} must be restored after the control-plane mask"
+            );
+        }
+        let key = run_entry.ca_key().display().to_string();
+        assert!(
+            !rendered.iter().any(|arg| arg == &key),
+            "the CA signing key must never be exposed to the sandbox"
+        );
+        let ca_dir = run_entry.ca_dir().display().to_string();
+        assert!(
+            !rendered.iter().any(|arg| arg == &ca_dir),
+            "binding the CA directory would also expose the signing key"
+        );
+    }
+
+    #[test]
+    #[cfg(target_os = "linux")]
+    fn filesystem_layout_skips_absent_ca_material() {
+        // With HTTPS MITM disabled no CA is generated, and the bundle exists
+        // only under `ca_trust_mode = "append_system_roots"`. Binding a missing
+        // source would make bwrap abort the launch.
+        let temp = tempfile::tempdir().expect("tempdir");
+        let cwd = temp.path().join("workspace");
+        std::fs::create_dir_all(&cwd).expect("mkdir workspace");
+        let runtime_dir = temp.path().join("runtime");
+        std::fs::create_dir_all(&runtime_dir).expect("mkdir runtime");
+
+        let identity =
+            crate::identity::RunIdentity::new(crate::identity::test_agent_id(), "generic");
+        let runtime_layout =
+            firma_runtime_state::RuntimeLayout::from_root(temp.path().join("control-plane"));
+        let run_entry = runtime_layout.run_entry_layout(&identity.sandbox_id);
+        std::fs::create_dir_all(run_entry.root()).expect("mkdir run entry");
+
+        let handle = handle_with(runtime_dir, identity);
+        let launch = launch_with_cwd_and_config(cwd, None);
+        let hardening = super::BwrapHardening::from_env(&launch.env);
+
+        let plan = super::BwrapMountPlan::build(&runtime_layout, &handle, &launch, &hardening)
+            .expect("build mount plan");
+
+        let rendered = rendered_plan(plan);
+        let ca_dir = run_entry.ca_dir().display().to_string();
+        assert!(
+            !rendered.iter().any(|arg| arg.starts_with(&ca_dir)),
+            "no CA path should be bound when the material is absent: {rendered:?}"
+        );
+    }
+
+    #[test]
+    #[cfg(target_os = "linux")]
+    fn filesystem_layout_restores_only_the_current_run_ca() {
+        // Run entries are siblings under `<runtime>/run`. A concurrent run's CA
+        // must stay behind the mask: the plan is keyed on this sandbox's
+        // identity, not on whatever CA files happen to exist.
+        let temp = tempfile::tempdir().expect("tempdir");
+        let cwd = temp.path().join("workspace");
+        std::fs::create_dir_all(&cwd).expect("mkdir workspace");
+        let runtime_dir = temp.path().join("runtime");
+        std::fs::create_dir_all(&runtime_dir).expect("mkdir runtime");
+
+        let identity =
+            crate::identity::RunIdentity::new(crate::identity::test_agent_id(), "generic");
+        let other = crate::identity::RunIdentity::new(crate::identity::test_agent_id(), "generic");
+        let runtime_layout =
+            firma_runtime_state::RuntimeLayout::from_root(temp.path().join("control-plane"));
+        let run_entry = runtime_layout.run_entry_layout(&identity.sandbox_id);
+        let other_entry = runtime_layout.run_entry_layout(&other.sandbox_id);
+        for entry in [&run_entry, &other_entry] {
+            std::fs::create_dir_all(entry.ca_dir()).expect("mkdir CA dir");
+            std::fs::write(entry.ca_cert(), "").expect("write CA cert");
+        }
+
+        let handle = handle_with(runtime_dir, identity);
+        let launch = launch_with_cwd_and_config(cwd, None);
+        let hardening = super::BwrapHardening::from_env(&launch.env);
+
+        let plan = super::BwrapMountPlan::build(&runtime_layout, &handle, &launch, &hardening)
+            .expect("build mount plan");
+
+        let rendered = rendered_plan(plan);
+        let own_cert = run_entry.ca_cert().display().to_string();
+        let other_cert = other_entry.ca_cert().display().to_string();
+        assert!(
+            rendered.iter().any(|arg| arg == &own_cert),
+            "this run's CA certificate must be restored"
+        );
+        assert!(
+            !rendered.iter().any(|arg| arg == &other_cert),
+            "another run's CA certificate must stay behind the mask"
+        );
+    }
+
     #[test]
     #[cfg(target_os = "linux")]
     fn mask_firma_dir_masks_home_firma_outside_cwd_ancestry() {

crates/firma-run/src/routing.rs

@@ -13,7 +13,7 @@ use firma_process_orchestrator::{
     ComponentEndpoint, ComponentSpec, LifecycleTimeouts, StackTopology, UnixEndpoint,
     spawn_stack_from_plan,
 };
-use firma_runtime_state::RuntimeLayout;
+use firma_runtime_state::{RunEntryLayout, RuntimeLayout};
 use firma_secret_provider::spec::http::HttpIntegrationSpec;
 
 #[cfg(unix)]
@@ -830,8 +830,9 @@ fn sidecar_trust_env_overrides(owned_sidecar_marker: Option<&Path>) -> BTreeMap<
     let Some(marker) = owned_sidecar_marker else {
         return env;
     };
-    let ca_dir = marker.join("firma-ca");
-    let ca_cert = ca_dir.join("firma-ca.crt");
+    let run_entry = RunEntryLayout::from_root(marker);
+    let ca_dir = run_entry.ca_dir();
+    let ca_cert = run_entry.ca_cert();
     env.insert(
         "FIRMA_SIDECAR_CA_DIR".to_string(),
         ca_dir.display().to_string(),

crates/firma-run/src/runtime/mod.rs

@@ -4,6 +4,7 @@ use std::path::PathBuf;
 use std::time::Duration;
 
 use firma_runtime_state::RuntimeLayout;
+use firma_runtime_state::runtime_paths::{CA_BUNDLE_FILE_NAME, CA_CERT_FILE_NAME, CA_DIR_NAME};
 use firma_secret_provider::IntegrationSpec;
 use serde::Serialize;
 
@@ -718,7 +719,7 @@ fn build_appended_ca_bundle_with_roots(firma_ca_path: &Path, roots: &[PathBuf])
         bundle.push(b'\n');
     }
     bundle.extend_from_slice(&firma_ca);
-    let bundle_path = firma_ca_path.with_file_name("firma-ca-bundle.crt");
+    let bundle_path = firma_ca_path.with_file_name(CA_BUNDLE_FILE_NAME);
     if let Err(error) = std::fs::write(&bundle_path, &bundle) {
         tracing::warn!(%error, path = %bundle_path.display(), "failed to write combined CA bundle; using sole firma-ca");
         return None;
@@ -752,7 +753,7 @@ fn resolve_sidecar_ca_cert_path(network_overrides: &BTreeMap<String, String>) ->
     if let Some(ca_dir) = network_overrides.get("FIRMA_SIDECAR_CA_DIR")
         && !ca_dir.trim().is_empty()
     {
-        let path = PathBuf::from(ca_dir).join("firma-ca.crt");
+        let path = PathBuf::from(ca_dir).join(CA_CERT_FILE_NAME);
         if path.is_file() {
             return Some(path);
         }
@@ -770,19 +771,19 @@ fn resolve_sidecar_ca_cert_path(network_overrides: &BTreeMap<String, String>) ->
     if let Ok(ca_dir) = std::env::var("FIRMA_SIDECAR_CA_DIR")
         && !ca_dir.trim().is_empty()
     {
-        let path = PathBuf::from(ca_dir).join("firma-ca.crt");
+        let path = PathBuf::from(ca_dir).join(CA_CERT_FILE_NAME);
         if path.is_file() {
             return Some(path);
         }
     }
 
     let cwd_candidate = std::env::current_dir()
         .ok()
-        .map(|cwd| cwd.join("firma-ca").join("firma-ca.crt"));
+        .map(|cwd| cwd.join(CA_DIR_NAME).join(CA_CERT_FILE_NAME));
     let default_candidates = [
         cwd_candidate,
-        Some(PathBuf::from("/etc/firma/ca/firma-ca.crt")),
-        Some(PathBuf::from("/var/lib/firma/ca/firma-ca.crt")),
+        Some(PathBuf::from("/etc/firma/ca").join(CA_CERT_FILE_NAME)),
+        Some(PathBuf::from("/var/lib/firma/ca").join(CA_CERT_FILE_NAME)),
     ];
 
     default_candidates

crates/firma-run/src/sidecar/config.rs

@@ -21,6 +21,7 @@ use sha2::{Digest, Sha256};
 use crate::error::RunError;
 use firma_config_loader::AgentProfile;
 use firma_identifiers::AgentId;
+use firma_runtime_state::RunEntryLayout;
 use firma_sidecar::authority_credentials::SidecarCredentialsConfig;
 
 const MINIMAL_MAPPING_RULES_TOML: &str = "\
@@ -898,7 +899,7 @@ fn override_ca_dir(value: &mut toml::Value, out_path: &Path) -> Result<(), RunEr
             out_path.display()
         ))
     })?;
-    let ca_dir = marker_dir.join("firma-ca");
+    let ca_dir = RunEntryLayout::from_root(marker_dir).ca_dir();
     let sidecar = sidecar_table_mut(value)?;
     let ca_table = sidecar
         .entry("ca".to_string())