aura_effects/
biometric.rs

1//! Layer 3: Biometric Authentication Effect Handlers
2//!
3//! Fallback implementation of BiometricEffects for platforms without biometric hardware.
4//!
5//! This handler implements the Null Object Pattern - it provides safe defaults for
6//! environments where biometric authentication is unavailable (servers, CI, headless
7//! systems, development machines without sensors).
8//!
9//! **When to use**: This is the default handler for platforms without biometric hardware.
10//! **For testing**: Use `MockBiometricHandler` from aura-testkit (Layer 8).
11//! **For production with hardware**: Implement platform-specific handlers (iOS, Android, etc.)
12
13use async_trait::async_trait;
14use aura_core::effects::{
15    BiometricCapability, BiometricConfig, BiometricEffects, BiometricEnrollmentResult,
16    BiometricError, BiometricStatistics, BiometricType, BiometricVerificationResult,
17};
18use std::collections::HashMap;
19
20/// Fallback biometric handler for platforms without biometric hardware.
21///
22/// This handler returns "not available" for all capability checks and descriptive
23/// errors for all operations. It enables code to run on any platform without
24/// requiring compile-time feature flags.
25///
26/// # Usage
27///
28/// ```rust,ignore
29/// use aura_effects::FallbackBiometricHandler;
30///
31/// let handler = FallbackBiometricHandler::new()?;
32/// // All capability checks return false
33/// assert!(!handler.supports_hardware_security());
34/// ```
35#[derive(Debug)]
36pub struct FallbackBiometricHandler {
37    platform_config: String,
38}
39
40impl FallbackBiometricHandler {
41    /// Create a new fallback biometric handler
42    pub fn new() -> Result<Self, BiometricError> {
43        Ok(Self {
44            platform_config: "fallback-no-hardware".to_string(),
45        })
46    }
47}
48
49impl Default for FallbackBiometricHandler {
50    fn default() -> Self {
51        Self {
52            platform_config: "fallback-no-hardware".to_string(),
53        }
54    }
55}
56
57#[async_trait]
58impl BiometricEffects for FallbackBiometricHandler {
59    fn supports_hardware_security(&self) -> bool {
60        false
61    }
62
63    fn get_platform_capabilities(&self) -> Vec<String> {
64        vec![self.platform_config.clone()]
65    }
66
67    async fn get_biometric_capabilities(&self) -> Result<Vec<BiometricCapability>, BiometricError> {
68        let capabilities = vec![
69            BiometricType::Fingerprint,
70            BiometricType::Face,
71            BiometricType::Iris,
72            BiometricType::Voice,
73            BiometricType::PalmPrint,
74            BiometricType::Behavioral,
75        ]
76        .into_iter()
77        .map(|biometric_type| {
78            let security_level = biometric_type.security_level();
79            BiometricCapability {
80                biometric_type,
81                available: false,
82                hardware_present: false,
83                enrolled: false,
84                security_level,
85                platform_features: vec!["software-fallback".to_string()],
86            }
87        })
88        .collect();
89
90        Ok(capabilities)
91    }
92
93    async fn is_biometric_available(
94        &self,
95        _biometric_type: BiometricType,
96    ) -> Result<bool, BiometricError> {
97        Ok(false)
98    }
99
100    async fn enroll_biometric(
101        &self,
102        _config: BiometricConfig,
103        _user_prompt: &str,
104    ) -> Result<BiometricEnrollmentResult, BiometricError> {
105        Ok(BiometricEnrollmentResult {
106            success: false,
107            template_id: None,
108            quality_score: None,
109            samples_captured: 0,
110            error: Some(
111                "Biometric hardware not available in software-fallback handler".to_string(),
112            ),
113        })
114    }
115
116    async fn verify_biometric(
117        &self,
118        _biometric_type: BiometricType,
119        _user_prompt: &str,
120        _template_id: Option<&str>,
121    ) -> Result<BiometricVerificationResult, BiometricError> {
122        Ok(BiometricVerificationResult {
123            verified: false,
124            confidence_score: Some(0.0),
125            matched_template_id: None,
126            liveness_detected: Some(false),
127            verification_time_ms: 0,
128            error: Some(
129                "Biometric verification not available on this platform handler".to_string(),
130            ),
131        })
132    }
133
134    async fn delete_biometric_template(
135        &self,
136        _biometric_type: BiometricType,
137        _template_id: Option<&str>,
138    ) -> Result<(), BiometricError> {
139        // No-op: nothing stored in this handler
140        Ok(())
141    }
142
143    async fn list_enrolled_templates(
144        &self,
145    ) -> Result<Vec<(String, BiometricType, f32)>, BiometricError> {
146        Ok(Vec::new())
147    }
148
149    async fn test_biometric_hardware(
150        &self,
151        _biometric_type: BiometricType,
152    ) -> Result<bool, BiometricError> {
153        Ok(false)
154    }
155
156    async fn configure_biometric_security(
157        &self,
158        _config: BiometricConfig,
159    ) -> Result<(), BiometricError> {
160        Ok(())
161    }
162
163    async fn get_biometric_statistics(&self) -> Result<BiometricStatistics, BiometricError> {
164        Ok(BiometricStatistics {
165            total_attempts: 0,
166            successful_verifications: 0,
167            failed_attempts: 0,
168            average_verification_time_ms: 0,
169            enrolled_templates_by_type: HashMap::new(),
170            last_verification_at: None,
171            false_acceptance_rate: None,
172            false_rejection_rate: None,
173        })
174    }
175
176    async fn cancel_biometric_operation(&self) -> Result<(), BiometricError> {
177        Ok(())
178    }
179}
180
181#[cfg(test)]
182mod tests {
183    use super::*;
184
185    #[tokio::test]
186    async fn test_fallback_biometric_handler_creation_succeeds() {
187        let result = FallbackBiometricHandler::new();
188        assert!(result.is_ok());
189    }
190
191    #[tokio::test]
192    async fn test_fallback_biometric_handler_capabilities() {
193        let handler = FallbackBiometricHandler::default();
194        let result = handler.get_biometric_capabilities().await;
195        assert!(result.is_ok());
196    }
197}
aura_effects/biometric.rs

aura_effects/
biometric.rs
