Mountain/Environment/

SecretProvider.rs

//! # SecretProvider (Environment)
//!
//! Implements the `SecretProvider` trait for `MountainEnvironment`, providing
//! secure storage and retrieval of secrets (passwords, tokens, keys) with
//! optional integration with system keychains and the Air service.
//!
//! ## RESPONSIBILITIES
//!
//! ### 1. Secret Storage
//! - Store secrets securely in encrypted format
//! - Support multiple secret types (passwords, API keys, tokens)
//! - Provide per-secret access control and metadata
//! - Handle secret creation, update, and deletion
//!
//! ### 2. Secret Retrieval
//! - Retrieve stored secrets by key
//! - Cache frequently accessed secrets for performance
//! - Support secret resolution with fallbacks
//! - Handle missing or expired secrets gracefully
//!
//! ### 3. Security
//! - Encrypt secrets at rest using strong cryptography
//! - Optional integration with system keychain (macOS Keychain, Windows DPAPI,
//!   etc.)
//! - Secure memory handling for secret values
//! - Audit logging for secret access (optional)
//!
//! ### 4. Air Integration (Optional)
//! - Delegate secret storage to Air service when available
//! - Support cloud-synced secrets across devices
//! - Handle Air service availability failures with fallback
//!
//! ## ARCHITECTURAL ROLE
//!
//! SecretProvider is the **secure credential manager** for Mountain:
//!
//! ```text
//! Provider ──► Store/Retrieve ──► Secret Storage (Local or Air)
//! ```
//!
//! ### Position in Mountain
//! - `Environment` module: Security capability provider
//! - Implements `CommonLibrary::Secret::SecretProvider` trait
//! - Accessible via `Environment.Require<dyn SecretProvider>()`
//!
//! ### Secret Storage Backends
//! - **Local Storage**: Encrypted file in app data directory (default)
//! - **System Keychain**: Platform-native secure storage (optional)
//! - **Air Service**: Cloud-based secret management (optional, feature-gated)
//!
//! ### Dependencies
//! - `ApplicationState`: For storage paths and state
//! - `ConfigurationProvider`: To read security settings
//! - `Log`: Secret access auditing (if enabled)
//!
//! ### Dependents
//! - Authentication flows: Store and retrieve OAuth tokens
//! - Git credentials: Store SCM passwords and tokens
//! - Extension secrets: Extension-specific API keys
//! - System secrets: Mountain service account credentials
//!
//! ## SECURITY CONSIDERATIONS
//!
//! - Secrets are never logged or exposed in error messages
//! - Secret values are zeroed from memory after use
//! - Access to secret storage should be audited
//! - Consider rate limiting secret retrieval attempts
//! - Implement secret expiration and rotation policies
//!
//! ## PERFORMANCE
//!
//! - Secret lookups are cached to avoid repeated decryption
//! - Async operations to avoid blocking the UI
//! - Consider lazy loading for rarely used secrets
//!
//! ## VS CODE REFERENCE
//!
//! Patterns from VS Code:
//! - `vs/platform/secrets/common/secrets.ts` - Secret storage API
//! - `vs/platform/secrets/electron-simulator/electronSecretStorage.ts` -
//!   Keychain integration
//!
//! ## TODO
//!
//! - [ ] Implement system keychain integration (macOS Keychain, Windows DPAPI,
//!   libsecret)
//! - [ ] Add secret encryption with hardware-backed keys (TPM, Secure Enclave)
//! - [ ] Implement secret versioning and history
//! - [ ] Add secret access control lists (ACL) per provider
//! - [ ] Support secret sharing between extensions
//! - [ ] Implement secret backup and restore
//! - [ ] Add secret expiration and automatic rotation
//! - [ ] Support secret references (pointer to external secret)
//! - [ ] Implement secret audit trail and compliance reporting
//! - [ ] Add secret strength validation and generation
//!
//! ## MODULE CONTENTS
//!
//! - [`SecretProvider`]: Main struct implementing the trait
//! - Secret storage and retrieval methods
//! - Encryption/decryption helpers
//! - System keychain abstraction
//! - Air service delegation logic

// Responsibilities:
//   - Securely store and retrieve secrets using the OS keychain.
//   - Provide a consistent API across platforms (Windows, macOS, Linux).
//   - Handle keychain access failures gracefully with proper error handling.
//   - Support secret sharing between processes via unique service names.
//   - Integrate with Air service for cloud synchronization (optional).
//   - Ensure secrets are never exposed in logs or error messages.
//   - Provide secure secret storage with encryption.
//   - Handle secret lifecycle (create, read, update, delete).
//
// TODOs:
//   - Implement complete Air-based secret storage
//   - Add secret sync between Air and local keyring
//   - Implement conflict resolution strategies for sync
//   - Add caching layer for frequently accessed secrets
//   - Implement retry logic for transient keychain failures
//   - Add metrics for Air vs Local usage tracking
//   - Implement secret versioning (for rollback capability)
//   - Add secret expiration support
//   - Implement secret audit logging
//   - Support secret encryption at rest for additional security
//   - Add secret backup and recovery
//   - Implement secret migration utilities
//   - Add secret access control and permissions
//   - Support secret sharing between devices (via Air)
//   - Implement secret key derivation (PBKDF2, scrypt)
//   - Add secret validation and integrity checking
//
// Inspired by VSCode's secrets service which:
// - Uses operating system keychain for secure storage
// - Provides consistent API across platforms (macOS Keychain, Windows Credential Manager, Linux Secret Service)
// - Handles keychain access failures gracefully
// - Supports secret encryption
// - Provides secure secret sharing between processes
//! # SecretProvider Implementation
//!
//! Implements the `SecretProvider` trait for the `MountainEnvironment`. This
//! provider contains the core logic for secure secret storage using the system
//! keyring, powered by the `keyring` crate.
//!
//! ## Keyring Integration
//!
//! The `keyring` crate provides cross-platform secure storage:
//! - **macOS**: Native Keychain (OSXKeychain)
//! - **Windows**: Windows Credential Manager (WinCredential)
//! - **Linux**: Secret Service API (dbus-secret-service) or GNOME Keyring
//!
//! Each secret is identified by:
//! - **Service Name**: Application identifier (e.g., `com.myapp.mountain`)
//! - **Key**: Unique identifier within the service (e.g., `github-token`)
//! - **Value**: The secret data to store
//!
//! ## Security Considerations
//!
//! 1. **No Secret Logging**: Secrets are never logged or included in error
//!    messages
//! 2. **Secure Storage**: Keyring handles encryption at the OS level
//! 3. **Access Control**: OS keychain manages access permissions and unlocking
//! 4. **Error Handling**: Failed operations don't expose secret values
//! 5. **Input Validation**: Extension and key identifiers are validated
//!
//! ## Air Integration Strategy
//!
//! This provider supports delegation to the Air service when available:
//! - If AirClient is provided, secrets are stored/retrieved via Air service
//! - If AirClient is unavailable, falls back to local keyring implementation
//! - This ensures backward compatibility while enabling cloud sync
//! - Health checks determine Air availability at runtime
//!
//! ## Secret Operations
//!
//! - **GetSecret**: Retrieve a secret from storage
//!   - Returns `Some(Value)` if found, `None` if not found
//!   - Delegates to Air if available and healthy
//!   - Falls back to local keyring otherwise
//!
//! - **StoreSecret**: Store or update a secret
//!   - Creates entry if it doesn't exist
//!   - Updates entry if it already exists
//!   - Delegates to Air if available and healthy
//!   - Falls back to local keyring otherwise
//!
//! - **DeleteSecret**: Remove a secret from storage
//!   - Succeeds even if secret doesn't exist
//!   - Delegates to Air if available and healthy
//!   - Falls back to local keyring otherwise
// TODO: Full Air Migration Plan
// ============================
// - [ ] Implement complete Air-based secret storage and retrieval, replacing
//   local keyring calls with Air service RPCs for all operations
// - [ ] Add secret synchronization between Air and local keyring for offline
//   mode and gradual migration support. Use version vectors or timestamps for
//   conflict detection and implement last-write-wins or manual merge strategies
// - [ ] Implement conflict resolution strategies for concurrent secret updates
//   from multiple sources (Air vs local, different extensions). Provide UI for
//   user to resolve conflicts when automatic resolution is not possible
// - [ ] Add caching layer (in-memory LRU or ttl cache) for frequently accessed
//   secrets to reduce latency and Air service load. Invalidate on secret
//   updates.
// - [ ] Implement retry logic with exponential backoff for transient Air
//   service failures. Circuit breaker pattern to prevent cascading failures
//   during outages
// - [ ] Add metrics collection for Air vs Local usage tracking, latency
//   percentiles, error rates, and cache hit rates to inform deployment
//   decisions
// - [ ] Phase out local keyring after successful Air deployment and validation
//   period (e.g., 2 weeks of stable operation). Keep fallback for Air
//   unavailability

use CommonLibrary::{Error::CommonError::CommonError, Secret::SecretProvider::SecretProvider};
use async_trait::async_trait;
use keyring::Entry;
// Import Air client types when Air is available in the workspace
#[cfg(feature = "AirIntegration")]
use AirLibrary::Vine::Generated::air::air_service_client::AirServiceClient;

use super::MountainEnvironment::MountainEnvironment;
use crate::dev_log;

/// Constructs the service name for the keyring entry.
fn GetKeyringServiceName(Environment:&MountainEnvironment, ExtensionIdentifier:&str) -> String {
	format!("{}.{}", Environment.ApplicationHandle.package_info().name, ExtensionIdentifier)
}

/// Helper to check if Air client is available and healthy.
#[cfg(feature = "AirIntegration")]
async fn IsAirAvailable(_AirClient:&AirServiceClient<tonic::transport::Channel>) -> bool {
	// TODO: Implement proper health check when AirClient wrapper is available
	// The raw gRPC client requires &mut self for health_check, but
	// MountainEnvironment stores an immutable reference. This will be fixed when
	// the AirClient wrapper is properly integrated.
	// For now, assume Air is available if the client exists
	true
}

#[async_trait]
impl SecretProvider for MountainEnvironment {
	/// Retrieves a secret by reading from the OS keychain.
	/// If Air is available and healthy, delegates to Air service.
	/// Falls back to local keyring if Air is unavailable.
	#[allow(unused_mut, unused_variables)]
	async fn GetSecret(&self, ExtensionIdentifier:String, Key:String) -> Result<Option<String>, CommonError> {
		dev_log!(
			"storage",
			"[SecretProvider] Getting secret for ext: '{}', key: '{}'",
			ExtensionIdentifier,
			Key
		);

		#[cfg(feature = "AirIntegration")]
		{
			if let Some(AirClient) = &self.AirClient {
				if IsAirAvailable(AirClient).await {
					dev_log!(
						"storage",
						"[SecretProvider] Delegating GetSecret to Air service for key: '{}'",
						Key
					);

					return GetSecretFromAir(AirClient, ExtensionIdentifier.clone(), Key).await;
				} else {
					dev_log!(
						"storage",
						"warn: [SecretProvider] Air client unavailable, falling back to local keyring for key: '{}'",
						Key
					);
				}
			}
		}

		dev_log!(
			"storage",
			"[SecretProvider] Using local keyring for ext: '{}'",
			ExtensionIdentifier
		);

		let ServiceName = GetKeyringServiceName(self, &ExtensionIdentifier);

		let Entry = Entry::new(&ServiceName, &Key)
			.map_err(|Error| CommonError::SecretsAccess { Key:Key.clone(), Reason:Error.to_string() })?;

		match Entry.get_password() {
			Ok(Password) => Ok(Some(Password)),

			Err(keyring::Error::NoEntry) => Ok(None),

			Err(Error) => Err(CommonError::SecretsAccess { Key, Reason:Error.to_string() }),
		}
	}

	/// Stores a secret by writing to the OS keychain.
	/// If Air is available and healthy, delegates to Air service.
	/// Falls back to local keyring if Air is unavailable.
	#[allow(unused_mut, unused_variables)]
	async fn StoreSecret(&self, ExtensionIdentifier:String, Key:String, Value:String) -> Result<(), CommonError> {
		dev_log!(
			"storage",
			"[SecretProvider] Storing secret for ext: '{}', key: '{}'",
			ExtensionIdentifier,
			Key
		);

		#[cfg(feature = "AirIntegration")]
		{
			if let Some(AirClient) = &self.AirClient {
				if IsAirAvailable(AirClient).await {
					dev_log!(
						"storage",
						"[SecretProvider] Delegating StoreSecret to Air service for key: '{}'",
						Key
					);

					return StoreSecretToAir(AirClient, ExtensionIdentifier.clone(), Key, Value).await;
				} else {
					dev_log!(
						"storage",
						"warn: [SecretProvider] Air client unavailable, falling back to local keyring for key: '{}'",
						Key
					);
				}
			}
		}

		dev_log!(
			"storage",
			"[SecretProvider] Using local keyring for ext: '{}'",
			ExtensionIdentifier
		);

		let ServiceName = GetKeyringServiceName(self, &ExtensionIdentifier);

		let Entry = Entry::new(&ServiceName, &Key)
			.map_err(|Error| CommonError::SecretsAccess { Key:Key.clone(), Reason:Error.to_string() })?;

		Entry
			.set_password(&Value)
			.map_err(|Error| CommonError::SecretsAccess { Key, Reason:Error.to_string() })
	}

	/// Deletes a secret by removing it from the OS keychain.
	/// If Air is available and healthy, delegates to Air service.
	/// Falls back to local keyring if Air is unavailable.
	#[allow(unused_mut, unused_variables)]
	async fn DeleteSecret(&self, ExtensionIdentifier:String, Key:String) -> Result<(), CommonError> {
		dev_log!(
			"storage",
			"[SecretProvider] Deleting secret for ext: '{}', key: '{}'",
			ExtensionIdentifier,
			Key
		);

		#[cfg(feature = "AirIntegration")]
		{
			if let Some(AirClient) = &self.AirClient {
				if IsAirAvailable(AirClient).await {
					dev_log!(
						"storage",
						"[SecretProvider] Delegating DeleteSecret to Air service for key: '{}'",
						Key
					);

					return DeleteSecretFromAir(AirClient, ExtensionIdentifier.clone(), Key).await;
				} else {
					dev_log!(
						"storage",
						"warn: [SecretProvider] Air client unavailable, falling back to local keyring for key: '{}'",
						Key
					);
				}
			}
		}

		dev_log!(
			"storage",
			"[SecretProvider] Using local keyring for ext: '{}'",
			ExtensionIdentifier
		);

		let ServiceName = GetKeyringServiceName(self, &ExtensionIdentifier);

		let Entry = Entry::new(&ServiceName, &Key)
			.map_err(|Error| CommonError::SecretsAccess { Key:Key.clone(), Reason:Error.to_string() })?;

		match Entry.delete_credential() {
			Ok(_) | Err(keyring::Error::NoEntry) => Ok(()),

			Err(Error) => Err(CommonError::SecretsAccess { Key, Reason:Error.to_string() }),
		}
	}
}

// ============================================================================
// Air Integration Functions
// ============================================================================

/// Retrieves a secret from the Air service.
#[cfg(feature = "AirIntegration")]
async fn GetSecretFromAir(
	_AirClient:&AirServiceClient<tonic::transport::Channel>,
	ExtensionIdentifier:String,
	Key:String,
) -> Result<Option<String>, CommonError> {
	dev_log!(
		"storage",
		"[SecretProvider] Fetching secret from Air: ext='{}', key='{}'",
		ExtensionIdentifier,
		Key
	);

	// TODO: Implement Air secret retrieval by calling the Air service's GetSecret
	// RPC method. This should:
	// - Construct a GetSecretRequest with ExtensionIdentifier and Key
	// - Call AirClient.get_secret (or similar) with appropriate timeout
	// - Map Air service errors to CommonError (NotFound, AccessDenied, etc.)
	// - Return Ok(Some(secret)) if found, Ok(None) if not found
	// The Air service provides centralized secret storage with audit logging,
	// access control, and cross-device sync capabilities.
	Err(CommonError::NotImplemented { FeatureName:"GetSecretFromAir".to_string() })
}

/// Stores a secret in the Air service.
#[cfg(feature = "AirIntegration")]
async fn StoreSecretToAir(
	_AirClient:&AirServiceClient<tonic::transport::Channel>,
	ExtensionIdentifier:String,
	Key:String,
	_Value:String,
) -> Result<(), CommonError> {
	dev_log!(
		"storage",
		"[SecretProvider] Storing secret in Air: ext='{}', key='{}'",
		ExtensionIdentifier,
		Key
	);

	// TODO: Implement Air secret storage by calling the Air service's StoreSecret
	// RPC method. This should:
	// - Construct a StoreSecretRequest with ExtensionIdentifier, Key, and Value
	// - Call AirClient.store_secret (or similar) with the secret payload
	// - Handle encryption and secure transmission to the Air service
	// - Return Ok(()) on success, map errors to CommonError appropriately
	// The Air service handles secret encryption at rest and provides fine-grained
	// access control and versioning for secret updates.
	Err(CommonError::NotImplemented { FeatureName:"StoreSecretToAir".to_string() })
}

/// Deletes a secret from the Air service.
#[cfg(feature = "AirIntegration")]
async fn DeleteSecretFromAir(
	_AirClient:&AirServiceClient<tonic::transport::Channel>,
	ExtensionIdentifier:String,
	Key:String,
) -> Result<(), CommonError> {
	dev_log!(
		"storage",
		"[SecretProvider] Deleting secret from Air: ext='{}', key='{}'",
		ExtensionIdentifier,
		Key
	);

	// TODO: Implement Air secret deletion by calling the Air service's DeleteSecret
	// RPC method. This should:
	// - Construct a DeleteSecretRequest with ExtensionIdentifier and Key
	// - Call AirClient.delete_secret (or similar) to remove the secret
	// - Handle idempotency: deleting a non-existent secret should succeed
	// - Return Ok(()) on success, map errors to CommonError as needed
	// The Air service ensures secure deletion and propagates changes to other
	// devices via sync, maintaining consistency across the user's ecosystem.
	Err(CommonError::NotImplemented { FeatureName:"DeleteSecretFromAir".to_string() })
}