webgates 1.0.0

Application-facing composition crate for webgates authentication and authorization.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

//! Authentication-specific error types.
//!
//! This module defines the authentication error surface used by login, logout,
//! and session-renewal workflows.
//!
//! [`AuthenticationError`] models leaf authentication failures.
//! [`AuthnError`] wraps those failures with category-level messaging for users,
//! developers, and support tooling.
//!
//! # Examples
//!
//! Basic construction and user-facing message extraction:
//!
//! ```rust
//! use webgates::authn::errors::{AuthenticationError, AuthnError};
//! use webgates::errors_core::UserFriendlyError;
//!
//! let err = AuthnError::from_authentication(
//!     AuthenticationError::InvalidCredentials,
//!     Some("login form".into()),
//! );
//! assert!(err.user_message().contains("username or password"));
//! assert!(err.developer_message().contains("Authentication failure"));
//! assert!(err.support_code().starts_with("AUTHN-"));
//! ```
//!
//! Convenience constructor:
//!
//! ```rust
//! use webgates::authn::errors::AuthnError;
//!
//! let _ = AuthnError::invalid_credentials(Some("signin".into()));
//! ```

use crate::errors_core::{ErrorSeverity, UserFriendlyError};

use thiserror::Error;

/// Leaf authentication error variants reused by [`AuthnError`].
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum AuthenticationError {
    /// Invalid credentials were provided.
    #[error("Invalid credentials provided")]
    InvalidCredentials,
}

/// Category-level authentication error.
///
/// This type wraps [`AuthenticationError`] and adds user-facing messaging,
/// developer-facing detail, support codes, severity, and retryability.
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum AuthnError {
    /// Authentication flow failure, such as invalid credentials.
    #[error("Authentication error: {error}")]
    Authentication {
        /// The specific authentication failure kind.
        #[source]
        error: AuthenticationError,
        /// Optional context about where/how the failure occurred (non-sensitive).
        context: Option<String>,
    },
}

impl AuthnError {
    /// Creates an `AuthnError` from a leaf authentication error and optional context.
    pub fn from_authentication(error: AuthenticationError, context: Option<String>) -> Self {
        AuthnError::Authentication { error, context }
    }

    /// Creates an invalid-credentials error.
    pub fn invalid_credentials(context: Option<String>) -> Self {
        Self::from_authentication(AuthenticationError::InvalidCredentials, context)
    }

    fn support_code_inner(&self) -> String {
        match self {
            AuthnError::Authentication { error, .. } => match error {
                AuthenticationError::InvalidCredentials => "AUTHN-INVALID-CREDS".to_string(),
            },
        }
    }
}

impl UserFriendlyError for AuthnError {
    fn user_message(&self) -> String {
        match self {
            AuthnError::Authentication { error, .. } => match error {
                AuthenticationError::InvalidCredentials => {
                    "The username or password you entered is incorrect. Please check your credentials and try again.".to_string()
                }
            },
        }
    }

    fn developer_message(&self) -> String {
        match self {
            AuthnError::Authentication { error, context } => {
                let context_info = context
                    .as_ref()
                    .map(|c| format!(" Context: {}", c))
                    .unwrap_or_default();
                format!("Authentication failure: {}.{}", error, context_info)
            }
        }
    }

    fn support_code(&self) -> String {
        self.support_code_inner()
    }

    fn severity(&self) -> ErrorSeverity {
        match self {
            AuthnError::Authentication { error, .. } => match error {
                AuthenticationError::InvalidCredentials => ErrorSeverity::Warning,
            },
        }
    }

    fn suggested_actions(&self) -> Vec<String> {
        match self {
            AuthnError::Authentication { error, .. } => match error {
                AuthenticationError::InvalidCredentials => vec![
                    "Double-check your username and password for typos".to_string(),
                    "Ensure Caps Lock is not accidentally enabled".to_string(),
                    "Use the 'Forgot Password' link if you can't remember your password"
                        .to_string(),
                    "Contact support if you're sure your credentials are correct".to_string(),
                ],
            },
        }
    }

    fn is_retryable(&self) -> bool {
        match self {
            AuthnError::Authentication { error, .. } => match error {
                AuthenticationError::InvalidCredentials => true,
            },
        }
    }
}