Skip to main content

auth_framework/
errors.rs

1//! Comprehensive error types for the AuthFramework.
2//!
3//! This module defines all error types used throughout the authentication framework,
4//! providing detailed error information for debugging, logging, and user feedback.
5//! All errors implement standard Rust error traits and provide contextual information
6//! to help diagnose issues.
7//!
8//! # Error Categories
9//!
10//! - **Authentication Errors**: Credential validation and method failures
11//! - **Authorization Errors**: Permission and access control failures
12//! - **Token Errors**: JWT creation, validation, and lifecycle issues
13//! - **Configuration Errors**: Setup and configuration problems
14//! - **Storage Errors**: Database and persistence layer issues
15//! - **Network Errors**: External service communication failures
16//! - **Cryptographic Errors**: Security operation failures
17//!
18//! # Error Handling Patterns
19//!
20//! The framework uses structured error handling with:
21//! - Contextual error messages with relevant details
22//! - Error chaining to preserve root cause information
23//! - Categorized errors for appropriate response handling
24//! - Security-safe error messages that don't leak sensitive data
25//!
26//! # Example Error Handling
27//!
28//! ```rust,no_run
29//! use auth_framework::{AuthFramework, AuthError};
30//! use auth_framework::authentication::credentials::Credential;
31//! use auth_framework::authentication::CredentialMetadata;
32//!
33//! # #[tokio::main]
34//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
35//! # let auth_framework: AuthFramework = unimplemented!();
36//! # let credential: Credential = unimplemented!();
37//! # fn handle_success<T>(_: T) {}
38//! # fn respond_with_auth_failure() {}
39//! # fn respond_with_rate_limit(_: Option<u64>) {}
40//! # fn respond_with_system_error() {}
41//! match auth_framework.authenticate("password", credential).await {
42//!     Ok(result) => handle_success(result),
43//!     Err(AuthError::InvalidCredential { credential_type, message, .. }) => {
44//!         tracing::warn!("Invalid {} credential: {}", credential_type, message);
45//!         respond_with_auth_failure()
46//!     },
47//!     Err(AuthError::RateLimit { message, .. }) => {
48//!         respond_with_rate_limit(None)
49//!     },
50//!     Err(e) => {
51//!         tracing::error!("Authentication system error: {}", e);
52//!         respond_with_system_error()
53//!     }
54//! }
55//! # Ok(())
56//! # }
57//! ```
58//!
59//! # Security Considerations
60//!
61//! Error messages are designed to:
62//! - Provide useful debugging information for developers
63//! - Avoid exposing sensitive information to potential attackers
64//! - Enable proper security monitoring and alerting
65//! - Support compliance requirements for audit logging
66
67use thiserror::Error;
68
69/// Type alias for Results in the authentication framework.
70///
71/// This alias simplifies error handling throughout the framework by defaulting
72/// to `AuthError` as the error type while allowing flexibility for other error
73/// types when needed.
74pub type Result<T, E = AuthError> = std::result::Result<T, E>;
75
76/// Comprehensive error type covering all authentication and authorization failures.
77///
78/// `AuthError` provides detailed error information for all aspects of the authentication
79/// framework, from configuration issues to runtime failures. Each error variant includes
80/// contextual information to aid in debugging and provide appropriate user feedback.
81///
82/// This enhanced error type provides:
83/// - **Actionable error messages** with specific suggestions for fixes
84/// - **Documentation links** to relevant guides and troubleshooting
85/// - **Contextual help** that guides users to solutions
86/// - **Security-aware messaging** that doesn't leak sensitive information
87///
88/// # Error Categories
89///
90/// ## Configuration Errors
91/// Errors that occur during framework setup and configuration validation.
92///
93/// ## Authentication Errors
94/// Errors related to credential validation and authentication method execution.
95///
96/// ## Authorization Errors
97/// Errors related to permission checking and access control.
98///
99/// ## Token Errors
100/// JWT token creation, validation, expiration, and lifecycle issues.
101///
102/// ## Storage Errors
103/// Database connectivity, query failures, and data persistence issues.
104///
105/// ## Network Errors
106/// External service communication, timeouts, and connectivity problems.
107///
108/// ## Cryptographic Errors
109/// Encryption, decryption, signing, and other security operation failures.
110///
111/// # Enhanced Error Handling
112///
113/// ```rust,no_run
114/// use auth_framework::AuthError;
115///
116/// # let auth_result: auth_framework::errors::Result<()> = Ok(());
117/// // Enhanced error handling with contextual help
118/// match auth_result {
119///     Err(AuthError::Configuration { message, help, docs_url, .. }) => {
120///         eprintln!("Configuration Error: {}", message);
121///         if let Some(help) = help {
122///             eprintln!("Help: {}", help);
123///         }
124///         if let Some(docs) = docs_url {
125///             eprintln!("See: {}", docs);
126///         }
127///     },
128///     Err(AuthError::InvalidCredential { credential_type, message, .. }) => {
129///         eprintln!("Invalid {}: {}", credential_type, message);
130///     },
131///     // ... handle other error types
132///     _ => {}
133/// }
134/// ```
135///
136/// # Security Notes
137///
138/// Error messages are carefully crafted to:
139/// - Provide sufficient detail for debugging and monitoring
140/// - Avoid exposing sensitive information that could aid attackers
141/// - Enable security teams to identify potential threats
142/// - Support compliance and audit requirements
143/// - Guide users to secure solutions and best practices
144#[derive(Error, Debug)]
145pub enum AuthError {
146    /// Configuration validation and setup errors.
147    ///
148    /// These errors occur when the authentication framework is misconfigured
149    /// or when configuration validation fails during startup.
150    #[error("Configuration error: {message}")]
151    Configuration {
152        message: String,
153        #[source]
154        source: Option<Box<dyn std::error::Error + Send + Sync>>,
155        /// Helpful guidance for fixing the issue
156        help: Option<String>,
157        /// Link to relevant documentation
158        docs_url: Option<String>,
159        /// Specific fix suggestion with commands or code
160        suggested_fix: Option<String>,
161    },
162
163    /// Authentication method execution errors.
164    ///
165    /// These errors occur when a specific authentication method fails to
166    /// execute properly, such as OAuth provider communication failures.
167    #[error("Authentication method '{method}' error: {message}")]
168    AuthMethod {
169        method: String,
170        message: String,
171        /// Helpful guidance for fixing the issue
172        help: Option<String>,
173        /// Link to relevant documentation
174        docs_url: Option<String>,
175        /// Specific fix suggestion
176        suggested_fix: Option<String>,
177    },
178
179    /// Token-related errors
180    #[error("Token error: {0}")]
181    Token(#[from] TokenError),
182
183    /// Permission-related errors
184    #[error("Permission error: {0}")]
185    Permission(#[from] PermissionError),
186
187    /// Storage-related errors
188    #[error("Storage error: {0}")]
189    Storage(#[from] StorageError),
190
191    /// Network/HTTP errors
192    #[error("Network error: {0}")]
193    Network(#[from] reqwest::Error),
194
195    /// JSON parsing errors
196    #[error("JSON error: {0}")]
197    Json(#[from] serde_json::Error),
198
199    /// JWT errors
200    #[error("JWT error: {0}")]
201    Jwt(#[from] jsonwebtoken::errors::Error),
202
203    /// YAML parsing errors
204    #[error("YAML error: {0}")]
205    Yaml(#[from] serde_saphyr::Error),
206
207    /// TOML parsing errors
208    #[error("TOML error: {0}")]
209    Toml(#[from] toml::ser::Error),
210
211    /// Prometheus metrics errors
212    #[cfg(feature = "prometheus")]
213    #[error("Metrics error: {0}")]
214    Metrics(#[from] prometheus::Error),
215
216    /// IO errors
217    #[error("IO error: {0}")]
218    Io(#[from] std::io::Error),
219
220    /// CLI interaction errors
221    #[error("CLI error: {0}")]
222    Cli(String),
223
224    /// System time errors
225    #[error("System time error: {0}")]
226    SystemTime(#[from] std::time::SystemTimeError),
227
228    /// Rate limiting errors
229    #[error("Rate limit exceeded: {message}")]
230    RateLimit { message: String },
231
232    /// Session-related errors
233    #[error(
234        "Too many concurrent sessions for user (limit reached). \
235             Revoke an existing session before creating a new one."
236    )]
237    TooManyConcurrentSessions,
238
239    /// MFA-related errors
240    #[error("MFA error: {0}")]
241    Mfa(#[from] MfaError),
242
243    /// Device flow errors
244    #[error("Device flow error: {0}")]
245    DeviceFlow(#[from] DeviceFlowError),
246
247    /// OAuth provider errors
248    #[error("OAuth provider error: {0}")]
249    OAuthProvider(#[from] OAuthProviderError),
250
251    /// The stored password hash does not match the supplied credential.
252    ///
253    /// This typically means the user entered the wrong password. Do **not**
254    /// reveal which field (username vs. password) was incorrect to the caller.
255    #[error("Password verification failed: {0}")]
256    PasswordVerification(String),
257
258    /// The password hashing algorithm (argon2/bcrypt) encountered an error.
259    #[error("Password hashing failed: {0}")]
260    PasswordHashing(String),
261
262    /// No user record exists for the given identifier.
263    #[error("User not found. The requested user ID does not exist in the store.")]
264    UserNotFound,
265
266    /// A request parameter failed validation (e.g. empty username, invalid email format).
267    #[error("Invalid input: {0}")]
268    InvalidInput(String),
269
270    /// A hardware security key (FIDO2 / WebAuthn) operation failed.
271    #[error("Hardware token error: {0}")]
272    HardwareToken(String),
273
274    /// A one-time backup code was rejected (already used, incorrect, or expired).
275    #[error("Backup code verification failed: {0}")]
276    BackupCodeVerification(String),
277
278    /// Failed to hash a backup code for secure storage.
279    #[error("Backup code hashing failed: {0}")]
280    BackupCodeHashing(String),
281
282    /// The TOTP or MFA secret is in an invalid format (e.g. not valid Base32).
283    #[error("Invalid secret format")]
284    InvalidSecret,
285
286    /// An error occurred while reading or updating a user profile.
287    #[error("User profile error: {message}")]
288    UserProfile { message: String },
289
290    /// Credential validation errors
291    #[error("Invalid credential: {credential_type} - {message}")]
292    InvalidCredential {
293        credential_type: String,
294        message: String,
295    },
296
297    /// An authentication operation did not complete within the allowed window.
298    #[error("Authentication timeout after {timeout_seconds} seconds")]
299    Timeout { timeout_seconds: u64 },
300
301    /// Provider configuration missing
302    #[error(
303        "Provider '{provider}' is not configured or supported. \
304             Add it via AuthConfig::method_config() or check available providers."
305    )]
306    ProviderNotConfigured { provider: String },
307
308    /// Cryptography errors
309    #[error("Cryptography error: {message}")]
310    Crypto { message: String },
311
312    /// Validation errors
313    #[error("Validation error: {message}")]
314    Validation { message: String },
315
316    /// Generic internal errors
317    #[error("Internal error: {message}")]
318    Internal { message: String },
319
320    /// Invalid request error
321    #[error("Invalid request: {0}")]
322    InvalidRequest(String),
323
324    /// Step-up authentication required
325    #[error(
326        "Step-up authentication required: current level '{current_level}', required level '{required_level}'"
327    )]
328    StepUpRequired {
329        current_level: String,
330        required_level: String,
331        step_up_url: String,
332    },
333
334    /// A session-layer error (e.g. session not found, session expired, store failure).
335    #[error("Session error: {0}")]
336    SessionError(String),
337
338    /// The caller lacks valid credentials or the credentials have been revoked.
339    #[error("Unauthorized: {0}")]
340    Unauthorized(String),
341
342    /// Token creation failed at the signing or encoding stage.
343    ///
344    /// Consider using [`AuthError::token`] for richer [`TokenError`] variants.
345    #[error("Token generation error: {0}")]
346    TokenGeneration(String),
347
348    /// Invalid token error.
349    ///
350    /// **Prefer** [`AuthError::token`] which routes through the structured
351    /// [`TokenError`] hierarchy for consistent token error handling.
352    #[deprecated(
353        since = "0.5.0",
354        note = "Use `AuthError::token(msg)` instead — it routes through the structured TokenError hierarchy"
355    )]
356    #[error("Invalid token: {0}")]
357    InvalidToken(String),
358
359    /// The named authentication provider is not compiled in or not recognized.
360    #[error("Unsupported provider: {0}")]
361    UnsupportedProvider(String),
362
363    /// Network error with custom message.
364    ///
365    /// **Prefer** [`AuthError::Internal`] with a descriptive message, or let
366    /// [`reqwest::Error`] convert automatically via the [`From`] impl on
367    /// [`AuthError::Network`].
368    #[deprecated(
369        since = "0.5.0",
370        note = "Use `AuthError::internal(msg)` or let `reqwest::Error` convert via `AuthError::Network` instead"
371    )]
372    #[error("Network error: {0}")]
373    NetworkError(String),
374
375    /// Parse error with custom message.
376    ///
377    /// **Prefer** [`AuthError::Internal`] with a descriptive message, or let
378    /// [`serde_json::Error`] convert automatically via the [`From`] impl on
379    /// [`AuthError::Json`].
380    #[deprecated(
381        since = "0.5.0",
382        note = "Use `AuthError::internal(msg)` or let serde errors convert via `AuthError::Json` instead"
383    )]
384    #[error("Parse error: {0}")]
385    ParseError(String),
386
387    /// Configuration error with custom message.
388    ///
389    /// **Prefer** [`AuthError::config`] or [`AuthError::config_with_help`] which
390    /// carry richer context (help text, docs URL, suggested fix).
391    #[deprecated(
392        since = "0.5.0",
393        note = "Use `AuthError::config(msg)` instead — it provides richer context fields"
394    )]
395    #[error("Configuration error: {0}")]
396    ConfigurationError(String),
397}
398
399/// Token-specific errors.
400///
401/// Covers the lifecycle of authentication tokens: creation, validation,
402/// refresh, and revocation.
403#[derive(Error, Debug)]
404pub enum TokenError {
405    /// The token's `exp` claim is in the past.
406    #[error("Token has expired")]
407    Expired,
408
409    /// The token failed signature verification or structural validation.
410    #[error("Token is invalid: {message}")]
411    Invalid { message: String },
412
413    /// No token matching the given identifier exists in the store.
414    #[error("Token not found")]
415    NotFound,
416
417    /// The request did not include a required token (e.g. missing `Authorization` header).
418    #[error("Token is missing")]
419    Missing,
420
421    /// A new token could not be issued (e.g. signing key unavailable).
422    #[error("Token creation failed: {message}")]
423    CreationFailed { message: String },
424
425    /// An existing token could not be refreshed (e.g. refresh token revoked).
426    #[error("Token refresh failed: {message}")]
427    RefreshFailed { message: String },
428
429    /// Token revocation did not complete (e.g. storage write failure).
430    #[error("Token revocation failed: {message}")]
431    RevocationFailed { message: String },
432}
433
434/// Permission and access-control errors.
435///
436/// Returned when an authenticated principal lacks the required permissions
437/// or roles to perform an operation.
438#[derive(Error, Debug)]
439pub enum PermissionError {
440    /// The principal does not hold the required permission for the target resource.
441    #[error("Access denied: missing permission '{permission}' for resource '{resource}'")]
442    AccessDenied {
443        permission: String,
444        resource: String,
445    },
446
447    /// The specified role does not exist in the role store.
448    #[error("Role '{role}' not found")]
449    RoleNotFound { role: String },
450
451    /// The specified permission identifier does not exist.
452    #[error("Permission '{permission}' not found")]
453    PermissionNotFound { permission: String },
454
455    /// A permission string could not be parsed (e.g. missing `resource:action` separator).
456    #[error("Invalid permission format: {message}")]
457    InvalidFormat { message: String },
458
459    /// General permission denial with a descriptive message.
460    #[error("Permission denied: {message}")]
461    Denied {
462        action: String,
463        resource: String,
464        message: String,
465    },
466}
467
468/// Storage backend errors.
469///
470/// Covers connectivity, query execution, and serialization issues for
471/// all storage backends (Memory, PostgreSQL, Redis, SQLite).
472#[derive(Error, Debug)]
473pub enum StorageError {
474    /// Could not establish a connection to the storage backend.
475    #[error("Connection failed: {message}")]
476    ConnectionFailed { message: String },
477
478    /// A read or write operation against the store failed.
479    #[error("Operation failed: {message}")]
480    OperationFailed { message: String },
481
482    /// Data could not be serialized to or deserialized from the storage format.
483    #[error("Serialization error: {message}")]
484    Serialization { message: String },
485
486    /// The configured storage backend is unreachable or not initialized.
487    #[error("Storage backend not available")]
488    BackendUnavailable,
489}
490
491/// Multi-factor authentication errors.
492#[derive(Error, Debug)]
493pub enum MfaError {
494    /// The MFA challenge window has elapsed; the user must request a new challenge.
495    #[error("MFA challenge expired")]
496    ChallengeExpired,
497
498    /// The TOTP or one-time code provided by the user is incorrect.
499    #[error("Invalid MFA code")]
500    InvalidCode,
501
502    /// The requested MFA method (e.g. SMS, hardware key) is not enabled.
503    #[error("MFA method not supported: {method}")]
504    MethodNotSupported { method: String },
505
506    /// MFA has not been configured for this account yet.
507    #[error("MFA setup required")]
508    SetupRequired,
509
510    /// MFA verification failed for a reason described in `message`.
511    #[error("MFA verification failed: {message}")]
512    VerificationFailed { message: String },
513}
514
515/// Device Authorization Grant (RFC 8628) errors.
516///
517/// These map 1-to-1 to the error codes defined in RFC 8628 §3.5.
518#[derive(Error, Debug)]
519pub enum DeviceFlowError {
520    /// The user has not yet completed authorization on the verification URI.
521    #[error("Authorization pending - user has not yet completed authorization")]
522    AuthorizationPending,
523
524    /// The client is polling faster than the allowed `interval`.
525    #[error("Slow down - polling too frequently")]
526    SlowDown,
527
528    /// The device code has exceeded its `expires_in` window.
529    #[error("Device code expired")]
530    ExpiredToken,
531
532    /// The end user denied the authorization request.
533    #[error("Access denied by user")]
534    AccessDenied,
535
536    /// The device code presented by the client is not recognized.
537    #[error("Invalid device code")]
538    InvalidDeviceCode,
539
540    /// The grant type is not supported by this server.
541    #[error("Unsupported grant type")]
542    UnsupportedGrantType,
543}
544
545/// OAuth 2.0 provider interaction errors.
546///
547/// Covers issues encountered when communicating with upstream OAuth providers
548/// or when validating OAuth protocol messages.
549#[derive(Error, Debug)]
550pub enum OAuthProviderError {
551    /// The authorization code is expired, already consumed, or invalid.
552    #[error("Invalid authorization code")]
553    InvalidAuthorizationCode,
554
555    /// The `redirect_uri` does not match the registered value for the client.
556    #[error("Invalid redirect URI")]
557    InvalidRedirectUri,
558
559    /// The client ID or client secret is incorrect.
560    #[error("Invalid client credentials")]
561    InvalidClientCredentials,
562
563    /// The granted scopes do not satisfy the required scopes for the operation.
564    #[error("Insufficient scope: required '{required}', granted '{granted}'")]
565    InsufficientScope { required: String, granted: String },
566
567    /// The provider does not implement the requested feature.
568    #[error("Provider '{provider}' does not support '{feature}'")]
569    UnsupportedFeature { provider: String, feature: String },
570
571    /// The upstream provider returned a rate-limit response.
572    #[error("Rate limited by provider: {message}")]
573    RateLimited { message: String },
574}
575
576impl AuthError {
577    /// Create a new configuration error.
578    ///
579    /// # Example
580    ///
581    /// ```rust
582    /// use auth_framework::AuthError;
583    ///
584    /// let err = AuthError::config("Missing database URL");
585    /// assert!(err.to_string().contains("Missing database URL"));
586    /// ```
587    pub fn config(message: impl Into<String>) -> Self {
588        Self::Configuration {
589            message: message.into(),
590            source: None,
591            help: None,
592            docs_url: None,
593            suggested_fix: None,
594        }
595    }
596
597    /// Create a configuration error with helpful context.
598    ///
599    /// Includes a human-readable `help` string and an optional `suggested_fix`
600    /// that can be displayed by CLI tools or IDE integrations.
601    ///
602    /// # Example
603    ///
604    /// ```rust
605    /// use auth_framework::AuthError;
606    ///
607    /// let err = AuthError::config_with_help(
608    ///     "JWT secret not set",
609    ///     "Set the JWT_SECRET environment variable",
610    ///     Some("export JWT_SECRET=$(openssl rand -hex 32)".into()),
611    /// );
612    /// assert!(err.to_string().contains("JWT secret not set"));
613    /// ```
614    pub fn config_with_help(
615        message: impl Into<String>,
616        help: impl Into<String>,
617        suggested_fix: Option<String>,
618    ) -> Self {
619        Self::Configuration {
620            message: message.into(),
621            source: None,
622            help: Some(help.into()),
623            docs_url: Some(
624                "https://docs.rs/auth-framework/latest/auth_framework/config/".to_string(),
625            ),
626            suggested_fix,
627        }
628    }
629
630    /// Create a JWT secret validation error with helpful guidance.
631    ///
632    /// # Example
633    ///
634    /// ```rust
635    /// use auth_framework::AuthError;
636    ///
637    /// let err = AuthError::jwt_secret_too_short(16);
638    /// assert!(err.to_string().contains("16 characters"));
639    /// ```
640    pub fn jwt_secret_too_short(current_length: usize) -> Self {
641        Self::Configuration {
642            message: format!(
643                "JWT secret too short (got {} characters, need 32+ for security)",
644                current_length
645            ),
646            source: None,
647            help: Some("Use a cryptographically secure random string of at least 32 characters".to_string()),
648            docs_url: Some("https://docs.rs/auth-framework/latest/auth_framework/config/struct.SecurityConfig.html".to_string()),
649            suggested_fix: Some("Generate a secure secret: `openssl rand -hex 32`".to_string()),
650        }
651    }
652
653    /// Create a production environment error with guidance.
654    ///
655    /// # Example
656    ///
657    /// ```rust
658    /// use auth_framework::AuthError;
659    ///
660    /// let err = AuthError::production_memory_storage();
661    /// assert!(err.to_string().contains("Memory storage"));
662    /// ```
663    pub fn production_memory_storage() -> Self {
664        Self::Configuration {
665            message: "Memory storage is not suitable for production environments".to_string(),
666            source: None,
667            help: Some("Use a persistent storage backend like PostgreSQL or Redis".to_string()),
668            docs_url: Some("https://docs.rs/auth-framework/latest/auth_framework/storage/".to_string()),
669            suggested_fix: Some("Configure PostgreSQL: .with_postgres(\"postgresql://...\") or Redis: .with_redis(\"redis://...\")".to_string()),
670        }
671    }
672
673    /// Create a new auth method error.
674    ///
675    /// # Example
676    ///
677    /// ```rust
678    /// use auth_framework::AuthError;
679    ///
680    /// let err = AuthError::auth_method("oauth2", "token endpoint unreachable");
681    /// assert!(err.to_string().contains("oauth2"));
682    /// ```
683    pub fn auth_method(method: impl Into<String>, message: impl Into<String>) -> Self {
684        Self::AuthMethod {
685            method: method.into(),
686            message: message.into(),
687            help: None,
688            docs_url: None,
689            suggested_fix: None,
690        }
691    }
692
693    /// Create an auth method error with helpful context.
694    ///
695    /// # Example
696    ///
697    /// ```rust
698    /// use auth_framework::AuthError;
699    ///
700    /// let err = AuthError::auth_method_with_help(
701    ///     "saml",
702    ///     "certificate expired",
703    ///     "Renew the SAML signing certificate",
704    ///     Some("openssl x509 -req -in cert.csr -signkey key.pem -out cert.pem".into()),
705    /// );
706    /// assert!(err.to_string().contains("saml"));
707    /// ```
708    pub fn auth_method_with_help(
709        method: impl Into<String>,
710        message: impl Into<String>,
711        help: impl Into<String>,
712        suggested_fix: Option<String>,
713    ) -> Self {
714        Self::AuthMethod {
715            method: method.into(),
716            message: message.into(),
717            help: Some(help.into()),
718            docs_url: Some(
719                "https://docs.rs/auth-framework/latest/auth_framework/methods/".to_string(),
720            ),
721            suggested_fix,
722        }
723    }
724
725    /// Create a new rate limit error.
726    ///
727    /// # Example
728    ///
729    /// ```rust
730    /// use auth_framework::AuthError;
731    ///
732    /// let err = AuthError::rate_limit("too many login attempts");
733    /// assert!(err.to_string().contains("too many login attempts"));
734    /// ```
735    pub fn rate_limit(message: impl Into<String>) -> Self {
736        Self::RateLimit {
737            message: message.into(),
738        }
739    }
740
741    /// Create a new crypto error.
742    ///
743    /// # Example
744    ///
745    /// ```rust
746    /// use auth_framework::AuthError;
747    ///
748    /// let err = AuthError::crypto("HMAC key too short");
749    /// assert!(err.to_string().contains("HMAC key too short"));
750    /// ```
751    pub fn crypto(message: impl Into<String>) -> Self {
752        Self::Crypto {
753            message: message.into(),
754        }
755    }
756
757    /// Create a new validation error.
758    ///
759    /// # Example
760    ///
761    /// ```rust
762    /// use auth_framework::AuthError;
763    ///
764    /// let err = AuthError::validation("email format invalid");
765    /// assert!(err.to_string().contains("email format invalid"));
766    /// ```
767    pub fn validation(message: impl Into<String>) -> Self {
768        Self::Validation {
769            message: message.into(),
770        }
771    }
772
773    /// Create a new internal error.
774    ///
775    /// # Example
776    ///
777    /// ```rust
778    /// use auth_framework::AuthError;
779    ///
780    /// let err = AuthError::internal("unexpected state");
781    /// assert!(err.to_string().contains("unexpected state"));
782    /// ```
783    pub fn internal(message: impl Into<String>) -> Self {
784        Self::Internal {
785            message: message.into(),
786        }
787    }
788
789    /// Create an authorization error.
790    ///
791    /// # Example
792    ///
793    /// ```rust
794    /// use auth_framework::AuthError;
795    ///
796    /// let err = AuthError::authorization("insufficient privileges");
797    /// assert!(err.to_string().contains("insufficient privileges"));
798    /// ```
799    pub fn authorization(message: impl Into<String>) -> Self {
800        Self::Permission(PermissionError::Denied {
801            action: "authorize".to_string(),
802            resource: "resource".to_string(),
803            message: message.into(),
804        })
805    }
806
807    /// Create an access denied error.
808    ///
809    /// # Example
810    ///
811    /// ```rust
812    /// use auth_framework::AuthError;
813    ///
814    /// let err = AuthError::access_denied("admin role required");
815    /// assert!(err.to_string().contains("admin role required"));
816    /// ```
817    pub fn access_denied(message: impl Into<String>) -> Self {
818        Self::Permission(PermissionError::Denied {
819            action: "access".to_string(),
820            resource: "resource".to_string(),
821            message: message.into(),
822        })
823    }
824
825    /// Create a token error.
826    ///
827    /// # Example
828    ///
829    /// ```rust
830    /// use auth_framework::AuthError;
831    ///
832    /// let err = AuthError::token("signature mismatch");
833    /// assert!(err.to_string().contains("signature mismatch"));
834    /// ```
835    pub fn token(message: impl Into<String>) -> Self {
836        Self::Token(TokenError::Invalid {
837            message: message.into(),
838        })
839    }
840
841    /// Create a device flow error.
842    ///
843    /// # Example
844    ///
845    /// ```rust
846    /// use auth_framework::errors::{AuthError, DeviceFlowError};
847    ///
848    /// let err = AuthError::device_flow(DeviceFlowError::ExpiredToken);
849    /// assert!(err.to_string().contains("expired"));
850    /// ```
851    pub fn device_flow(error: DeviceFlowError) -> Self {
852        Self::DeviceFlow(error)
853    }
854
855    /// Create an OAuth provider error.
856    ///
857    /// # Example
858    ///
859    /// ```rust
860    /// use auth_framework::errors::{AuthError, OAuthProviderError};
861    ///
862    /// let err = AuthError::oauth_provider(OAuthProviderError::InvalidRedirectUri);
863    /// assert!(err.to_string().contains("redirect"));
864    /// ```
865    pub fn oauth_provider(error: OAuthProviderError) -> Self {
866        Self::OAuthProvider(error)
867    }
868
869    /// Create a user profile error.
870    ///
871    /// # Example
872    ///
873    /// ```rust
874    /// use auth_framework::AuthError;
875    ///
876    /// let err = AuthError::user_profile("email already in use");
877    /// assert!(err.to_string().contains("email already in use"));
878    /// ```
879    pub fn user_profile(message: impl Into<String>) -> Self {
880        Self::UserProfile {
881            message: message.into(),
882        }
883    }
884
885    /// Create an invalid credential error.
886    ///
887    /// # Example
888    ///
889    /// ```rust
890    /// use auth_framework::AuthError;
891    ///
892    /// let err = AuthError::invalid_credential("password", "too short");
893    /// assert!(err.to_string().contains("password"));
894    /// ```
895    pub fn invalid_credential(
896        credential_type: impl Into<String>,
897        message: impl Into<String>,
898    ) -> Self {
899        Self::InvalidCredential {
900            credential_type: credential_type.into(),
901            message: message.into(),
902        }
903    }
904
905    /// Create a timeout error.
906    ///
907    /// # Example
908    ///
909    /// ```rust
910    /// use auth_framework::AuthError;
911    ///
912    /// let err = AuthError::timeout(30);
913    /// assert!(err.to_string().contains("30"));
914    /// ```
915    pub fn timeout(timeout_seconds: u64) -> Self {
916        Self::Timeout { timeout_seconds }
917    }
918
919    /// Create a provider not configured error.
920    ///
921    /// # Example
922    ///
923    /// ```rust
924    /// use auth_framework::AuthError;
925    ///
926    /// let err = AuthError::provider_not_configured("github");
927    /// assert!(err.to_string().contains("github"));
928    /// ```
929    pub fn provider_not_configured(provider: impl Into<String>) -> Self {
930        Self::ProviderNotConfigured {
931            provider: provider.into(),
932        }
933    }
934
935    /// Create a rate limited error (alias for [`rate_limit`](Self::rate_limit)).
936    ///
937    /// # Example
938    ///
939    /// ```rust
940    /// use auth_framework::AuthError;
941    ///
942    /// let err = AuthError::rate_limited("5 requests per second exceeded");
943    /// assert!(err.to_string().contains("5 requests"));
944    /// ```
945    pub fn rate_limited(message: impl Into<String>) -> Self {
946        Self::RateLimit {
947            message: message.into(),
948        }
949    }
950
951    /// Create a configuration error (alias for [`config`](Self::config)).
952    ///
953    /// # Example
954    ///
955    /// ```rust
956    /// use auth_framework::AuthError;
957    ///
958    /// let err = AuthError::configuration("invalid issuer URL");
959    /// assert!(err.to_string().contains("invalid issuer URL"));
960    /// ```
961    pub fn configuration(message: impl Into<String>) -> Self {
962        Self::Configuration {
963            message: message.into(),
964            source: None,
965            help: None,
966            docs_url: None,
967            suggested_fix: None,
968        }
969    }
970
971    // -----------------------------------------------------------------------
972    // Classification helpers — framework-agnostic error introspection
973    // -----------------------------------------------------------------------
974
975    /// Return the HTTP status code that best represents this error.
976    ///
977    /// This is framework-agnostic and works without enabling any web framework
978    /// feature flag. Web framework integrations (actix-web, axum, …) use this
979    /// internally but you can also call it directly when building custom
980    /// response types.
981    ///
982    /// # Example
983    ///
984    /// ```rust
985    /// use auth_framework::AuthError;
986    ///
987    /// assert_eq!(AuthError::rate_limit("slow down").http_status_code(), 429);
988    /// assert_eq!(AuthError::internal("oops").http_status_code(), 500);
989    /// assert_eq!(AuthError::token("bad jwt").http_status_code(), 401);
990    /// ```
991    pub fn http_status_code(&self) -> u16 {
992        match self {
993            // 400 Bad Request
994            Self::InvalidInput(_)
995            | Self::Validation { .. }
996            | Self::InvalidCredential { .. }
997            | Self::HardwareToken(_)
998            | Self::InvalidRequest(_)
999            | Self::InvalidSecret => 400,
1000
1001            // 401 Unauthorized
1002            Self::Token(_)
1003            | Self::AuthMethod { .. }
1004            | Self::Jwt(_)
1005            | Self::Unauthorized(_)
1006            | Self::PasswordVerification(_) => 401,
1007
1008            // 403 Forbidden
1009            Self::Permission(_) | Self::StepUpRequired { .. } => 403,
1010
1011            // 404 Not Found
1012            Self::UserNotFound | Self::ProviderNotConfigured { .. } => 404,
1013
1014            // 408 Request Timeout
1015            Self::Timeout { .. } => 408,
1016
1017            // 429 Too Many Requests
1018            Self::RateLimit { .. } | Self::TooManyConcurrentSessions => 429,
1019
1020            // 502 Bad Gateway (upstream provider errors)
1021            Self::OAuthProvider(_) | Self::Network(_) => 502,
1022
1023            // 503 Service Unavailable (storage / infra)
1024            Self::Storage(_) => 503,
1025
1026            // 500 Internal Server Error (everything else)
1027            Self::Configuration { .. }
1028            | Self::Crypto { .. }
1029            | Self::Internal { .. }
1030            | Self::Json(_)
1031            | Self::Yaml(_)
1032            | Self::Toml(_)
1033            | Self::Io(_)
1034            | Self::Mfa(_)
1035            | Self::DeviceFlow(_)
1036            | Self::TokenGeneration(_)
1037            | Self::SessionError(_)
1038            | Self::UserProfile { .. }
1039            | Self::Cli(_)
1040            | Self::SystemTime(_)
1041            | Self::PasswordHashing(_)
1042            | Self::BackupCodeVerification(_)
1043            | Self::BackupCodeHashing(_)
1044            | Self::UnsupportedProvider(_) => 500,
1045
1046            #[cfg(feature = "prometheus")]
1047            Self::Metrics(_) => 500,
1048
1049            // Deprecated variants
1050            #[allow(
1051                deprecated,
1052                reason = "matches deprecated variants so old errors still classify until removal"
1053            )]
1054            Self::InvalidToken(_)
1055            | Self::NetworkError(_)
1056            | Self::ParseError(_)
1057            | Self::ConfigurationError(_) => 500,
1058        }
1059    }
1060
1061    /// Whether this error is transient and the operation may succeed on retry.
1062    ///
1063    /// Returns `true` for rate-limit, timeout, network, and storage
1064    /// connectivity errors. Returns `false` for authentication failures,
1065    /// validation errors, and other permanent conditions.
1066    ///
1067    /// # Example
1068    ///
1069    /// ```rust
1070    /// use auth_framework::AuthError;
1071    ///
1072    /// assert!(AuthError::rate_limit("too fast").is_retryable());
1073    /// assert!(AuthError::timeout(30).is_retryable());
1074    /// assert!(!AuthError::token("invalid").is_retryable());
1075    /// assert!(!AuthError::validation("bad input").is_retryable());
1076    /// ```
1077    pub fn is_retryable(&self) -> bool {
1078        matches!(
1079            self,
1080            Self::RateLimit { .. }
1081                | Self::Timeout { .. }
1082                | Self::TooManyConcurrentSessions
1083                | Self::Network(_)
1084                | Self::Storage(StorageError::ConnectionFailed { .. })
1085        )
1086    }
1087
1088    /// A short, stable, machine-readable code for this error category.
1089    ///
1090    /// Useful for API responses, metrics labels, and log filtering.
1091    /// These codes are stable across patch releases.
1092    ///
1093    /// # Example
1094    ///
1095    /// ```rust
1096    /// use auth_framework::AuthError;
1097    ///
1098    /// assert_eq!(AuthError::rate_limit("nope").error_code(), "rate_limit");
1099    /// assert_eq!(AuthError::token("bad").error_code(), "invalid_token");
1100    /// assert_eq!(AuthError::config("bad").error_code(), "configuration");
1101    /// ```
1102    pub fn error_code(&self) -> &'static str {
1103        match self {
1104            Self::Configuration { .. } => "configuration",
1105            Self::AuthMethod { .. } => "auth_method",
1106            Self::Token(_) => "invalid_token",
1107            Self::Permission(_) => "insufficient_permissions",
1108            Self::Storage(_) => "storage",
1109            Self::Network(_) => "network",
1110            Self::Json(_) | Self::Yaml(_) | Self::Toml(_) => "serialization",
1111            Self::Jwt(_) => "jwt",
1112            Self::Io(_) => "io",
1113            Self::RateLimit { .. } => "rate_limit",
1114            Self::TooManyConcurrentSessions => "concurrent_sessions",
1115            Self::Mfa(_) => "mfa",
1116            Self::DeviceFlow(_) => "device_flow",
1117            Self::OAuthProvider(_) => "oauth_provider",
1118            Self::PasswordVerification(_) => "password_verification",
1119            Self::UserNotFound => "user_not_found",
1120            Self::InvalidInput(_) => "invalid_input",
1121            Self::HardwareToken(_) => "hardware_token",
1122            Self::InvalidCredential { .. } => "invalid_credential",
1123            Self::Timeout { .. } => "timeout",
1124            Self::Crypto { .. } => "crypto",
1125            Self::Validation { .. } => "validation",
1126            Self::Internal { .. } => "internal",
1127            Self::StepUpRequired { .. } => "step_up_required",
1128            Self::SessionError(_) => "session",
1129            Self::Unauthorized(_) => "unauthorized",
1130            Self::TokenGeneration(_) => "token_generation",
1131            Self::UserProfile { .. } => "user_profile",
1132            Self::ProviderNotConfigured { .. } => "provider_not_configured",
1133            Self::Cli(_) => "cli",
1134            Self::SystemTime(_) => "internal",
1135            Self::PasswordHashing(_) => "password_hashing",
1136            Self::BackupCodeVerification(_) => "backup_code",
1137            Self::BackupCodeHashing(_) => "backup_code",
1138            Self::InvalidSecret => "invalid_secret",
1139            Self::InvalidRequest(_) => "invalid_request",
1140            Self::UnsupportedProvider(_) => "unsupported_provider",
1141            #[cfg(feature = "prometheus")]
1142            Self::Metrics(_) => "metrics",
1143            #[allow(
1144                deprecated,
1145                reason = "matches a deprecated variant so old errors still map until removal"
1146            )]
1147            Self::InvalidToken(_) => "invalid_token",
1148            #[allow(
1149                deprecated,
1150                reason = "matches a deprecated variant so old errors still map until removal"
1151            )]
1152            Self::NetworkError(_) => "network",
1153            #[allow(
1154                deprecated,
1155                reason = "matches a deprecated variant so old errors still map until removal"
1156            )]
1157            Self::ParseError(_) => "parse",
1158            #[allow(
1159                deprecated,
1160                reason = "matches a deprecated variant so old errors still map until removal"
1161            )]
1162            Self::ConfigurationError(_) => "configuration",
1163        }
1164    }
1165
1166    /// Whether this is a client-side error (4xx status code).
1167    ///
1168    /// # Example
1169    ///
1170    /// ```rust
1171    /// use auth_framework::AuthError;
1172    ///
1173    /// assert!(AuthError::validation("bad").is_client_error());
1174    /// assert!(!AuthError::internal("oops").is_client_error());
1175    /// ```
1176    pub fn is_client_error(&self) -> bool {
1177        (400..500).contains(&self.http_status_code())
1178    }
1179
1180    /// Whether this is a server-side error (5xx status code).
1181    ///
1182    /// # Example
1183    ///
1184    /// ```rust
1185    /// use auth_framework::AuthError;
1186    ///
1187    /// assert!(AuthError::internal("oops").is_server_error());
1188    /// assert!(!AuthError::validation("bad").is_server_error());
1189    /// ```
1190    pub fn is_server_error(&self) -> bool {
1191        self.http_status_code() >= 500
1192    }
1193}
1194
1195impl TokenError {
1196    /// Create a new token creation failed error.
1197    ///
1198    /// # Example
1199    ///
1200    /// ```rust
1201    /// use auth_framework::errors::TokenError;
1202    ///
1203    /// let err = TokenError::creation_failed("signing key unavailable");
1204    /// assert!(err.to_string().contains("signing key unavailable"));
1205    /// ```
1206    pub fn creation_failed(message: impl Into<String>) -> Self {
1207        Self::CreationFailed {
1208            message: message.into(),
1209        }
1210    }
1211
1212    /// Create a new token refresh failed error.
1213    ///
1214    /// # Example
1215    ///
1216    /// ```rust
1217    /// use auth_framework::errors::TokenError;
1218    ///
1219    /// let err = TokenError::refresh_failed("refresh token revoked");
1220    /// assert!(err.to_string().contains("refresh token revoked"));
1221    /// ```
1222    pub fn refresh_failed(message: impl Into<String>) -> Self {
1223        Self::RefreshFailed {
1224            message: message.into(),
1225        }
1226    }
1227
1228    /// Create a new token revocation failed error.
1229    ///
1230    /// # Example
1231    ///
1232    /// ```rust
1233    /// use auth_framework::errors::TokenError;
1234    ///
1235    /// let err = TokenError::revocation_failed("storage write failed");
1236    /// assert!(err.to_string().contains("storage write failed"));
1237    /// ```
1238    pub fn revocation_failed(message: impl Into<String>) -> Self {
1239        Self::RevocationFailed {
1240            message: message.into(),
1241        }
1242    }
1243}
1244
1245impl PermissionError {
1246    /// Create a new access denied error.
1247    ///
1248    /// # Example
1249    ///
1250    /// ```rust
1251    /// use auth_framework::errors::PermissionError;
1252    ///
1253    /// let err = PermissionError::access_denied("write", "documents");
1254    /// assert!(err.to_string().contains("write"));
1255    /// ```
1256    pub fn access_denied(permission: impl Into<String>, resource: impl Into<String>) -> Self {
1257        Self::AccessDenied {
1258            permission: permission.into(),
1259            resource: resource.into(),
1260        }
1261    }
1262
1263    /// Create a new role not found error.
1264    ///
1265    /// # Example
1266    ///
1267    /// ```rust
1268    /// use auth_framework::errors::PermissionError;
1269    ///
1270    /// let err = PermissionError::role_not_found("superadmin");
1271    /// assert!(err.to_string().contains("superadmin"));
1272    /// ```
1273    pub fn role_not_found(role: impl Into<String>) -> Self {
1274        Self::RoleNotFound { role: role.into() }
1275    }
1276
1277    /// Create a new permission not found error.
1278    ///
1279    /// # Example
1280    ///
1281    /// ```rust
1282    /// use auth_framework::errors::PermissionError;
1283    ///
1284    /// let err = PermissionError::permission_not_found("delete_user");
1285    /// assert!(err.to_string().contains("delete_user"));
1286    /// ```
1287    pub fn permission_not_found(permission: impl Into<String>) -> Self {
1288        Self::PermissionNotFound {
1289            permission: permission.into(),
1290        }
1291    }
1292
1293    /// Create a new invalid format error.
1294    ///
1295    /// # Example
1296    ///
1297    /// ```rust
1298    /// use auth_framework::errors::PermissionError;
1299    ///
1300    /// let err = PermissionError::invalid_format("missing resource:action separator");
1301    /// assert!(err.to_string().contains("separator"));
1302    /// ```
1303    pub fn invalid_format(message: impl Into<String>) -> Self {
1304        Self::InvalidFormat {
1305            message: message.into(),
1306        }
1307    }
1308}
1309
1310impl StorageError {
1311    /// Create a new connection failed error.
1312    ///
1313    /// # Example
1314    ///
1315    /// ```rust
1316    /// use auth_framework::errors::StorageError;
1317    ///
1318    /// let err = StorageError::connection_failed("connection refused");
1319    /// assert!(err.to_string().contains("connection refused"));
1320    /// ```
1321    pub fn connection_failed(message: impl Into<String>) -> Self {
1322        Self::ConnectionFailed {
1323            message: message.into(),
1324        }
1325    }
1326
1327    /// Create a new operation failed error.
1328    ///
1329    /// # Example
1330    ///
1331    /// ```rust
1332    /// use auth_framework::errors::StorageError;
1333    ///
1334    /// let err = StorageError::operation_failed("table not found");
1335    /// assert!(err.to_string().contains("table not found"));
1336    /// ```
1337    pub fn operation_failed(message: impl Into<String>) -> Self {
1338        Self::OperationFailed {
1339            message: message.into(),
1340        }
1341    }
1342
1343    /// Create a new serialization error.
1344    ///
1345    /// # Example
1346    ///
1347    /// ```rust
1348    /// use auth_framework::errors::StorageError;
1349    ///
1350    /// let err = StorageError::serialization("invalid JSON");
1351    /// assert!(err.to_string().contains("invalid JSON"));
1352    /// ```
1353    pub fn serialization(message: impl Into<String>) -> Self {
1354        Self::Serialization {
1355            message: message.into(),
1356        }
1357    }
1358}
1359
1360impl MfaError {
1361    /// Create a new method not supported error.
1362    ///
1363    /// # Example
1364    ///
1365    /// ```rust
1366    /// use auth_framework::errors::MfaError;
1367    ///
1368    /// let err = MfaError::method_not_supported("biometric");
1369    /// assert!(err.to_string().contains("biometric"));
1370    /// ```
1371    pub fn method_not_supported(method: impl Into<String>) -> Self {
1372        Self::MethodNotSupported {
1373            method: method.into(),
1374        }
1375    }
1376
1377    /// Create a new verification failed error.
1378    ///
1379    /// # Example
1380    ///
1381    /// ```rust
1382    /// use auth_framework::errors::MfaError;
1383    ///
1384    /// let err = MfaError::verification_failed("code expired");
1385    /// assert!(err.to_string().contains("code expired"));
1386    /// ```
1387    pub fn verification_failed(message: impl Into<String>) -> Self {
1388        Self::VerificationFailed {
1389            message: message.into(),
1390        }
1391    }
1392}
1393
1394// Actix-web ResponseError implementation
1395#[cfg(feature = "actix-web")]
1396impl actix_web::ResponseError for AuthError {
1397    fn error_response(&self) -> actix_web::HttpResponse {
1398        match self {
1399            AuthError::Token(_) => {
1400                actix_web::HttpResponse::Unauthorized().json(serde_json::json!({
1401                    "error": "invalid_token",
1402                    "error_description": self.to_string()
1403                }))
1404            }
1405            AuthError::Permission(_) => {
1406                actix_web::HttpResponse::Forbidden().json(serde_json::json!({
1407                    "error": "insufficient_permissions",
1408                    "error_description": self.to_string()
1409                }))
1410            }
1411            AuthError::RateLimit { .. } => {
1412                actix_web::HttpResponse::TooManyRequests().json(serde_json::json!({
1413                    "error": "rate_limit_exceeded",
1414                    "error_description": self.to_string()
1415                }))
1416            }
1417            AuthError::Configuration { .. }
1418            | AuthError::Storage(_)
1419            | AuthError::Internal { .. } => {
1420                actix_web::HttpResponse::InternalServerError().json(serde_json::json!({
1421                    "error": "internal_error",
1422                    "error_description": "An internal error occurred"
1423                }))
1424            }
1425            _ => actix_web::HttpResponse::BadRequest().json(serde_json::json!({
1426                "error": "bad_request",
1427                "error_description": self.to_string()
1428            })),
1429        }
1430    }
1431
1432    fn status_code(&self) -> actix_web::http::StatusCode {
1433        match self {
1434            AuthError::Token(_) => actix_web::http::StatusCode::UNAUTHORIZED,
1435            AuthError::Permission(_) => actix_web::http::StatusCode::FORBIDDEN,
1436            AuthError::RateLimit { .. } => actix_web::http::StatusCode::TOO_MANY_REQUESTS,
1437            AuthError::Internal { .. }
1438            | AuthError::Configuration { .. }
1439            | AuthError::Storage(_) => actix_web::http::StatusCode::INTERNAL_SERVER_ERROR,
1440            _ => actix_web::http::StatusCode::BAD_REQUEST,
1441        }
1442    }
1443}
1444
1445// Additional From implementations for admin tools
1446impl From<Box<dyn std::error::Error + Send + Sync>> for AuthError {
1447    fn from(error: Box<dyn std::error::Error + Send + Sync>) -> Self {
1448        AuthError::Cli(format!("Admin tool error: {}", error))
1449    }
1450}
1451
1452impl From<Box<dyn std::error::Error>> for AuthError {
1453    fn from(error: Box<dyn std::error::Error>) -> Self {
1454        AuthError::Cli(format!("Admin tool error: {}", error))
1455    }
1456}
1457
1458#[cfg(test)]
1459mod tests {
1460    use super::*;
1461    use std::error::Error;
1462
1463    #[test]
1464    fn test_auth_error_creation() {
1465        let token_error = AuthError::token("Invalid JWT signature");
1466        assert!(matches!(token_error, AuthError::Token(_)));
1467        assert!(token_error.to_string().contains("Invalid JWT signature"));
1468
1469        let permission_error = AuthError::access_denied("Access denied");
1470        assert!(matches!(permission_error, AuthError::Permission(_)));
1471        assert!(permission_error.to_string().contains("Access denied"));
1472
1473        let config_error = AuthError::config("Database connection failed");
1474        assert!(matches!(config_error, AuthError::Configuration { .. }));
1475        assert!(
1476            config_error
1477                .to_string()
1478                .contains("Database connection failed")
1479        );
1480    }
1481
1482    #[test]
1483    fn test_auth_error_categorization() {
1484        // Test various error types maintain their category
1485        let errors = vec![
1486            (AuthError::token("test"), "Token"),
1487            (AuthError::access_denied("test"), "Permission"),
1488            (AuthError::config("test"), "Configuration"),
1489            (AuthError::crypto("test"), "Crypto"),
1490            (AuthError::validation("test"), "Validation"),
1491        ];
1492
1493        for (error, expected_category) in errors {
1494            let error_string = format!("{:?}", error);
1495            assert!(
1496                error_string.contains(expected_category),
1497                "Error {:?} should contain category {}",
1498                error,
1499                expected_category
1500            );
1501        }
1502    }
1503
1504    #[test]
1505    fn test_rate_limit_error() {
1506        let rate_limit_error = AuthError::rate_limit("Too many requests");
1507
1508        match rate_limit_error {
1509            AuthError::RateLimit { message } => {
1510                assert_eq!(message, "Too many requests");
1511            }
1512            _ => panic!("Expected RateLimit error"),
1513        }
1514    }
1515
1516    #[test]
1517    fn test_validation_error() {
1518        let validation_error = AuthError::validation("username must not be empty");
1519
1520        match validation_error {
1521            AuthError::Validation { message } => {
1522                assert_eq!(message, "username must not be empty");
1523            }
1524            _ => panic!("Expected Validation error"),
1525        }
1526    }
1527
1528    #[test]
1529    fn test_configuration_error() {
1530        let config_error = AuthError::config("jwt_secret is required");
1531
1532        match config_error {
1533            AuthError::Configuration { message, .. } => {
1534                assert_eq!(message, "jwt_secret is required");
1535            }
1536            _ => panic!("Expected Configuration error"),
1537        }
1538    }
1539
1540    #[test]
1541    fn test_error_chain() {
1542        let root_cause = std::io::Error::new(std::io::ErrorKind::NotFound, "File not found");
1543        let auth_error = AuthError::internal(format!("Config file error: {}", root_cause));
1544
1545        // Test that error information is preserved
1546        assert!(auth_error.to_string().contains("File not found"));
1547        assert!(auth_error.to_string().contains("Config file error"));
1548    }
1549
1550    #[test]
1551    fn test_error_source() {
1552        let token_error = AuthError::token("JWT parsing failed");
1553
1554        // AuthError implements Error trait
1555        // Token error wraps TokenError, so it should have a source
1556        assert!(token_error.source().is_some());
1557
1558        // Test error display
1559        let error_msg = format!("{}", token_error);
1560        assert!(error_msg.contains("JWT parsing failed"));
1561    }
1562
1563    #[test]
1564    fn test_from_conversions() {
1565        // Test conversion from std::io::Error
1566        let io_error = std::io::Error::new(std::io::ErrorKind::PermissionDenied, "Access denied");
1567        let auth_error: AuthError = io_error.into();
1568        assert!(matches!(auth_error, AuthError::Io(_)));
1569
1570        // Test conversion from serde_json::Error
1571        let json_str = r#"{"invalid": json"#;
1572        let json_error: serde_json::Error =
1573            serde_json::from_str::<serde_json::Value>(json_str).unwrap_err();
1574        let auth_error: AuthError = json_error.into();
1575        assert!(matches!(auth_error, AuthError::Json(_)));
1576    }
1577
1578    #[test]
1579    fn test_error_equality() {
1580        let error1 = AuthError::token("Same message");
1581        let error2 = AuthError::token("Same message");
1582        let error3 = AuthError::token("Different message");
1583
1584        // Test Debug representation for consistency
1585        assert_eq!(format!("{:?}", error1), format!("{:?}", error2));
1586        assert_ne!(format!("{:?}", error1), format!("{:?}", error3));
1587    }
1588
1589    #[test]
1590    fn test_actix_web_integration() {
1591        #[cfg(feature = "actix-web")]
1592        {
1593            use actix_web::ResponseError;
1594
1595            // Test status codes
1596            assert_eq!(
1597                AuthError::token("test").status_code(),
1598                actix_web::http::StatusCode::UNAUTHORIZED
1599            );
1600            assert_eq!(
1601                AuthError::access_denied("test").status_code(),
1602                actix_web::http::StatusCode::FORBIDDEN
1603            );
1604            assert_eq!(
1605                AuthError::rate_limit("test").status_code(),
1606                actix_web::http::StatusCode::TOO_MANY_REQUESTS
1607            );
1608            assert_eq!(
1609                AuthError::internal("test").status_code(),
1610                actix_web::http::StatusCode::INTERNAL_SERVER_ERROR
1611            );
1612        }
1613    }
1614
1615    #[test]
1616    fn test_error_message_safety() {
1617        // Ensure error messages don't leak sensitive information
1618        let sensitive_data = "password123";
1619        let safe_error = AuthError::token("Invalid credentials");
1620
1621        // Error message should not contain sensitive data
1622        assert!(!safe_error.to_string().contains(sensitive_data));
1623
1624        // Test that we can create errors without exposing internals
1625        let config_error = AuthError::config("connection failed");
1626        assert!(!config_error.to_string().contains("password"));
1627        assert!(!config_error.to_string().contains("secret"));
1628    }
1629
1630    #[test]
1631    fn test_cli_error_conversion() {
1632        let boxed_error: Box<dyn std::error::Error + Send + Sync> = "CLI operation failed".into();
1633        let auth_error: AuthError = boxed_error.into();
1634
1635        assert!(matches!(auth_error, AuthError::Cli(_)));
1636        assert!(auth_error.to_string().contains("CLI operation failed"));
1637    }
1638
1639    #[test]
1640    fn test_error_variants_coverage() {
1641        // Ensure all error variants can be created and have proper messages
1642        let test_errors = vec![
1643            AuthError::token("token error"),
1644            AuthError::access_denied("permission error"),
1645            AuthError::internal("internal error"),
1646            AuthError::crypto("crypto error"),
1647            AuthError::Cli("cli error".to_string()),
1648            AuthError::validation("validation error"),
1649            AuthError::config("config error"),
1650            AuthError::rate_limit("rate limit error"),
1651        ];
1652
1653        for error in test_errors {
1654            // All errors should have non-empty messages
1655            assert!(
1656                !error.to_string().is_empty(),
1657                "Error should have message: {:?}",
1658                error
1659            );
1660
1661            // All errors should implement Debug
1662            let debug_repr = format!("{:?}", error);
1663            assert!(
1664                !debug_repr.is_empty(),
1665                "Error should have debug representation: {:?}",
1666                error
1667            );
1668        }
1669    }
1670
1671    #[test]
1672    fn test_oauth_specific_errors() {
1673        // Test OAuth-specific error creation using auth_method
1674        let invalid_client = AuthError::auth_method("oauth", "Client authentication failed");
1675        assert!(
1676            invalid_client
1677                .to_string()
1678                .contains("Client authentication failed")
1679        );
1680
1681        let invalid_grant = AuthError::auth_method("oauth", "Authorization code expired");
1682        assert!(
1683            invalid_grant
1684                .to_string()
1685                .contains("Authorization code expired")
1686        );
1687    }
1688
1689    #[test]
1690    fn test_error_context_preservation() {
1691        // Test that errors maintain context through transformations
1692        let original_msg = "Original error message";
1693        let context_msg = "Additional context";
1694
1695        let base_error = AuthError::internal(original_msg);
1696        let contextual_error = AuthError::internal(format!("{}: {}", context_msg, base_error));
1697
1698        assert!(contextual_error.to_string().contains(original_msg));
1699        assert!(contextual_error.to_string().contains(context_msg));
1700    }
1701
1702    #[test]
1703    fn test_error_serialization() {
1704        // Test that errors can be converted to JSON for API responses
1705        let error = AuthError::validation("email invalid format");
1706
1707        // Should be able to include in structured responses
1708        let error_response = serde_json::json!({
1709            "error": "validation_failed",
1710            "message": error.to_string(),
1711            "field": "email"
1712        });
1713
1714        assert!(
1715            error_response["message"]
1716                .as_str()
1717                .unwrap()
1718                .contains("invalid format")
1719        );
1720    }
1721
1722    #[test]
1723    fn test_concurrent_error_creation() {
1724        use std::thread;
1725
1726        let handles: Vec<_> = (0..10)
1727            .map(|i| {
1728                thread::spawn(move || {
1729                    let error = AuthError::token(format!("Concurrent error {}", i));
1730                    assert!(
1731                        error
1732                            .to_string()
1733                            .contains(&format!("Concurrent error {}", i))
1734                    );
1735                    error
1736                })
1737            })
1738            .collect();
1739
1740        // Wait for all threads and verify errors
1741        for handle in handles {
1742            let error = handle.join().unwrap();
1743            assert!(!error.to_string().is_empty());
1744        }
1745    }
1746}