refactor(auth): separate sandbox identity from TLS (#3110)

* refactor(auth): separate sandbox identity from TLS

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

* docs(auth): clarify gateway mTLS behavior

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

* test(auth): include workspace scope in TLS authorization checks

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

* test(e2e): bound service auth sandbox names for large PIDs

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

---------

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

Author: drew

.agents/skills/helm-dev-environment/SKILL.md

@@ -83,7 +83,10 @@ capability-free workload Pod and a directly managed capability-free supervisor
 Pod. One namespace-wide NetworkPolicy denies direct egress from every OpenShell
 workload Pod. The
 `pkiInitJob` hook (a pre-install Job that runs `openshell-gateway generate-certs`)
-generates mTLS secrets on first install. The default Skaffold values export
+generates gateway and CLI TLS secrets on first install. Supervisor Pods project
+only `ca.crt` and authenticate gateway RPCs with sandbox bearer tokens. User
+client certificates and private keys remain outside supervisor and workload Pods.
+The default Skaffold values export
 gateway and Kubernetes-driver traces to the collector service installed by
 `helm:k3s:create`. Envoy Gateway is opt-in; see the Optional Add-ons section.
 

crates/openshell-bootstrap/src/pki.rs

@@ -93,7 +93,7 @@ pub fn generate_pki(extra_sans: &[String]) -> Result<PkiBundle> {
         .into_diagnostic()
         .wrap_err("failed to sign server certificate")?;
 
-    // --- Client cert (shared by CLI and sandbox pods) ---
+    // --- User client cert (CLI only; sandboxes use bearer identity) ---
     let client_key = KeyPair::generate()
         .into_diagnostic()
         .wrap_err("failed to generate client key")?;

crates/openshell-core/src/config.rs

@@ -378,13 +378,13 @@ pub struct OidcConfig {
     pub scopes_claim: String,
 }
 
-/// mTLS user authentication for local, single-user gateways.
+/// mTLS user authentication for gateway users.
 #[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct MtlsAuthConfig {
     /// When true, the gateway maps a verified TLS client certificate into a
-    /// user principal. Keep disabled for Kubernetes deployments because
-    /// Kubernetes sandbox pods and external users must not share user auth.
+    /// user principal. Sandbox and supervisor clients use bearer identity, so
+    /// this setting is independent of the selected compute driver.
     #[serde(default)]
     pub enabled: bool,
 }

crates/openshell-core/src/container_paths.rs

@@ -44,8 +44,6 @@ pub const SUPERVISOR_CONTAINER_DIR: &str = "/opt/openshell/bin";
 pub const SUPERVISOR_CONTAINER_BINARY: &str = "/opt/openshell/bin/openshell-sandbox";
 pub const TLS_CLIENT_DIR: &str = "/etc/openshell/tls/client";
 pub const TLS_CA_MOUNT_PATH: &str = "/etc/openshell/tls/client/ca.crt";
-pub const TLS_CERT_MOUNT_PATH: &str = "/etc/openshell/tls/client/tls.crt";
-pub const TLS_KEY_MOUNT_PATH: &str = "/etc/openshell/tls/client/tls.key";
 pub const SANDBOX_TOKEN_MOUNT_PATH: &str = "/etc/openshell/auth/sandbox.jwt";
 pub const UPSTREAM_PROXY_AUTH_MOUNT_PATH: &str = "/etc/openshell/auth/upstream-proxy";
 pub const CONTAINER_POLICY_PATH: &str = "/etc/openshell/policy.yaml";
@@ -60,8 +58,6 @@ pub const SUPERVISOR_CA_CERT_PATH: &str = "/etc/openshell-tls/openshell-ca.pem";
 pub const SUPERVISOR_CA_BUNDLE_PATH: &str = "/etc/openshell-tls/ca-bundle.pem";
 
 pub const VM_GUEST_TLS_CA_PATH: &str = "/opt/openshell/tls/ca.crt";
-pub const VM_GUEST_TLS_CERT_PATH: &str = "/opt/openshell/tls/tls.crt";
-pub const VM_GUEST_TLS_KEY_PATH: &str = "/opt/openshell/tls/tls.key";
 pub const VM_GUEST_SANDBOX_TOKEN_PATH: &str = "/opt/openshell/auth/sandbox.jwt";
 pub const VM_GUEST_INIT_DROPIN_DIR: &str = "/opt/openshell/init.d";
 pub const VM_GUEST_INIT_DROPIN_MANIFEST: &str = "/opt/openshell/init.d.manifest";
@@ -109,8 +105,6 @@ mod tests {
             SUPERVISOR_CONTAINER_BINARY,
             TLS_CLIENT_DIR,
             TLS_CA_MOUNT_PATH,
-            TLS_CERT_MOUNT_PATH,
-            TLS_KEY_MOUNT_PATH,
             SANDBOX_TOKEN_MOUNT_PATH,
             UPSTREAM_PROXY_AUTH_MOUNT_PATH,
             CONTAINER_POLICY_PATH,
@@ -123,8 +117,6 @@ mod tests {
             SUPERVISOR_CA_CERT_PATH,
             SUPERVISOR_CA_BUNDLE_PATH,
             VM_GUEST_TLS_CA_PATH,
-            VM_GUEST_TLS_CERT_PATH,
-            VM_GUEST_TLS_KEY_PATH,
             VM_GUEST_SANDBOX_TOKEN_PATH,
             VM_GUEST_UPSTREAM_PROXY_AUTH_PATH,
             VM_GUEST_PROXY_CA_PATH,

crates/openshell-core/src/driver_utils.rs

@@ -104,22 +104,15 @@ pub const SUPERVISOR_CONTAINER_BINARY: &str = "/opt/openshell/bin/openshell-sand
 // ---------------------------------------------------------------------------
 // In-container mount paths for guest TLS materials and the sandbox token.
 //
-// All container-based drivers (Docker, Podman, Kubernetes) mount the gateway's
-// mTLS client credentials at these fixed paths inside every sandbox container.
-// The supervisor reads these paths on startup to establish its gRPC-over-mTLS
-// connection back to the gateway. The paths must remain stable across driver
-// versions since the supervisor binary is built and packaged separately.
+// Container-based drivers mount the gateway CA at this fixed path inside every
+// supervisor container. The supervisor reads it on startup to authenticate the
+// gateway TLS endpoint. Sandbox identity is provided separately by a bearer
+// token.
 // ---------------------------------------------------------------------------
 
-/// Container-side mount path for the guest mTLS CA certificate.
+/// Container-side mount path for the gateway CA certificate.
 pub const TLS_CA_MOUNT_PATH: &str = "/etc/openshell/tls/client/ca.crt";
 
-/// Container-side mount path for the guest mTLS client certificate.
-pub const TLS_CERT_MOUNT_PATH: &str = "/etc/openshell/tls/client/tls.crt";
-
-/// Container-side mount path for the guest mTLS client private key.
-pub const TLS_KEY_MOUNT_PATH: &str = "/etc/openshell/tls/client/tls.key";
-
 /// Container-side mount path for the per-sandbox JWT token.
 pub const SANDBOX_TOKEN_MOUNT_PATH: &str = "/etc/openshell/auth/sandbox.jwt";
 

crates/openshell-core/src/grpc_client.rs

@@ -40,7 +40,7 @@ use openshell_extension_core::{BearerTokenSlot, ExtensionCredentialStore};
 use tonic::Status;
 use tonic::metadata::AsciiMetadataValue;
 use tonic::service::interceptor::InterceptedService;
-use tonic::transport::{Certificate, Channel, ClientTlsConfig, Endpoint, Identity};
+use tonic::transport::{Certificate, Channel, ClientTlsConfig, Endpoint};
 use tracing::{debug, info, warn};
 
 /// Preserve the gRPC status as a source so callers can classify retryable errors.
@@ -201,10 +201,9 @@ impl tonic::service::Interceptor for AuthInterceptor {
 
 /// Build the plain (un-intercepted) gRPC channel.
 ///
-/// When the endpoint uses `https://`, mTLS is configured using these env vars:
+/// When the endpoint uses `https://`, server-authenticated TLS is configured
+/// using this env var:
 /// - `OPENSHELL_TLS_CA` -- path to the CA certificate
-/// - `OPENSHELL_TLS_CERT` -- path to the client certificate
-/// - `OPENSHELL_TLS_KEY` -- path to the client private key
 ///
 /// When the endpoint uses `http://`, a plaintext connection is used (for
 /// deployments where TLS is disabled, e.g. behind a Cloudflare Tunnel).
@@ -223,34 +222,20 @@ async fn build_plain_channel(endpoint: &str) -> Result<Channel> {
 
     let tls_enabled = endpoint.starts_with("https://");
 
-    // TODO: TLS certs are loaded once here and never re-read. The gateway
+    // TODO: The TLS CA is loaded once here and never re-read. The gateway
     // server side supports hot-reload (ArcSwap + notify in tls.rs). The
     // supervisor should do the same so that cert-manager rotations take
     // effect without restarting the sandbox.
     if tls_enabled {
         let ca_path = std::env::var(sandbox_env::TLS_CA)
             .into_diagnostic()
             .wrap_err("OPENSHELL_TLS_CA is required")?;
-        let cert_path = std::env::var(sandbox_env::TLS_CERT)
-            .into_diagnostic()
-            .wrap_err("OPENSHELL_TLS_CERT is required")?;
-        let key_path = std::env::var(sandbox_env::TLS_KEY)
-            .into_diagnostic()
-            .wrap_err("OPENSHELL_TLS_KEY is required")?;
-
         let ca_pem = std::fs::read(&ca_path)
             .into_diagnostic()
             .wrap_err_with(|| format!("failed to read CA cert from {ca_path}"))?;
-        let cert_pem = std::fs::read(&cert_path)
-            .into_diagnostic()
-            .wrap_err_with(|| format!("failed to read client cert from {cert_path}"))?;
-        let key_pem = std::fs::read(&key_path)
-            .into_diagnostic()
-            .wrap_err_with(|| format!("failed to read client key from {key_path}"))?;
 
         // Trust only the configured CA — this is the chart's internal CA
-        // that signs both the gateway's internal server certificate and
-        // this client's identity certificate.  The gateway uses SNI-based
+        // that signs the gateway's internal server certificate. The gateway uses SNI-based
         // certificate selection to present this internal cert to supervisor
         // connections, so no public root trust is needed here.
         //
@@ -259,9 +244,7 @@ async fn build_plain_channel(endpoint: &str) -> Result<Channel> {
         // (Docker/Podman drivers), and broadening the trust store would let
         // an attacker who controls the image + DNS present a publicly valid
         // certificate and intercept the supervisor→gateway TLS connection.
-        let mut tls_config = ClientTlsConfig::new()
-            .ca_certificate(Certificate::from_pem(ca_pem))
-            .identity(Identity::from_pem(cert_pem, key_pem));
+        let mut tls_config = ClientTlsConfig::new().ca_certificate(Certificate::from_pem(ca_pem));
         if let Ok(server_name) = std::env::var(sandbox_env::GATEWAY_TLS_SERVER_NAME)
             && !server_name.is_empty()
         {

crates/openshell-core/src/sandbox_env.rs

@@ -185,7 +185,7 @@ pub const PROXY_CA_KEY: &str = "OPENSHELL_PROXY_CA_KEY";
 /// Whether the control-owned SSH Unix socket is shared across trusted UIDs.
 pub const SSH_SOCKET_SHARED: &str = "OPENSHELL_SSH_SOCKET_SHARED";
 
-/// Path to the CA certificate for mTLS communication with the gateway.
+/// Path to the CA certificate used to authenticate the gateway TLS endpoint.
 pub const TLS_CA: &str = "OPENSHELL_TLS_CA";
 
 /// Path to the client certificate for mTLS communication with the gateway.

crates/openshell-driver-docker/README.md

@@ -177,6 +177,10 @@ The driver publishes host loopback as the backend address for
 mediated path, so policies can reach host services without a Docker bridge,
 container DNS alias, or another gateway listener.
 
+For HTTPS endpoints, the supervisor receives only the gateway CA and
+uses its sandbox-scoped bearer token to authenticate RPCs. User client
+certificates and private keys are not delivered to either container.
+
 Docker Engine on Linux supports host networking directly. Docker Desktop
 requires host networking to be enabled in Settings and does not support it
 when Enhanced Container Isolation is enabled.
@@ -189,7 +193,7 @@ The supervisor owns these security-critical variables:
 - `OPENSHELL_SANDBOX_TOKEN_FILE`
 - `OPENSHELL_SSH_SOCKET_PATH`
 - `OPENSHELL_MAIN_PROCESS_SPEC`
-- TLS path variables when HTTPS is enabled
+- `OPENSHELL_TLS_CA` when HTTPS is enabled
 
 Template and sandbox environment is encoded in the protected bootstrap and
 exposed only to workload children. Workload input cannot override

crates/openshell-driver-docker/src/lib.rs

@@ -189,13 +189,15 @@ pub struct DockerComputeConfig {
     /// Image containing the trusted `openshell-supervisor` binary.
     pub supervisor_image: Option<String>,
 
-    /// Host-side CA certificate for Docker sandbox mTLS.
+    /// Host-side CA certificate for sandbox-to-gateway TLS.
     pub guest_tls_ca: Option<PathBuf>,
 
-    /// Host-side client certificate for Docker sandbox mTLS.
+    /// Deprecated. Sandboxes authenticate with bearer tokens and must not
+    /// receive a user client certificate.
     pub guest_tls_cert: Option<PathBuf>,
 
-    /// Host-side private key for Docker sandbox mTLS.
+    /// Deprecated. Sandboxes authenticate with bearer tokens and must not
+    /// receive a user client private key.
     pub guest_tls_key: Option<PathBuf>,
 
     /// Unix socket path used for interactive sandbox access.
@@ -293,8 +295,6 @@ impl Default for DockerComputeConfig {
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub(crate) struct DockerGuestTlsPaths {
     pub(crate) ca: PathBuf,
-    pub(crate) cert: PathBuf,
-    pub(crate) key: PathBuf,
 }
 
 #[derive(Debug, Clone)]
@@ -4676,11 +4676,7 @@ async fn docker_supervisor_bundle_archive(
             SUPERVISOR_UID,
             SUPERVISOR_GID,
         )?;
-        for (name, path) in [
-            ("ca.pem", &tls.ca),
-            ("cert.pem", &tls.cert),
-            ("key.pem", &tls.key),
-        ] {
+        for (name, path) in [("ca.pem", &tls.ca)] {
             let contents = tokio::fs::read(path).await.map_err(|error| {
                 Status::internal(format!(
                     "read Docker supervisor TLS file {}: {error}",
@@ -5097,20 +5093,10 @@ async fn spawn_docker_control_process(
         ),
     ];
     if config.guest_tls.is_some() {
-        environment.extend([
-            format!(
-                "{}={SUPERVISOR_STATE_MOUNT_PATH}/tls/ca.pem",
-                openshell_core::sandbox_env::TLS_CA
-            ),
-            format!(
-                "{}={SUPERVISOR_STATE_MOUNT_PATH}/tls/cert.pem",
-                openshell_core::sandbox_env::TLS_CERT
-            ),
-            format!(
-                "{}={SUPERVISOR_STATE_MOUNT_PATH}/tls/key.pem",
-                openshell_core::sandbox_env::TLS_KEY
-            ),
-        ]);
+        environment.push(format!(
+            "{}={SUPERVISOR_STATE_MOUNT_PATH}/tls/ca.pem",
+            openshell_core::sandbox_env::TLS_CA
+        ));
     }
     if let Some(socket) = config.provider_spiffe_workload_api_socket.as_ref() {
         let projected = openshell_core::driver_utils::projected_provider_spiffe_socket_path(socket)
@@ -6505,8 +6491,6 @@ fn canonicalize_existing_file(path: &Path, description: &str) -> CoreResult<Path
 
 fn docker_guest_tls_configured(docker_config: &DockerComputeConfig) -> bool {
     docker_config.guest_tls_ca.is_some()
-        && docker_config.guest_tls_cert.is_some()
-        && docker_config.guest_tls_key.is_some()
 }
 
 fn default_docker_supervisor_grpc_endpoint(gateway_port: u16, tls: bool) -> String {
@@ -6521,24 +6505,25 @@ pub(crate) fn docker_guest_tls_paths(
         || docker_config.guest_tls_cert.is_some()
         || docker_config.guest_tls_key.is_some();
 
+    if docker_config.guest_tls_cert.is_some() || docker_config.guest_tls_key.is_some() {
+        return Err(Error::config(
+            "guest_tls_cert and guest_tls_key are no longer supported; sandboxes authenticate to the gateway with bearer tokens",
+        ));
+    }
+
     if !docker_config.grpc_endpoint.starts_with("https://") {
         if tls_flags_provided {
             return Err(Error::config(format!(
-                "guest_tls_ca/guest_tls_cert/guest_tls_key were provided but grpc_endpoint is '{}'; TLS materials require an https:// endpoint",
+                "guest_tls_ca was provided but grpc_endpoint is '{}'; TLS materials require an https:// endpoint",
                 docker_config.grpc_endpoint,
             )));
         }
         return Ok(None);
     }
 
-    let provided = [
-        docker_config.guest_tls_ca.as_ref(),
-        docker_config.guest_tls_cert.as_ref(),
-        docker_config.guest_tls_key.as_ref(),
-    ];
-    if provided.iter().all(Option::is_none) {
+    if docker_config.guest_tls_ca.is_none() {
         return Err(Error::config(
-            "docker compute driver requires guest_tls_ca, guest_tls_cert, and guest_tls_key when grpc_endpoint uses https://",
+            "docker compute driver requires guest_tls_ca when grpc_endpoint uses https://",
         ));
     }
 
@@ -6547,21 +6532,8 @@ pub(crate) fn docker_guest_tls_paths(
             "guest_tls_ca is required when Docker sandbox TLS materials are configured",
         ));
     };
-    let Some(cert) = docker_config.guest_tls_cert.clone() else {
-        return Err(Error::config(
-            "guest_tls_cert is required when Docker sandbox TLS materials are configured",
-        ));
-    };
-    let Some(key) = docker_config.guest_tls_key.clone() else {
-        return Err(Error::config(
-            "guest_tls_key is required when Docker sandbox TLS materials are configured",
-        ));
-    };
-
     Ok(Some(DockerGuestTlsPaths {
         ca: canonicalize_existing_file(&ca, "docker TLS CA certificate")?,
-        cert: canonicalize_existing_file(&cert, "docker TLS client certificate")?,
-        key: canonicalize_existing_file(&key, "docker TLS client private key")?,
     }))
 }
 

crates/openshell-driver-docker/src/tests.rs

@@ -188,8 +188,6 @@ fn runtime_config() -> DockerDriverRuntimeConfig {
         ssh_socket_path: openshell_core::container_paths::SSH_SOCKET_PATH.to_string(),
         guest_tls: Some(DockerGuestTlsPaths {
             ca: PathBuf::from("/tmp/ca.crt"),
-            cert: PathBuf::from("/tmp/tls.crt"),
-            key: PathBuf::from("/tmp/tls.key"),
         }),
         gpu: DockerGpuRuntimeCapabilities {
             cdi_supported: false,
@@ -3237,18 +3235,19 @@ fn workload_mounts_only_the_shared_channel_volume() {
 }
 
 #[test]
-fn docker_guest_tls_paths_require_all_files_for_https() {
+fn docker_guest_tls_paths_accept_ca_only_for_https() {
     let tempdir = TempDir::new().unwrap();
     let ca = tempdir.path().join("ca.crt");
     fs::write(&ca, b"ca").unwrap();
 
-    let err = docker_guest_tls_paths(&DockerComputeConfig {
+    let paths = docker_guest_tls_paths(&DockerComputeConfig {
         grpc_endpoint: "https://localhost:8443".to_string(),
-        guest_tls_ca: Some(ca),
+        guest_tls_ca: Some(ca.clone()),
         ..Default::default()
     })
-    .unwrap_err();
-    assert!(err.to_string().contains("guest_tls_cert"));
+    .unwrap()
+    .expect("CA-only TLS paths");
+    assert_eq!(paths.ca, ca.canonicalize().unwrap());
 }
 
 #[test]