garrison 0.9.0

Garrison - 面向 Rust 生态的一站式身份认证鉴权框架
Documentation
// Copyright (c) 2026 Kirky.X🌠
// SPDX-License-Identifier: Apache-2.0

//! SmsVerificationService 实现:发送/验证/异常检测三层抽象。

use super::rate_limiter::validate_phone;
use super::{GarrisonDao, GarrisonResult, SmsRateLimiter, SmsSender, SmsVerificationService};
use crate::error::GarrisonError;
use crate::secure::ct_eq::constant_time_eq;
use std::sync::Arc;

/// 错误码:`verify_code` 验证码不匹配时返回 `InvalidParam(ERR_SMS_CODE_WRONG)`(带 `::` 后缀);
/// 消费方用此常量做 `starts_with` 匹配,避免硬编码字符串契约。
pub const ERR_SMS_CODE_WRONG: &str = "secure-sms-code-wrong";

impl SmsVerificationService {
    /// 创建验证码服务实例。
    pub fn new(
        rate_limiter: SmsRateLimiter,
        sender: Arc<dyn SmsSender>,
        dao: Arc<dyn GarrisonDao>,
        max_verify_attempts: u32,
        unverified_threshold: u32,
    ) -> Self {
        Self {
            rate_limiter,
            sender,
            dao,
            max_verify_attempts,
            unverified_threshold,
        }
    }

    /// 发送验证码。
    pub async fn send_code(&self, phone: &str) -> GarrisonResult<()> {
        validate_phone(phone)?;

        let recycled_key = format!("sms:recycled:{}", phone);
        if self.dao.get(&recycled_key).await?.is_some() {
            return Err(GarrisonError::SmsChannelRecycled);
        }

        // 限速检查(携带窗口桶快照,供失败路径回滚)
        let windows = self.rate_limiter.check_and_increment_with(phone).await?;

        let code = generate_code()?;

        let code_key = format!("sms:code:{}", phone);
        if let Err(e) = self.dao.set(&code_key, &code, 300).await {
            // 存储失败:best-effort 回滚限速(清理失败仅告警),保留原始存储错误
            if let Err(re) = self.rate_limiter.rollback_with(phone, &windows).await {
                tracing::error!(
                    error = %re,
                    phone = %mask_phone(phone),
                    "rollback rate limiter counter failed after code store failure"
                );
            }
            return Err(e);
        }

        // 未验证计数(TTL 24h);递增失败须回滚验证码与限速计数(best-effort),否则残留无发送记录的验证码与膨胀计数
        let unverified_key = format!("sms:unverified:{}", phone);
        let unverified_count = match self.dao.incr(&unverified_key, 86400).await {
            Ok(count) => count,
            Err(e) => {
                if let Err(re) = self.rate_limiter.rollback_with(phone, &windows).await {
                    tracing::error!(
                        error = %re,
                        phone = %mask_phone(phone),
                        "rollback rate limiter counter failed after unverified incr failure"
                    );
                }
                if let Err(re) = self.dao.delete(&code_key).await {
                    tracing::error!(
                        error = %re,
                        key = %code_key,
                        "delete stored code failed after unverified incr failure"
                    );
                }
                return Err(e);
            },
        };

        if unverified_count > self.unverified_threshold as u64 {
            if let Err(e) = self.rate_limiter.rollback_with(phone, &windows).await {
                // 以 error 触发运维告警
                tracing::error!(
                    error = %e,
                    phone = %mask_phone(phone),
                    "rollback rate limiter counter failed during channel recycling"
                );
            }
            if let Err(e) = SmsRateLimiter::decrement_counter(&*self.dao, &unverified_key).await {
                // 以 error 触发运维告警
                tracing::error!(
                    error = %e,
                    key = %mask_phone_in_key(&unverified_key),
                    "rollback unverified counter failed"
                );
            }
            self.dao.set(&recycled_key, "1", 86400).await?;
            return Err(GarrisonError::SmsChannelRecycled);
        }

        if let Err(e) = self.sender.send(phone, &code).await {
            // 发送失败:聚合清理(限速回滚 + 删码 + 递减未验证计数),单项失败仅告警不中断剩余清理,保留原始发送错误;
            // 删码必须尽力——否则验证码在 TTL 内仍有效,攻击者可用其完成验证。
            if let Err(re) = self.rate_limiter.rollback_with(phone, &windows).await {
                tracing::error!(
                    error = %re,
                    phone = %mask_phone(phone),
                    "rollback rate limiter counter failed after send failure"
                );
            }
            if let Err(re) = self.dao.delete(&code_key).await {
                tracing::error!(
                    error = %re,
                    key = %code_key,
                    "delete code failed after send failure"
                );
            }
            if let Err(re) = SmsRateLimiter::decrement_counter(&*self.dao, &unverified_key).await {
                // 以 error 触发运维告警
                tracing::error!(
                    error = %re,
                    key = %mask_phone_in_key(&unverified_key),
                    "rollback unverified counter failed after send failure"
                );
            }
            return Err(e);
        }

        Ok(())
    }

    /// 验证验证码。
    pub async fn verify_code(&self, phone: &str, code: &str) -> GarrisonResult<()> {
        validate_phone(phone)?;

        let code_key = format!("sms:code:{}", phone);
        let stored = self.dao.get(&code_key).await?;
        let stored = stored.ok_or(GarrisonError::SmsCodeNotFound)?;

        // 比对走 ADR-0003 常量时间原语(sms-rate-limit 依赖 secure-ct-eq);验证码定长 6 位,长度不符必然不等,
        // 提前短路(用户可控长度不得进入比较循环,长度公开、提前拒绝不泄露秘密);不等时走失败分支计入尝试次数。
        let matched = code.len() == 6 && constant_time_eq(stored.as_bytes(), code.as_bytes());
        if matched {
            // 验证成功:聚合删除 code / unverified / attempts(首个失败不中断),返回首个错误——
            // code 已删后其余 delete 失败不应让调用方误以为验证码仍有效。
            let mut first_err: Option<GarrisonError> = None;
            if let Err(e) = self.dao.delete(&code_key).await {
                first_err.get_or_insert(e);
            }
            let unverified_key = format!("sms:unverified:{}", phone);
            if let Err(e) = self.dao.delete(&unverified_key).await {
                first_err.get_or_insert(e);
            }
            let attempts_key = format!("sms:attempts:{}", phone);
            if let Err(e) = self.dao.delete(&attempts_key).await {
                first_err.get_or_insert(e);
            }
            match first_err {
                Some(e) => Err(e),
                None => Ok(()),
            }
        } else {
            let attempts_key = format!("sms:attempts:{}", phone);
            let attempts = self.dao.incr(&attempts_key, 300).await?;
            if attempts > self.max_verify_attempts as u64 {
                self.dao.delete(&code_key).await?;
                self.dao.delete(&attempts_key).await?;
                Err(GarrisonError::SmsVerifyMaxAttempts)
            } else {
                Err(GarrisonError::InvalidParam(format!(
                    "{ERR_SMS_CODE_WRONG}::"
                )))
            }
        }
    }
}

/// 生成 6 位随机数字验证码:范围 `100000..1000000` 保证首位非零且永不生成 `000000`(弱码易爆破)。
pub(super) fn generate_code() -> GarrisonResult<String> {
    use rand::RngExt;
    let code: u32 = rand::rng().random_range(100000..1000000);
    Ok(format!("{:06}", code))
}

/// 手机号脱敏(日志 PII 防护):保留前 3 后 4,长度 < 7 时整体以 `*` 屏蔽(长度与输入一致)。
pub(super) fn mask_phone(phone: &str) -> String {
    let chars: Vec<char> = phone.chars().collect();
    if chars.len() < 7 {
        return "*".repeat(chars.len());
    }
    let prefix: String = chars[..3].iter().collect();
    let suffix: String = chars[chars.len() - 4..].iter().collect();
    let stars = "*".repeat(chars.len() - 7);
    format!("{prefix}{stars}{suffix}")
}

/// 对含手机号的 key 字符串脱敏(`sms:unverified:{phone}` → `sms:unverified:138****8000`)。
pub(super) fn mask_phone_in_key(key: &str) -> String {
    // 取最后一个 `:` 之前为 key 前缀(如 "sms:unverified"),末段视为 phone 主体
    match key.rsplit_once(':') {
        Some((prefix, phone)) => format!("{}:{}", prefix, mask_phone(phone)),
        None => mask_phone(key),
    }
}