webylib/

passkey.rs

//! Passkey encryption for Webcash wallets
//!
//! This module provides state-of-the-art passkey encryption functionality for Webcash wallets,
//! supporting both iOS (Face ID/Touch ID) and Android (Passkey API) platforms.
//!
//! # Security Architecture
//!
//! The passkey encryption system follows these principles:
//! 1. **Key Isolation**: Encryption keys are protected by platform hardware security modules
//! 2. **Zero Secrets**: Passkey data never leaves the device's secure enclave
//! 3. **Forward Secrecy**: Keys are regenerated when passkey enrollment changes
//! 4. **Defense in Depth**: Multiple layers of encryption and authentication
//!
//! # Implementation Strategy
//!
//! ## iOS Integration
//! - Uses iOS Keychain Services with `kSecAccessControl` and `.biometryAny` flags
//! - Leverages Secure Enclave for key storage and passkey verification
//! - Supports both Face ID and Touch ID seamlessly
//! - Falls back to device passcode when passkeys unavailable
//!
//! ## Android Integration
//! - Uses Android Keystore with passkey authentication requirements
//! - Supports fingerprint, face unlock, and iris scanning
//! - Integrates with Android Credential Manager API for unified experience
//! - Hardware security module protection when available
//!
//! # Usage Patterns
//!
//! ```rust,no_run
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! use webylib::passkey::{PasskeyEncryption, EncryptionConfig};
//!
//! // Initialize with platform-specific configuration
//! let mut passkey = PasskeyEncryption::new(EncryptionConfig::default())?;
//!
//! // Encrypt wallet with passkey protection
//! let wallet_data = b"wallet data";
//! let encrypted_data = passkey.encrypt_with_passkey(wallet_data).await?;
//!
//! // Decrypt wallet (triggers passkey prompt)
//! let decrypted_data = passkey.decrypt_with_passkey(&encrypted_data).await?;
//! # Ok(())
//! # }
//! ```

use crate::crypto::CryptoSecret;
use crate::error::{Error, Result};
use aes_gcm::aead::{generic_array::GenericArray, Aead};
use hkdf::Hkdf;
use serde::{Deserialize, Serialize};
use sha2::Sha256;
use zeroize::Zeroize;

/// Configuration for passkey encryption
#[derive(Debug, Clone)]
pub struct EncryptionConfig {
    /// Application identifier for keychain/keystore
    pub app_identifier: String,
    /// Service name for key storage
    pub service_name: String,
    /// Require passkey authentication for every use
    pub require_auth_every_use: bool,
    /// Authentication timeout in seconds (0 = always require auth)
    pub auth_timeout_seconds: u32,
    /// Fallback to device passcode when passkey fails
    pub allow_device_passcode_fallback: bool,
}

impl Default for EncryptionConfig {
    fn default() -> Self {
        Self {
            app_identifier: "com.webycash.webylib".to_string(),
            service_name: "WalletEncryption".to_string(),
            require_auth_every_use: true,
            auth_timeout_seconds: 0,
            allow_device_passcode_fallback: true,
        }
    }
}

/// Encrypted data container with metadata
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EncryptedData {
    /// Encrypted payload
    pub ciphertext: Vec<u8>,
    /// AES-GCM nonce/IV
    pub nonce: [u8; 12],
    /// Key derivation salt
    pub salt: [u8; 32],
    /// Encryption algorithm identifier
    pub algorithm: String,
    /// Key derivation parameters
    pub kdf_params: KdfParams,
    /// Metadata (non-sensitive)
    pub metadata: EncryptionMetadata,
}

/// Key derivation parameters
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct KdfParams {
    /// HKDF info string
    pub info: String,
    /// Iteration count (for PBKDF2 if used)
    pub iterations: u32,
    /// Memory cost (for Argon2 if used)
    pub memory_cost: u32,
    /// Parallelism (for Argon2 if used)
    pub parallelism: u32,
}

impl Default for KdfParams {
    fn default() -> Self {
        Self {
            info: "webycash-passkey-v1".to_string(),
            iterations: 100_000,
            memory_cost: 65536, // 64MB
            parallelism: 4,
        }
    }
}

/// Encryption metadata (non-sensitive information)
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EncryptionMetadata {
    /// Timestamp when encrypted
    pub encrypted_at: String,
    /// Platform (ios/android/other)
    pub platform: String,
    /// Wallet version
    pub version: String,
    /// Passkey type used (if known)
    pub passkey_type: Option<String>,
}

/// Main passkey encryption interface
pub struct PasskeyEncryption {
    #[allow(dead_code)] // Reserved for future platform-specific keychain/keystore implementations
    config: EncryptionConfig,
    cached_key: Option<CryptoSecret>,
}

impl PasskeyEncryption {
    /// Create new passkey encryption instance
    pub fn new(config: EncryptionConfig) -> Result<Self> {
        Ok(Self {
            config,
            cached_key: None,
        })
    }

    /// Encrypt data with passkey protection
    ///
    /// This method:
    /// 1. Generates or retrieves a passkey-protected key
    /// 2. Derives encryption key using HKDF
    /// 3. Encrypts data using AES-256-GCM
    /// 4. Returns encrypted container with all metadata
    pub async fn encrypt_with_passkey(&mut self, plaintext: &[u8]) -> Result<EncryptedData> {
        // Generate salt for key derivation
        let mut salt = [0u8; 32];
        getrandom::getrandom(&mut salt)
            .map_err(|e| Error::crypto(format!("Failed to generate salt: {}", e)))?;

        // Get or generate master key protected by passkey
        let master_key = self.get_or_create_passkey_key().await?;

        // Derive encryption key using HKDF
        let encryption_key = self.derive_encryption_key(&master_key, &salt)?;

        // Generate nonce for AES-GCM
        let cipher = encryption_key.create_cipher();
        let mut nonce_bytes = [0u8; 12];
        getrandom::getrandom(&mut nonce_bytes)
            .map_err(|e| Error::crypto(format!("Failed to generate nonce: {}", e)))?;
        let nonce = GenericArray::from_slice(&nonce_bytes);

        // Encrypt the data
        let ciphertext = cipher
            .encrypt(nonce, plaintext)
            .map_err(|e| Error::crypto(format!("Encryption failed: {}", e)))?;

        // Create metadata
        let metadata = EncryptionMetadata {
            encrypted_at: format!(
                "{}",
                std::time::SystemTime::now()
                    .duration_since(std::time::UNIX_EPOCH)
                    .unwrap()
                    .as_secs()
            ),
            platform: self.get_platform_name(),
            version: "1.0".to_string(),
            passkey_type: self.get_available_passkey_type().await,
        };

        Ok(EncryptedData {
            ciphertext,
            nonce: nonce_bytes,
            salt,
            algorithm: "AES-256-GCM".to_string(),
            kdf_params: KdfParams::default(),
            metadata,
        })
    }

    /// Decrypt data using passkey authentication
    ///
    /// This method:
    /// 1. Triggers passkey authentication
    /// 2. Retrieves the passkey-protected key
    /// 3. Derives decryption key using stored parameters
    /// 4. Decrypts and returns the original data
    pub async fn decrypt_with_passkey(
        &mut self,
        encrypted_data: &EncryptedData,
    ) -> Result<Vec<u8>> {
        // Validate encryption format
        if encrypted_data.algorithm != "AES-256-GCM" {
            return Err(Error::crypto("Unsupported encryption algorithm"));
        }

        // Authenticate and get master key
        let master_key = self.authenticate_and_get_key().await?;

        // Derive decryption key
        let decryption_key = self.derive_encryption_key(&master_key, &encrypted_data.salt)?;

        // Decrypt the data
        let cipher = decryption_key.create_cipher();
        let nonce = GenericArray::from_slice(&encrypted_data.nonce);

        let plaintext = cipher
            .decrypt(nonce, encrypted_data.ciphertext.as_slice())
            .map_err(|e| Error::crypto(format!("Decryption failed: {}", e)))?;

        Ok(plaintext)
    }

    /// Clear any cached keys from memory
    pub fn clear_cached_keys(&mut self) {
        if let Some(mut key) = self.cached_key.take() {
            key.zeroize();
        }
    }

    /// Check if passkey authentication is available on this device
    /// Check if passkey is available. The keyring crate supports all major platforms.
    pub async fn is_passkey_available(&self) -> Result<bool> {
        // Try creating a keyring entry — if it succeeds, the platform supports it
        keyring::Entry::new(&self.config.service_name, &self.config.app_identifier)
            .map(|_| true)
            .or(Ok(false))
    }

    /// Get available passkey type description for this platform.
    pub async fn get_available_passkey_type(&self) -> Option<String> {
        #[cfg(target_os = "macos")]
        {
            Some("macOS Keychain (Touch ID / Apple Watch / Passcode)".to_string())
        }
        #[cfg(target_os = "ios")]
        {
            Some("iOS Keychain (Face ID / Touch ID)".to_string())
        }
        #[cfg(target_os = "linux")]
        {
            Some("Linux Secret Service (GNOME Keyring / KDE Wallet)".to_string())
        }
        #[cfg(target_os = "windows")]
        {
            Some("Windows Credential Manager".to_string())
        }
        #[cfg(target_os = "freebsd")]
        {
            Some("FreeBSD file-based keyring".to_string())
        }
        #[cfg(not(any(
            target_os = "macos",
            target_os = "ios",
            target_os = "linux",
            target_os = "windows",
            target_os = "freebsd"
        )))]
        {
            None
        }
    }

    // Private implementation methods

    /// Get or create a master key protected by passkey
    async fn get_or_create_passkey_key(&mut self) -> Result<CryptoSecret> {
        // Check if we have a cached key (for performance)
        if let Some(ref key) = self.cached_key {
            return Ok(key.clone());
        }

        // Try to retrieve existing key first
        match self.retrieve_passkey_key().await {
            Ok(key) => {
                self.cached_key = Some(key.clone());
                Ok(key)
            }
            Err(_) => {
                // No existing key, create new one
                let key = CryptoSecret::generate()
                    .map_err(|e| Error::crypto(format!("Failed to generate master key: {}", e)))?;

                self.store_passkey_key(&key).await?;
                self.cached_key = Some(key.clone());
                Ok(key)
            }
        }
    }

    /// Authenticate with passkey and get the master key
    async fn authenticate_and_get_key(&mut self) -> Result<CryptoSecret> {
        // Check cached key first
        if let Some(ref key) = self.cached_key {
            // Verify the cached key is still valid
            if self.verify_passkey_access().await? {
                return Ok(key.clone());
            } else {
                // Clear invalid cached key
                self.clear_cached_keys();
            }
        }

        // Perform passkey authentication and retrieve key
        let key = self.retrieve_passkey_key().await?;
        self.cached_key = Some(key.clone());
        Ok(key)
    }

    /// Derive encryption key from master key using HKDF
    fn derive_encryption_key(
        &self,
        master_key: &CryptoSecret,
        salt: &[u8; 32],
    ) -> Result<CryptoSecret> {
        let hk = Hkdf::<Sha256>::new(Some(salt), master_key.as_bytes());
        let mut okm = [0u8; 32];
        hk.expand(b"webycash-passkey-v1", &mut okm)
            .map_err(|e| Error::crypto(format!("Key derivation failed: {}", e)))?;

        Ok(CryptoSecret::from_bytes(okm))
    }

    /// Get platform name
    fn get_platform_name(&self) -> String {
        #[cfg(target_os = "ios")]
        return "ios".to_string();
        #[cfg(target_os = "android")]
        return "android".to_string();
        #[cfg(target_os = "macos")]
        return "macos".to_string();
        #[cfg(target_os = "linux")]
        return "linux".to_string();
        #[cfg(target_os = "windows")]
        return "windows".to_string();
        #[cfg(not(any(
            target_os = "ios",
            target_os = "android",
            target_os = "macos",
            target_os = "linux",
            target_os = "windows"
        )))]
        return "other".to_string();
    }

    // All platform-specific passkey storage is handled by the keyring crate.
    // macOS: Security Framework Keychain (Touch ID / Apple Watch / Passcode)
    // iOS: Security Framework Keychain (Face ID / Touch ID)
    // Linux: libsecret (GNOME Keyring / KDE Wallet)
    // Windows: Windows Credential Manager
    // FreeBSD: file-based keyring
    //
    // ── Cross-platform passkey storage via keyring crate ──────────────
    // macOS: Keychain (Touch ID / Apple Watch / device passcode)
    // iOS: Keychain
    // Linux: libsecret (GNOME Keyring / KDE Wallet)
    // Windows: Windows Credential Manager
    // FreeBSD: file-based with encryption

    async fn store_passkey_key(&self, key: &CryptoSecret) -> Result<()> {
        let entry = keyring::Entry::new(&self.config.service_name, &self.config.app_identifier)
            .map_err(|e| Error::crypto(format!("Passkey keyring init failed: {}", e)))?;

        // Store key as base64 (keyring stores strings, not raw bytes)
        let key_b64 =
            base64::Engine::encode(&base64::engine::general_purpose::STANDARD, key.as_bytes());
        entry
            .set_password(&key_b64)
            .map_err(|e| Error::crypto(format!("Passkey store failed: {}", e)))?;

        Ok(())
    }

    async fn retrieve_passkey_key(&self) -> Result<CryptoSecret> {
        let entry = keyring::Entry::new(&self.config.service_name, &self.config.app_identifier)
            .map_err(|e| Error::crypto(format!("Passkey keyring init failed: {}", e)))?;

        let key_b64 = entry
            .get_password()
            .map_err(|e| Error::crypto(format!("Passkey retrieve failed: {}", e)))?;

        let key_bytes =
            base64::Engine::decode(&base64::engine::general_purpose::STANDARD, &key_b64)
                .map_err(|e| Error::crypto(format!("Passkey decode failed: {}", e)))?;

        if key_bytes.len() != 32 {
            return Err(Error::crypto(format!(
                "Invalid key length: expected 32, got {}",
                key_bytes.len()
            )));
        }

        let mut arr = [0u8; 32];
        arr.copy_from_slice(&key_bytes);
        Ok(CryptoSecret::from_bytes(arr))
    }

    async fn verify_passkey_access(&self) -> Result<bool> {
        self.retrieve_passkey_key()
            .await
            .map(|_| true)
            .or(Ok(false))
    }
}

impl Drop for PasskeyEncryption {
    fn drop(&mut self) {
        self.clear_cached_keys();
    }
}

/// Encrypt data with a password-based key (fallback when passkeys unavailable).
pub fn encrypt_with_password(plaintext: &[u8], password: &str) -> Result<EncryptedData> {
    // Generate salt
    let mut salt = [0u8; 32];
    getrandom::getrandom(&mut salt)
        .map_err(|e| Error::crypto(format!("Failed to generate salt: {}", e)))?;

    // Derive key using Argon2 (more secure than PBKDF2)
    let mut key_bytes = [0u8; 32];
    argon2::Argon2::default()
        .hash_password_into(password.as_bytes(), &salt, &mut key_bytes)
        .map_err(|e| Error::crypto(format!("Password key derivation failed: {}", e)))?;

    let encryption_key = CryptoSecret::from_bytes(key_bytes);

    // Encrypt using AES-256-GCM
    let cipher = encryption_key.create_cipher();
    let mut nonce_bytes = [0u8; 12];
    getrandom::getrandom(&mut nonce_bytes)
        .map_err(|e| Error::crypto(format!("Failed to generate nonce: {}", e)))?;
    let nonce = GenericArray::from_slice(&nonce_bytes);

    let ciphertext = cipher
        .encrypt(nonce, plaintext)
        .map_err(|e| Error::crypto(format!("Password encryption failed: {}", e)))?;

    let metadata = EncryptionMetadata {
        encrypted_at: format!(
            "{}",
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap()
                .as_secs()
        ),
        platform: "password".to_string(),
        version: "1.0".to_string(),
        passkey_type: None,
    };

    Ok(EncryptedData {
        ciphertext,
        nonce: nonce_bytes,
        salt,
        algorithm: "AES-256-GCM-PASSWORD".to_string(),
        kdf_params: KdfParams {
            info: "webycash-password-v1".to_string(),
            iterations: 0, // Not used for Argon2
            memory_cost: 65536,
            parallelism: 4,
        },
        metadata,
    })
}

/// Decrypt data with a password-based key
pub fn decrypt_with_password(encrypted_data: &EncryptedData, password: &str) -> Result<Vec<u8>> {
    if encrypted_data.algorithm != "AES-256-GCM-PASSWORD" {
        return Err(Error::crypto("Wrong decryption method for this data"));
    }

    // Derive key using same parameters
    let mut key_bytes = [0u8; 32];
    argon2::Argon2::default()
        .hash_password_into(password.as_bytes(), &encrypted_data.salt, &mut key_bytes)
        .map_err(|e| Error::crypto(format!("Password key derivation failed: {}", e)))?;

    let decryption_key = CryptoSecret::from_bytes(key_bytes);

    // Decrypt
    let cipher = decryption_key.create_cipher();
    let nonce = GenericArray::from_slice(&encrypted_data.nonce);

    let plaintext = cipher
        .decrypt(nonce, encrypted_data.ciphertext.as_slice())
        .map_err(|e| Error::crypto(format!("Password decryption failed: {}", e)))?;

    Ok(plaintext)
}

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

    #[tokio::test]
    async fn test_password_encryption_roundtrip() {
        let plaintext = b"Hello, secure world!";
        let password = "test_password_123";

        // Encrypt
        let encrypted = encrypt_with_password(plaintext, password).unwrap();

        // Verify structure
        assert_eq!(encrypted.algorithm, "AES-256-GCM-PASSWORD");
        assert_eq!(encrypted.nonce.len(), 12);
        assert_eq!(encrypted.salt.len(), 32);

        // Decrypt
        let decrypted = decrypt_with_password(&encrypted, password).unwrap();
        assert_eq!(decrypted, plaintext);

        // Wrong password should fail
        let wrong_result = decrypt_with_password(&encrypted, "wrong_password");
        assert!(wrong_result.is_err());
    }

    #[tokio::test]
    async fn test_passkey_encryption_config() {
        let config = EncryptionConfig::default();
        let passkey = PasskeyEncryption::new(config);
        assert!(passkey.is_ok());
    }

    #[test]
    fn test_crypto_secret_security() {
        let secret = CryptoSecret::generate().unwrap();

        // Debug should not reveal secret
        let debug_str = format!("{:?}", secret);
        assert_eq!(debug_str, "CryptoSecret([REDACTED])");

        // Display should not reveal secret
        let display_str = format!("{}", secret);
        assert_eq!(display_str, "[REDACTED 32-byte secret]");
    }
}