axum_gate/
verification_result.rs

1//! Verification value objects for domain operations.
2//!
3//! This module contains value objects that represent the results
4//! of verification operations in the domain layer.
5
6/// Result of a secret / credential verification operation.
7///
8/// This enum is used throughout the authentication pipeline (hash verification,
9/// credential repository checks, login services) to distinguish a successful
10/// verification from an unauthorized outcome **without** revealing *why* it failed
11/// (e.g. wrong password vs. unknown user) when higher layers deliberately collapse
12/// those states to resist user enumeration.
13///
14/// # Semantics
15/// - [`VerificationResult::Ok`] — Supplied value matched the stored/expected secret.
16/// - [`VerificationResult::Unauthorized`] — Value did **not** match, or the subject/identity
17///   was intentionally treated as non-existent/mismatched for security uniformity.
18///
19/// # Conversions
20/// - `VerificationResult::from(bool)` maps `true -> Ok`, `false -> Unauthorized`.
21/// - `bool::from(VerificationResult)` returns `true` for `Ok`, `false` otherwise.
22///
23/// # When to Use
24/// Prefer this over `Result<bool, E>` when:
25/// - You want an explicit success vs. unauthorized domain signal
26/// - Errors/exceptions are reserved strictly for infrastructural failures
27///
28/// # Side‑Channel Guidance
29/// Combine it with constant‑time hash verification and unified handling
30/// to avoid exposing whether an identifier exists.
31///
32/// # Example
33/// ```
34/// use axum_gate::verification_result::VerificationResult;
35///
36/// fn check(match_flag: bool) -> VerificationResult {
37///     VerificationResult::from(match_flag)
38/// }
39///
40/// assert_eq!(check(true), VerificationResult::Ok);
41/// assert_eq!(check(false), VerificationResult::Unauthorized);
42/// ```
43#[derive(Eq, PartialEq, Debug, Clone, Copy)]
44pub enum VerificationResult {
45    /// The verification succeeded (value matched).
46    Ok,
47    /// The supplied value failed verification (non-match / unauthorized).
48    Unauthorized,
49}
50
51impl From<bool> for VerificationResult {
52    fn from(value: bool) -> Self {
53        if value { Self::Ok } else { Self::Unauthorized }
54    }
55}
56
57impl From<VerificationResult> for bool {
58    fn from(result: VerificationResult) -> Self {
59        matches!(result, VerificationResult::Ok)
60    }
61}
62
63#[cfg(test)]
64mod tests {
65    use super::*;
66
67    #[test]
68    fn from_bool_conversion() {
69        assert_eq!(VerificationResult::Ok, VerificationResult::from(true));
70        assert_eq!(
71            VerificationResult::Unauthorized,
72            VerificationResult::from(false)
73        );
74    }
75
76    #[test]
77    fn verification_result_properties() {
78        let ok_result = VerificationResult::Ok;
79        let unauthorized_result = VerificationResult::Unauthorized;
80
81        // Test equality
82        assert_eq!(ok_result, VerificationResult::Ok);
83        assert_eq!(unauthorized_result, VerificationResult::Unauthorized);
84        assert_ne!(ok_result, unauthorized_result);
85    }
86}
axum_gate/verification_result.rs

axum_gate/
verification_result.rs
