zlayer_secrets/

jwt.rs

//! JWT signing-key management for the `ZLayer` API daemon.
//!
//! Mirrors [`KeyManager`](crate::KeyManager) for the JWT secret used by
//! `zlayer-api` to sign session cookies. Without persistence, every daemon
//! restart that omits `ZLAYER_JWT_SECRET` invalidates every previously
//! issued session cookie — users get logged out on every restart.
//!
//! ## Resolution Priority
//!
//! 1. `ZLAYER_JWT_SECRET` environment variable — operator opt-out, returned
//!    verbatim and never persisted.
//! 2. File at `{base_dir}/jwt_secret_{deployment}.key` — loaded as bytes.
//! 3. Auto-generated: 64 random bytes (sufficient for HMAC-SHA256), saved
//!    to the same file with mode `0600` for future runs.

use std::fs;
use std::path::{Path, PathBuf};

use rand::rngs::OsRng;
use rand::TryRngCore;
use secrecy::SecretString;
#[cfg(unix)]
use tracing::warn;
use tracing::{debug, info};

use crate::{Result, SecretsError};

/// Environment variable name for the operator-supplied JWT secret.
pub const ENV_JWT_SECRET: &str = "ZLAYER_JWT_SECRET";

/// Length in bytes of an auto-generated JWT secret. 64 is the natural ceiling
/// for HMAC-SHA256 (HS256): keys longer than the hash block size get hashed
/// before use, so 64 random bytes is the upper end of what the signer
/// actually consumes.
const GENERATED_SECRET_BYTES: usize = 64;

/// Manages the API daemon's JWT signing secret.
///
/// Use [`JwtSecretManager::with_base_dir`] alongside [`KeyManager`](crate::KeyManager)
/// during daemon startup so both keys live in the same directory.
#[derive(Debug, Clone)]
pub struct JwtSecretManager {
    base_dir: PathBuf,
}

impl JwtSecretManager {
    /// Creates a manager rooted at `base_dir`.
    #[must_use]
    pub fn with_base_dir(base_dir: impl AsRef<Path>) -> Self {
        Self {
            base_dir: base_dir.as_ref().to_path_buf(),
        }
    }

    /// Returns the path to the JWT secret file for `deployment`.
    fn secret_file_path(&self, deployment: &str) -> PathBuf {
        self.base_dir.join(format!("jwt_secret_{deployment}.key"))
    }

    /// Returns the path to the cluster-wide JWT secret file.
    ///
    /// This file holds the *literal* signing string the whole cluster shares
    /// (propagated from the leader during a node join), as opposed to the
    /// per-node random `jwt_secret_{deployment}.key`. When present, daemon
    /// startup prefers it over `get_or_create`, so a session cookie minted on
    /// any node validates cluster-wide.
    #[must_use]
    pub fn cluster_secret_file_path(&self) -> PathBuf {
        self.base_dir.join("cluster_jwt_secret")
    }

    /// Load the cluster-wide JWT secret if one was propagated to this node by
    /// the leader during a join.
    ///
    /// Returns `Ok(None)` when the file is absent (the standalone / never-joined
    /// case) so the caller can fall back to [`Self::get_or_create`]. The file
    /// holds the secret verbatim (UTF-8, trailing newline tolerated).
    ///
    /// # Errors
    ///
    /// Returns [`SecretsError::Encryption`] if the file exists but cannot be
    /// read or is empty.
    pub fn load_cluster_secret(&self) -> Result<Option<SecretString>> {
        let path = self.cluster_secret_file_path();
        if !path.exists() {
            return Ok(None);
        }
        let raw = fs::read_to_string(&path).map_err(|e| {
            SecretsError::Encryption(format!(
                "Failed to read cluster JWT secret file {}: {e}",
                path.display()
            ))
        })?;
        let trimmed = raw.trim_end_matches(['\n', '\r']);
        if trimmed.is_empty() {
            return Err(SecretsError::Encryption(format!(
                "cluster JWT secret file {} is empty",
                path.display()
            )));
        }
        debug!("Loaded cluster JWT secret from {}", path.display());
        Ok(Some(SecretString::from(trimmed.to_string())))
    }

    /// Persist the cluster-wide JWT secret propagated by the leader, writing
    /// the literal signing string to [`Self::cluster_secret_file_path`] with
    /// mode `0600` on Unix.
    ///
    /// Idempotent in effect: an existing file is overwritten with the
    /// leader-supplied value (the leader is the source of truth).
    ///
    /// # Errors
    ///
    /// Returns [`SecretsError::Encryption`] if `secret` is empty or the file
    /// cannot be written.
    pub fn import_cluster_secret(&self, secret: &str) -> Result<()> {
        if secret.is_empty() {
            return Err(SecretsError::Encryption(
                "refusing to persist empty cluster JWT secret".to_string(),
            ));
        }
        let path = self.cluster_secret_file_path();
        if let Some(parent) = path.parent() {
            fs::create_dir_all(parent).map_err(|e| {
                SecretsError::Encryption(format!(
                    "Failed to create cluster JWT secret directory {}: {e}",
                    parent.display()
                ))
            })?;
        }
        fs::write(&path, secret.as_bytes()).map_err(|e| {
            SecretsError::Encryption(format!(
                "Failed to write cluster JWT secret file {}: {e}",
                path.display()
            ))
        })?;

        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;
            let perms = fs::Permissions::from_mode(0o600);
            if let Err(e) = fs::set_permissions(&path, perms) {
                warn!(
                    "Failed to set permissions on cluster JWT secret file {}: {e}",
                    path.display()
                );
            }
        }

        info!("Persisted cluster JWT secret at {}", path.display());
        Ok(())
    }

    /// Resolves the JWT secret, generating + persisting a fresh one when
    /// neither the env var nor a saved file is present.
    ///
    /// # Errors
    ///
    /// Returns [`SecretsError::Encryption`] if the file system cannot be
    /// read or written, or if the loaded file is empty.
    pub fn get_or_create(&self, deployment: &str) -> Result<SecretString> {
        if let Ok(secret) = std::env::var(ENV_JWT_SECRET) {
            if secret.is_empty() {
                return Err(SecretsError::Encryption(format!(
                    "{ENV_JWT_SECRET} is set but empty"
                )));
            }
            debug!("Using JWT secret from {ENV_JWT_SECRET} environment variable");
            return Ok(SecretString::from(secret));
        }

        let path = self.secret_file_path(deployment);
        if path.exists() {
            debug!("Loading JWT secret from file: {}", path.display());
            return Self::load_from_file(&path);
        }

        info!(
            "Generating new JWT secret for deployment '{}' at {}",
            deployment,
            path.display()
        );
        Self::generate_and_save(&path)
    }

    fn load_from_file(path: &Path) -> Result<SecretString> {
        let bytes = fs::read(path).map_err(|e| {
            SecretsError::Encryption(format!(
                "Failed to read JWT secret file {}: {e}",
                path.display()
            ))
        })?;
        if bytes.is_empty() {
            return Err(SecretsError::Encryption(format!(
                "JWT secret file {} is empty",
                path.display()
            )));
        }
        Ok(SecretString::from(hex::encode(bytes)))
    }

    fn generate_and_save(path: &Path) -> Result<SecretString> {
        if let Some(parent) = path.parent() {
            fs::create_dir_all(parent).map_err(|e| {
                SecretsError::Encryption(format!(
                    "Failed to create JWT secret directory {}: {e}",
                    parent.display()
                ))
            })?;
        }

        let mut bytes = vec![0u8; GENERATED_SECRET_BYTES];
        OsRng
            .try_fill_bytes(&mut bytes)
            .map_err(|e| SecretsError::Encryption(format!("OS RNG failed: {e}")))?;

        fs::write(path, &bytes).map_err(|e| {
            SecretsError::Encryption(format!(
                "Failed to write JWT secret file {}: {e}",
                path.display()
            ))
        })?;

        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;
            let perms = fs::Permissions::from_mode(0o600);
            if let Err(e) = fs::set_permissions(path, perms) {
                warn!(
                    "Failed to set permissions on JWT secret file {}: {e}",
                    path.display()
                );
            }
        }

        info!("Created new JWT secret at {}", path.display());
        Ok(SecretString::from(hex::encode(&bytes)))
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use secrecy::ExposeSecret;
    use serial_test::serial;
    use std::env;
    use tempfile::TempDir;

    struct EnvGuard;

    impl EnvGuard {
        fn new() -> Self {
            env::remove_var(ENV_JWT_SECRET);
            Self
        }
    }

    impl Drop for EnvGuard {
        fn drop(&mut self) {
            env::remove_var(ENV_JWT_SECRET);
        }
    }

    fn setup() -> (JwtSecretManager, TempDir) {
        let dir = TempDir::new().unwrap();
        (JwtSecretManager::with_base_dir(dir.path()), dir)
    }

    #[test]
    #[serial]
    fn generates_and_persists() {
        let _g = EnvGuard::new();
        let (mgr, _t) = setup();
        let s1 = mgr.get_or_create("dev").unwrap();
        let path = mgr.secret_file_path("dev");
        assert!(path.exists(), "secret file should be persisted");
        // Hex of 64 bytes is 128 chars.
        assert_eq!(s1.expose_secret().len(), GENERATED_SECRET_BYTES * 2);
    }

    #[test]
    #[serial]
    fn stable_across_calls() {
        let _g = EnvGuard::new();
        let (mgr, _t) = setup();
        let s1 = mgr.get_or_create("dev").unwrap();
        let s2 = mgr.get_or_create("dev").unwrap();
        assert_eq!(s1.expose_secret(), s2.expose_secret());
    }

    #[test]
    #[serial]
    fn different_deployments_get_different_secrets() {
        let _g = EnvGuard::new();
        let (mgr, _t) = setup();
        let a = mgr.get_or_create("a").unwrap();
        let b = mgr.get_or_create("b").unwrap();
        assert_ne!(a.expose_secret(), b.expose_secret());
    }

    #[test]
    #[serial]
    fn env_overrides_file() {
        let _g = EnvGuard::new();
        let (mgr, _t) = setup();
        // Pre-create a file-backed secret.
        let _file_secret = mgr.get_or_create("dev").unwrap();
        env::set_var(ENV_JWT_SECRET, "operator-supplied");
        let env_secret = mgr.get_or_create("dev").unwrap();
        assert_eq!(env_secret.expose_secret(), "operator-supplied");
    }

    #[test]
    #[serial]
    fn empty_env_is_rejected() {
        let _g = EnvGuard::new();
        let (mgr, _t) = setup();
        env::set_var(ENV_JWT_SECRET, "");
        let result = mgr.get_or_create("dev");
        assert!(result.is_err());
    }

    #[test]
    #[serial]
    fn cluster_secret_absent_returns_none() {
        let _g = EnvGuard::new();
        let (mgr, _t) = setup();
        assert!(
            mgr.load_cluster_secret().unwrap().is_none(),
            "no cluster secret file means standalone -> None"
        );
    }

    #[test]
    #[serial]
    fn cluster_secret_import_then_load_roundtrips() {
        let _g = EnvGuard::new();
        let (mgr, _t) = setup();
        mgr.import_cluster_secret("cluster-shared-signing-key")
            .unwrap();
        let loaded = mgr.load_cluster_secret().unwrap().expect("present");
        assert_eq!(loaded.expose_secret(), "cluster-shared-signing-key");
    }

    #[test]
    #[serial]
    fn cluster_secret_tolerates_trailing_newline() {
        let _g = EnvGuard::new();
        let (mgr, _t) = setup();
        fs::write(mgr.cluster_secret_file_path(), b"key-with-newline\n").unwrap();
        let loaded = mgr.load_cluster_secret().unwrap().expect("present");
        assert_eq!(loaded.expose_secret(), "key-with-newline");
    }

    #[test]
    #[serial]
    fn cluster_secret_rejects_empty_import() {
        let _g = EnvGuard::new();
        let (mgr, _t) = setup();
        assert!(mgr.import_cluster_secret("").is_err());
    }

    #[cfg(unix)]
    #[test]
    #[serial]
    fn cluster_secret_file_has_restrictive_perms() {
        use std::os::unix::fs::PermissionsExt;
        let _g = EnvGuard::new();
        let (mgr, _t) = setup();
        mgr.import_cluster_secret("k").unwrap();
        let mode = fs::metadata(mgr.cluster_secret_file_path())
            .unwrap()
            .permissions()
            .mode()
            & 0o777;
        assert_eq!(mode, 0o600);
    }

    #[cfg(unix)]
    #[test]
    #[serial]
    fn file_has_restrictive_perms() {
        use std::os::unix::fs::PermissionsExt;
        let _g = EnvGuard::new();
        let (mgr, _t) = setup();
        mgr.get_or_create("dev").unwrap();
        let path = mgr.secret_file_path("dev");
        let mode = fs::metadata(&path).unwrap().permissions().mode() & 0o777;
        assert_eq!(mode, 0o600);
    }
}