axum_gate/hashing/
hashing_service.rs

1use super::HashedValue;
2use crate::errors::Result;
3use crate::verification_result::VerificationResult;
4
5/// Abstraction over password / secret hashing and verification.
6///
7/// Implement this trait to plug in alternative hashing algorithms or services
8/// (e.g. Argon2 variants, bcrypt, scrypt, external KMS / HSM, remote API).
9///
10/// # Requirements
11/// Implementations SHOULD:
12/// - Use a modern, memory‑hard password hashing algorithm (default provided: Argon2id)
13/// - Embed salt & parameters in the produced [`HashedValue`] when the format supports it
14/// - Return only opaque, self‑contained hash strings (safe to store directly)
15///
16/// # Error Semantics
17/// - Return `Ok(HashedValue)` / `Ok(VerificationResult)` for normal outcomes
18/// - Return `Err(..)` only for exceptional failures (misconfiguration, resource exhaustion,
19///   serialization/encoding failure, upstream service error, etc.)
20///
21/// # Enumeration & Timing
22/// This trait itself does not enforce constant‑time behavior; callers such as
23/// the login flow will layer enumeration resistance. However, implementations
24/// SHOULD avoid obviously data‑dependent early exits where practical.
25///
26/// See [`Argon2Hasher`](crate::hashing::argon2::Argon2Hasher) for a production‑ready implementation.
27pub trait HashingService {
28    /// Hash a plaintext secret into an opaque, self‑contained representation.
29    ///
30    /// Expectations:
31    /// - MUST NOT return the plaintext
32    /// - SHOULD generate a cryptographically secure random salt per invocation
33    /// - SHOULD embed algorithm parameters allowing future verification / upgrades
34    fn hash_value(&self, plain_value: &str) -> Result<HashedValue>;
35    /// Verify a plaintext input against a previously produced hash.
36    ///
37    /// Returns:
38    /// - `Ok(VerificationResult::Ok)` if the value matches
39    /// - `Ok(VerificationResult::Unauthorized)` if it does not match
40    /// - `Err(..)` only if verification could not be performed (e.g. malformed hash)
41    fn verify_value(&self, plain_value: &str, hashed_value: &str) -> Result<VerificationResult>;
42}
axum_gate/hashing/hashing_service.rs

axum_gate/hashing/
hashing_service.rs
