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
//! Password hashing and verification services.
//!
//! This module provides secure password hashing functionality using industry-standard
//! algorithms. The primary implementation uses Argon2, which is recommended by security
//! experts for password hashing due to its resistance to both brute-force and side-channel
//! attacks.
//!
//! # Key Components
//!
//! - [`HashingService`] - Service for hashing and verifying passwords
//! - [`HashedValue`] - Represents a hashed password with algorithm metadata
//! - [`argon2`] - Argon2 algorithm implementation with secure defaults
//!
//! # Quick Start
//!
//! ```rust
//! use axum_gate::hashing::{HashingService, argon2::Argon2Hasher};
//! use axum_gate::verification_result::VerificationResult;
//!
//! let hasher = Argon2Hasher::new_recommended().unwrap();
//!
//! // Hash a password
//! let hashed = hasher.hash_value("user_password").unwrap();
//! println!("Hashed password: {}", hashed);
//!
//! // Verify a password
//! let result = hasher.verify_value("user_password", &hashed).unwrap();
//! assert_eq!(result, VerificationResult::Ok);
//! ```
//!
//! # Security Features
//!
//! - **Argon2id algorithm** - Recommended by password hashing competition
//! - **Configurable parameters** - Memory cost, time cost, and parallelism
//! - **Built-in salt generation** - Each password gets a unique random salt
//! - **Constant-time verification** - Prevents timing attacks
//! - **Development vs production profiles** - Fast hashing in debug builds, secure in release
//!
//! # Performance Considerations
//!
//! The hashing service automatically adjusts parameters based on build configuration:
//! - **Debug builds**: Fast parameters for development efficiency
//! - **Release builds**: Secure parameters for production security
//! - **Custom parameters**: Override via `Argon2Hasher::with_params()`
pub use HashingService;
pub use ;
/// A hashed value produced by password hashing algorithms.
///
/// This type represents the output of cryptographic password hashing functions,
/// typically containing the algorithm identifier, parameters, salt, and hash in
/// a standardized format.
///
/// ## Format
///
/// For Argon2id hashes, the format follows the PHC (Password Hashing Competition) standard:
/// ```text
/// $argon2id$v=19$m=65536,t=3,p=1$<salt>$<hash>
/// ```
///
/// Where:
/// - `argon2id` - Algorithm identifier
/// - `v=19` - Algorithm version
/// - `m=65536,t=3,p=1` - Memory cost, time cost, parallelism parameters
/// - `<salt>` - Base64-encoded random salt
/// - `<hash>` - Base64-encoded password hash
///
/// ## Security Properties
///
/// - **Self-contained**: Includes all information needed for verification
/// - **Salt included**: Each hash has a unique random salt to prevent rainbow table attacks
/// - **Parameter embedded**: Hash contains the parameters used, enabling verification
/// - **Future-proof**: Format supports algorithm upgrades and parameter changes
///
/// ## Usage
///
/// ```rust
/// use axum_gate::hashing::{argon2::Argon2Hasher, HashingService, HashedValue};
///
/// let hasher = Argon2Hasher::new_recommended().unwrap();
/// let hashed: HashedValue = hasher.hash_value("my_password").unwrap();
///
/// // The hashed value is self-contained and can be stored directly
/// println!("Hashed password: {}", hashed);
///
/// // Later, verify against the stored hash
/// use axum_gate::verification_result::VerificationResult;
/// let result = hasher.verify_value("my_password", &hashed).unwrap();
/// assert_eq!(result, VerificationResult::Ok);
/// ```
///
/// ## Storage Considerations
///
/// - **Database storage**: Store as TEXT/VARCHAR with sufficient length (≥100 characters recommended)
/// - **No additional encoding needed**: The string is already in a safe, printable format
/// - **Indexing**: Generally should not be indexed as hashes are not used for lookups
/// - **Migration**: Hash format changes require re-hashing passwords during user login
pub type HashedValue = String;