Skip to main content

yang_base/action/auth/
password.rs

1//! 密码哈希与校验的受控执行边界。
2//!
3//! Argon2 是刻意的内存困难算法,直接运行在异步运行时上会阻塞工作线程;
4//! [`PasswordEngine`] 把所有哈希/校验运算收敛到 `spawn_blocking`,并用信号量限制
5//! 全局并发上限,避免认证洪泛耗尽阻塞线程池。并发上限等参数由构造函数注入,
6//! 不读取任何应用配置。
7
8use argon2::password_hash::{Error as PasswordHashError, PasswordHash, SaltString};
9use argon2::{Argon2, PasswordHasher, PasswordVerifier};
10use rand_core::OsRng;
11use std::sync::Arc;
12use tokio::sync::Semaphore;
13use yang_base::BaseError;
14
15/// 密码哈希执行器:Argon2 运算 + 受控并发上限。
16#[derive(Clone)]
17pub struct PasswordEngine {
18    permits: Arc<Semaphore>,
19}
20
21impl PasswordEngine {
22    /// 创建执行器;`max_concurrency` 为同时进行的 Argon2 运算上限,必须大于 0。
23    pub fn new(max_concurrency: usize) -> Result<Self, BaseError> {
24        if max_concurrency == 0 {
25            return Err(BaseError::ConfigError(
26                "argon2_max_concurrency 必须大于 0".to_string(),
27            ));
28        }
29        Ok(Self {
30            permits: Arc::new(Semaphore::new(max_concurrency)),
31        })
32    }
33
34    /// 计算密码的 Argon2 哈希(PHC 字符串格式)。
35    pub async fn hash(&self, password: &str) -> Result<String, BaseError> {
36        let password = password.to_owned();
37        self.run_blocking(move || {
38            let salt = SaltString::generate(&mut OsRng);
39            Argon2::default()
40                .hash_password(password.as_bytes(), &salt)
41                .map(|value| value.to_string())
42                .map_err(|_| BaseError::Unknown("密码哈希失败".to_string()))
43        })
44        .await
45    }
46
47    /// 校验密码明文与已存储的 PHC 哈希是否匹配。
48    pub async fn verify(&self, password: &str, encoded: &str) -> Result<bool, BaseError> {
49        let password = password.to_owned();
50        let encoded = encoded.to_owned();
51        self.run_blocking(move || {
52            let parsed = PasswordHash::new(&encoded)
53                .map_err(|_| BaseError::Unknown("数据库中的密码哈希格式无效".to_string()))?;
54            match Argon2::default().verify_password(password.as_bytes(), &parsed) {
55                Ok(()) => Ok(true),
56                Err(PasswordHashError::Password) => Ok(false),
57                Err(_) => Err(BaseError::Unknown("密码校验失败".to_string())),
58            }
59        })
60        .await
61    }
62
63    async fn run_blocking<T>(
64        &self,
65        operation: impl FnOnce() -> Result<T, BaseError> + Send + 'static,
66    ) -> Result<T, BaseError>
67    where
68        T: Send + 'static,
69    {
70        let permit = Arc::clone(&self.permits)
71            .acquire_owned()
72            .await
73            .map_err(|_| BaseError::Unknown("密码执行器已关闭".to_string()))?;
74        tokio::task::spawn_blocking(move || {
75            let _permit = permit;
76            operation()
77        })
78        .await
79        .map_err(|error| BaseError::Unknown(format!("密码任务执行失败: {error}")))?
80    }
81}
82
83#[cfg(test)]
84mod tests {
85    use super::*;
86
87    #[tokio::test]
88    async fn password_hash_round_trip() {
89        let engine =
90            PasswordEngine::new(1).unwrap_or_else(|error| panic!("密码执行器应构建成功: {error}"));
91        let encoded = engine
92            .hash("correct-horse-battery-staple")
93            .await
94            .unwrap_or_else(|error| panic!("密码应成功哈希: {error}"));
95
96        assert!(engine
97            .verify("correct-horse-battery-staple", &encoded)
98            .await
99            .unwrap_or_else(|error| panic!("密码应成功校验: {error}")));
100        assert!(!engine
101            .verify("wrong-password", &encoded)
102            .await
103            .unwrap_or_else(|error| panic!("错误密码应得到 false: {error}")));
104        assert!(!encoded.contains("correct-horse-battery-staple"));
105    }
106
107    #[test]
108    fn zero_concurrency_is_rejected() {
109        assert!(matches!(
110            PasswordEngine::new(0),
111            Err(BaseError::ConfigError(message)) if message.contains("argon2_max_concurrency")
112        ));
113    }
114}