Skip to main content

auth_framework/
auth.rs

1//! Main authentication framework implementation.
2
3use crate::auth_operations::{
4    AuditLogQuery, DelegationRequest, PermissionContext, SessionCreateRequest, UserListQuery,
5};
6use crate::authentication::credentials::{Credential, CredentialMetadata};
7use crate::config::AuthConfig;
8use crate::distributed::DistributedSessionStore;
9use crate::errors::{AuthError, MfaError, Result};
10use crate::methods::{AuthMethod, AuthMethodEnum, MethodResult, MfaChallenge};
11use crate::permissions::PermissionChecker;
12use crate::storage::{AuthStorage, MemoryStorage, SessionData};
13use crate::tokens::{AuthToken, TokenManager};
14use crate::utils::rate_limit::RateLimiter;
15use std::collections::HashMap;
16use std::sync::Arc;
17use std::time::Duration;
18use tokio::sync::RwLock;
19use tracing::{debug, error, info, warn};
20
21/// Result of an authentication attempt.
22#[derive(Debug, Clone)]
23pub enum AuthResult {
24    /// Authentication was successful
25    Success(Box<AuthToken>),
26
27    /// Multi-factor authentication is required
28    MfaRequired(Box<MfaChallenge>),
29
30    /// Authentication failed
31    Failure(String),
32}
33
34/// Information about a user.
35#[derive(Debug, Clone)]
36pub struct UserInfo {
37    /// User ID
38    pub id: String,
39
40    /// Username
41    pub username: String,
42
43    /// Email address
44    pub email: Option<String>,
45
46    /// Display name
47    pub name: Option<String>,
48
49    /// User roles
50    pub roles: crate::types::Roles,
51
52    /// Whether the user is active
53    pub active: bool,
54
55    /// Whether the user's email address has been verified
56    pub email_verified: bool,
57
58    /// Additional user attributes
59    pub attributes: crate::types::UserAttributes,
60}
61
62/// Returns true when running in a test environment.
63///
64/// Checks `cfg!(test)`, the `RUST_TEST` env var (set by `TestEnvironmentGuard`), and the
65/// `ENVIRONMENT=test` convention. This allows relaxed security constraints (e.g. short JWT
66/// secrets) in automated tests while enforcing them in production.
67///
68/// An explicit `ENVIRONMENT=production` setting always overrides → returns `false`, so tests
69/// that deliberately validate production-mode behaviour can opt out of the bypass.
70#[inline]
71fn is_test_env() -> bool {
72    // An explicit production override always wins — never bypass security checks.
73    if std::env::var("ENVIRONMENT").as_deref() == Ok("production") {
74        return false;
75    }
76    cfg!(test)
77        || std::env::var("RUST_TEST").is_ok()
78        || std::env::var("ENVIRONMENT").as_deref() == Ok("test")
79}
80
81/// The primary authentication and authorization framework for Rust applications.
82///
83/// `AuthFramework` is the central component that orchestrates all authentication
84/// and authorization operations. It provides a unified interface for multiple
85/// authentication methods, token management, session handling, and security monitoring.
86///
87/// # Core Capabilities
88///
89/// - **Multi-Method Authentication**: Support for password, OAuth2, MFA, passkeys, and custom methods
90/// - **Token Management**: JWT token creation, validation, and lifecycle management
91/// - **Session Management**: Secure session handling with configurable storage backends
92/// - **Permission System**: Role-based and resource-based authorization
93/// - **Security Monitoring**: Real-time threat detection and audit logging
94/// - **Rate Limiting**: Configurable rate limiting for brute force protection
95///
96/// # Thread Safety
97///
98/// The framework is designed for concurrent use and can be safely shared across
99/// multiple threads using `Arc<AuthFramework>`.
100///
101/// # Storage Backends
102///
103/// Supports multiple storage backends:
104/// - In-memory (for development/testing)
105/// - Redis (for production with clustering)
106/// - PostgreSQL (for persistent storage)
107/// - Custom implementations via the `AuthStorage` trait
108///
109/// # Example
110///
111/// ```rust,no_run
112/// use auth_framework::{AuthFramework, AuthConfig};
113/// use auth_framework::authentication::credentials::Credential;
114/// use auth_framework::methods::AuthMethodEnum;
115///
116/// # #[tokio::main]
117/// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
118/// // Create framework with default configuration
119/// let config = AuthConfig::default();
120/// let mut auth = AuthFramework::new(config);
121///
122/// // Register an authentication method
123/// # let password_method: AuthMethodEnum = unimplemented!();
124/// auth.register_method("password", password_method);
125///
126/// // Authenticate a user
127/// # let credential: Credential = unimplemented!();
128/// let result = auth.authenticate("password", credential).await?;
129/// # Ok(())
130/// # }
131/// ```
132///
133/// # Security Considerations
134///
135/// - All tokens are signed with cryptographically secure keys
136/// - Session data is encrypted at rest when using persistent storage
137/// - Rate limiting prevents brute force attacks
138/// - Audit logging captures all security-relevant events
139/// - Configurable security policies for enterprise compliance
140pub struct AuthFramework {
141    /// Configuration
142    config: AuthConfig,
143
144    /// Registered authentication methods
145    methods: HashMap<String, AuthMethodEnum>,
146
147    /// Token manager
148    token_manager: TokenManager,
149
150    /// Storage backend
151    storage: Arc<dyn AuthStorage>,
152
153    /// Authorization manager for role/permission operations
154    authorization_manager: crate::auth_modular::authorization_manager::AuthorizationManager,
155
156    /// Rate limiter
157    rate_limiter: Option<RateLimiter>,
158
159    /// Monitoring manager for metrics and health checks
160    monitoring_manager: Arc<crate::monitoring::MonitoringManager>,
161
162    /// Audit manager for security event logging
163    audit_manager: Arc<crate::audit::AuditLogger<Arc<crate::storage::MemoryStorage>>>,
164
165    /// Security manager for rate limiting, DoS protection, and IP blacklisting
166    #[cfg(feature = "api-server")]
167    security_manager: Arc<crate::api::SecurityManager>,
168
169    /// Runtime-mutable configuration. Updated live by the admin API without restart.
170    pub(crate) runtime_config: Arc<tokio::sync::RwLock<crate::config::RuntimeConfig>>,
171
172    /// Decoupled user lifecycle manager.
173    user_manager: crate::auth_modular::user_manager::UserManager,
174
175    /// Decoupled session lifecycle manager.
176    session_manager: crate::auth_modular::session_manager::SessionManager,
177
178    /// Decoupled MFA manager (TOTP, SMS, email, backup codes).
179    mfa_manager: crate::auth_modular::mfa::MfaManager,
180
181    /// Framework initialization state
182    initialized: bool,
183
184    /// Whether the caller explicitly replaced the storage backend.
185    storage_overridden: bool,
186}
187
188pub use crate::auth_operations::{
189    AdminOperations, AuditOperations, AuthorizationOperations, MaintenanceOperations,
190    MfaOperations, MonitoringOperations, SessionOperations, TokenOperations, UserOperations,
191};
192
193/// Extract JWT secret bytes from `config` or the `JWT_SECRET` env-var.
194///
195/// Tries (in order): `config.security.secret_key`, `config.secret`, `$JWT_SECRET`.
196/// Returns an error when none is present; callers in non-production environments may
197/// substitute a dev-only fallback when this function returns `Err`.
198fn resolve_jwt_secret_bytes(config: &AuthConfig) -> Result<Vec<u8>> {
199    if let Some(secret) = &config.security.secret_key {
200        if secret.len() < 32 && !is_test_env() {
201            return Err(AuthError::configuration(
202                "JWT secret must be at least 32 characters for production security",
203            ));
204        }
205        return Ok(secret.as_bytes().to_vec());
206    }
207    if let Some(secret) = &config.secret {
208        if secret.len() < 32 && !is_test_env() {
209            return Err(AuthError::configuration(
210                "JWT secret must be at least 32 characters for production security",
211            ));
212        }
213        return Ok(secret.as_bytes().to_vec());
214    }
215    if let Ok(jwt_secret) = std::env::var("JWT_SECRET") {
216        if jwt_secret.len() < 32 && !is_test_env() {
217            return Err(AuthError::configuration(
218                "JWT_SECRET must be at least 32 characters for production security",
219            ));
220        }
221        return Ok(jwt_secret.as_bytes().to_vec());
222    }
223    Err(AuthError::configuration(
224        "JWT secret not configured! Please set JWT_SECRET environment variable or provide in configuration.\n\
225           For security reasons, no default secret is provided.\n\
226           Generate a secure secret with: openssl rand -base64 32",
227    ))
228}
229
230impl AuthFramework {
231    /// Access focused user-management operations.
232    pub fn users(&self) -> UserOperations<'_> {
233        UserOperations { framework: self }
234    }
235
236    /// Access focused session-management operations.
237    pub fn sessions(&self) -> SessionOperations<'_> {
238        SessionOperations { framework: self }
239    }
240
241    /// Access focused token-management operations.
242    pub fn tokens(&self) -> TokenOperations<'_> {
243        TokenOperations { framework: self }
244    }
245
246    /// Access focused authorization operations.
247    pub fn authorization(&self) -> AuthorizationOperations<'_> {
248        AuthorizationOperations { framework: self }
249    }
250
251    /// Access focused multi-factor authentication operations.
252    pub fn mfa(&self) -> MfaOperations<'_> {
253        MfaOperations { framework: self }
254    }
255
256    /// Access focused monitoring and health operations.
257    pub fn monitoring(&self) -> MonitoringOperations<'_> {
258        MonitoringOperations { framework: self }
259    }
260
261    /// Access focused audit log operations.
262    pub fn audit(&self) -> AuditOperations<'_> {
263        AuditOperations { framework: self }
264    }
265
266    /// Access focused maintenance operations.
267    pub fn maintenance(&self) -> MaintenanceOperations<'_> {
268        MaintenanceOperations { framework: self }
269    }
270
271    /// Read the current runtime-mutable configuration.
272    pub async fn runtime_config(&self) -> crate::config::RuntimeConfig {
273        self.runtime_config.read().await.clone()
274    }
275
276    #[deprecated(since = "0.6.0", note = "Use `runtime_config()` instead")]
277    #[doc(hidden)]
278    pub async fn get_runtime_config(&self) -> crate::config::RuntimeConfig {
279        self.runtime_config().await
280    }
281
282    /// Apply a partial or full update to the runtime-mutable configuration.
283    ///
284    /// The update is applied atomically. Returns the updated configuration.
285    /// Returns `Err` if any field value is out of range (e.g. zero token lifetime).
286    pub async fn update_runtime_config(
287        &self,
288        update: crate::config::RuntimeConfig,
289    ) -> Result<crate::config::RuntimeConfig> {
290        // Basic sanity checks before persisting.
291        if update.token_lifetime_secs == 0 {
292            return Err(AuthError::config("token_lifetime_secs must be > 0"));
293        }
294        if update.refresh_token_lifetime_secs == 0 {
295            return Err(AuthError::config("refresh_token_lifetime_secs must be > 0"));
296        }
297        if update.refresh_token_lifetime_secs <= update.token_lifetime_secs {
298            return Err(AuthError::config(
299                "refresh_token_lifetime_secs must be greater than token_lifetime_secs",
300            ));
301        }
302        if update.min_password_length == 0 {
303            return Err(AuthError::config("min_password_length must be > 0"));
304        }
305        let mut cfg = self.runtime_config.write().await;
306        *cfg = update.clone();
307        Ok(update)
308    }
309
310    /// Access focused advanced administration operations (ABAC, delegation, role hierarchy).
311    pub fn admin(&self) -> AdminOperations<'_> {
312        AdminOperations { framework: self }
313    }
314
315    /// Create a new authentication framework.
316    ///
317    /// This method is infallible and creates a basic framework instance.
318    /// Configuration validation and component initialization is deferred to `initialize()`.
319    /// An ephemeral random secret is used for the token manager until `initialize()`
320    /// replaces it with the configured secret. Tokens issued before initialization
321    /// will NOT be valid afterwards.
322    pub fn new(config: AuthConfig) -> Self {
323        // Store configuration for later validation during initialize()
324        let storage = Arc::new(MemoryStorage::new()) as Arc<dyn AuthStorage>;
325        let audit_storage = Arc::new(crate::storage::MemoryStorage::new());
326        let audit_manager = Arc::new(crate::audit::AuditLogger::new(audit_storage));
327
328        // Create a token manager with a cryptographically random ephemeral secret.
329        // This avoids holding a well-known hardcoded secret in memory.  The real
330        // configured secret is applied during initialize().
331        // SAFETY: CSPRNG failure at initialization is terminal; the framework
332        // cannot operate without entropy.
333        let ephemeral_secret = {
334            let rng = ring::rand::SystemRandom::new();
335            let mut buf = [0u8; 32];
336            ring::rand::SecureRandom::fill(&rng, &mut buf)
337                .expect("AuthFramework fatal: system CSPRNG unavailable — the operating system cannot provide cryptographic randomness");
338            buf
339        };
340        let token_manager =
341            TokenManager::new_hmac(&ephemeral_secret, "auth-framework", "auth-framework");
342
343        let user_manager = crate::auth_modular::user_manager::UserManager::new(storage.clone());
344        let session_manager =
345            crate::auth_modular::session_manager::SessionManager::new(storage.clone());
346        let mfa_manager = crate::auth_modular::mfa::MfaManager::new(storage.clone());
347        let authorization_manager =
348            crate::auth_modular::authorization_manager::AuthorizationManager::new(
349                Arc::new(RwLock::new(PermissionChecker::new())),
350                storage.clone(),
351            );
352
353        Self {
354            config,
355            methods: HashMap::new(),
356            token_manager,
357            storage,
358            authorization_manager,
359            rate_limiter: None, // Will be set during initialization
360            monitoring_manager: Arc::new(crate::monitoring::MonitoringManager::new(
361                crate::monitoring::MonitoringConfig::default(),
362            )),
363            audit_manager,
364            #[cfg(feature = "api-server")]
365            security_manager: Arc::new(crate::api::SecurityManager::new()),
366            runtime_config: Arc::new(tokio::sync::RwLock::new(
367                crate::config::RuntimeConfig::default(),
368            )),
369            user_manager,
370            session_manager,
371            mfa_manager,
372            initialized: false,
373            storage_overridden: false,
374        }
375    }
376
377    /// Create a new authentication framework with validation.
378    ///
379    /// This method validates the configuration immediately and returns an error
380    /// if the configuration is invalid. Use this when you want early validation.
381    pub fn new_validated(config: AuthConfig) -> Result<Self> {
382        // Validate configuration - return error instead of panicking
383        config.validate().map_err(|e| {
384            AuthError::configuration(format!("Configuration validation failed: {}", e))
385        })?;
386
387        // Create token manager with proper error handling
388        let current_secret_bytes = resolve_jwt_secret_bytes(&config)?;
389
390        let mut token_manager =
391            TokenManager::new_hmac(&current_secret_bytes, "auth-framework", "auth-framework");
392
393        // Handle gracefully retained old secret for zero-downtime key rotation
394        if let Some(prev_secret) = &config.security.previous_secret_key {
395            // Initialize with previous key, then rotate to the new key
396            token_manager =
397                TokenManager::new_hmac(prev_secret.as_bytes(), "auth-framework", "auth-framework");
398            token_manager.rotate_hmac_key(&current_secret_bytes);
399        }
400
401        // Create storage backend with proper error handling
402        let storage: Arc<dyn AuthStorage> = match &config.storage {
403            #[cfg(feature = "redis-storage")]
404            crate::config::StorageConfig::Redis { url, key_prefix } => Arc::new(
405                crate::storage::RedisStorage::new(url, key_prefix).map_err(|e| {
406                    AuthError::configuration(format!("Failed to create Redis storage: {}", e))
407                })?,
408            ),
409            _ => Arc::new(MemoryStorage::new()) as Arc<dyn AuthStorage>,
410        };
411
412        // Create rate limiter if enabled
413        let rate_limiter = if config.rate_limiting.enabled {
414            Some(RateLimiter::new(
415                config.rate_limiting.max_requests,
416                config.rate_limiting.window,
417            ))
418        } else {
419            None
420        };
421
422        // Create audit manager
423        let audit_storage = Arc::new(crate::storage::MemoryStorage::new());
424        let audit_manager = Arc::new(crate::audit::AuditLogger::new(audit_storage));
425
426        let user_manager = crate::auth_modular::user_manager::UserManager::new(storage.clone());
427        let session_manager =
428            crate::auth_modular::session_manager::SessionManager::new(storage.clone());
429        let mfa_manager = crate::auth_modular::mfa::MfaManager::new(storage.clone());
430        let authorization_manager =
431            crate::auth_modular::authorization_manager::AuthorizationManager::new(
432                Arc::new(RwLock::new(PermissionChecker::new())),
433                storage.clone(),
434            );
435
436        Ok(Self {
437            config: config.clone(),
438            methods: HashMap::new(),
439            token_manager,
440            storage,
441            authorization_manager,
442            rate_limiter,
443            monitoring_manager: Arc::new(crate::monitoring::MonitoringManager::new(
444                crate::monitoring::MonitoringConfig::default(),
445            )),
446            audit_manager,
447            #[cfg(feature = "api-server")]
448            security_manager: Arc::new(crate::api::SecurityManager::new()),
449            runtime_config: Arc::new(tokio::sync::RwLock::new(
450                crate::config::RuntimeConfig::from_auth_config(&config),
451            )),
452            user_manager,
453            session_manager,
454            mfa_manager,
455            initialized: false,
456            storage_overridden: false,
457        })
458    }
459
460    /// Replace the storage backend with a custom implementation.
461    ///
462    /// This will swap the internal storage Arc so subsequent operations use
463    /// the provided storage instance. Implementations that rely on a
464    /// different concrete storage may need additional reconfiguration by the
465    /// caller.
466    pub fn replace_storage(&mut self, storage: std::sync::Arc<dyn AuthStorage>) {
467        self.storage = storage.clone();
468        self.user_manager = crate::auth_modular::user_manager::UserManager::new(storage.clone());
469        self.session_manager =
470            crate::auth_modular::session_manager::SessionManager::new(storage.clone());
471        self.mfa_manager = crate::auth_modular::mfa::MfaManager::new(storage.clone());
472        self.authorization_manager =
473            crate::auth_modular::authorization_manager::AuthorizationManager::new(
474                Arc::new(RwLock::new(PermissionChecker::new())),
475                storage,
476            );
477        self.storage_overridden = true;
478    }
479
480    /// Replace the distributed session store.
481    ///
482    /// Call this during application startup after configuring a distributed cache
483    /// (Redis, Valkey, Hazelcast, etc.) so that
484    /// [`coordinate_distributed_sessions`][Self::coordinate_distributed_sessions]
485    /// reports accurate cross-node session counts instead of `0`.
486    pub fn set_distributed_store(&mut self, store: Arc<dyn DistributedSessionStore>) {
487        self.session_manager.set_distributed_store(store);
488    }
489
490    /// Convenience constructor that creates a framework with a custom storage instance.
491    pub fn new_with_storage(config: AuthConfig, storage: std::sync::Arc<dyn AuthStorage>) -> Self {
492        let mut framework = Self::new(config);
493        framework.replace_storage(storage);
494        framework
495    }
496
497    /// Register an authentication method.
498    pub fn register_method(&mut self, name: impl Into<String>, method: AuthMethodEnum) {
499        let name = name.into();
500        info!("Registering authentication method: {}", name);
501
502        // Validate method configuration
503        if let Err(e) = method.validate_config() {
504            error!("Method '{}' configuration validation failed: {}", name, e);
505            return;
506        }
507
508        self.methods.insert(name, method);
509    }
510
511    /// Returns `Ok(())` when the framework has been initialised, or a clear
512    /// error telling the caller what to do.
513    ///
514    /// Prefer calling this at the top of every public method that touches
515    /// storage, tokens, sessions, or authorisation state.
516    fn require_initialized(&self) -> Result<()> {
517        if self.initialized {
518            Ok(())
519        } else {
520            Err(AuthError::configuration(
521                "Framework not initialized. Call `initialize().await` first, \
522                 or use `AuthFramework::builder().build().await` which initializes automatically.",
523            ))
524        }
525    }
526
527    /// Initialize the authentication framework.
528    ///
529    /// This method performs configuration validation, sets up secure components,
530    /// and prepares the framework for use. It must be called before any other operations.
531    ///
532    /// # Security Note
533    ///
534    /// This method validates JWT secrets and replaces any temporary secrets with
535    /// properly configured ones for production security.
536    pub async fn initialize(&mut self) -> Result<()> {
537        if self.initialized {
538            return Ok(());
539        }
540
541        info!("Initializing authentication framework");
542
543        // Validate configuration
544        self.config.validate().map_err(|e| {
545            AuthError::configuration(format!("Configuration validation failed: {}", e))
546        })?;
547
548        // Set up proper token manager with validated configuration
549        let token_manager = match resolve_jwt_secret_bytes(&self.config) {
550            Ok(bytes) => TokenManager::new_hmac(&bytes, "auth-framework", "auth-framework"),
551            Err(_) => {
552                if Self::is_production_environment() {
553                    return Err(AuthError::configuration(
554                        "Production deployment requires JWT_SECRET environment variable or configuration!\n\
555                         Generate a secure secret with: openssl rand -base64 32\n\
556                         Set it with: export JWT_SECRET=\"your-secret-here\"",
557                    ));
558                }
559                warn!("No JWT secret configured, using development-only default");
560                warn!("CRITICAL: Set JWT_SECRET environment variable for production!");
561                warn!("This configuration is NOT SECURE and should only be used in development!");
562                self.token_manager.clone()
563            }
564        };
565
566        // Replace token manager with properly configured one
567        self.token_manager = token_manager;
568
569        // Set up storage backend if not already configured
570        if !self.storage_overridden {
571            let storage =
572                crate::storage::factory::build_storage_backend(&self.config.storage, None).await?;
573            self.replace_storage(storage);
574            self.storage_overridden = false;
575        }
576
577        // Set up rate limiter if enabled
578        if self.config.rate_limiting.enabled {
579            self.rate_limiter = Some(RateLimiter::new(
580                self.config.rate_limiting.max_requests,
581                self.config.rate_limiting.window,
582            ));
583        }
584
585        // Initialize permission checker with default roles
586        self.authorization_manager.create_default_roles().await;
587
588        // Load any previously persisted roles and user→role assignments
589        self.authorization_manager.load_persisted_roles().await?;
590
591        // Perform any necessary setup
592        self.cleanup_expired_data().await?;
593
594        self.initialized = true;
595        info!("Authentication framework initialized successfully");
596
597        Ok(())
598    }
599
600    /// Authenticate a user with the specified method.
601    ///
602    /// `method_name` must match a previously registered authentication method
603    /// (e.g. `"password"`, `"jwt"`, `"oauth2"`).
604    ///
605    /// # Returns
606    ///
607    /// - [`AuthResult::Success`] — authentication succeeded; contains the issued token.
608    /// - [`AuthResult::MfaRequired`] — first factor passed but MFA is required.
609    /// - [`AuthResult::Failure`] — invalid credentials.
610    ///
611    /// # Example
612    ///
613    /// ```rust,no_run
614    /// # use auth_framework::prelude::*;
615    /// # use auth_framework::authentication::credentials::Credential;
616    /// # use auth_framework::auth::AuthResult;
617    /// # async fn example(auth: &AuthFramework) -> Result<(), AuthError> {
618    /// let result = auth.authenticate("password", Credential::password("alice", "S3cur3P@ss!")).await?;
619    /// match result {
620    ///     AuthResult::Success(token) => println!("Token: {}", token.access_token),
621    ///     AuthResult::MfaRequired(challenge) => println!("MFA needed: {:?}", challenge),
622    ///     AuthResult::Failure(msg) => eprintln!("Login failed: {msg}"),
623    /// }
624    /// # Ok(())
625    /// # }
626    /// ```
627    pub async fn authenticate(
628        &self,
629        method_name: &str,
630        credential: Credential,
631    ) -> Result<AuthResult> {
632        self.authenticate_with_metadata(method_name, credential, CredentialMetadata::new())
633            .await
634    }
635
636    /// Authenticate a user with the specified method and metadata.
637    pub async fn authenticate_with_metadata(
638        &self,
639        method_name: &str,
640        credential: Credential,
641        metadata: CredentialMetadata,
642    ) -> Result<AuthResult> {
643        use std::time::Instant;
644        use tokio::time::{Duration as TokioDuration, sleep};
645
646        let start_time = Instant::now();
647
648        // Record authentication request
649        self.monitoring_manager.record_auth_request().await;
650
651        self.require_initialized()?;
652
653        // Perform the authentication logic
654        let result = self
655            .authenticate_internal(method_name, credential, metadata)
656            .await;
657
658        // Ensure minimum response time to prevent timing attacks
659        let min_duration = TokioDuration::from_millis(100); // 100ms minimum
660        let elapsed = start_time.elapsed();
661        if elapsed < min_duration {
662            sleep(min_duration - elapsed).await;
663        }
664
665        // Record authentication performance
666        if let Ok(ref auth_result) = result {
667            match auth_result {
668                AuthResult::Success(token) => {
669                    self.monitoring_manager
670                        .record_auth_success(&token.user_id, elapsed)
671                        .await;
672                }
673                AuthResult::Failure(reason) => {
674                    self.monitoring_manager
675                        .record_auth_failure(None, reason)
676                        .await;
677                }
678                _ => {} // MFA required - not counted as failure
679            }
680        }
681
682        result
683    }
684
685    /// Internal authentication logic without timing protection
686    async fn authenticate_internal(
687        &self,
688        method_name: &str,
689        credential: Credential,
690        metadata: CredentialMetadata,
691    ) -> Result<AuthResult> {
692        // Check rate limiting
693        if let Some(ref rate_limiter) = self.rate_limiter {
694            let rate_key = format!(
695                "auth:{}:{}",
696                method_name,
697                metadata.client_ip.as_deref().unwrap_or("unknown")
698            );
699
700            if !rate_limiter.is_allowed(&rate_key) {
701                warn!(
702                    "Rate limit exceeded for method '{}' from IP {:?}",
703                    method_name, metadata.client_ip
704                );
705                return Err(AuthError::rate_limit("Too many authentication attempts"));
706            }
707        }
708
709        // Built-in password authentication: reads credentials from framework storage directly.
710        // This handles password auth even when no "password" method has been explicitly registered,
711        // allowing the register endpoint and login endpoint to work with the same storage backend.
712        if method_name == "password"
713            && let Credential::Password {
714                ref username,
715                ref password,
716            } = credential
717        {
718            return self
719                .authenticate_password_builtin(username, password, &metadata)
720                .await;
721        }
722
723        if method_name == "jwt" {
724            return match credential {
725                Credential::Jwt { token } | Credential::Bearer { token } => {
726                    self.authenticate_jwt_builtin(&token, &metadata, "jwt")
727                        .await
728                }
729                _ => Ok(AuthResult::Failure(
730                    "JWT authentication expects Credential::jwt or Credential::bearer".to_string(),
731                )),
732            };
733        }
734
735        if matches!(method_name, "api_key" | "api-key") {
736            return match credential {
737                Credential::ApiKey { key } => {
738                    self.authenticate_api_key_builtin(&key, &metadata, "api_key")
739                        .await
740                }
741                _ => Ok(AuthResult::Failure(
742                    "API key authentication expects Credential::api_key".to_string(),
743                )),
744            };
745        }
746
747        if method_name == "oauth2" {
748            return self
749                .authenticate_oauth2_builtin(credential, &metadata)
750                .await;
751        }
752
753        // Get the authentication method
754        let method = self.methods.get(method_name).ok_or_else(|| {
755            AuthError::auth_method(method_name, "Authentication method not found".to_string())
756        })?;
757
758        // Log authentication attempt
759        debug!(
760            "Authentication attempt with method '{}' for credential: {}",
761            method_name,
762            credential.safe_display()
763        );
764
765        // Perform authentication
766        let result = method.authenticate(credential, metadata.clone()).await?;
767
768        // Log and handle the result
769        match &result {
770            MethodResult::Success(token) => {
771                info!(
772                    "Authentication successful for user '{}' with method '{}'",
773                    token.user_id, method_name
774                );
775
776                // Store token
777                self.storage.store_token(token).await?;
778
779                // Log audit event
780                self.log_audit_event("auth_success", &token.user_id, method_name, &metadata)
781                    .await;
782
783                Ok(AuthResult::Success(token.clone()))
784            }
785
786            MethodResult::MfaRequired(challenge) => {
787                info!(
788                    "MFA required for user '{}' with method '{}'",
789                    challenge.user_id, method_name
790                );
791
792                // Store MFA challenge with resource limits
793                self.guard_and_store_mfa_challenge((**challenge).clone())
794                    .await?;
795
796                // Log audit event
797                self.log_audit_event("mfa_required", &challenge.user_id, method_name, &metadata)
798                    .await;
799
800                Ok(AuthResult::MfaRequired(challenge.clone()))
801            }
802
803            MethodResult::Failure { reason } => {
804                warn!(
805                    "Authentication failed for method '{}': {}",
806                    method_name, reason
807                );
808
809                // Log audit event
810                self.log_audit_event("auth_failure", "unknown", method_name, &metadata)
811                    .await;
812
813                Ok(AuthResult::Failure(reason.clone()))
814            }
815        }
816    }
817
818    async fn authenticate_jwt_builtin(
819        &self,
820        token: &str,
821        metadata: &CredentialMetadata,
822        auth_method: &str,
823    ) -> Result<AuthResult> {
824        if token.is_empty() {
825            return Ok(AuthResult::Failure("JWT token cannot be empty".to_string()));
826        }
827
828        // The "jwt" method authenticates a user's own session: a token issued to an OAuth client
829        // is refused there.
830        let validated = if auth_method == "jwt" {
831            self.token_manager.validate_session_jwt_token(token)
832        } else {
833            self.token_manager.validate_jwt_token(token)
834        };
835        match validated {
836            Ok(claims) => {
837                let token =
838                    Self::build_validated_jwt_auth_token(token, claims, metadata, auth_method);
839                Ok(AuthResult::Success(Box::new(token)))
840            }
841            Err(error) => {
842                if let Some(reason) = Self::credential_failure_reason(&error) {
843                    Ok(AuthResult::Failure(reason))
844                } else {
845                    Err(error)
846                }
847            }
848        }
849    }
850
851    async fn authenticate_api_key_builtin(
852        &self,
853        api_key: &str,
854        metadata: &CredentialMetadata,
855        auth_method: &str,
856    ) -> Result<AuthResult> {
857        if api_key.is_empty() {
858            return Ok(AuthResult::Failure("API key cannot be empty".to_string()));
859        }
860
861        match self.validate_api_key(api_key).await {
862            Ok(user) => {
863                let scopes: Vec<String> = if user.roles.is_empty() {
864                    vec!["api_user".to_string()]
865                } else {
866                    user.roles.to_vec()
867                };
868                let mut token = self
869                    .token_manager
870                    .create_auth_token(&user.id, scopes.clone(), auth_method, None)?
871                    .with_roles(user.roles)
872                    .with_scopes(scopes);
873                token.metadata.issued_ip = metadata.client_ip.clone();
874                token.metadata.user_agent = metadata.user_agent.clone();
875                Ok(AuthResult::Success(Box::new(token)))
876            }
877            Err(error) => {
878                if let Some(reason) = Self::credential_failure_reason(&error) {
879                    Ok(AuthResult::Failure(reason))
880                } else {
881                    Err(error)
882                }
883            }
884        }
885    }
886
887    async fn authenticate_oauth2_builtin(
888        &self,
889        credential: Credential,
890        metadata: &CredentialMetadata,
891    ) -> Result<AuthResult> {
892        match credential {
893            Credential::OAuth {
894                authorization_code, ..
895            } => {
896                if authorization_code.is_empty() {
897                    return Ok(AuthResult::Failure(
898                        "OAuth authorization code cannot be empty".to_string(),
899                    ));
900                }
901                Ok(AuthResult::Failure(
902                    "OAuth 2.0 authorization codes must be exchanged through an OAuth provider or server endpoint before authentication completes"
903                        .to_string(),
904                ))
905            }
906            Credential::OAuthRefresh { refresh_token } => {
907                if refresh_token.is_empty() {
908                    return Ok(AuthResult::Failure(
909                        "OAuth refresh token cannot be empty".to_string(),
910                    ));
911                }
912                Ok(AuthResult::Failure(
913                    "OAuth 2.0 refresh tokens must be exchanged through an OAuth provider or server endpoint before authentication completes"
914                        .to_string(),
915                ))
916            }
917            Credential::Jwt { token }
918            | Credential::Bearer { token }
919            | Credential::OpenIdConnect { id_token: token, .. } => {
920                self.authenticate_jwt_builtin(&token, metadata, "oauth2").await
921            }
922            _ => Ok(AuthResult::Failure(
923                "OAuth2 authentication expects Credential::oauth_code, Credential::oauth_refresh, Credential::jwt, Credential::bearer, or Credential::openid_connect"
924                    .to_string(),
925            )),
926        }
927    }
928
929    fn build_validated_jwt_auth_token(
930        raw_token: &str,
931        claims: crate::tokens::JwtClaims,
932        metadata: &CredentialMetadata,
933        auth_method: &str,
934    ) -> AuthToken {
935        let crate::tokens::JwtClaims {
936            sub,
937            iss,
938            exp,
939            iat,
940            jti,
941            scope,
942            permissions,
943            roles,
944            client_id,
945            ..
946        } = claims;
947
948        let now = chrono::Utc::now();
949        let issued_at = chrono::DateTime::<chrono::Utc>::from_timestamp(iat, 0).unwrap_or(now);
950        let expires_at = chrono::DateTime::<chrono::Utc>::from_timestamp(exp, 0)
951            .unwrap_or(now + chrono::Duration::hours(1));
952        let lifetime = (expires_at - now)
953            .to_std()
954            .unwrap_or_else(|_| Duration::from_secs(1));
955        let scopes = if scope.trim().is_empty() {
956            Vec::new()
957        } else {
958            scope.split_whitespace().map(str::to_string).collect()
959        };
960
961        let mut token = AuthToken::new(sub.clone(), raw_token.to_string(), lifetime, auth_method)
962            .with_scopes(scopes)
963            .with_permissions(permissions.unwrap_or_default())
964            .with_roles(roles.unwrap_or_default());
965        token.token_id = jti;
966        token.subject = Some(sub);
967        token.issuer = Some(iss);
968        token.issued_at = issued_at;
969        token.expires_at = expires_at;
970        token.metadata.issued_ip = metadata.client_ip.clone();
971        token.metadata.user_agent = metadata.user_agent.clone();
972        if let Some(client_id) = client_id {
973            token.client_id = Some(client_id);
974        }
975        token
976    }
977
978    fn credential_failure_reason(error: &AuthError) -> Option<String> {
979        match error {
980            AuthError::Token(_) | AuthError::Jwt(_) => Some(error.to_string()),
981            AuthError::Validation { message } => Some(message.clone()),
982            AuthError::UserNotFound => Some("User not found".to_string()),
983            _ => None,
984        }
985    }
986
987    /// Built-in password authentication against framework storage.
988    async fn authenticate_password_builtin(
989        &self,
990        username: &str,
991        password: &str,
992        metadata: &CredentialMetadata,
993    ) -> Result<AuthResult> {
994        use crate::auth_modular::user_manager::CredentialCheckResult;
995
996        if username.is_empty() || password.is_empty() {
997            return Ok(AuthResult::Failure(
998                "Username or password cannot be empty".to_string(),
999            ));
1000        }
1001
1002        match self
1003            .user_manager
1004            .verify_login_credentials(username, password)
1005            .await?
1006        {
1007            None => {
1008                self.log_audit_event("auth_failure", "unknown", "password", metadata)
1009                    .await;
1010                Ok(AuthResult::Failure(
1011                    "Invalid username or password".to_string(),
1012                ))
1013            }
1014            Some(CredentialCheckResult {
1015                ref user_id,
1016                mfa_enabled: true,
1017            }) => {
1018                let now = chrono::Utc::now();
1019                let challenge = MfaChallenge {
1020                    id: crate::utils::string::generate_id(Some("mfa")),
1021                    mfa_type: crate::methods::MfaType::MultiMethod,
1022                    user_id: user_id.clone(),
1023                    created_at: now,
1024                    expires_at: now + chrono::Duration::minutes(5),
1025                    attempts: 0,
1026                    max_attempts: 5,
1027                    code_hash: None,
1028                    message: Some(
1029                        "Provide your current TOTP code or a backup code to complete login"
1030                            .to_string(),
1031                    ),
1032                    data: HashMap::new(),
1033                };
1034                self.guard_and_store_mfa_challenge(challenge.clone())
1035                    .await?;
1036                self.log_audit_event("mfa_required", user_id, "password", metadata)
1037                    .await;
1038                info!(
1039                    "Built-in password authentication requires MFA for user: {}",
1040                    username
1041                );
1042                Ok(AuthResult::MfaRequired(Box::new(challenge)))
1043            }
1044            Some(CredentialCheckResult {
1045                ref user_id,
1046                mfa_enabled: false,
1047            }) => {
1048                let token = self
1049                    .mint_and_store_token(
1050                        user_id,
1051                        vec!["read".to_string(), "write".to_string()],
1052                        "password",
1053                        None,
1054                    )
1055                    .await?;
1056                self.monitoring_manager.record_auth_request().await;
1057                self.log_audit_event("auth_success", user_id, "password", metadata)
1058                    .await;
1059                info!(
1060                    "Built-in password authentication successful for user: {}",
1061                    username
1062                );
1063                Ok(AuthResult::Success(Box::new(token)))
1064            }
1065        }
1066    }
1067
1068    /// Complete multi-factor authentication.
1069    pub async fn complete_mfa(&self, challenge: MfaChallenge, mfa_code: &str) -> Result<AuthToken> {
1070        debug!("Completing MFA for challenge '{}'", challenge.id);
1071
1072        let stored_challenge = self
1073            .mfa_manager
1074            .get_challenge(&challenge.id)
1075            .await?
1076            .ok_or(MfaError::ChallengeExpired)?;
1077
1078        if stored_challenge.is_expired() {
1079            self.mfa_manager.remove_challenge(&challenge.id).await?;
1080            return Err(MfaError::ChallengeExpired.into());
1081        }
1082
1083        if !self.verify_mfa_code(&stored_challenge, mfa_code).await? {
1084            return Err(MfaError::InvalidCode.into());
1085        }
1086
1087        self.mfa_manager.remove_challenge(&challenge.id).await?;
1088
1089        let scopes = self
1090            .user_manager
1091            .get_user_roles(&challenge.user_id)
1092            .await
1093            .unwrap_or_else(|_| vec!["user".to_string()]);
1094
1095        let token = self
1096            .mint_and_store_token(&challenge.user_id, scopes, "mfa", None)
1097            .await?;
1098
1099        info!(
1100            "MFA completed successfully for user '{}'",
1101            challenge.user_id
1102        );
1103        Ok(token)
1104    }
1105
1106    /// Complete MFA using a previously issued challenge ID.
1107    pub async fn complete_mfa_by_id(
1108        &self,
1109        challenge_id: &str,
1110        mfa_code: &str,
1111    ) -> Result<AuthToken> {
1112        let challenge = self
1113            .mfa_manager
1114            .get_challenge(challenge_id)
1115            .await?
1116            .ok_or(MfaError::ChallengeExpired)?;
1117
1118        self.complete_mfa(challenge, mfa_code).await
1119    }
1120
1121    /// Validate a token.
1122    pub async fn validate_token(&self, token: &AuthToken) -> Result<bool> {
1123        self.require_initialized()?;
1124        let valid = token.is_valid()
1125            && self.token_manager.validate_auth_token(token).is_ok()
1126            && self.touch_stored_token(token).await?;
1127        self.monitoring_manager.record_token_validation(valid).await;
1128        Ok(valid)
1129    }
1130
1131    async fn touch_stored_token(&self, token: &AuthToken) -> Result<bool> {
1132        let Some(mut stored) = self.storage.get_token(&token.token_id).await? else {
1133            return Ok(false);
1134        };
1135        stored.mark_used();
1136        self.storage.update_token(&stored).await?;
1137        Ok(true)
1138    }
1139
1140    /// Get user information from a token.
1141    pub async fn get_user_info(&self, token: &AuthToken) -> Result<UserInfo> {
1142        if !self.validate_token(token).await? {
1143            return Err(AuthError::auth_method("token", "Invalid token".to_string()));
1144        }
1145
1146        let token_info = self.token_manager.extract_token_info(&token.access_token)?;
1147
1148        // Fetch authoritative user state (active flag, current roles) from storage.
1149        // Fall back to token claims if the user record is not found.
1150        match self.user_manager.get_user_info(&token_info.user_id).await {
1151            Ok(mut info) => {
1152                // Overlay any token-specific attributes on top of the stored profile.
1153                if !token_info.attributes.is_empty() {
1154                    let string_attrs: HashMap<String, String> = token_info
1155                        .attributes
1156                        .into_iter()
1157                        .map(|(k, v)| {
1158                            (
1159                                k,
1160                                v.as_str()
1161                                    .map(|s| s.to_string())
1162                                    .unwrap_or_else(|| v.to_string()),
1163                            )
1164                        })
1165                        .collect();
1166                    info.attributes = string_attrs.into();
1167                }
1168                Ok(info)
1169            }
1170            Err(_) => {
1171                let string_attrs: HashMap<String, String> = token_info
1172                    .attributes
1173                    .into_iter()
1174                    .map(|(k, v)| {
1175                        (
1176                            k,
1177                            v.as_str()
1178                                .map(|s| s.to_string())
1179                                .unwrap_or_else(|| v.to_string()),
1180                        )
1181                    })
1182                    .collect();
1183                Ok(UserInfo {
1184                    id: token_info.user_id,
1185                    username: token_info.username.unwrap_or_else(|| "unknown".to_string()),
1186                    email: token_info.email,
1187                    name: token_info.name,
1188                    roles: token_info.roles.into(),
1189                    active: false,
1190                    email_verified: false,
1191                    attributes: string_attrs.into(),
1192                })
1193            }
1194        }
1195    }
1196
1197    /// Check if a token has permission to perform an action on a resource.
1198    ///
1199    /// This method validates the token and checks if the authenticated user
1200    /// has the required permission for the specified action on the given resource.
1201    ///
1202    /// # Parameters
1203    /// - `token`: The authentication token to validate and check permissions for
1204    /// - `action`: The action being requested (e.g., "read", "write", "delete")
1205    /// - `resource`: The resource being accessed (e.g., "documents", "users", "reports/123")
1206    ///
1207    /// # Returns
1208    /// Returns `true` if the token is valid and the user has the required permission,
1209    /// `false` if the token is invalid or the user lacks permission.
1210    ///
1211    /// # Example
1212    /// ```rust,no_run
1213    /// # use auth_framework::prelude::*;
1214    /// # async fn example(auth: &AuthFramework, token: &AuthToken) -> Result<(), AuthError> {
1215    /// if auth.check_permission(token, "read", "documents").await? {
1216    ///     println!("User can read documents");
1217    /// } else {
1218    ///     println!("Access denied");
1219    /// }
1220    /// # Ok(())
1221    /// # }
1222    /// ```
1223    pub async fn check_permission(
1224        &self,
1225        token: &AuthToken,
1226        action: &str,
1227        resource: &str,
1228    ) -> Result<bool> {
1229        if !self.validate_token(token).await? {
1230            return Ok(false);
1231        }
1232        self.authorization_manager
1233            .check_token_permission(token, action, resource)
1234            .await
1235    }
1236
1237    /// Refresh a token.
1238    pub async fn refresh_token(&self, token: &AuthToken) -> Result<AuthToken> {
1239        self.require_initialized()?;
1240        debug!("Refreshing token for user '{}'", token.user_id);
1241
1242        // Check if the auth method supports refresh
1243        if let Some(method) = self.methods.get(&token.auth_method)
1244            && method.supports_refresh()
1245            && let Some(ref refresh_token) = token.refresh_token
1246        {
1247            let new_token = method.refresh_token(refresh_token.to_string()).await?;
1248            self.storage.store_token(&new_token).await?;
1249            return Ok(new_token);
1250        }
1251
1252        // Fallback to creating a new token with the same properties
1253        let new_token = self.token_manager.refresh_token(token)?;
1254        self.storage.store_token(&new_token).await?;
1255
1256        info!("Token refreshed for user '{}'", token.user_id);
1257
1258        Ok(new_token)
1259    }
1260
1261    /// Revoke a token.
1262    pub async fn revoke_token(&self, token: &AuthToken) -> Result<()> {
1263        self.require_initialized()?;
1264        debug!("Revoking token for user '{}'", token.user_id);
1265
1266        // Mark token as revoked
1267        let mut revoked_token = token.clone();
1268        revoked_token.revoke(Some("Manual revocation".to_string()));
1269
1270        // Update in storage
1271        self.storage.update_token(&revoked_token).await?;
1272
1273        info!("Token revoked for user '{}'", token.user_id);
1274
1275        Ok(())
1276    }
1277
1278    /// Create a new API key for a user.
1279    pub async fn create_api_key(
1280        &self,
1281        user_id: &str,
1282        expires_in: Option<Duration>,
1283    ) -> Result<String> {
1284        self.require_initialized()?;
1285        self.user_manager.create_api_key(user_id, expires_in).await
1286    }
1287
1288    /// Validate an API key and return user information.
1289    pub async fn validate_api_key(&self, api_key: &str) -> Result<UserInfo> {
1290        self.require_initialized()?;
1291        self.user_manager.validate_api_key(api_key).await
1292    }
1293
1294    /// Revoke an API key.
1295    pub async fn revoke_api_key(&self, api_key: &str) -> Result<()> {
1296        self.require_initialized()?;
1297        self.user_manager.revoke_api_key(api_key).await
1298    }
1299
1300    /// Create a new session.
1301    pub async fn create_session(
1302        &self,
1303        user_id: &str,
1304        expires_in: Duration,
1305        ip_address: Option<String>,
1306        user_agent: Option<String>,
1307    ) -> Result<String> {
1308        self.require_initialized()?;
1309        let (session_id, new_total) = self
1310            .session_manager
1311            .create_session_limited(user_id, expires_in, ip_address, user_agent)
1312            .await?;
1313        self.monitoring_manager
1314            .update_session_count(new_total)
1315            .await;
1316        Ok(session_id)
1317    }
1318
1319    /// Create a new session using a [`SessionCreateRequest`] for better readability.
1320    ///
1321    /// Prefer [`create_session_with_request`](Self::create_session_with_request)
1322    /// with a [`SessionCreateRequest`] for better readability when using optional fields.
1323    ///
1324    /// # Example
1325    ///
1326    /// ```rust,no_run
1327    /// # use auth_framework::{prelude::*, auth_operations::SessionCreateRequest};
1328    /// # use std::time::Duration;
1329    /// # async fn example(auth: &AuthFramework) -> Result<(), auth_framework::errors::AuthError> {
1330    /// let session_id = auth.create_session_with_request(
1331    ///     SessionCreateRequest::new("user_123", Duration::from_secs(3600))
1332    ///         .ip_address("192.168.1.1")
1333    ///         .user_agent("MyApp/1.0")
1334    /// ).await?;
1335    /// # Ok(())
1336    /// # }
1337    /// ```
1338    pub async fn create_session_with_request(&self, req: SessionCreateRequest) -> Result<String> {
1339        self.create_session(
1340            req.get_user_id(),
1341            req.get_expires_in(),
1342            req.get_ip_address().map(|s| s.to_string()),
1343            req.get_user_agent().map(|s| s.to_string()),
1344        )
1345        .await
1346    }
1347
1348    /// Get session information.
1349    pub async fn get_session(&self, session_id: &str) -> Result<Option<SessionData>> {
1350        self.require_initialized()?;
1351        self.session_manager.get_session(session_id).await
1352    }
1353
1354    /// Delete a session.
1355    pub async fn delete_session(&self, session_id: &str) -> Result<()> {
1356        self.require_initialized()?;
1357        self.session_manager.delete_session(session_id).await?;
1358
1359        let remaining = self
1360            .session_manager
1361            .count_active_sessions()
1362            .await
1363            .unwrap_or(0);
1364        self.monitoring_manager
1365            .update_session_count(remaining)
1366            .await;
1367
1368        Ok(())
1369    }
1370
1371    /// Get all tokens for a user.
1372    pub async fn list_user_tokens(&self, user_id: &str) -> Result<Vec<AuthToken>> {
1373        self.require_initialized()?;
1374        self.storage.list_user_tokens(user_id).await
1375    }
1376
1377    /// Clean up expired data.
1378    pub async fn cleanup_expired_data(&self) -> Result<()> {
1379        debug!("Cleaning up expired data");
1380
1381        // Clean up storage
1382        self.storage.cleanup_expired().await?;
1383
1384        // Clean up MFA challenges via mfa manager
1385        self.mfa_manager.cleanup_expired_challenges().await?;
1386
1387        // Clean up sessions via session manager
1388        self.session_manager.cleanup_expired_sessions().await?;
1389
1390        // Clean up rate limiter
1391        if let Some(ref rate_limiter) = self.rate_limiter {
1392            let _ = rate_limiter.cleanup().ok();
1393        }
1394
1395        Ok(())
1396    }
1397
1398    /// Detect if the process is running in a production environment by inspecting
1399    /// well-known environment variables and container indicators.
1400    fn is_production_environment() -> bool {
1401        if let Ok(env) = std::env::var("ENVIRONMENT")
1402            && (env.to_lowercase() == "production" || env.to_lowercase() == "prod")
1403        {
1404            return true;
1405        }
1406        if let Ok(env) = std::env::var("ENV")
1407            && (env.to_lowercase() == "production" || env.to_lowercase() == "prod")
1408        {
1409            return true;
1410        }
1411        if let Ok(env) = std::env::var("NODE_ENV")
1412            && env.to_lowercase() == "production"
1413        {
1414            return true;
1415        }
1416        if let Ok(env) = std::env::var("RUST_ENV")
1417            && env.to_lowercase() == "production"
1418        {
1419            return true;
1420        }
1421        std::env::var("KUBERNETES_SERVICE_HOST").is_ok()
1422            || std::env::var("DOCKER_CONTAINER").is_ok()
1423    }
1424
1425    /// Get authentication framework statistics.
1426    pub async fn get_stats(&self) -> Result<AuthStats> {
1427        let mut stats = AuthStats::default();
1428
1429        if let Err(e) = self.storage.cleanup_expired().await {
1430            warn!("Failed to cleanup expired data: {}", e);
1431        }
1432        if let Some(rate_limiter) = &self.rate_limiter {
1433            let _ = rate_limiter.cleanup().ok();
1434        }
1435
1436        let active_sessions = self
1437            .session_manager
1438            .count_active_sessions()
1439            .await
1440            .unwrap_or(0) as u32;
1441
1442        stats.registered_methods = self.methods.keys().cloned().collect();
1443        stats.active_sessions = active_sessions as u64;
1444        stats.active_mfa_challenges = self.mfa_manager.get_active_challenge_count().await as u64;
1445        // Use monitoring counters for accurate cumulative tracking
1446        let perf = self.monitoring_manager.get_performance_metrics();
1447        stats.tokens_issued = perf.get("token_creations").copied().unwrap_or(0);
1448        stats.auth_attempts = perf.get("auth_successes").copied().unwrap_or(0)
1449            + perf.get("auth_failures").copied().unwrap_or(0);
1450
1451        Ok(stats)
1452    }
1453
1454    /// Returns a reference to the underlying [`TokenManager`].
1455    ///
1456    /// Useful for advanced token operations not exposed by the
1457    /// [`TokenOperations`] facade.
1458    pub fn token_manager(&self) -> &TokenManager {
1459        &self.token_manager
1460    }
1461
1462    /// Validates a username against the configured format rules.
1463    ///
1464    /// Returns `Ok(true)` when the name is acceptable, or an error describing
1465    /// the specific rule that was violated (length, characters, etc.).
1466    ///
1467    /// # Errors
1468    ///
1469    /// Returns [`AuthError`] if the username is empty, too long, or contains
1470    /// forbidden characters per the active [`SecurityConfig`].
1471    pub async fn validate_username(&self, username: &str) -> Result<bool> {
1472        self.user_manager.validate_username(username).await
1473    }
1474
1475    /// Validates a display name against the configured format rules.
1476    ///
1477    /// # Errors
1478    ///
1479    /// Returns [`AuthError`] if the display name is empty or exceeds the
1480    /// configured maximum length.
1481    pub async fn validate_display_name(&self, display_name: &str) -> Result<bool> {
1482        self.user_manager.validate_display_name(display_name).await
1483    }
1484
1485    /// Checks a password against the active security policy.
1486    ///
1487    /// Validates minimum length, character-class requirements, and (optionally)
1488    /// checks against known-breached password lists.
1489    ///
1490    /// # Errors
1491    ///
1492    /// Returns [`AuthError`] describing which policy rule the password violates.
1493    pub async fn validate_password_strength(&self, password: &str) -> Result<bool> {
1494        self.user_manager.validate_password_strength(password).await
1495    }
1496
1497    /// Validates arbitrary user input against common injection patterns.
1498    ///
1499    /// Checks for SQL injection, XSS, and command injection markers.
1500    /// Returns `Ok(true)` when the input is safe.
1501    pub async fn validate_user_input(&self, input: &str) -> Result<bool> {
1502        Ok(crate::utils::validation::validate_user_input(input))
1503    }
1504
1505    /// Creates an authentication token directly.
1506    ///
1507    /// This is a low-level API intended for **testing, migration tools, and
1508    /// administrative tasks**. In production, tokens should be created through
1509    /// [`authenticate`](Self::authenticate) instead.
1510    ///
1511    /// # Parameters
1512    ///
1513    /// * `user_id`     — the subject the token is issued to.
1514    /// * `scopes`      — OAuth-style scopes (accepts `Vec<String>`, `Scopes`, or `&[&str]`).
1515    /// * `method_name` — the auth method to record (must be registered).
1516    /// * `lifetime`    — override the default token TTL; `None` uses the
1517    ///   framework-configured default.
1518    ///
1519    /// # Errors
1520    ///
1521    /// * [`AuthError::AuthMethod`] if `method_name` is not registered.
1522    /// * [`AuthError::RateLimit`] if the user already holds the maximum number
1523    ///   of active tokens.
1524    pub async fn create_auth_token(
1525        &self,
1526        user_id: impl Into<String>,
1527        scopes: impl Into<crate::types::Scopes>,
1528        method_name: impl Into<String>,
1529        lifetime: Option<Duration>,
1530    ) -> Result<AuthToken> {
1531        let method_name = method_name.into();
1532        let user_id = user_id.into();
1533        let scopes: crate::types::Scopes = scopes.into();
1534
1535        // Validate the method exists and is correctly configured
1536        let auth_method = self
1537            .methods
1538            .get(&method_name)
1539            .ok_or_else(|| AuthError::auth_method(&method_name, "Method not found"))?;
1540        auth_method.validate_config()?;
1541
1542        // ENTERPRISE SECURITY: Check token limits to prevent resource exhaustion
1543        const MAX_TOKENS_PER_USER: usize = 100;
1544        let user_tokens = self.storage.list_user_tokens(&user_id).await?;
1545        if user_tokens.len() >= MAX_TOKENS_PER_USER {
1546            warn!(
1547                "User '{}' has reached maximum tokens ({})",
1548                user_id, MAX_TOKENS_PER_USER
1549            );
1550            return Err(AuthError::rate_limit(
1551                "Maximum tokens per user exceeded. Please revoke unused tokens.",
1552            ));
1553        }
1554
1555        let token = self
1556            .mint_and_store_token(&user_id, scopes, &method_name, lifetime)
1557            .await?;
1558        self.monitoring_manager
1559            .record_token_creation(&method_name)
1560            .await;
1561        Ok(token)
1562    }
1563
1564    /// Initiates an SMS-based MFA challenge for `user_id`.
1565    ///
1566    /// Sends a one-time code via the configured SMS provider and returns a
1567    /// challenge ID that must be passed to [`verify_sms_code`](Self::verify_sms_code).
1568    ///
1569    /// # Errors
1570    ///
1571    /// Returns [`AuthError`] if no phone number is registered or the SMS
1572    /// provider fails to deliver.
1573    pub async fn initiate_sms_challenge(&self, user_id: &str) -> Result<String> {
1574        self.mfa_manager.sms.initiate_challenge(user_id).await
1575    }
1576
1577    /// Verifies an SMS challenge code previously issued by
1578    /// [`initiate_sms_challenge`](Self::initiate_sms_challenge).
1579    ///
1580    /// # Errors
1581    ///
1582    /// Returns [`AuthError`] if the challenge has expired or if the code is
1583    /// invalid.
1584    pub async fn verify_sms_code(&self, challenge_id: &str, code: &str) -> Result<bool> {
1585        self.mfa_manager.sms.verify_code(challenge_id, code).await
1586    }
1587
1588    /// Registers an email address for email-based MFA for `user_id`.
1589    ///
1590    /// # Errors
1591    ///
1592    /// Returns [`AuthError`] if the email format is invalid or the user does
1593    /// not exist.
1594    pub async fn register_email(&self, user_id: &str, email: &str) -> Result<()> {
1595        self.mfa_manager.email.register_email(user_id, email).await
1596    }
1597
1598    /// Generates a new TOTP secret and stores it for `user_id`.
1599    ///
1600    /// The returned string is a Base32-encoded secret suitable for importing
1601    /// into authenticator apps. Pair with
1602    /// [`generate_totp_qr_code`](Self::generate_totp_qr_code) for a scan-ready
1603    /// URI.
1604    ///
1605    /// # Errors
1606    ///
1607    /// Returns [`AuthError`] if secret generation or storage fails.
1608    pub async fn generate_totp_secret(&self, user_id: &str) -> Result<String> {
1609        self.mfa_manager.totp.generate_secret(user_id).await
1610    }
1611
1612    /// Generates an `otpauth://` URI suitable for rendering as a QR code.
1613    ///
1614    /// # Parameters
1615    ///
1616    /// * `user_id`  — identifies the user in the authenticator label.
1617    /// * `app_name` — the issuer name shown in the authenticator app.
1618    /// * `secret`   — the Base32 TOTP secret from [`generate_totp_secret`](Self::generate_totp_secret).
1619    pub async fn generate_totp_qr_code(
1620        &self,
1621        user_id: &str,
1622        app_name: &str,
1623        secret: &str,
1624    ) -> Result<String> {
1625        self.mfa_manager
1626            .totp
1627            .generate_qr_code(user_id, app_name, secret)
1628            .await
1629    }
1630
1631    /// Generates the current TOTP code for the given Base32 `secret`.
1632    ///
1633    /// Primarily useful for testing; in production the *user* generates the
1634    /// code on their device.
1635    pub async fn generate_totp_code(&self, secret: &str) -> Result<String> {
1636        self.mfa_manager.totp.generate_code(secret).await
1637    }
1638
1639    /// Generates a TOTP code for the given `secret` and optional time window.
1640    ///
1641    /// When `time_window` is `None`, the current 30-second window is used.
1642    pub async fn generate_totp_code_for_window(
1643        &self,
1644        secret: &str,
1645        time_window: Option<u64>,
1646    ) -> Result<String> {
1647        self.mfa_manager
1648            .totp
1649            .generate_code_for_window(secret, time_window)
1650            .await
1651    }
1652
1653    /// Verifies a TOTP code against the stored secret for `user_id`.
1654    ///
1655    /// Applies a configurable clock-skew window (default: ±1 step).
1656    ///
1657    /// # Errors
1658    ///
1659    /// Returns [`AuthError`] if no TOTP secret is registered for the user.
1660    pub async fn verify_totp_code(&self, user_id: &str, code: &str) -> Result<bool> {
1661        self.mfa_manager.totp.verify_code(user_id, code).await
1662    }
1663
1664    /// Checks whether the given IP address is within the configured rate limit.
1665    ///
1666    /// Returns `Ok(true)` if the request is allowed, or an
1667    /// [`AuthError::RateLimit`] if the caller should be throttled.
1668    pub async fn check_ip_rate_limit(&self, ip: &str) -> Result<bool> {
1669        debug!("Checking IP rate limit for '{}'", ip);
1670        let Some(ref rate_limiter) = self.rate_limiter else {
1671            return Ok(true);
1672        };
1673        if !rate_limiter.is_allowed(&format!("ip:{}", ip)) {
1674            warn!("Rate limit exceeded for IP: {}", ip);
1675            return Err(AuthError::rate_limit(format!(
1676                "Too many requests from IP {}. Please try again later.",
1677                ip
1678            )));
1679        }
1680        Ok(true)
1681    }
1682
1683    /// Return security metrics for monitoring dashboards.
1684    ///
1685    /// Keys include `active_sessions`, `total_tokens`, `failed_attempts`,
1686    /// `successful_attempts`, and `expired_tokens`.
1687    pub async fn get_security_metrics(&self) -> Result<std::collections::HashMap<String, u64>> {
1688        debug!("Getting security metrics");
1689        let mut metrics = std::collections::HashMap::new();
1690        let total_active_sessions = self
1691            .session_manager
1692            .count_active_sessions()
1693            .await
1694            .unwrap_or(0);
1695        metrics.insert("active_sessions".to_string(), total_active_sessions);
1696        metrics.insert("total_tokens".to_string(), total_active_sessions);
1697        metrics.insert(
1698            "failed_attempts".to_string(),
1699            self.audit_manager
1700                .get_failed_login_count_24h()
1701                .await
1702                .unwrap_or(0),
1703        );
1704        metrics.insert(
1705            "successful_attempts".to_string(),
1706            self.audit_manager
1707                .get_successful_login_count_24h()
1708                .await
1709                .unwrap_or(0),
1710        );
1711        metrics.insert("expired_tokens".to_string(), 0u64);
1712        Ok(metrics)
1713    }
1714
1715    /// Registers a phone number for SMS-based MFA.
1716    ///
1717    /// # Errors
1718    ///
1719    /// Returns [`AuthError`] if the phone number format is invalid.
1720    pub async fn register_phone_number(&self, user_id: &str, phone_number: &str) -> Result<()> {
1721        self.mfa_manager
1722            .sms
1723            .register_phone_number(user_id, phone_number)
1724            .await
1725    }
1726
1727    /// Generate `count` one-time backup codes for the given user.
1728    ///
1729    /// Codes are persisted server-side (hashed); plaintext codes are returned
1730    /// to the caller for display to the user.
1731    pub async fn generate_backup_codes(&self, user_id: &str, count: usize) -> Result<Vec<String>> {
1732        self.mfa_manager
1733            .backup_codes
1734            .generate_codes(user_id, count)
1735            .await
1736    }
1737    /// Grants an authorization permission to a user.
1738    ///
1739    /// # Parameters
1740    ///
1741    /// * `user_id`  — the user receiving the permission.
1742    /// * `action`   — the action being allowed (e.g. `"read"`, `"write"`).
1743    /// * `resource` — the resource scope (e.g. `"documents"`, `"users:*"`).
1744    ///
1745    /// # Errors
1746    ///
1747    /// Returns [`AuthError`] if the user does not exist or storage fails.
1748    pub async fn grant_permission(
1749        &self,
1750        user_id: &str,
1751        action: &str,
1752        resource: &str,
1753    ) -> Result<()> {
1754        self.authorization_manager
1755            .grant_permission(user_id, action, resource)
1756            .await
1757    }
1758
1759    /// Initiates an email-based MFA challenge for `user_id`.
1760    ///
1761    /// Sends a one-time code to the registered email address and returns a
1762    /// challenge ID.
1763    ///
1764    /// # Errors
1765    ///
1766    /// Returns [`AuthError`] if no email is registered for the user or
1767    /// delivery fails.
1768    pub async fn initiate_email_challenge(&self, user_id: &str) -> Result<String> {
1769        self.mfa_manager.email.initiate_challenge(user_id).await
1770    }
1771
1772    /// Returns a cloned handle to the storage backend.
1773    ///
1774    /// Useful when you need to pass storage to another component or run
1775    /// direct queries outside the framework's managed API.
1776    pub fn storage(&self) -> Arc<dyn AuthStorage> {
1777        self.storage.clone()
1778    }
1779
1780    /// Returns a reference to the active framework configuration.
1781    pub fn config(&self) -> &AuthConfig {
1782        &self.config
1783    }
1784
1785    /// Reset runtime authorization state back to the default roles.
1786    pub async fn reset_authorization_runtime(&self) {
1787        self.authorization_manager.reset_runtime_state().await;
1788    }
1789
1790    /// Register a new user with username, email, and password.
1791    ///
1792    /// The password is hashed with the configured algorithm (default: Argon2)
1793    /// before storage.  Returns the generated user ID on success.
1794    ///
1795    /// # Errors
1796    ///
1797    /// Returns [`AuthError`] if:
1798    /// - The username or email is already taken
1799    /// - The password does not meet the configured complexity requirements
1800    /// - The storage backend is unavailable
1801    ///
1802    /// # Example
1803    ///
1804    /// ```rust,no_run
1805    /// # use auth_framework::prelude::*;
1806    /// # async fn example(auth: &AuthFramework) -> Result<(), AuthError> {
1807    /// let user_id = auth.users().register("alice", "alice@example.com", "S3cur3P@ss!").await?;
1808    /// println!("Created user: {user_id}");
1809    /// # Ok(())
1810    /// # }
1811    /// ```
1812    pub async fn register_user(
1813        &self,
1814        username: &str,
1815        email: &str,
1816        password: &str,
1817    ) -> Result<String> {
1818        self.require_initialized()?;
1819        self.user_manager
1820            .register_user(username, email, password)
1821            .await
1822    }
1823
1824    /// List users from the canonical user index with optional filtering and pagination.
1825    ///
1826    /// This method provides paginated access to the user directory with optional
1827    /// filtering by active status.
1828    ///
1829    /// # Parameters
1830    /// - `limit`: Maximum number of users to return (None for no limit)
1831    /// - `offset`: Number of users to skip for pagination (None for start from beginning)
1832    /// - `active_only`: If true, only return active users; if false, return all users
1833    ///
1834    /// # Returns
1835    /// Returns a vector of [`UserInfo`] structs containing user details.
1836    ///
1837    /// # Example
1838    /// ```rust,no_run
1839    /// # use auth_framework::prelude::*;
1840    /// # async fn example(auth: &AuthFramework) -> Result<(), AuthError> {
1841    /// // Get first 10 active users
1842    /// let users = auth.list_users(Some(10), None, true).await?;
1843    /// println!("Found {} active users", users.len());
1844    ///
1845    /// // Get all users (active and inactive)
1846    /// let all_users = auth.list_users(None, None, false).await?;
1847    /// # Ok(())
1848    /// # }
1849    /// ```
1850    #[deprecated(
1851        since = "0.6.0",
1852        note = "use `list_users_with_query(UserListQuery::new().limit(n).active_only())` instead"
1853    )]
1854    pub async fn list_users(
1855        &self,
1856        limit: Option<usize>,
1857        offset: Option<usize>,
1858        active_only: bool,
1859    ) -> Result<Vec<UserInfo>> {
1860        self.require_initialized()?;
1861        self.user_manager
1862            .list_users(limit, offset, active_only)
1863            .await
1864    }
1865
1866    /// List users using a [`UserListQuery`] for better readability.
1867    ///
1868    /// Prefer [`list_users_with_query`](Self::list_users_with_query)
1869    /// with a [`UserListQuery`] for better readability when using pagination or filtering.
1870    ///
1871    /// # Example
1872    ///
1873    /// ```rust,no_run
1874    /// # use auth_framework::{prelude::*, auth_operations::UserListQuery};
1875    /// # async fn example(auth: &AuthFramework) -> Result<(), auth_framework::errors::AuthError> {
1876    /// let users = auth.list_users_with_query(
1877    ///     UserListQuery::new()
1878    ///         .limit(50)
1879    ///         .active_only()
1880    /// ).await?;
1881    /// # Ok(())
1882    /// # }
1883    /// ```
1884    pub async fn list_users_with_query(&self, query: UserListQuery) -> Result<Vec<UserInfo>> {
1885        self.require_initialized()?;
1886        self.user_manager
1887            .list_users(
1888                query.get_limit(),
1889                query.get_offset(),
1890                query.get_active_only(),
1891            )
1892            .await
1893    }
1894
1895    /// Get user information by canonical user ID.
1896    pub async fn get_user_record(&self, user_id: &str) -> Result<UserInfo> {
1897        self.require_initialized()?;
1898        self.user_manager.get_user_info(user_id).await
1899    }
1900
1901    /// Update the roles assigned to a user.
1902    pub async fn update_user_roles(&self, user_id: &str, roles: &[String]) -> Result<()> {
1903        self.require_initialized()?;
1904        self.user_manager.update_user_roles(user_id, roles).await
1905    }
1906
1907    /// Set a user's active / deactivated status.
1908    pub async fn set_user_active(&self, user_id: &str, active: bool) -> Result<()> {
1909        self.require_initialized()?;
1910        self.user_manager.set_user_active(user_id, active).await
1911    }
1912
1913    /// Update a user's email address.
1914    pub async fn update_user_email(&self, user_id: &str, email: &str) -> Result<()> {
1915        self.require_initialized()?;
1916        self.user_manager.update_user_email(user_id, email).await
1917    }
1918
1919    /// Verify a user's password by user_id against the stored bcrypt hash.
1920    pub async fn verify_user_password(&self, user_id: &str, password: &str) -> Result<bool> {
1921        self.require_initialized()?;
1922        self.user_manager
1923            .verify_user_password(user_id, password)
1924            .await
1925    }
1926
1927    /// Look up a user's username by their user_id.
1928    pub async fn get_username_by_id(&self, user_id: &str) -> Result<String> {
1929        self.user_manager.get_username_by_id(user_id).await
1930    }
1931
1932    /// Check if a username exists.
1933    pub async fn username_exists(&self, username: &str) -> Result<bool> {
1934        self.user_manager.username_exists(username).await
1935    }
1936
1937    /// Check if an email exists.
1938    pub async fn email_exists(&self, email: &str) -> Result<bool> {
1939        self.user_manager.email_exists(email).await
1940    }
1941
1942    /// Get user data by username.
1943    pub async fn get_user_by_username(
1944        &self,
1945        username: &str,
1946    ) -> Result<HashMap<String, serde_json::Value>> {
1947        self.user_manager.get_user_by_username(username).await
1948    }
1949
1950    /// Update user password.
1951    pub async fn update_user_password(&self, username: &str, new_password: &str) -> Result<()> {
1952        self.require_initialized()?;
1953        self.user_manager
1954            .update_user_password(username, new_password)
1955            .await
1956    }
1957
1958    /// Update user password by canonical user ID.
1959    pub async fn update_user_password_by_id(
1960        &self,
1961        user_id: &str,
1962        new_password: &str,
1963    ) -> Result<()> {
1964        self.require_initialized()?;
1965        self.user_manager
1966            .update_user_password_by_id(user_id, new_password)
1967            .await
1968    }
1969
1970    /// Delete a user by username.
1971    pub async fn delete_user(&self, username: &str) -> Result<()> {
1972        self.require_initialized()?;
1973        self.user_manager.delete_user(username).await
1974    }
1975
1976    /// Delete a user by canonical user ID.
1977    pub async fn delete_user_by_id(&self, user_id: &str) -> Result<()> {
1978        self.require_initialized()?;
1979        self.user_manager.delete_user_by_id(user_id).await
1980    }
1981
1982    /// Verify MFA code with proper challenge validation.
1983    async fn verify_mfa_code(&self, challenge: &MfaChallenge, code: &str) -> Result<bool> {
1984        self.mfa_manager
1985            .verify_challenge_code(challenge, code)
1986            .await
1987    }
1988
1989    /// Log an audit event via tracing, subject to per-event-type config guards.
1990    async fn log_audit_event(
1991        &self,
1992        event_type: &str,
1993        user_id: &str,
1994        method: &str,
1995        metadata: &CredentialMetadata,
1996    ) {
1997        if !self.config.audit.enabled {
1998            return;
1999        }
2000        let should_log = match event_type {
2001            "auth_success" | "mfa_required" => self.config.audit.log_success,
2002            "auth_failure" => self.config.audit.log_failures,
2003            _ => true,
2004        };
2005        if should_log {
2006            self.audit_manager
2007                .log_auth_trace_event(
2008                    event_type,
2009                    user_id,
2010                    method,
2011                    metadata.client_ip.as_deref().unwrap_or("unknown"),
2012                    metadata.user_agent.as_deref().unwrap_or("unknown"),
2013                )
2014                .await;
2015        }
2016    }
2017
2018    /// Guard the global MFA-challenge budget and store the challenge.
2019    async fn guard_and_store_mfa_challenge(&self, challenge: MfaChallenge) -> Result<()> {
2020        self.mfa_manager.guard_and_store(challenge).await
2021    }
2022
2023    /// Create and immediately store an auth token, returning it.
2024    async fn mint_and_store_token(
2025        &self,
2026        user_id: &str,
2027        scopes: impl Into<crate::types::Scopes>,
2028        method: &str,
2029        lifetime: Option<Duration>,
2030    ) -> Result<AuthToken> {
2031        let token = self
2032            .token_manager
2033            .create_auth_token(user_id, scopes, method, lifetime)?;
2034        self.storage.store_token(&token).await?;
2035        Ok(token)
2036    }
2037
2038    /// Coordinate session state across distributed instances.
2039    pub async fn coordinate_distributed_sessions(&self) -> Result<SessionCoordinationStats> {
2040        self.session_manager.coordinate_distributed_sessions().await
2041    }
2042
2043    /// Synchronize a specific session with remote instances.
2044    pub async fn synchronize_session(&self, session_id: &str) -> Result<()> {
2045        self.session_manager.synchronize_session(session_id).await
2046    }
2047
2048    /// Returns the monitoring manager for metrics collection and health checks.
2049    pub fn monitoring_manager(&self) -> Arc<crate::monitoring::MonitoringManager> {
2050        self.monitoring_manager.clone()
2051    }
2052
2053    /// Returns the security manager for rate limiting, DoS protection, and IP blacklisting.
2054    #[cfg(feature = "api-server")]
2055    pub fn security_manager(&self) -> Option<Arc<crate::api::SecurityManager>> {
2056        Some(self.security_manager.clone())
2057    }
2058
2059    /// Return current performance metrics (token counts, latencies, etc.).
2060    pub async fn get_performance_metrics(&self) -> std::collections::HashMap<String, u64> {
2061        self.monitoring_manager.get_performance_metrics()
2062    }
2063
2064    /// Run a health check on all sub-systems (storage, token engine, etc.).
2065    pub async fn health_check(
2066        &self,
2067    ) -> Result<std::collections::HashMap<String, crate::monitoring::HealthCheckResult>> {
2068        self.monitoring_manager.health_check().await
2069    }
2070
2071    /// Export all collected metrics in Prometheus text exposition format.
2072    pub async fn export_prometheus_metrics(&self) -> String {
2073        self.monitoring_manager.export_prometheus_metrics().await
2074    }
2075    /// Create a new role.
2076    pub async fn create_role(&self, role: crate::permissions::Role) -> Result<()> {
2077        self.require_initialized()?;
2078        self.authorization_manager.create_role(role).await
2079    }
2080
2081    /// Return all defined roles.
2082    pub async fn list_roles(&self) -> Vec<crate::permissions::Role> {
2083        self.authorization_manager.list_roles().await
2084    }
2085
2086    /// Fetch a role definition by name.
2087    pub async fn get_role(&self, role_name: &str) -> Result<crate::permissions::Role> {
2088        self.authorization_manager.get_role(role_name).await
2089    }
2090
2091    /// Add a permission to an existing role.
2092    pub async fn add_role_permission(
2093        &self,
2094        role_name: &str,
2095        permission: crate::permissions::Permission,
2096    ) -> Result<()> {
2097        self.authorization_manager
2098            .add_role_permission(role_name, permission)
2099            .await
2100    }
2101
2102    /// Assign a role to a user.
2103    pub async fn assign_role(&self, user_id: &str, role_name: &str) -> Result<()> {
2104        self.require_initialized()?;
2105        self.authorization_manager
2106            .assign_role(user_id, role_name)
2107            .await
2108    }
2109
2110    /// Remove a role from a user.
2111    pub async fn remove_role(&self, user_id: &str, role_name: &str) -> Result<()> {
2112        self.require_initialized()?;
2113        self.authorization_manager
2114            .remove_role(user_id, role_name)
2115            .await
2116    }
2117
2118    /// Set role inheritance.
2119    pub async fn set_role_inheritance(&self, child_role: &str, parent_role: &str) -> Result<()> {
2120        self.require_initialized()?;
2121        self.authorization_manager
2122            .set_role_inheritance(child_role, parent_role)
2123            .await
2124    }
2125
2126    /// Revoke permission from a user.
2127    pub async fn revoke_permission(
2128        &self,
2129        user_id: &str,
2130        action: &str,
2131        resource: &str,
2132    ) -> Result<()> {
2133        self.require_initialized()?;
2134        self.authorization_manager
2135            .revoke_permission(user_id, action, resource)
2136            .await
2137    }
2138
2139    /// Check if user has a role.
2140    pub async fn user_has_role(&self, user_id: &str, role_name: &str) -> Result<bool> {
2141        self.authorization_manager
2142            .user_has_role(user_id, role_name)
2143            .await
2144    }
2145
2146    /// List the currently assigned runtime roles for a user.
2147    pub async fn list_user_roles(&self, user_id: &str) -> Result<Vec<String>> {
2148        self.authorization_manager.list_user_roles(user_id).await
2149    }
2150
2151    /// Get effective permissions for a user.
2152    pub async fn get_effective_permissions(&self, user_id: &str) -> Result<Vec<String>> {
2153        self.authorization_manager
2154            .get_effective_permissions(user_id)
2155            .await
2156    }
2157
2158    /// Create ABAC policy.
2159    pub async fn create_abac_policy(&self, name: &str, description: &str) -> Result<()> {
2160        self.authorization_manager
2161            .create_abac_policy(name, description)
2162            .await
2163    }
2164
2165    /// Set a user attribute value for ABAC (Attribute-Based Access Control) evaluation.
2166    ///
2167    /// User attributes are key-value pairs associated with users that can be used
2168    /// in dynamic permission rules. This method stores or updates an attribute value.
2169    ///
2170    /// # Parameters
2171    /// - `user_id`: The ID of the user to set the attribute for
2172    /// - `attribute`: The name of the attribute to set
2173    /// - `value`: The value to assign to the attribute
2174    ///
2175    /// # Example
2176    /// ```rust,no_run
2177    /// # use auth_framework::prelude::*;
2178    /// # async fn example(auth: &AuthFramework) -> Result<(), AuthError> {
2179    /// // Set user attributes for policy evaluation
2180    /// auth.map_user_attribute("example_user", "department", "engineering").await?;
2181    /// auth.map_user_attribute("example_user", "clearance_level", "confidential").await?;
2182    /// # Ok(())
2183    /// # }
2184    /// ```
2185    pub async fn map_user_attribute(
2186        &self,
2187        user_id: &str,
2188        attribute: &str,
2189        value: &str,
2190    ) -> Result<()> {
2191        self.authorization_manager
2192            .map_user_attribute(user_id, attribute, value)
2193            .await
2194    }
2195
2196    /// Get a user attribute value for ABAC (Attribute-Based Access Control) evaluation.
2197    ///
2198    /// User attributes are key-value pairs associated with users that can be used
2199    /// in dynamic permission rules. Common attributes include department, clearance level,
2200    /// location, etc.
2201    ///
2202    /// # Parameters
2203    /// - `user_id`: The ID of the user whose attribute to retrieve
2204    /// - `attribute`: The name of the attribute to retrieve
2205    ///
2206    /// # Returns
2207    /// Returns `Some(value)` if the attribute exists, `None` if it doesn't exist.
2208    ///
2209    /// # Example
2210    /// ```rust,no_run
2211    /// # use auth_framework::prelude::*;
2212    /// # async fn example(auth: &AuthFramework) -> Result<(), AuthError> {
2213    /// if let Some(dept) = auth.get_user_attribute("example_user", "department").await? {
2214    ///     println!("User is in department: {}", dept);
2215    /// }
2216    /// # Ok(())
2217    /// # }
2218    /// ```
2219    pub async fn get_user_attribute(
2220        &self,
2221        user_id: &str,
2222        attribute: &str,
2223    ) -> Result<Option<String>> {
2224        self.authorization_manager
2225            .get_user_attribute(user_id, attribute)
2226            .await
2227    }
2228
2229    /// Check dynamic permission with context evaluation (ABAC - Attribute-Based Access Control).
2230    ///
2231    /// This method evaluates permissions based on user attributes, resource attributes,
2232    /// and environmental context rather than just role assignments. It's more flexible
2233    /// than simple role-based checks but requires more complex policy rules.
2234    ///
2235    /// # Parameters
2236    /// - `user_id`: The ID of the user requesting access
2237    /// - `action`: The action being requested (e.g., "read", "write", "delete")
2238    /// - `resource`: The resource being accessed (e.g., "documents", "users", "reports/123")
2239    /// - `context`: Additional context key-value pairs for policy evaluation
2240    ///
2241    /// # Returns
2242    /// Returns `true` if the permission is granted based on the dynamic policy evaluation.
2243    ///
2244    /// # Example
2245    /// ```rust,no_run
2246    /// # use auth_framework::prelude::*;
2247    /// # use std::collections::HashMap;
2248    /// # async fn example(auth: &AuthFramework) -> Result<(), AuthError> {
2249    /// let mut context = HashMap::new();
2250    /// context.insert("time_of_day".to_string(), "business_hours".to_string());
2251    /// context.insert("ip_location".to_string(), "office".to_string());
2252    ///
2253    /// if auth.check_dynamic_permission("example_user", "read", "confidential_docs", context).await? {
2254    ///     println!("Access granted based on dynamic policy");
2255    /// }
2256    /// # Ok(())
2257    /// # }
2258    /// ```
2259    pub async fn check_dynamic_permission(
2260        &self,
2261        user_id: &str,
2262        action: &str,
2263        resource: &str,
2264        context: std::collections::HashMap<String, String>,
2265    ) -> Result<bool> {
2266        self.authorization_manager
2267            .check_dynamic_permission(user_id, action, resource, context)
2268            .await
2269    }
2270
2271    /// Check dynamic permission using a structured context (preferred).
2272    ///
2273    /// Prefer [`check_dynamic_permission_with_context`](Self::check_dynamic_permission_with_context)
2274    /// with a [`PermissionContext`] for better type safety and readability.
2275    ///
2276    /// # Example
2277    /// ```rust,no_run
2278    /// # use auth_framework::{prelude::*, auth_operations::PermissionContext};
2279    /// # async fn example(auth: &AuthFramework) -> Result<(), AuthError> {
2280    /// let context = PermissionContext::new()
2281    ///     .with_attribute("time_of_day", "business_hours")
2282    ///     .with_attribute("ip_location", "office");
2283    ///
2284    /// if auth.check_dynamic_permission_with_context("example_user", "read", "confidential_docs", context).await? {
2285    ///     println!("Access granted based on dynamic policy");
2286    /// }
2287    /// # Ok(())
2288    /// # }
2289    /// ```
2290    pub async fn check_dynamic_permission_with_context(
2291        &self,
2292        user_id: &str,
2293        action: &str,
2294        resource: &str,
2295        context: PermissionContext,
2296    ) -> Result<bool> {
2297        self.check_dynamic_permission(user_id, action, resource, context.into_attributes())
2298            .await
2299    }
2300
2301    /// Create resource for permission management.
2302    pub async fn create_resource(&self, resource: &str) -> Result<()> {
2303        self.authorization_manager.create_resource(resource).await
2304    }
2305
2306    /// Delegate permission from one user to another using a [`DelegationRequest`].
2307    ///
2308    /// This is the preferred method for delegation as it avoids passing multiple
2309    /// parameters and makes the call site self-documenting.
2310    ///
2311    /// # Example
2312    ///
2313    /// ```rust,no_run
2314    /// # use auth_framework::{AuthFramework, AuthConfig};
2315    /// # use auth_framework::auth_operations::DelegationRequest;
2316    /// # use std::time::Duration;
2317    /// # async fn example(auth: &AuthFramework) -> Result<(), auth_framework::errors::AuthError> {
2318    /// let req = DelegationRequest::new("admin_1", "user_2", "write", "reports")
2319    ///     .duration(Duration::from_secs(3600));
2320    /// auth.delegate_permission_with_request(req).await?;
2321    /// # Ok(())
2322    /// # }
2323    /// ```
2324    pub async fn delegate_permission_with_request(&self, req: DelegationRequest) -> Result<()> {
2325        self.authorization_manager
2326            .delegate_permission(
2327                req.delegator_id(),
2328                req.delegatee_id(),
2329                req.action(),
2330                req.resource(),
2331                req.get_duration(),
2332            )
2333            .await
2334    }
2335
2336    /// Delegate permission from one user to another.
2337    ///
2338    /// Prefer [`delegate_permission_with_request`](Self::delegate_permission_with_request)
2339    /// with a [`DelegationRequest`] for better readability when delegating permissions.
2340    pub async fn delegate_permission(
2341        &self,
2342        delegator_id: &str,
2343        delegatee_id: &str,
2344        action: &str,
2345        resource: &str,
2346        duration: std::time::Duration,
2347    ) -> Result<()> {
2348        self.authorization_manager
2349            .delegate_permission(delegator_id, delegatee_id, action, resource, duration)
2350            .await
2351    }
2352
2353    /// Get active delegations for a user.
2354    pub async fn get_active_delegations(&self, user_id: &str) -> Result<Vec<String>> {
2355        self.authorization_manager
2356            .get_active_delegations(user_id)
2357            .await
2358    }
2359
2360    /// Get permission audit logs with filtering.
2361    pub async fn get_permission_audit_logs(
2362        &self,
2363        user_id: Option<&str>,
2364        action: Option<&str>,
2365        resource: Option<&str>,
2366        limit: Option<usize>,
2367    ) -> Result<Vec<String>> {
2368        self.audit_manager
2369            .get_permission_audit_logs(user_id, action, resource, limit)
2370            .await
2371    }
2372
2373    /// Get permission audit logs using an [`AuditLogQuery`] for better readability.
2374    ///
2375    /// Prefer [`get_permission_audit_logs_with_query`](Self::get_permission_audit_logs_with_query)
2376    /// with an [`AuditLogQuery`] for better readability when using multiple filters.
2377    ///
2378    /// # Example
2379    ///
2380    /// ```rust,no_run
2381    /// # use auth_framework::{prelude::*, auth_operations::AuditLogQuery};
2382    /// # async fn example(auth: &AuthFramework) -> Result<(), auth_framework::errors::AuthError> {
2383    /// let logs = auth.get_permission_audit_logs_with_query(
2384    ///     AuditLogQuery::new()
2385    ///         .user("user_123")
2386    ///         .action("read")
2387    ///         .limit(50)
2388    /// ).await?;
2389    /// # Ok(())
2390    /// # }
2391    /// ```
2392    pub async fn get_permission_audit_logs_with_query(
2393        &self,
2394        query: AuditLogQuery,
2395    ) -> Result<Vec<String>> {
2396        self.audit_manager
2397            .get_permission_audit_logs(
2398                query.get_user_id(),
2399                query.get_action(),
2400                query.get_resource(),
2401                query.get_limit(),
2402            )
2403            .await
2404    }
2405
2406    /// Get permission metrics for monitoring.
2407    pub async fn get_permission_metrics(
2408        &self,
2409    ) -> Result<std::collections::HashMap<String, u64>, AuthError> {
2410        let active_sessions = self.storage.count_active_sessions().await.unwrap_or(0);
2411        let permission_checks_last_hour = self
2412            .audit_manager
2413            .get_permission_checks_last_hour()
2414            .await
2415            .unwrap_or(0);
2416        self.authorization_manager
2417            .get_permission_metrics(active_sessions, permission_checks_last_hour)
2418            .await
2419    }
2420
2421    /// Collect comprehensive security audit statistics.
2422    pub async fn get_security_audit_stats(&self) -> Result<SecurityAuditStats> {
2423        let active_sessions = self
2424            .session_manager
2425            .count_active_sessions()
2426            .await
2427            .unwrap_or(0);
2428        self.audit_manager
2429            .get_security_audit_stats(active_sessions)
2430            .await
2431    }
2432
2433    /// Get user profile information
2434    pub async fn get_user_profile(
2435        &self,
2436        user_id: &str,
2437    ) -> Result<crate::providers::ProviderProfile> {
2438        self.user_manager.get_user_profile(user_id).await
2439    }
2440}
2441
2442pub use crate::audit::SecurityAuditStats;
2443
2444pub use crate::auth_modular::session_manager::SessionCoordinationStats;
2445
2446/// Authentication framework statistics.
2447#[derive(Debug, Clone, Default)]
2448pub struct AuthStats {
2449    /// Number of registered authentication methods
2450    pub registered_methods: Vec<String>,
2451
2452    /// Number of active sessions
2453    pub active_sessions: u64,
2454
2455    /// Number of active MFA challenges
2456    pub active_mfa_challenges: u64,
2457
2458    /// Number of tokens issued (this would need proper tracking)
2459    pub tokens_issued: u64,
2460
2461    /// Number of authentication attempts (this would need proper tracking)
2462    pub auth_attempts: u64,
2463}
2464
2465#[cfg(test)]
2466mod tests {
2467    use super::*;
2468    use crate::config::{AuthConfig, SecurityConfig};
2469    #[tokio::test]
2470    async fn test_framework_initialization() {
2471        let config = AuthConfig::new().security(SecurityConfig {
2472            min_password_length: 8,
2473            require_password_complexity: false,
2474            password_hash_algorithm: crate::config::PasswordHashAlgorithm::Bcrypt,
2475            jwt_algorithm: crate::config::JwtAlgorithm::HS256,
2476            secret_key: Some("test_secret_key_32_bytes_long!!!!".to_string()),
2477            secure_cookies: false,
2478            cookie_same_site: crate::config::CookieSameSite::Lax,
2479            csrf_protection: false,
2480            session_timeout: Duration::from_secs(3600),
2481            previous_secret_key: None,
2482        });
2483        let mut framework = AuthFramework::new(config);
2484
2485        assert!(framework.initialize().await.is_ok());
2486        assert!(framework.initialized);
2487    }
2488
2489    #[tokio::test]
2490    async fn test_method_registration() {
2491        // Method registration test disabled due to trait object lifetime constraints
2492        // This test would require dynamic trait objects which have complex lifetime requirements
2493        // Production implementations should use static method registration or dependency injection
2494
2495        let config = AuthConfig::new().security(SecurityConfig {
2496            min_password_length: 8,
2497            require_password_complexity: false,
2498            password_hash_algorithm: crate::config::PasswordHashAlgorithm::Bcrypt,
2499            jwt_algorithm: crate::config::JwtAlgorithm::HS256,
2500            secret_key: Some("test_secret_key_32_bytes_long!!!!".to_string()),
2501            secure_cookies: false,
2502            cookie_same_site: crate::config::CookieSameSite::Lax,
2503            csrf_protection: false,
2504            session_timeout: Duration::from_secs(3600),
2505            previous_secret_key: None,
2506        });
2507        let framework = AuthFramework::new(config);
2508
2509        // Verify framework initialization works without dynamic method registration
2510        assert!(!framework.initialized);
2511
2512        // Method registration system supports flexible authentication methods
2513        // using factory pattern for better lifetime management
2514    }
2515
2516    #[tokio::test]
2517    async fn test_token_validation() {
2518        let config = AuthConfig::new().security(SecurityConfig {
2519            min_password_length: 8,
2520            require_password_complexity: false,
2521            password_hash_algorithm: crate::config::PasswordHashAlgorithm::Bcrypt,
2522            jwt_algorithm: crate::config::JwtAlgorithm::HS256,
2523            secret_key: Some("test_secret_key_32_bytes_long!!!!".to_string()),
2524            secure_cookies: false,
2525            cookie_same_site: crate::config::CookieSameSite::Lax,
2526            csrf_protection: false,
2527            session_timeout: Duration::from_secs(3600),
2528            previous_secret_key: None,
2529        });
2530        let mut framework = AuthFramework::new(config);
2531        framework.initialize().await.unwrap();
2532
2533        let token = framework
2534            .token_manager
2535            .create_auth_token("test-user", vec!["read".to_string()], "test", None)
2536            .unwrap();
2537
2538        // Store the token first
2539        framework.storage.store_token(&token).await.unwrap();
2540
2541        assert!(framework.validate_token(&token).await.unwrap());
2542    }
2543
2544    #[tokio::test]
2545    async fn test_session_management() {
2546        let config = AuthConfig::new().security(SecurityConfig {
2547            min_password_length: 8,
2548            require_password_complexity: false,
2549            password_hash_algorithm: crate::config::PasswordHashAlgorithm::Bcrypt,
2550            jwt_algorithm: crate::config::JwtAlgorithm::HS256,
2551            secret_key: Some("test_secret_key_32_bytes_long!!!!".to_string()),
2552            secure_cookies: false,
2553            cookie_same_site: crate::config::CookieSameSite::Lax,
2554            csrf_protection: false,
2555            session_timeout: Duration::from_secs(3600),
2556            previous_secret_key: None,
2557        });
2558        let mut framework = AuthFramework::new(config);
2559        framework.initialize().await.unwrap();
2560
2561        let session_id = framework
2562            .create_session(
2563                "test-user",
2564                Duration::from_secs(3600),
2565                Some("192.168.1.1".to_string()),
2566                Some("Test Agent".to_string()),
2567            )
2568            .await
2569            .unwrap();
2570
2571        let session = framework.get_session(&session_id).await.unwrap();
2572        assert!(session.is_some());
2573
2574        framework.delete_session(&session_id).await.unwrap();
2575        let session = framework.get_session(&session_id).await.unwrap();
2576        assert!(session.is_none());
2577    }
2578
2579    #[tokio::test]
2580    async fn test_grouped_operations_accessors() {
2581        let config = AuthConfig::new().security(SecurityConfig {
2582            min_password_length: 8,
2583            require_password_complexity: false,
2584            password_hash_algorithm: crate::config::PasswordHashAlgorithm::Bcrypt,
2585            jwt_algorithm: crate::config::JwtAlgorithm::HS256,
2586            secret_key: Some("test_secret_key_32_bytes_long!!!!".to_string()),
2587            secure_cookies: false,
2588            cookie_same_site: crate::config::CookieSameSite::Lax,
2589            csrf_protection: false,
2590            session_timeout: Duration::from_secs(3600),
2591            previous_secret_key: None,
2592        });
2593        let mut framework = AuthFramework::new(config);
2594        framework.initialize().await.unwrap();
2595
2596        let user_id = framework
2597            .users()
2598            .register("grouped-user", "grouped-user@example.com", "P@ssw0rd123")
2599            .await
2600            .unwrap();
2601        assert!(
2602            framework
2603                .users()
2604                .exists_by_username("grouped-user")
2605                .await
2606                .unwrap()
2607        );
2608
2609        let session_id = framework
2610            .sessions()
2611            .create(&user_id, Duration::from_secs(300), None, None)
2612            .await
2613            .unwrap();
2614        assert!(
2615            framework
2616                .sessions()
2617                .get(&session_id)
2618                .await
2619                .unwrap()
2620                .is_some()
2621        );
2622        assert_eq!(
2623            framework
2624                .sessions()
2625                .list_for_user(&user_id)
2626                .await
2627                .unwrap()
2628                .len(),
2629            1
2630        );
2631
2632        framework
2633            .authorization()
2634            .grant(&user_id, "read", "documents")
2635            .await
2636            .unwrap();
2637        let permissions = framework
2638            .authorization()
2639            .effective_permissions(&user_id)
2640            .await
2641            .unwrap();
2642        assert!(
2643            permissions
2644                .iter()
2645                .any(|permission| permission == "read:documents")
2646        );
2647
2648        framework.sessions().delete(&session_id).await.unwrap();
2649        assert!(
2650            framework
2651                .sessions()
2652                .get(&session_id)
2653                .await
2654                .unwrap()
2655                .is_none()
2656        );
2657    }
2658
2659    #[tokio::test]
2660    async fn test_cleanup_expired_data() {
2661        let config = AuthConfig::new().security(SecurityConfig {
2662            min_password_length: 8,
2663            require_password_complexity: false,
2664            password_hash_algorithm: crate::config::PasswordHashAlgorithm::Bcrypt,
2665            jwt_algorithm: crate::config::JwtAlgorithm::HS256,
2666            secret_key: Some("test_secret_key_32_bytes_long!!!!".to_string()),
2667            secure_cookies: false,
2668            cookie_same_site: crate::config::CookieSameSite::Lax,
2669            csrf_protection: false,
2670            session_timeout: Duration::from_secs(3600),
2671            previous_secret_key: None,
2672        });
2673        let mut framework = AuthFramework::new(config);
2674        framework.initialize().await.unwrap();
2675
2676        // This test would need expired data to be meaningful
2677        assert!(framework.cleanup_expired_data().await.is_ok());
2678    }
2679}