authen 0.1.0

A robust, modular, high-level, and secure authentication crate for Rust.
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

//! Password management trait for secure password hashing and verification.
//!
//! This module defines the [`SecurePasswordManager`] trait, which provides an abstraction
//! for securely hashing and verifying passwords. Implementations of this trait are responsible
//! for using cryptographically secure algorithms to protect user credentials.
//!
//! # Example
//!
//! ```rust,ignore
//! use your_crate::core::password::manager::SecurePasswordManager;
//!
//! struct MyPasswordManager;
//!
//! #[async_trait::async_trait]
//! impl SecurePasswordManager for MyPasswordManager {
//!     async fn hash_password(&self, password: &str) -> Result<String, AuthError> {
//!         // Implementation here
//!         Ok("hashed".to_string())
//!     }
//!
//!     async fn verify_password(&self, password: &str, hashed_password: &str) -> Result<bool, AuthError> {
//!         // Implementation here
//!         Ok(true)
//!     }
//! }
//! ```

use crate::error::AuthError;

#[async_trait::async_trait]
/// Trait for secure password management, including hashing and verification.
///
/// Implement this trait to provide password hashing and verification using a secure algorithm
/// (e.g., Argon2, bcrypt, scrypt). The trait is asynchronous to support non-blocking operations
/// in environments where password hashing may be computationally expensive.
#[async_trait::async_trait]
pub trait SecurePasswordManager {
    /// Hashes a plaintext password using a secure algorithm.
    ///
    /// # Arguments
    ///
    /// * `password` - The plaintext password to hash.
    ///
    /// # Returns
    ///
    /// * `Ok(String)` containing the hashed password if successful.
    /// * `Err(AuthError)` if hashing fails.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// let hashed = manager.hash_password("my_password").await?;
    /// ```
    async fn hash_password(&self, password: &str) -> Result<String, AuthError>;

    /// Verifies a plaintext password against a hashed password.
    ///
    /// # Arguments
    ///
    /// * `password` - The plaintext password to verify.
    /// * `hashed_password` - The hashed password to compare against.
    ///
    /// # Returns
    ///
    /// * `Ok(true)` if the password matches the hash.
    /// * `Ok(false)` if the password does not match.
    /// * `Err(AuthError)` if verification fails.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// let is_valid = manager.verify_password("my_password", &hashed).await?;
    /// ```
    async fn verify_password(
        &self,
        password: &str,
        hashed_password: &str,
    ) -> Result<bool, AuthError>;
}