polyoxide-core 0.39.0

//! OS keychain credential storage.
//!
//! Provides `get`, `set`, and `delete` functions for storing, retrieving, and
//! removing individual credential strings from the platform keychain (macOS
//! Keychain, Windows Credential Manager, Linux Secret Service).
//!
//! Gated behind the `keychain` feature flag.

use keyring::Entry;
use polyoxide_venue::{Class, Classify};

/// Error type for keychain operations.
#[derive(Debug, thiserror::Error)]
pub enum KeychainError {
    /// The requested keychain entry does not exist.
    #[error("Keychain entry not found: service={service}, key={key}")]
    NotFound {
        /// The service name that was queried.
        service: String,
        /// The key name that was queried.
        key: String,
    },

    /// An error from the underlying keychain backend.
    #[error("Keychain error: {0}")]
    Backend(#[from] keyring::Error),
}

/// Every keychain failure is [`Class::InvalidRequest`]: the credential the
/// caller asked for cannot be read on this machine, and no venue was asked.
impl Classify for KeychainError {
    fn class(&self) -> Class {
        match self {
            Self::NotFound { .. } | Self::Backend(_) => Class::InvalidRequest,
        }
    }
}

/// Retrieve a credential from the OS keychain.
///
/// # Arguments
///
/// * `service` - The service name (e.g., `"polyoxide-clob"`)
/// * `key` - The key name (e.g., `"api_key"`)
pub fn get(service: &str, key: &str) -> Result<String, KeychainError> {
    let entry = Entry::new(service, key)?;
    entry.get_password().map_err(|e| match e {
        keyring::Error::NoEntry => KeychainError::NotFound {
            service: service.to_string(),
            key: key.to_string(),
        },
        other => KeychainError::Backend(other),
    })
}

/// Store a credential in the OS keychain.
///
/// Creates or overwrites the entry for the given `(service, key)` pair.
///
/// # Arguments
///
/// * `service` - The service name (e.g., `"polyoxide-clob"`)
/// * `key` - The key name (e.g., `"api_key"`)
/// * `value` - The credential value to store
pub fn set(service: &str, key: &str, value: &str) -> Result<(), KeychainError> {
    let entry = Entry::new(service, key)?;
    entry.set_password(value)?;
    Ok(())
}

/// Delete a credential from the OS keychain.
///
/// Returns `Ok(())` if the entry was deleted or did not exist.
///
/// # Arguments
///
/// * `service` - The service name (e.g., `"polyoxide-clob"`)
/// * `key` - The key name (e.g., `"api_key"`)
pub fn delete(service: &str, key: &str) -> Result<(), KeychainError> {
    let entry = Entry::new(service, key)?;
    match entry.delete_credential() {
        Ok(()) => Ok(()),
        Err(keyring::Error::NoEntry) => Ok(()),
        Err(e) => Err(KeychainError::Backend(e)),
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn not_found_error_includes_service_and_key() {
        let err = KeychainError::NotFound {
            service: "test-svc".to_string(),
            key: "test-key".to_string(),
        };
        let msg = err.to_string();
        assert!(msg.contains("test-svc"), "missing service: {msg}");
        assert!(msg.contains("test-key"), "missing key: {msg}");
    }

    #[test]
    fn backend_error_display() {
        let err = KeychainError::Backend(keyring::Error::NoEntry);
        let msg = err.to_string();
        assert!(msg.contains("Keychain error"), "unexpected: {msg}");
    }

    #[test]
    fn every_variant_classifies() {
        let rows = [
            KeychainError::NotFound {
                service: "svc".into(),
                key: "key".into(),
            },
            KeychainError::Backend(keyring::Error::NoEntry),
        ];
        for err in rows {
            assert_eq!(err.class(), Class::InvalidRequest, "{err:?}");
            assert!(err.is_fault(), "{err:?}");
            assert_eq!(err.retry_after(), None, "{err:?}");
            assert!(!err.is_retriable(), "{err:?}");
        }
    }
}