Enum AuthError 

pub enum AuthError {
    Configuration {
        message: String,
        source: Option<Box<dyn Error + Send + Sync>>,
        help: Option<String>,
        docs_url: Option<String>,
        suggested_fix: Option<String>,
    },
    AuthMethod {
        method: String,
        message: String,
        help: Option<String>,
        docs_url: Option<String>,
        suggested_fix: Option<String>,
    },
    Token(TokenError),
    Permission(PermissionError),
    Storage(StorageError),
    Network(Error),
    Json(Error),
    Jwt(Error),
    Yaml(Error),
    Toml(Error),
    Io(Error),
    Cli(String),
    SystemTime(SystemTimeError),
    RateLimit {
        message: String,
    },
    TooManyConcurrentSessions,
    Mfa(MfaError),
    DeviceFlow(DeviceFlowError),
    OAuthProvider(OAuthProviderError),
    PasswordVerification(String),
    PasswordHashing(String),
    UserNotFound,
    InvalidInput(String),
    HardwareToken(String),
    BackupCodeVerification(String),
    BackupCodeHashing(String),
    InvalidSecret,
    UserProfile {
        message: String,
    },
    InvalidCredential {
        credential_type: String,
        message: String,
    },
    Timeout {
        timeout_seconds: u64,
    },
    ProviderNotConfigured {
        provider: String,
    },
    Crypto {
        message: String,
    },
    Validation {
        message: String,
    },
    Internal {
        message: String,
    },
    InvalidRequest(String),
    StepUpRequired {
        current_level: String,
        required_level: String,
        step_up_url: String,
    },
    SessionError(String),
    Unauthorized(String),
    TokenGeneration(String),
    InvalidToken(String),
    UnsupportedProvider(String),
    NetworkError(String),
    ParseError(String),
    ConfigurationError(String),
}

Comprehensive error type covering all authentication and authorization failures.

AuthError provides detailed error information for all aspects of the authentication framework, from configuration issues to runtime failures. Each error variant includes contextual information to aid in debugging and provide appropriate user feedback.

This enhanced error type provides:

• Actionable error messages with specific suggestions for fixes
• Documentation links to relevant guides and troubleshooting
• Contextual help that guides users to solutions
• Security-aware messaging that doesn’t leak sensitive information

Error Categories

Configuration Errors

Errors that occur during framework setup and configuration validation.

Authentication Errors

Errors related to credential validation and authentication method execution.

Authorization Errors

Errors related to permission checking and access control.

Token Errors

JWT token creation, validation, expiration, and lifecycle issues.

Storage Errors

Database connectivity, query failures, and data persistence issues.

Network Errors

External service communication, timeouts, and connectivity problems.

Cryptographic Errors

Encryption, decryption, signing, and other security operation failures.

Enhanced Error Handling

use auth_framework::AuthError;

// Enhanced error handling with contextual help
match auth_result {
    Err(AuthError::Configuration { message, help, docs_url, .. }) => {
        eprintln!("Configuration Error: {}", message);
        if let Some(help) = help {
            eprintln!("Help: {}", help);
        }
        if let Some(docs) = docs_url {
            eprintln!("See: {}", docs);
        }
    },
    Err(AuthError::InvalidCredential { credential_type, message, .. }) => {
        eprintln!("Invalid {}: {}", credential_type, message);
    },
    // ... handle other error types
    _ => {}
}

Security Notes

Error messages are carefully crafted to:

• Provide sufficient detail for debugging and monitoring
• Avoid exposing sensitive information that could aid attackers
• Enable security teams to identify potential threats
• Support compliance and audit requirements
• Guide users to secure solutions and best practices

Variants

Configuration

Configuration validation and setup errors.

These errors occur when the authentication framework is misconfigured or when configuration validation fails during startup.

Fields

message: String

source: Option<Box<dyn Error + Send + Sync>>

help: Option<String>

Helpful guidance for fixing the issue

docs_url: Option<String>

Link to relevant documentation

suggested_fix: Option<String>

Specific fix suggestion with commands or code

AuthMethod

Authentication method execution errors.

These errors occur when a specific authentication method fails to execute properly, such as OAuth provider communication failures.

Fields

method: String

message: String

help: Option<String>

Helpful guidance for fixing the issue

docs_url: Option<String>

Link to relevant documentation

suggested_fix: Option<String>

Specific fix suggestion

Token(TokenError)

Token-related errors

Permission(PermissionError)

Permission-related errors

Storage(StorageError)

Storage-related errors

Network(Error)

Network/HTTP errors

Json(Error)

JSON parsing errors

Jwt(Error)

JWT errors

Yaml(Error)

YAML parsing errors

Toml(Error)

TOML parsing errors

Io(Error)

IO errors

Cli(String)

CLI interaction errors

SystemTime(SystemTimeError)

System time errors

RateLimit

Rate limiting errors

Fields

message: String

TooManyConcurrentSessions

Session-related errors

Mfa(MfaError)

MFA-related errors

DeviceFlow(DeviceFlowError)

Device flow errors

OAuthProvider(OAuthProviderError)

OAuth provider errors

PasswordVerification(String)

The stored password hash does not match the supplied credential.

This typically means the user entered the wrong password. Do not reveal which field (username vs. password) was incorrect to the caller.

PasswordHashing(String)

The password hashing algorithm (argon2/bcrypt) encountered an error.

UserNotFound

No user record exists for the given identifier.

InvalidInput(String)

A request parameter failed validation (e.g. empty username, invalid email format).

HardwareToken(String)

A hardware security key (FIDO2 / WebAuthn) operation failed.

BackupCodeVerification(String)

A one-time backup code was rejected (already used, incorrect, or expired).

BackupCodeHashing(String)

Failed to hash a backup code for secure storage.

InvalidSecret

The TOTP or MFA secret is in an invalid format (e.g. not valid Base32).

UserProfile

An error occurred while reading or updating a user profile.

Fields

message: String

InvalidCredential

Credential validation errors

Fields

credential_type: String

message: String

Timeout

An authentication operation did not complete within the allowed window.

Fields

timeout_seconds: u64

ProviderNotConfigured

Provider configuration missing

Fields

provider: String

Crypto

Cryptography errors

Fields

message: String

Validation

Validation errors

Fields

message: String

Internal

Generic internal errors

Fields

message: String

InvalidRequest(String)

Invalid request error

StepUpRequired

Step-up authentication required

Fields

current_level: String

required_level: String

step_up_url: String

SessionError(String)

A session-layer error (e.g. session not found, session expired, store failure).

Unauthorized(String)

The caller lacks valid credentials or the credentials have been revoked.

TokenGeneration(String)

Token creation failed at the signing or encoding stage.

Consider using AuthError::token for richer TokenError variants.

InvalidToken(String)

👎Deprecated since 0.5.0:

Use AuthError::token(msg) instead — it routes through the structured TokenError hierarchy

Invalid token error.

Prefer AuthError::token which routes through the structured TokenError hierarchy for consistent token error handling.

UnsupportedProvider(String)

The named authentication provider is not compiled in or not recognized.

NetworkError(String)

👎Deprecated since 0.5.0:

Use AuthError::internal(msg) or let reqwest::Error convert via AuthError::Network instead

Network error with custom message.

Prefer AuthError::Internal with a descriptive message, or let reqwest::Error convert automatically via the From impl on AuthError::Network.

ParseError(String)

👎Deprecated since 0.5.0:

Use AuthError::internal(msg) or let serde errors convert via AuthError::Json instead

Parse error with custom message.

Prefer AuthError::Internal with a descriptive message, or let serde_json::Error convert automatically via the From impl on AuthError::Json.

ConfigurationError(String)

👎Deprecated since 0.5.0:

Use AuthError::config(msg) instead — it provides richer context fields

Configuration error with custom message.

Prefer AuthError::config or AuthError::config_with_help which carry richer context (help text, docs URL, suggested fix).

Implementations

impl AuthError

pub fn config(message: impl Into<String>) -> Self

Create a new configuration error.

Example

use auth_framework::AuthError;

let err = AuthError::config("Missing database URL");
assert!(err.to_string().contains("Missing database URL"));

pub fn config_with_help( message: impl Into<String>, help: impl Into<String>, suggested_fix: Option<String>, ) -> Self

Create a configuration error with helpful context.

Includes a human-readable help string and an optional suggested_fix that can be displayed by CLI tools or IDE integrations.

Example

use auth_framework::AuthError;

let err = AuthError::config_with_help(
    "JWT secret not set",
    "Set the JWT_SECRET environment variable",
    Some("export JWT_SECRET=$(openssl rand -hex 32)".into()),
);
assert!(err.to_string().contains("JWT secret not set"));

pub fn jwt_secret_too_short(current_length: usize) -> Self

Create a JWT secret validation error with helpful guidance.

Example

use auth_framework::AuthError;

let err = AuthError::jwt_secret_too_short(16);
assert!(err.to_string().contains("16 characters"));

pub fn production_memory_storage() -> Self

Create a production environment error with guidance.

Example

use auth_framework::AuthError;

let err = AuthError::production_memory_storage();
assert!(err.to_string().contains("Memory storage"));

pub fn auth_method( method: impl Into<String>, message: impl Into<String>, ) -> Self

Create a new auth method error.

Example

use auth_framework::AuthError;

let err = AuthError::auth_method("oauth2", "token endpoint unreachable");
assert!(err.to_string().contains("oauth2"));

pub fn auth_method_with_help( method: impl Into<String>, message: impl Into<String>, help: impl Into<String>, suggested_fix: Option<String>, ) -> Self

Create an auth method error with helpful context.

Example

use auth_framework::AuthError;

let err = AuthError::auth_method_with_help(
    "saml",
    "certificate expired",
    "Renew the SAML signing certificate",
    Some("openssl x509 -req -in cert.csr -signkey key.pem -out cert.pem".into()),
);
assert!(err.to_string().contains("saml"));

pub fn rate_limit(message: impl Into<String>) -> Self

Create a new rate limit error.

Example

use auth_framework::AuthError;

let err = AuthError::rate_limit("too many login attempts");
assert!(err.to_string().contains("too many login attempts"));

pub fn crypto(message: impl Into<String>) -> Self

Create a new crypto error.

Example

use auth_framework::AuthError;

let err = AuthError::crypto("HMAC key too short");
assert!(err.to_string().contains("HMAC key too short"));

pub fn validation(message: impl Into<String>) -> Self

Create a new validation error.

Example

use auth_framework::AuthError;

let err = AuthError::validation("email format invalid");
assert!(err.to_string().contains("email format invalid"));

pub fn internal(message: impl Into<String>) -> Self

Create a new internal error.

Example

use auth_framework::AuthError;

let err = AuthError::internal("unexpected state");
assert!(err.to_string().contains("unexpected state"));

pub fn authorization(message: impl Into<String>) -> Self

Create an authorization error.

Example

use auth_framework::AuthError;

let err = AuthError::authorization("insufficient privileges");
assert!(err.to_string().contains("insufficient privileges"));

pub fn access_denied(message: impl Into<String>) -> Self

Create an access denied error.

Example

use auth_framework::AuthError;

let err = AuthError::access_denied("admin role required");
assert!(err.to_string().contains("admin role required"));

pub fn token(message: impl Into<String>) -> Self

Create a token error.

Example

use auth_framework::AuthError;

let err = AuthError::token("signature mismatch");
assert!(err.to_string().contains("signature mismatch"));

pub fn device_flow(error: DeviceFlowError) -> Self

Create a device flow error.

Example

use auth_framework::errors::{AuthError, DeviceFlowError};

let err = AuthError::device_flow(DeviceFlowError::ExpiredToken);
assert!(err.to_string().contains("expired"));

pub fn oauth_provider(error: OAuthProviderError) -> Self

Create an OAuth provider error.

Example

use auth_framework::errors::{AuthError, OAuthProviderError};

let err = AuthError::oauth_provider(OAuthProviderError::InvalidRedirectUri);
assert!(err.to_string().contains("redirect"));

pub fn user_profile(message: impl Into<String>) -> Self

Create a user profile error.

Example

use auth_framework::AuthError;

let err = AuthError::user_profile("email already in use");
assert!(err.to_string().contains("email already in use"));

pub fn invalid_credential( credential_type: impl Into<String>, message: impl Into<String>, ) -> Self

Create an invalid credential error.

Example

use auth_framework::AuthError;

let err = AuthError::invalid_credential("password", "too short");
assert!(err.to_string().contains("password"));

pub fn timeout(timeout_seconds: u64) -> Self

Create a timeout error.

Example

use auth_framework::AuthError;

let err = AuthError::timeout(30);
assert!(err.to_string().contains("30"));

pub fn provider_not_configured(provider: impl Into<String>) -> Self

Create a provider not configured error.

Example

use auth_framework::AuthError;

let err = AuthError::provider_not_configured("github");
assert!(err.to_string().contains("github"));

pub fn rate_limited(message: impl Into<String>) -> Self

Create a rate limited error (alias for rate_limit).

Example

use auth_framework::AuthError;

let err = AuthError::rate_limited("5 requests per second exceeded");
assert!(err.to_string().contains("5 requests"));

pub fn configuration(message: impl Into<String>) -> Self

Create a configuration error (alias for config).

Example

use auth_framework::AuthError;

let err = AuthError::configuration("invalid issuer URL");
assert!(err.to_string().contains("invalid issuer URL"));

pub fn http_status_code(&self) -> u16

Return the HTTP status code that best represents this error.

This is framework-agnostic and works without enabling any web framework feature flag. Web framework integrations (actix-web, axum, …) use this internally but you can also call it directly when building custom response types.

Example

use auth_framework::AuthError;

assert_eq!(AuthError::rate_limit("slow down").http_status_code(), 429);
assert_eq!(AuthError::internal("oops").http_status_code(), 500);
assert_eq!(AuthError::token("bad jwt").http_status_code(), 401);

pub fn is_retryable(&self) -> bool

Whether this error is transient and the operation may succeed on retry.

Returns true for rate-limit, timeout, network, and storage connectivity errors. Returns false for authentication failures, validation errors, and other permanent conditions.

Example

use auth_framework::AuthError;

assert!(AuthError::rate_limit("too fast").is_retryable());
assert!(AuthError::timeout(30).is_retryable());
assert!(!AuthError::token("invalid").is_retryable());
assert!(!AuthError::validation("bad input").is_retryable());

pub fn error_code(&self) -> &'static str

A short, stable, machine-readable code for this error category.

Useful for API responses, metrics labels, and log filtering. These codes are stable across patch releases.

Example

use auth_framework::AuthError;

assert_eq!(AuthError::rate_limit("nope").error_code(), "rate_limit");
assert_eq!(AuthError::token("bad").error_code(), "invalid_token");
assert_eq!(AuthError::config("bad").error_code(), "configuration");

pub fn is_client_error(&self) -> bool

Whether this is a client-side error (4xx status code).

Example

use auth_framework::AuthError;

assert!(AuthError::validation("bad").is_client_error());
assert!(!AuthError::internal("oops").is_client_error());

pub fn is_server_error(&self) -> bool

Whether this is a server-side error (5xx status code).

Example

use auth_framework::AuthError;

assert!(AuthError::internal("oops").is_server_error());
assert!(!AuthError::validation("bad").is_server_error());

Trait Implementations

impl Debug for AuthError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for AuthError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for AuthError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<AuthError> for ApiResponse<()>

Convert an AuthError into an appropriate API error response.

Maps error variants to HTTP-semantic error codes:

• Token → INVALID_TOKEN
• Validation → VALIDATION_ERROR
• AuthMethod → INVALID_CREDENTIALS
• UserNotFound → NOT_FOUND
• Permission → FORBIDDEN
• RateLimit → RATE_LIMITED
• everything else → SERVER_ERROR

fn from(error: AuthError) -> Self

Converts to this type from the input type.

impl From<Box<dyn Error>> for AuthError

fn from(error: Box<dyn Error>) -> Self

Converts to this type from the input type.

impl From<Box<dyn Error + Sync + Send>> for AuthError

fn from(error: Box<dyn Error + Send + Sync>) -> Self

Converts to this type from the input type.

impl From<DeviceFlowError> for AuthError

fn from(source: DeviceFlowError) -> Self

Converts to this type from the input type.

impl From<Error> for AuthError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for AuthError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for AuthError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for AuthError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for AuthError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for AuthError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<MfaError> for AuthError

fn from(source: MfaError) -> Self

Converts to this type from the input type.

impl From<OAuthProviderError> for AuthError

fn from(source: OAuthProviderError) -> Self

Converts to this type from the input type.

impl From<PermissionError> for AuthError

fn from(source: PermissionError) -> Self

Converts to this type from the input type.

impl From<StorageError> for AuthError

fn from(source: StorageError) -> Self

Converts to this type from the input type.

impl From<SystemTimeError> for AuthError

fn from(source: SystemTimeError) -> Self

Converts to this type from the input type.

impl From<TenantRegistryError> for AuthError

fn from(err: TenantRegistryError) -> Self

Converts to this type from the input type.

impl From<TokenError> for AuthError

fn from(source: TokenError) -> Self

Converts to this type from the input type.