fix(auth): harden sandbox identity checks

Require persisted sandbox records before IssueSandboxToken and RefreshSandboxToken mint gateway JWTs. This closes the stale-token path where a deleted sandbox identity could continue refreshing itself until token expiry windows were repeatedly extended.

Pin PushSandboxLogs streams to the first validated sandbox id. A sandbox now validates scope and sandbox existence once, then any later batch that changes sandbox_id is rejected instead of being accepted under the original validation.

For Kubernetes bootstrap, add service_account_name to the Kubernetes driver config, set it on sandbox pod specs, and require TokenReview usernames to match system:serviceaccount:<sandbox-namespace>:<service-account>. The Helm chart provisions a dedicated sandbox ServiceAccount, places it in the sandbox namespace, scopes sandbox RBAC there, and writes the generated name into gateway.toml.

Update Helm unit coverage, Helm README, gateway/driver docs, architecture notes, and debug-openshell-cluster guidance for the new sandbox ServiceAccount behavior.

Validation: mise run pre-commit; Kubernetes smoke e2e via helm-dev-environment/k3d; Docker smoke e2e; Podman smoke e2e.

Author: TaylorMutch

.agents/skills/debug-openshell-cluster/SKILL.md

@@ -212,6 +212,18 @@ helm -n openshell get values openshell | grep sandboxNamespace
 
 Then inspect sandbox resources in that namespace.
 
+Check the configured sandbox service account when TokenReview bootstrap or
+sandbox registration fails. Helm creates a dedicated sandbox service account by
+default and writes it to `[openshell.drivers.kubernetes].service_account_name`;
+the gateway rejects projected tokens from other service accounts.
+
+```bash
+helm -n openshell get values openshell | grep -A3 sandboxServiceAccount
+kubectl -n <sandbox-namespace> get serviceaccount openshell-sandbox
+kubectl -n openshell get configmap openshell-config -o jsonpath='{.data.gateway\.toml}'
+kubectl -n <sandbox-namespace> get sandbox <sandbox-name> -o jsonpath='{.spec.template.spec.serviceAccountName}{"\n"}'
+```
+
 ### Step 6: Check VM-Backed Gateways
 
 Use the VM driver logs and host diagnostics available in the user's environment. Verify:

architecture/gateway.md

@@ -50,10 +50,11 @@ Sandbox secrets are gateway-signed JWTs bound to a single sandbox ID. Docker,
 Podman, and VM drivers deliver the initial token through supervisor-only
 runtime material; Kubernetes supervisors exchange a projected ServiceAccount
 token through `IssueSandboxToken`. The gateway validates that projected token
-with Kubernetes `TokenReview`, checks the returned pod binding against the live
-pod UID, and reads the pod's sandbox annotation before minting the gateway JWT.
-Supervisors renew gateway JWTs in memory before expiry. Older tokens are not
-server-revoked; deployments bound replay exposure with short
+with Kubernetes `TokenReview`, requires the configured sandbox service account,
+checks the returned pod binding against the live pod UID, and reads the pod's
+sandbox annotation before minting the gateway JWT. Supervisors renew gateway
+JWTs in memory before expiry only while the sandbox record still exists. Older
+tokens are not server-revoked; deployments bound replay exposure with short
 `gateway_jwt.ttl_secs` lifetimes.
 
 Sandbox JWTs are not user credentials. The gRPC router accepts

crates/openshell-driver-kubernetes/README.md

@@ -38,6 +38,12 @@ The driver injects gateway callback configuration, sandbox identity, TLS client
 material, and the supervisor SSH socket path into the workload. Driver-owned
 values must override image-provided environment variables.
 
+Sandbox pods run as `service_account_name` and keep
+`automountServiceAccountToken: false`. The only Kubernetes token exposed to the
+supervisor is an explicit, audience-bound projected token mounted at
+`/var/run/secrets/openshell/token` for the one-shot `IssueSandboxToken`
+bootstrap exchange.
+
 The gateway uses the supervisor relay for connect, exec, and file sync. Sandbox
 pods do not need direct external ingress for SSH.
 

crates/openshell-driver-kubernetes/src/config.rs

@@ -7,6 +7,9 @@ use serde::{Deserialize, Serialize};
 /// Default Kubernetes namespace for sandbox resources.
 pub const DEFAULT_K8S_NAMESPACE: &str = "openshell";
 
+/// Default Kubernetes `ServiceAccount` assigned to sandbox pods.
+pub const DEFAULT_SANDBOX_SERVICE_ACCOUNT_NAME: &str = "default";
+
 /// Default storage size for the workspace PVC.
 pub const DEFAULT_WORKSPACE_STORAGE_SIZE: &str = "2Gi";
 
@@ -51,6 +54,9 @@ impl std::str::FromStr for SupervisorSideloadMethod {
 #[serde(default, deny_unknown_fields)]
 pub struct KubernetesComputeConfig {
     pub namespace: String,
+    /// Kubernetes `ServiceAccount` assigned to sandbox pods and accepted by
+    /// the gateway's `TokenReview` bootstrap authenticator.
+    pub service_account_name: String,
     pub default_image: String,
     pub image_pull_policy: String,
     /// Image that provides the `openshell-sandbox` supervisor binary.
@@ -91,6 +97,7 @@ impl Default for KubernetesComputeConfig {
     fn default() -> Self {
         Self {
             namespace: DEFAULT_K8S_NAMESPACE.to_string(),
+            service_account_name: DEFAULT_SANDBOX_SERVICE_ACCOUNT_NAME.to_string(),
             default_image: openshell_core::image::default_sandbox_image(),
             // Default empty so the gateway omits `imagePullPolicy` from pod
             // specs and Kubernetes applies its own default (Always for `latest`,
@@ -139,6 +146,15 @@ mod tests {
         );
     }
 
+    #[test]
+    fn default_service_account_name_is_default() {
+        let cfg = KubernetesComputeConfig::default();
+        assert_eq!(
+            cfg.service_account_name,
+            DEFAULT_SANDBOX_SERVICE_ACCOUNT_NAME
+        );
+    }
+
     #[test]
     fn serde_override_workspace_storage_size() {
         let json = serde_json::json!({
@@ -147,4 +163,13 @@ mod tests {
         let cfg: KubernetesComputeConfig = serde_json::from_value(json).unwrap();
         assert_eq!(cfg.workspace_default_storage_size, "10Gi");
     }
+
+    #[test]
+    fn serde_override_service_account_name() {
+        let json = serde_json::json!({
+            "service_account_name": "openshell-sandbox"
+        });
+        let cfg: KubernetesComputeConfig = serde_json::from_value(json).unwrap();
+        assert_eq!(cfg.service_account_name, "openshell-sandbox");
+    }
 }

crates/openshell-driver-kubernetes/src/driver.rs

@@ -4,7 +4,8 @@
 //! Kubernetes compute driver.
 
 use crate::config::{
-    DEFAULT_WORKSPACE_STORAGE_SIZE, KubernetesComputeConfig, SupervisorSideloadMethod,
+    DEFAULT_SANDBOX_SERVICE_ACCOUNT_NAME, DEFAULT_WORKSPACE_STORAGE_SIZE, KubernetesComputeConfig,
+    SupervisorSideloadMethod,
 };
 use futures::{Stream, StreamExt, TryStreamExt};
 use k8s_openapi::api::core::v1::{Event as KubeEventObj, Node};
@@ -320,6 +321,7 @@ impl KubernetesComputeDriver {
             supervisor_image: &self.config.supervisor_image,
             supervisor_image_pull_policy: &self.config.supervisor_image_pull_policy,
             supervisor_sideload_method: self.config.supervisor_sideload_method,
+            service_account_name: &self.config.service_account_name,
             sandbox_id: &sandbox.id,
             sandbox_name: &sandbox.name,
             grpc_endpoint: &self.config.grpc_endpoint,
@@ -1048,6 +1050,7 @@ struct SandboxPodParams<'a> {
     supervisor_image: &'a str,
     supervisor_image_pull_policy: &'a str,
     supervisor_sideload_method: SupervisorSideloadMethod,
+    service_account_name: &'a str,
     sandbox_id: &'a str,
     sandbox_name: &'a str,
     grpc_endpoint: &'a str,
@@ -1069,6 +1072,7 @@ impl Default for SandboxPodParams<'_> {
             supervisor_image: "",
             supervisor_image_pull_policy: "",
             supervisor_sideload_method: SupervisorSideloadMethod::default(),
+            service_account_name: DEFAULT_SANDBOX_SERVICE_ACCOUNT_NAME,
             sandbox_id: "",
             sandbox_name: "",
             grpc_endpoint: "",
@@ -1223,6 +1227,13 @@ fn sandbox_template_to_k8s(
         }
     }
 
+    if !params.service_account_name.is_empty() {
+        spec.insert(
+            "serviceAccountName".to_string(),
+            serde_json::json!(params.service_account_name),
+        );
+    }
+
     // Disable service account token auto-mounting for security hardening.
     // Sandbox pods should not have access to the Kubernetes API by default.
     spec.insert(
@@ -2492,6 +2503,32 @@ mod tests {
         );
     }
 
+    #[test]
+    fn sandbox_template_sets_configured_service_account_name() {
+        let params = SandboxPodParams {
+            service_account_name: "openshell-sandbox",
+            ..Default::default()
+        };
+        let pod_template = sandbox_template_to_k8s(
+            &SandboxTemplate::default(),
+            false,
+            &std::collections::HashMap::new(),
+            true,
+            &params,
+        );
+
+        assert_eq!(
+            pod_template["spec"]["serviceAccountName"],
+            serde_json::json!("openshell-sandbox"),
+            "sandbox pods must run under the configured service account"
+        );
+        assert_eq!(
+            pod_template["spec"]["automountServiceAccountToken"],
+            serde_json::json!(false),
+            "explicit service account selection must not re-enable default token automounting"
+        );
+    }
+
     #[test]
     fn platform_config_bool_extracts_value() {
         let template = SandboxTemplate {

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

@@ -6,7 +6,8 @@ pub mod driver;
 pub mod grpc;
 
 pub use config::{
-    DEFAULT_WORKSPACE_STORAGE_SIZE, KubernetesComputeConfig, SupervisorSideloadMethod,
+    DEFAULT_SANDBOX_SERVICE_ACCOUNT_NAME, DEFAULT_WORKSPACE_STORAGE_SIZE, KubernetesComputeConfig,
+    SupervisorSideloadMethod,
 };
 pub use driver::{KubernetesComputeDriver, KubernetesDriverError};
 pub use grpc::ComputeDriverService;

crates/openshell-driver-kubernetes/src/main.rs

@@ -10,8 +10,8 @@ use tracing_subscriber::EnvFilter;
 use openshell_core::VERSION;
 use openshell_core::proto::compute::v1::compute_driver_server::ComputeDriverServer;
 use openshell_driver_kubernetes::{
-    ComputeDriverService, KubernetesComputeConfig, KubernetesComputeDriver,
-    SupervisorSideloadMethod,
+    ComputeDriverService, DEFAULT_SANDBOX_SERVICE_ACCOUNT_NAME, KubernetesComputeConfig,
+    KubernetesComputeDriver, SupervisorSideloadMethod,
 };
 
 #[derive(Parser, Debug)]
@@ -31,6 +31,13 @@ struct Args {
     #[arg(long, env = "OPENSHELL_SANDBOX_NAMESPACE", default_value = "default")]
     sandbox_namespace: String,
 
+    #[arg(
+        long,
+        env = "OPENSHELL_K8S_SANDBOX_SERVICE_ACCOUNT",
+        default_value = DEFAULT_SANDBOX_SERVICE_ACCOUNT_NAME
+    )]
+    sandbox_service_account: String,
+
     #[arg(long, env = "OPENSHELL_SANDBOX_IMAGE")]
     sandbox_image: Option<String>,
 
@@ -88,6 +95,7 @@ async fn main() -> Result<()> {
 
     let driver = KubernetesComputeDriver::new(KubernetesComputeConfig {
         namespace: args.sandbox_namespace,
+        service_account_name: args.sandbox_service_account,
         default_image: args.sandbox_image.unwrap_or_default(),
         image_pull_policy: args.sandbox_image_pull_policy.unwrap_or_default(),
         supervisor_image: args

crates/openshell-server/src/auth/k8s_sa.rs

@@ -137,17 +137,24 @@ pub struct LiveK8sResolver {
     pods_api: Api<Pod>,
     expected_audience: String,
     sandbox_namespace: String,
+    expected_service_account: String,
 }
 
 impl LiveK8sResolver {
-    pub fn new(client: kube::Client, namespace: &str, expected_audience: String) -> Self {
+    pub fn new(
+        client: kube::Client,
+        namespace: &str,
+        expected_audience: String,
+        expected_service_account: String,
+    ) -> Self {
         let token_reviews_api: Api<TokenReview> = Api::all(client.clone());
         let pods_api: Api<Pod> = Api::namespaced(client, namespace);
         Self {
             token_reviews_api,
             pods_api,
             expected_audience,
             sandbox_namespace: namespace.to_string(),
+            expected_service_account,
         }
     }
 }
@@ -175,15 +182,20 @@ impl K8sIdentityResolver for LiveK8sResolver {
         let status = review
             .status
             .ok_or_else(|| Status::internal("TokenReview response missing status"))?;
-        let Some(identity) =
-            token_review_identity(&status, &self.expected_audience, &self.sandbox_namespace)?
+        let Some(identity) = token_review_identity(
+            &status,
+            &self.expected_audience,
+            &self.sandbox_namespace,
+            &self.expected_service_account,
+        )?
         else {
             return Ok(None);
         };
 
         info!(
             pod_name = %identity.pod_name,
             pod_uid = %identity.pod_uid,
+            service_account = %self.expected_service_account,
             "validated K8s SA token via TokenReview"
         );
 
@@ -243,6 +255,7 @@ fn token_review_identity(
     status: &TokenReviewStatus,
     expected_audience: &str,
     sandbox_namespace: &str,
+    expected_service_account: &str,
 ) -> Result<Option<TokenReviewIdentity>, Status> {
     if status.authenticated != Some(true) {
         debug!(
@@ -270,15 +283,17 @@ fn token_review_identity(
         .username
         .as_deref()
         .ok_or_else(|| Status::permission_denied("TokenReview response missing username"))?;
-    let expected_prefix = format!("system:serviceaccount:{sandbox_namespace}:");
-    if !username.starts_with(&expected_prefix) {
+    let expected_username =
+        format!("system:serviceaccount:{sandbox_namespace}:{expected_service_account}");
+    if username != expected_username {
         warn!(
             username = %username,
             sandbox_namespace = %sandbox_namespace,
-            "K8s TokenReview principal is outside the sandbox namespace"
+            service_account = %expected_service_account,
+            "K8s TokenReview principal is not the configured sandbox service account"
         );
         return Err(Status::permission_denied(
-            "SA token is outside the sandbox namespace",
+            "SA token is not from the configured sandbox service account",
         ));
     }
 
@@ -388,7 +403,7 @@ mod tests {
             ],
         );
 
-        let identity = token_review_identity(&status, "openshell-gateway", "openshell")
+        let identity = token_review_identity(&status, "openshell-gateway", "openshell", "default")
             .unwrap()
             .expect("authenticated token should resolve");
 
@@ -405,7 +420,7 @@ mod tests {
         };
 
         assert!(
-            token_review_identity(&status, "openshell-gateway", "openshell")
+            token_review_identity(&status, "openshell-gateway", "openshell", "default")
                 .unwrap()
                 .is_none()
         );
@@ -423,7 +438,7 @@ mod tests {
             ],
         );
 
-        let err = token_review_identity(&status, "openshell-gateway", "openshell")
+        let err = token_review_identity(&status, "openshell-gateway", "openshell", "default")
             .expect_err("wrong audience must fail closed");
         assert_eq!(err.code(), tonic::Code::Unauthenticated);
     }
@@ -440,11 +455,28 @@ mod tests {
             ],
         );
 
-        let err = token_review_identity(&status, "openshell-gateway", "openshell")
+        let err = token_review_identity(&status, "openshell-gateway", "openshell", "default")
             .expect_err("other namespace must be rejected");
         assert_eq!(err.code(), tonic::Code::PermissionDenied);
     }
 
+    #[test]
+    fn token_review_identity_requires_configured_service_account() {
+        let status = token_review_status(
+            true,
+            vec!["openshell-gateway"],
+            "system:serviceaccount:openshell:other",
+            vec![
+                (POD_NAME_EXTRA, "openshell-sandbox-a"),
+                (POD_UID_EXTRA, "uid-a"),
+            ],
+        );
+
+        let err = token_review_identity(&status, "openshell-gateway", "openshell", "default")
+            .expect_err("other service account must be rejected");
+        assert_eq!(err.code(), tonic::Code::PermissionDenied);
+    }
+
     #[test]
     fn token_review_identity_requires_pod_bound_extras() {
         let status = token_review_status(
@@ -454,7 +486,7 @@ mod tests {
             vec![],
         );
 
-        let err = token_review_identity(&status, "openshell-gateway", "openshell")
+        let err = token_review_identity(&status, "openshell-gateway", "openshell", "default")
             .expect_err("non pod-bound tokens must be rejected");
         assert_eq!(err.code(), tonic::Code::PermissionDenied);
     }