zlayer_secrets/

credentials.rs

//! Credential store for API authentication.
//!
//! Built on top of [`PersistentSecretsStore`], this module provides API-key
//! based authentication with Argon2id password hashing.
//!
//! Credentials are stored in the `credentials` scope of the secrets store.
//! Each credential is a JSON object containing the argon2id hash of the
//! API secret and an array of roles.
//!
//! # Example
//!
//! ```rust,ignore
//! use zlayer_secrets::credentials::CredentialStore;
//! use zlayer_secrets::{EncryptionKey, PersistentSecretsStore};
//!
//! # async fn example() -> zlayer_secrets::Result<()> {
//! let key = EncryptionKey::generate();
//! let secrets_dir = zlayer_paths::ZLayerDirs::system_default().secrets();
//! let store = PersistentSecretsStore::open(&secrets_dir, key).await?;
//! let cred_store = CredentialStore::new(store);
//!
//! // Create an API key
//! cred_store.create_api_key("admin", "super-secret-password", &["admin"]).await?;
//!
//! // Validate credentials
//! let roles = cred_store.validate("admin", "super-secret-password").await?;
//! assert!(roles.is_some());
//! # Ok(())
//! # }
//! ```

use argon2::{
    password_hash::{rand_core::OsRng, PasswordHash, PasswordHasher, PasswordVerifier, SaltString},
    Argon2,
};
use serde::{Deserialize, Serialize};
use tracing::{debug, info};

use crate::{Result, Secret, SecretsError, SecretsStore};

/// The scope used for storing API credentials in the secrets store.
const CREDENTIALS_SCOPE: &str = "credentials";

/// Stored credential record (JSON-serialised inside the encrypted secret).
#[derive(Debug, Clone, Serialize, Deserialize)]
struct StoredCredential {
    /// Argon2id hash of the API secret / password.
    hash: String,
    /// Roles assigned to this credential (e.g. `["admin"]`).
    roles: Vec<String>,
}

/// A credential record exported for propagation (e.g. node-join admin
/// propagation), carrying the **pre-computed** argon2id hash and the roles
/// array. Importing this record stores the hash verbatim — the plaintext
/// password is never seen or re-hashed.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ExportedCredential {
    /// Argon2id PHC-string hash of the API secret / password.
    pub hash: String,
    /// Roles assigned to this credential (e.g. `["admin"]`).
    pub roles: Vec<String>,
}

/// Credential store for API key authentication.
///
/// Wraps a [`SecretsStore`] implementation and stores credentials as encrypted
/// JSON blobs keyed by API key name under the `credentials` scope.
pub struct CredentialStore<S: SecretsStore> {
    store: S,
}

impl<S: SecretsStore> std::fmt::Debug for CredentialStore<S> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("CredentialStore")
            .field("store", &"<secrets store>")
            .finish()
    }
}

impl<S: SecretsStore> CredentialStore<S> {
    /// Create a new credential store backed by the provided secrets store.
    pub fn new(store: S) -> Self {
        Self { store }
    }

    /// Borrow the underlying secrets store.
    ///
    /// Useful for constructing sibling typed stores (e.g.
    /// [`crate::RegistryCredentialStore`] / [`crate::GitCredentialStore`]) that
    /// share the same concrete backing store without re-opening it. When `S` is
    /// an `Arc<_>` (the common case), call `.clone()` on the returned reference
    /// for a cheap refcount bump.
    #[must_use]
    pub fn store(&self) -> &S {
        &self.store
    }

    /// Validate an API key and secret pair.
    ///
    /// Returns `Some(roles)` if the credentials are valid, `None` if invalid.
    ///
    /// # Arguments
    /// * `api_key` - The API key (used as the secret name in the store)
    /// * `api_secret` - The password/secret to verify against the stored hash
    ///
    /// # Errors
    /// Returns a `SecretsError` if there is a storage or decryption error
    /// (NOT for invalid credentials -- that returns `Ok(None)`).
    pub async fn validate(&self, api_key: &str, api_secret: &str) -> Result<Option<Vec<String>>> {
        // Look up the credential by API key
        let secret = match self.store.get_secret(CREDENTIALS_SCOPE, api_key).await {
            Ok(s) => s,
            Err(SecretsError::NotFound { .. }) => {
                debug!(api_key = %api_key, "Credential not found");
                return Ok(None);
            }
            Err(e) => return Err(e),
        };

        // Deserialise the stored credential
        let stored: StoredCredential = serde_json::from_str(secret.expose()).map_err(|e| {
            SecretsError::Storage(format!("corrupt credential record for '{api_key}': {e}"))
        })?;

        // Verify the password against the stored argon2id hash
        let parsed_hash = PasswordHash::new(&stored.hash).map_err(|e| {
            SecretsError::Storage(format!("invalid password hash for '{api_key}': {e}"))
        })?;

        let argon2 = Argon2::default();
        if argon2
            .verify_password(api_secret.as_bytes(), &parsed_hash)
            .is_ok()
        {
            debug!(api_key = %api_key, "Credential validated successfully");
            Ok(Some(stored.roles))
        } else {
            debug!(api_key = %api_key, "Invalid password");
            Ok(None)
        }
    }

    /// Create a new API key credential.
    ///
    /// The password is hashed with Argon2id before storage. If a credential
    /// with the same key already exists, it will be overwritten.
    ///
    /// # Arguments
    /// * `api_key` - The API key identifier
    /// * `password` - The password/secret to hash and store
    /// * `roles` - Roles assigned to this credential
    ///
    /// # Errors
    /// Returns a `SecretsError` if hashing or storage fails.
    pub async fn create_api_key(
        &self,
        api_key: &str,
        password: &str,
        roles: &[&str],
    ) -> Result<()> {
        // Hash the password with Argon2id
        let salt = SaltString::generate(&mut OsRng);
        let argon2 = Argon2::default();
        let hash = argon2
            .hash_password(password.as_bytes(), &salt)
            .map_err(|e| SecretsError::Encryption(format!("failed to hash password: {e}")))?
            .to_string();

        let credential = StoredCredential {
            hash,
            roles: roles.iter().map(|r| (*r).to_string()).collect(),
        };

        let json = serde_json::to_string(&credential)
            .map_err(|e| SecretsError::Storage(format!("failed to serialise credential: {e}")))?;

        self.store
            .set_secret(CREDENTIALS_SCOPE, api_key, &Secret::new(json))
            .await?;

        info!(api_key = %api_key, roles = ?roles, "Created API key credential");
        Ok(())
    }

    /// Export a credential's raw record (argon2id hash + roles) for
    /// propagation, WITHOUT decrypting any password.
    ///
    /// Returns `Ok(None)` when no credential exists for `api_key`. The hash in
    /// the returned [`ExportedCredential`] is the verbatim PHC string; pairing
    /// it with [`Self::import_record`] on another node reproduces a credential
    /// that validates the same password without re-hashing.
    ///
    /// # Errors
    /// Returns a `SecretsError` on storage/decryption errors or a corrupt
    /// record (but NOT for a missing key — that yields `Ok(None)`).
    pub async fn export_record(&self, api_key: &str) -> Result<Option<ExportedCredential>> {
        let secret = match self.store.get_secret(CREDENTIALS_SCOPE, api_key).await {
            Ok(s) => s,
            Err(SecretsError::NotFound { .. }) => return Ok(None),
            Err(e) => return Err(e),
        };
        let stored: StoredCredential = serde_json::from_str(secret.expose()).map_err(|e| {
            SecretsError::Storage(format!("corrupt credential record for '{api_key}': {e}"))
        })?;
        Ok(Some(ExportedCredential {
            hash: stored.hash,
            roles: stored.roles,
        }))
    }

    /// Import a pre-hashed credential record (as produced by
    /// [`Self::export_record`]) under `api_key`, storing the argon2id hash
    /// AS-IS. No password is supplied and nothing is re-hashed, so the imported
    /// credential validates exactly the password the original was created with.
    ///
    /// If a credential with the same key already exists it is overwritten.
    ///
    /// # Errors
    /// Returns a `SecretsError` if serialisation or storage fails.
    pub async fn import_record(&self, api_key: &str, record: &ExportedCredential) -> Result<()> {
        let credential = StoredCredential {
            hash: record.hash.clone(),
            roles: record.roles.clone(),
        };
        let json = serde_json::to_string(&credential)
            .map_err(|e| SecretsError::Storage(format!("failed to serialise credential: {e}")))?;
        self.store
            .set_secret(CREDENTIALS_SCOPE, api_key, &Secret::new(json))
            .await?;
        info!(api_key = %api_key, roles = ?record.roles, "Imported pre-hashed credential record");
        Ok(())
    }

    /// Delete an API key credential.
    ///
    /// # Arguments
    /// * `api_key` - The API key to delete
    ///
    /// # Errors
    /// Returns `SecretsError::NotFound` if the credential doesn't exist.
    pub async fn delete_api_key(&self, api_key: &str) -> Result<()> {
        self.store.delete_secret(CREDENTIALS_SCOPE, api_key).await?;
        info!(api_key = %api_key, "Deleted API key credential");
        Ok(())
    }

    /// Check if an API key credential exists.
    ///
    /// # Errors
    /// Returns a `SecretsError` if there is a storage or decryption error.
    pub async fn exists(&self, api_key: &str) -> Result<bool> {
        self.store.exists(CREDENTIALS_SCOPE, api_key).await
    }

    /// Overwrite the roles array on an existing credential, preserving the
    /// password hash. Use this to keep credential roles in sync with the
    /// authoritative user-store role when an admin changes a user's role.
    ///
    /// # Arguments
    /// * `api_key` - The API key whose roles should be updated
    /// * `roles` - The new role list (replaces existing)
    ///
    /// # Errors
    /// Returns `SecretsError::NotFound` if the credential doesn't exist, or a
    /// `SecretsError` if the storage or (de)serialisation fails.
    pub async fn set_roles(&self, api_key: &str, roles: &[&str]) -> Result<()> {
        let secret = self.store.get_secret(CREDENTIALS_SCOPE, api_key).await?;
        let mut stored: StoredCredential = serde_json::from_str(secret.expose()).map_err(|e| {
            SecretsError::Storage(format!("corrupt credential record for '{api_key}': {e}"))
        })?;

        stored.roles = roles.iter().map(|r| (*r).to_string()).collect();

        let json = serde_json::to_string(&stored)
            .map_err(|e| SecretsError::Storage(format!("failed to serialise credential: {e}")))?;

        self.store
            .set_secret(CREDENTIALS_SCOPE, api_key, &Secret::new(json))
            .await?;

        info!(api_key = %api_key, roles = ?roles, "Updated credential roles");
        Ok(())
    }

    /// Ensure a default admin credential exists.
    ///
    /// If no credential with the given `api_key` exists, one is created with
    /// the provided password and `["admin"]` role. Returns the password that
    /// was set (either the provided one or the existing one if already present).
    ///
    /// # Arguments
    /// * `api_key` - The admin API key name (e.g. "admin")
    /// * `password` - The password to use if the credential doesn't exist
    ///
    /// # Returns
    /// `true` if a new credential was created, `false` if one already existed.
    ///
    /// # Errors
    /// Returns a `SecretsError` if hashing or storage fails during creation.
    pub async fn ensure_admin(&self, api_key: &str, password: &str) -> Result<bool> {
        if self.exists(api_key).await? {
            debug!(api_key = %api_key, "Admin credential already exists");
            return Ok(false);
        }

        self.create_api_key(api_key, password, &["admin"]).await?;
        Ok(true)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::{EncryptionKey, PersistentSecretsStore};
    use zlayer_paths::ZLayerDirs;

    async fn create_test_store() -> (PersistentSecretsStore, zlayer_types::Scratch) {
        let temp_dir = ZLayerDirs::system_default()
            .scratch_dir("create-test-store-")
            .unwrap();
        let db_path = temp_dir.path().join("test_creds.sqlite");
        let key = EncryptionKey::generate();
        let store = PersistentSecretsStore::open(&db_path, key).await.unwrap();
        (store, temp_dir)
    }

    #[tokio::test]
    async fn test_create_and_validate() {
        let (store, _temp) = create_test_store().await;
        let cred_store = CredentialStore::new(store);

        cred_store
            .create_api_key("test-key", "test-secret", &["admin", "reader"])
            .await
            .unwrap();

        // Valid credentials
        let roles = cred_store
            .validate("test-key", "test-secret")
            .await
            .unwrap();
        assert!(roles.is_some());
        let roles = roles.unwrap();
        assert!(roles.contains(&"admin".to_string()));
        assert!(roles.contains(&"reader".to_string()));
    }

    #[tokio::test]
    async fn test_validate_wrong_password() {
        let (store, _temp) = create_test_store().await;
        let cred_store = CredentialStore::new(store);

        cred_store
            .create_api_key("test-key", "correct-password", &["admin"])
            .await
            .unwrap();

        let roles = cred_store
            .validate("test-key", "wrong-password")
            .await
            .unwrap();
        assert!(roles.is_none());
    }

    #[tokio::test]
    async fn test_validate_nonexistent_key() {
        let (store, _temp) = create_test_store().await;
        let cred_store = CredentialStore::new(store);

        let roles = cred_store
            .validate("nonexistent", "password")
            .await
            .unwrap();
        assert!(roles.is_none());
    }

    #[tokio::test]
    async fn test_exists() {
        let (store, _temp) = create_test_store().await;
        let cred_store = CredentialStore::new(store);

        assert!(!cred_store.exists("test-key").await.unwrap());

        cred_store
            .create_api_key("test-key", "password", &["admin"])
            .await
            .unwrap();

        assert!(cred_store.exists("test-key").await.unwrap());
    }

    #[tokio::test]
    async fn test_delete_api_key() {
        let (store, _temp) = create_test_store().await;
        let cred_store = CredentialStore::new(store);

        cred_store
            .create_api_key("delete-me", "password", &["admin"])
            .await
            .unwrap();
        assert!(cred_store.exists("delete-me").await.unwrap());

        cred_store.delete_api_key("delete-me").await.unwrap();
        assert!(!cred_store.exists("delete-me").await.unwrap());
    }

    #[tokio::test]
    async fn test_set_roles_preserves_hash() {
        let (store, _temp) = create_test_store().await;
        let cred_store = CredentialStore::new(store);

        cred_store
            .create_api_key("alice@example.com", "hunter2hunter2", &["user"])
            .await
            .unwrap();

        cred_store
            .set_roles("alice@example.com", &["admin"])
            .await
            .unwrap();

        // Old password still works (hash preserved)
        let roles = cred_store
            .validate("alice@example.com", "hunter2hunter2")
            .await
            .unwrap()
            .expect("should validate");
        assert_eq!(roles, vec!["admin".to_string()]);
    }

    #[tokio::test]
    async fn test_set_roles_missing_errors() {
        let (store, _temp) = create_test_store().await;
        let cred_store = CredentialStore::new(store);

        let err = cred_store
            .set_roles("nonexistent", &["admin"])
            .await
            .unwrap_err();
        assert!(
            matches!(err, SecretsError::NotFound { .. }),
            "unexpected: {err}"
        );
    }

    #[tokio::test]
    async fn test_ensure_admin_creates() {
        let (store, _temp) = create_test_store().await;
        let cred_store = CredentialStore::new(store);

        let created = cred_store
            .ensure_admin("admin", "admin-password")
            .await
            .unwrap();
        assert!(created);

        // Should be able to validate
        let roles = cred_store
            .validate("admin", "admin-password")
            .await
            .unwrap();
        assert!(roles.is_some());
        assert!(roles.unwrap().contains(&"admin".to_string()));
    }

    #[tokio::test]
    async fn test_ensure_admin_skips_existing() {
        let (store, _temp) = create_test_store().await;
        let cred_store = CredentialStore::new(store);

        // Create first
        cred_store
            .create_api_key("admin", "original-password", &["admin"])
            .await
            .unwrap();

        // ensure_admin should not overwrite
        let created = cred_store
            .ensure_admin("admin", "new-password")
            .await
            .unwrap();
        assert!(!created);

        // Original password should still work
        let roles = cred_store
            .validate("admin", "original-password")
            .await
            .unwrap();
        assert!(roles.is_some());

        // New password should NOT work
        let roles = cred_store.validate("admin", "new-password").await.unwrap();
        assert!(roles.is_none());
    }

    #[tokio::test]
    async fn test_export_then_import_preserves_hash() {
        // Create a credential on "node A".
        let (store_a, _temp_a) = create_test_store().await;
        let cred_a = CredentialStore::new(store_a);
        cred_a
            .create_api_key("admin@example.com", "correcthorsebatterystaple", &["admin"])
            .await
            .unwrap();

        // Export the raw record (hash + roles); no plaintext password involved.
        let exported = cred_a
            .export_record("admin@example.com")
            .await
            .unwrap()
            .expect("record present");
        assert_eq!(exported.roles, vec!["admin".to_string()]);
        assert!(exported.hash.starts_with("$argon2"), "PHC hash expected");

        // Import it verbatim into a SEPARATE store ("node B"). No re-hash.
        let (store_b, _temp_b) = create_test_store().await;
        let cred_b = CredentialStore::new(store_b);
        cred_b
            .import_record("admin@example.com", &exported)
            .await
            .unwrap();

        // The same password validates on node B against the imported hash.
        let roles = cred_b
            .validate("admin@example.com", "correcthorsebatterystaple")
            .await
            .unwrap()
            .expect("imported credential must validate");
        assert_eq!(roles, vec!["admin".to_string()]);

        // A wrong password is still rejected.
        let none = cred_b
            .validate("admin@example.com", "wrong-password")
            .await
            .unwrap();
        assert!(none.is_none());
    }

    #[tokio::test]
    async fn test_export_missing_returns_none() {
        let (store, _temp) = create_test_store().await;
        let cred = CredentialStore::new(store);
        assert!(cred.export_record("nope").await.unwrap().is_none());
    }

    #[tokio::test]
    async fn test_overwrite_credential() {
        let (store, _temp) = create_test_store().await;
        let cred_store = CredentialStore::new(store);

        cred_store
            .create_api_key("key", "password1", &["reader"])
            .await
            .unwrap();

        // Overwrite with new password and roles
        cred_store
            .create_api_key("key", "password2", &["admin"])
            .await
            .unwrap();

        // Old password should NOT work
        let roles = cred_store.validate("key", "password1").await.unwrap();
        assert!(roles.is_none());

        // New password should work with new roles
        let roles = cred_store.validate("key", "password2").await.unwrap();
        assert!(roles.is_some());
        let roles = roles.unwrap();
        assert!(roles.contains(&"admin".to_string()));
        assert!(!roles.contains(&"reader".to_string()));
    }
}