refactor!(auth): drop SSH handshake secret in favor of mTLS

The OPENSHELL_SSH_HANDSHAKE_SECRET / x-sandbox-secret mechanism was
misnamed: it does not authenticate SSH (which flows over the
RelayStream gRPC RPC and is gated by mTLS plus supervisor Unix-socket
permissions). It only gated a small set of sandbox-to-gateway
control-plane RPCs, and production deployments already enforce mTLS
on that channel — so the shared secret was redundant.

Replace the secret check with an mTLS-presence marker. Sandbox-class
methods (ReportPolicyStatus, PushSandboxLogs,
GetSandboxProviderEnvironment, SubmitPolicyAnalysis, GetSandboxConfig,
GetInferenceBundle) accept callers without a Bearer token; the gRPC
mTLS handshake is the trust boundary. Dual-auth methods treat
Bearer-present as full-scope CLI access and Bearer-absent as
sandbox-restricted scope via validate_sandbox_caller_update.

Drops the secret from all drivers (K8s, Podman, VM), the sandbox gRPC
interceptor, the Helm chart (values + pre-install hook + StatefulSet
env), the RPM bootstrap script, the man pages, and the
debug-openshell-cluster skill. Also removes the never-read
ssh_handshake_skew_secs flag and config field.

BREAKING CHANGE: --ssh-handshake-secret / OPENSHELL_SSH_HANDSHAKE_SECRET
and --ssh-handshake-skew-secs / OPENSHELL_SSH_HANDSHAKE_SKEW_SECS are
removed from the gateway, sandbox, and all driver binaries. The
openshell-ssh-handshake K8s Secret is no longer managed by the chart;
operators may delete the orphan. Deployments using
--disable-gateway-auth must enforce caller authentication at the
fronting proxy, since the gateway no longer validates a per-request
secret on sandbox-class methods.

Refs OS-174.

Author: TaylorMutch

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

@@ -114,7 +114,6 @@ Check required Helm deployment secrets:
 
 ```bash
 kubectl -n openshell get secret \
-  openshell-ssh-handshake \
   openshell-server-tls \
   openshell-server-client-ca \
   openshell-client-tls

crates/openshell-core/src/config.rs

@@ -27,9 +27,6 @@ pub const DEFAULT_SERVER_PORT: u16 = 8080;
 /// Default container stop timeout in seconds (SIGTERM → SIGKILL).
 pub const DEFAULT_STOP_TIMEOUT_SECS: u32 = 10;
 
-/// Default allowed clock skew for SSH handshake validation, in seconds.
-pub const DEFAULT_SSH_HANDSHAKE_SKEW_SECS: u64 = 300;
-
 /// Default Podman bridge network name.
 pub const DEFAULT_NETWORK_NAME: &str = "openshell";
 
@@ -272,14 +269,6 @@ pub struct Config {
     #[serde(default = "default_sandbox_ssh_socket_path")]
     pub sandbox_ssh_socket_path: String,
 
-    /// Shared secret for gateway-to-sandbox SSH handshake.
-    #[serde(default)]
-    pub ssh_handshake_secret: String,
-
-    /// Allowed clock skew for SSH handshake validation, in seconds.
-    #[serde(default = "default_ssh_handshake_skew_secs")]
-    pub ssh_handshake_skew_secs: u64,
-
     /// TTL for SSH session tokens, in seconds. 0 disables expiry.
     #[serde(default = "default_ssh_session_ttl_secs")]
     pub ssh_session_ttl_secs: u64,
@@ -429,8 +418,6 @@ impl Config {
             ssh_gateway_port: default_ssh_gateway_port(),
             sandbox_ssh_port: default_sandbox_ssh_port(),
             sandbox_ssh_socket_path: default_sandbox_ssh_socket_path(),
-            ssh_handshake_secret: String::new(),
-            ssh_handshake_skew_secs: default_ssh_handshake_skew_secs(),
             ssh_session_ttl_secs: default_ssh_session_ttl_secs(),
             client_tls_secret_name: String::new(),
             host_gateway_ip: String::new(),
@@ -544,20 +531,6 @@ impl Config {
         self
     }
 
-    /// Create a new configuration with the SSH handshake secret.
-    #[must_use]
-    pub fn with_ssh_handshake_secret(mut self, secret: impl Into<String>) -> Self {
-        self.ssh_handshake_secret = secret.into();
-        self
-    }
-
-    /// Create a new configuration with SSH handshake skew allowance.
-    #[must_use]
-    pub const fn with_ssh_handshake_skew_secs(mut self, secs: u64) -> Self {
-        self.ssh_handshake_skew_secs = secs;
-        self
-    }
-
     /// Create a new configuration with the SSH session TTL.
     #[must_use]
     pub const fn with_ssh_session_ttl_secs(mut self, secs: u64) -> Self {
@@ -707,10 +680,6 @@ const fn default_sandbox_ssh_port() -> u16 {
     DEFAULT_SSH_PORT
 }
 
-const fn default_ssh_handshake_skew_secs() -> u64 {
-    DEFAULT_SSH_HANDSHAKE_SKEW_SECS
-}
-
 const fn default_ssh_session_ttl_secs() -> u64 {
     86400 // 24 hours
 }

crates/openshell-core/src/sandbox_env.rs

@@ -20,12 +20,6 @@ pub const SANDBOX_ID: &str = "OPENSHELL_SANDBOX_ID";
 /// Filesystem path to the UNIX socket used for the in-sandbox SSH server.
 pub const SSH_SOCKET_PATH: &str = "OPENSHELL_SSH_SOCKET_PATH";
 
-/// Shared secret used for HMAC-based SSH handshake authentication.
-pub const SSH_HANDSHAKE_SECRET: &str = "OPENSHELL_SSH_HANDSHAKE_SECRET";
-
-/// Allowed clock-skew tolerance in seconds for the SSH handshake.
-pub const SSH_HANDSHAKE_SKEW_SECS: &str = "OPENSHELL_SSH_HANDSHAKE_SKEW_SECS";
-
 /// Log level for the sandbox supervisor (e.g. `"debug"`, `"info"`, `"warn"`).
 pub const LOG_LEVEL: &str = "OPENSHELL_LOG_LEVEL";
 

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

@@ -53,8 +53,6 @@ pub struct KubernetesComputeConfig {
     pub supervisor_sideload_method: SupervisorSideloadMethod,
     pub grpc_endpoint: String,
     pub ssh_socket_path: String,
-    pub ssh_handshake_secret: String,
-    pub ssh_handshake_skew_secs: u64,
     pub client_tls_secret_name: String,
     pub host_gateway_ip: String,
     pub enable_user_namespaces: bool,

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

@@ -176,10 +176,6 @@ impl KubernetesComputeDriver {
         &self.config.ssh_socket_path
     }
 
-    pub const fn ssh_handshake_skew_secs(&self) -> u64 {
-        self.config.ssh_handshake_skew_secs
-    }
-
     fn watch_api(&self) -> Api<DynamicObject> {
         let gvk = GroupVersionKind::gvk(SANDBOX_GROUP, SANDBOX_VERSION, SANDBOX_KIND);
         let resource = ApiResource::from_gvk(&gvk);
@@ -296,10 +292,6 @@ impl KubernetesComputeDriver {
         }
     }
 
-    fn ssh_handshake_secret(&self) -> &str {
-        &self.config.ssh_handshake_secret
-    }
-
     pub async fn create_sandbox(&self, sandbox: &Sandbox) -> Result<(), KubernetesDriverError> {
         let name = sandbox.name.as_str();
         info!(
@@ -328,8 +320,6 @@ impl KubernetesComputeDriver {
             sandbox_name: &sandbox.name,
             grpc_endpoint: &self.config.grpc_endpoint,
             ssh_socket_path: self.ssh_socket_path(),
-            ssh_handshake_secret: self.ssh_handshake_secret(),
-            ssh_handshake_skew_secs: self.ssh_handshake_skew_secs(),
             client_tls_secret_name: &self.config.client_tls_secret_name,
             host_gateway_ip: &self.config.host_gateway_ip,
             enable_user_namespaces: self.config.enable_user_namespaces,
@@ -984,8 +974,6 @@ struct SandboxPodParams<'a> {
     sandbox_name: &'a str,
     grpc_endpoint: &'a str,
     ssh_socket_path: &'a str,
-    ssh_handshake_secret: &'a str,
-    ssh_handshake_skew_secs: u64,
     client_tls_secret_name: &'a str,
     host_gateway_ip: &'a str,
     enable_user_namespaces: bool,
@@ -1146,8 +1134,6 @@ fn sandbox_template_to_k8s(
         params.sandbox_name,
         params.grpc_endpoint,
         params.ssh_socket_path,
-        params.ssh_handshake_secret,
-        params.ssh_handshake_skew_secs,
         !params.client_tls_secret_name.is_empty(),
     );
 
@@ -1310,8 +1296,6 @@ fn build_env_list(
     sandbox_name: &str,
     grpc_endpoint: &str,
     ssh_socket_path: &str,
-    ssh_handshake_secret: &str,
-    ssh_handshake_skew_secs: u64,
     tls_enabled: bool,
 ) -> Vec<serde_json::Value> {
     let mut env = existing_env.cloned().unwrap_or_default();
@@ -1323,8 +1307,6 @@ fn build_env_list(
         sandbox_name,
         grpc_endpoint,
         ssh_socket_path,
-        ssh_handshake_secret,
-        ssh_handshake_skew_secs,
         tls_enabled,
     );
     env
@@ -1341,15 +1323,12 @@ fn apply_env_map(
 
 // Required env vars are passed individually for clarity at call sites; grouping into a struct
 // would not improve readability for this internal helper.
-#[allow(clippy::too_many_arguments)]
 fn apply_required_env(
     env: &mut Vec<serde_json::Value>,
     sandbox_id: &str,
     sandbox_name: &str,
     grpc_endpoint: &str,
     ssh_socket_path: &str,
-    ssh_handshake_secret: &str,
-    ssh_handshake_skew_secs: u64,
     tls_enabled: bool,
 ) {
     upsert_env(env, openshell_core::sandbox_env::SANDBOX_ID, sandbox_id);
@@ -1367,16 +1346,6 @@ fn apply_required_env(
             ssh_socket_path,
         );
     }
-    upsert_env(
-        env,
-        openshell_core::sandbox_env::SSH_HANDSHAKE_SECRET,
-        ssh_handshake_secret,
-    );
-    upsert_env(
-        env,
-        openshell_core::sandbox_env::SSH_HANDSHAKE_SKEW_SECS,
-        &ssh_handshake_skew_secs.to_string(),
-    );
     // TLS cert paths for sandbox-to-server mTLS. Only set when TLS is enabled
     // and the client TLS secret is mounted into the sandbox pod.
     if tls_enabled {
@@ -1535,29 +1504,27 @@ mod tests {
     use prost_types::{Struct, Value, value::Kind};
 
     #[test]
-    fn apply_required_env_always_injects_ssh_handshake_secret() {
+    fn apply_required_env_does_not_inject_handshake_env() {
         let mut env = Vec::new();
         apply_required_env(
             &mut env,
             "sandbox-1",
             "my-sandbox",
             "https://endpoint:8080",
             "0.0.0.0:2222",
-            "my-secret-value",
-            300,
             true,
         );
 
-        let secret_entry = env
-            .iter()
-            .find(|e| {
-                e.get("name").and_then(|v| v.as_str()) == Some("OPENSHELL_SSH_HANDSHAKE_SECRET")
-            })
-            .expect("OPENSHELL_SSH_HANDSHAKE_SECRET must be present in env");
-        assert_eq!(
-            secret_entry.get("value").and_then(|v| v.as_str()),
-            Some("my-secret-value")
-        );
+        for name in [
+            "OPENSHELL_SSH_HANDSHAKE_SECRET",
+            "OPENSHELL_SSH_HANDSHAKE_SKEW_SECS",
+        ] {
+            assert!(
+                !env.iter()
+                    .any(|e| e.get("name").and_then(|v| v.as_str()) == Some(name)),
+                "{name} must not appear in sandbox pod env after handshake-secret removal"
+            );
+        }
     }
 
     #[test]
@@ -1790,8 +1757,6 @@ mod tests {
             "my-sandbox",
             "https://endpoint:8080",
             "0.0.0.0:2222",
-            "secret",
-            300,
             true, // tls_enabled
         );
 

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

@@ -47,12 +47,6 @@ struct Args {
     )]
     sandbox_ssh_socket_path: String,
 
-    #[arg(long, env = "OPENSHELL_SSH_HANDSHAKE_SECRET")]
-    ssh_handshake_secret: String,
-
-    #[arg(long, env = "OPENSHELL_SSH_HANDSHAKE_SKEW_SECS", default_value_t = 300)]
-    ssh_handshake_skew_secs: u64,
-
     #[arg(long, env = "OPENSHELL_CLIENT_TLS_SECRET_NAME")]
     client_tls_secret_name: Option<String>,
 
@@ -96,8 +90,6 @@ async fn main() -> Result<()> {
         supervisor_sideload_method: args.supervisor_sideload_method,
         grpc_endpoint: args.grpc_endpoint.unwrap_or_default(),
         ssh_socket_path: args.sandbox_ssh_socket_path,
-        ssh_handshake_secret: args.ssh_handshake_secret,
-        ssh_handshake_skew_secs: args.ssh_handshake_skew_secs,
         client_tls_secret_name: args.client_tls_secret_name.unwrap_or_default(),
         host_gateway_ip: args.host_gateway_ip.unwrap_or_default(),
         enable_user_namespaces: args.enable_user_namespaces,

crates/openshell-driver-podman/README.md

@@ -215,13 +215,9 @@ via sandbox templates:
 - `OPENSHELL_SANDBOX_ID`
 - `OPENSHELL_ENDPOINT`
 - `OPENSHELL_SSH_SOCKET_PATH`
-- `OPENSHELL_SSH_HANDSHAKE_SKEW_SECS`
 - `OPENSHELL_CONTAINER_IMAGE`
 - `OPENSHELL_SANDBOX_COMMAND`
 
-The `PodmanComputeConfig::Debug` implementation redacts the handshake secret as
-`[REDACTED]`.
-
 ## Sandbox Lifecycle
 
 ### Creation Flow
@@ -239,18 +235,15 @@ sequenceDiagram
     D->>P: pull_image(supervisor, "missing")
     D->>P: pull_image(sandbox_image, policy)
 
-    D->>P: create_secret(handshake)
-    Note over D: On failure below, rollback secret
-
     D->>P: create_volume(workspace)
-    Note over D: On failure below, rollback volume + secret
+    Note over D: On failure below, rollback volume
 
     D->>P: create_container(spec)
     alt Conflict (409)
-        D->>P: remove_volume + remove_secret
+        D->>P: remove_volume
         D-->>GW: AlreadyExists
     end
-    Note over D: On failure below, rollback container + volume + secret
+    Note over D: On failure below, rollback container + volume
 
     D->>P: start_container
     D-->>GW: Ok
@@ -300,8 +293,6 @@ Podman resources after out-of-band container removal or label drift.
 | `OPENSHELL_GATEWAY_PORT` | `--gateway-port` | `8080` | Gateway port used for endpoint auto-detection by the standalone binary. |
 | `OPENSHELL_NETWORK_NAME` | `--network-name` | `openshell` | Podman bridge network name. |
 | `OPENSHELL_SANDBOX_SSH_PORT` | `--sandbox-ssh-port` | `2222` | SSH compatibility port inside the container. |
-| `OPENSHELL_SSH_HANDSHAKE_SECRET` | `--ssh-handshake-secret` | Required standalone, gateway-generated in-process | Shared secret for the NSSH1 handshake. |
-| `OPENSHELL_SSH_HANDSHAKE_SKEW_SECS` | `--ssh-handshake-skew-secs` | `300` | Allowed timestamp skew for SSH handshake validation. |
 | `OPENSHELL_SANDBOX_SSH_SOCKET_PATH` | `--sandbox-ssh-socket-path` | `/run/openshell/ssh.sock` | Standalone driver only: supervisor Unix socket path in `PodmanComputeConfig`. In-gateway Podman uses server `config.sandbox_ssh_socket_path`. |
 | `OPENSHELL_STOP_TIMEOUT` | `--stop-timeout` | `10` | Container stop timeout in seconds. |
 | `OPENSHELL_SUPERVISOR_IMAGE` | `--supervisor-image` | `openshell/supervisor:latest` through the gateway, required standalone | OCI image containing the supervisor binary. |