garrison 0.9.0

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

//! 暴力破解防护策略:`BruteForceStrategy` 实现 `GarrisonFirewallStrategy`,用 limiteron `BanStorage`(封禁记录)+
//! `DistributedLimiter`(原子计数 `incr_with_ttl`,消除 TOCTOU 竞争窗口)实现。
//!
//! 检查顺序:已封禁(`is_banned`)直接拦截;否则递增计数,`count > max_attempts` 时经 `BanStorage::save` 记录封禁并返回 `FirewallBlocked`。
//! count key 保持 `bf:{ip}:count` 格式;封禁记录经 `BanStorage` trait 统一抽象(is_banned/save/remove_ban)。

use crate::constants::DaoKeyPrefix;
use crate::dao::GarrisonDao;
use crate::error::{GarrisonError, GarrisonResult};
use crate::limiteron::{GarrisonDaoBanStorage, GarrisonDaoDistributedLimiter};
use crate::strategy::firewall::{FirewallContext, GarrisonFirewallStrategy};
use async_trait::async_trait;
use chrono::Utc;
use limiteron::limiters::DistributedLimiter;
use limiteron::storage::{BanRecord, BanStorage, BanTarget};
use std::sync::Arc;
use std::time::Duration;

/// 暴力破解防护配置:所有阈值显式配置(确定性逻辑),不交给模型判断。
#[derive(Debug, Clone)]
pub struct BruteForceConfig {
    /// 最大尝试次数(超阈值后拦截)。
    pub max_attempts: u32,
    /// 计数窗口(秒),过期后计数重置。
    pub window_seconds: u64,
    /// 锁定时长(秒),触发拦截后该 IP 持续被拦截。
    pub lock_seconds: u64,
}

impl Default for BruteForceConfig {
    fn default() -> Self {
        Self {
            max_attempts: 5,
            window_seconds: 60,
            lock_seconds: 300,
        }
    }
}

impl BruteForceConfig {
    /// 校验配置合法性(对齐 `AnomalousAnalyzerConfig::validate`):三字段任一为 0 返回 `InvalidParam`——
    /// max_attempts=0 首个请求即被封禁、window_seconds=0 计数 key 立即过期、lock_seconds=0 封禁形同虚设。
    pub fn validate(&self) -> GarrisonResult<()> {
        if self.max_attempts == 0 {
            return Err(GarrisonError::InvalidParam(
                "firewall-bruteforce-max-attempts-zero::".to_string(),
            ));
        }
        if self.window_seconds == 0 {
            return Err(GarrisonError::InvalidParam(
                "firewall-bruteforce-window-seconds-zero::".to_string(),
            ));
        }
        if self.lock_seconds == 0 {
            return Err(GarrisonError::InvalidParam(
                "firewall-bruteforce-lock-seconds-zero::".to_string(),
            ));
        }
        Ok(())
    }
}

/// 暴力破解防护策略,用 limiteron BanStorage + DistributedLimiter 实现。
///
/// # 构造
///
/// ```ignore
/// use std::sync::Arc;
/// use garrison::dao::GarrisonDao;
/// use garrison::strategy::firewall::brute_force::{BruteForceConfig, BruteForceStrategy};
///
/// let dao: Arc<dyn GarrisonDao> = /* oxcache 实现 */;
/// let strategy = BruteForceStrategy::new(BruteForceConfig::default(), dao);
/// ```
pub struct BruteForceStrategy {
    /// 配置(阈值 + 窗口 + 锁定时长)。
    config: BruteForceConfig,
    /// 封禁存储(limiteron BanStorage 适配器)。
    ban_storage: Arc<dyn BanStorage>,
    /// 分布式限流器(limiteron DistributedLimiter 适配器,原子计数)。
    limiter: Arc<dyn DistributedLimiter>,
}

impl BruteForceStrategy {
    /// 创建暴力破解防护策略实例:内部创建 [`GarrisonDaoBanStorage`] + [`GarrisonDaoDistributedLimiter`] 适配器,将 `dao` 桥接到 limiteron trait。
    pub fn new(config: BruteForceConfig, dao: Arc<dyn GarrisonDao>) -> Self {
        // 配置校验:new 签名不返回 Result(不破坏调用方),debug 构建下断言非法配置,release 下由 check/record_failure 的运行时守卫兜底(见 ensure_valid_config)
        debug_assert!(
            config.validate().is_ok(),
            "invalid BruteForceConfig: {:?} (0 值阈值会导致全拦截/计数失效)",
            config
        );
        let ban_storage = Arc::new(GarrisonDaoBanStorage::new(dao.clone()));
        let limiter = Arc::new(GarrisonDaoDistributedLimiter::new(dao));
        Self {
            config,
            ban_storage,
            limiter,
        }
    }

    /// 运行时配置守卫(debug_assert 的 release 兜底):0 值阈值显性返回 InvalidParam。
    fn ensure_valid_config(&self) -> GarrisonResult<()> {
        self.config.validate()
    }

    /// 检查目标 IP 是否已被封禁(只读,不计数;封禁期内返回 `Ok(true)`)。
    ///
    /// 用于认证路径在校验**前**短路:已封禁的 IP 直接拒绝,避免继续消耗校验资源;与 [`check`](GarrisonFirewallStrategy::check) 不同,
    /// 本方法**不递增计数**,适合"仅在失败时计数"的场景(如 API Key 校验,成功请求不应计入失败限速)。
    pub async fn is_blocked(&self, ctx: &FirewallContext) -> GarrisonResult<bool> {
        let target = BanTarget::Ip(ctx.ip.clone());
        Ok(self
            .ban_storage
            .is_banned(&target)
            .await
            .map_err(|e| GarrisonError::Dao(format!("strategy-ban-is-banned::{}", e)))?
            .is_some())
    }

    /// 记录一次认证失败:原子递增计数,超阈值则封禁该 IP `lock_seconds` 秒(CWE-307)。
    ///
    /// 用于认证路径在校验**失败**时调用(成功路径不调用,实现"仅失败计数");计数窗口过期后自动重置。
    pub async fn record_failure(&self, ctx: &FirewallContext) -> GarrisonResult<()> {
        self.ensure_valid_config()?;
        let target = BanTarget::Ip(ctx.ip.clone());
        let count_key = format!("{}{}:count", DaoKeyPrefix::BruteForce, ctx.ip);
        let new_count = self
            .limiter
            .incr_with_ttl(
                &count_key,
                1,
                Duration::from_secs(self.config.window_seconds),
            )
            .await
            .map_err(|e| GarrisonError::Dao(format!("strategy-incr-ttl::{}", e)))?;
        if new_count > self.config.max_attempts as u64 {
            let record = BanRecord {
                target: target.clone(),
                ban_times: 1,
                duration: Duration::from_secs(self.config.lock_seconds),
                banned_at: Utc::now(),
                expires_at: Utc::now() + chrono::Duration::seconds(self.config.lock_seconds as i64),
                is_manual: false,
                reason: format!(
                    "strategy-firewall-bruteforce-reason::{}::{}",
                    new_count, self.config.max_attempts
                ),
            };
            self.ban_storage
                .save(&record)
                .await
                .map_err(|e| GarrisonError::Dao(format!("strategy-ban-save::{}", e)))?;
        }
        Ok(())
    }
}

#[async_trait]
impl GarrisonFirewallStrategy for BruteForceStrategy {
    async fn check(&self, ctx: &FirewallContext) -> GarrisonResult<()> {
        self.ensure_valid_config()?;
        let target = BanTarget::Ip(ctx.ip.clone());
        let count_key = format!("{}{}:count", DaoKeyPrefix::BruteForce, ctx.ip);

        // 已封禁则拦截(BanStorage 统一封禁管理)
        if self
            .ban_storage
            .is_banned(&target)
            .await
            .map_err(|e| GarrisonError::Dao(format!("strategy-ban-is-banned::{}", e)))?
            .is_some()
        {
            return Err(GarrisonError::FirewallBlocked(format!(
                "strategy-firewall-bruteforce-locked::{}",
                ctx.ip
            )));
        }

        // 原子递增计数(DistributedLimiter.incr_with_ttl 消除 TOCTOU)
        let new_count = self
            .limiter
            .incr_with_ttl(
                &count_key,
                1,
                Duration::from_secs(self.config.window_seconds),
            )
            .await
            .map_err(|e| GarrisonError::Dao(format!("strategy-incr-ttl::{}", e)))?;

        if new_count > self.config.max_attempts as u64 {
            // 超阈值:封禁 IP(BanStorage.save)
            let record = BanRecord {
                target: target.clone(),
                ban_times: 1,
                duration: Duration::from_secs(self.config.lock_seconds),
                banned_at: Utc::now(),
                expires_at: Utc::now() + chrono::Duration::seconds(self.config.lock_seconds as i64),
                is_manual: false,
                reason: format!(
                    "strategy-firewall-bruteforce-reason::{}::{}",
                    new_count, self.config.max_attempts
                ),
            };
            self.ban_storage
                .save(&record)
                .await
                .map_err(|e| GarrisonError::Dao(format!("strategy-ban-save::{}", e)))?;
            Err(GarrisonError::FirewallBlocked(format!(
                "strategy-firewall-bruteforce-blocked::{}::{}::{}",
                ctx.ip, new_count, self.config.max_attempts
            )))
        } else {
            Ok(())
        }
    }
}

inventory::submit! {
    crate::strategy::firewall::StrategyRegistration {
        name: "bruteforce",
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::dao::tests::MockDao;
    use crate::error::GarrisonError;

    /// 验证暴力破解防护:max_attempts=5 时,连续 5 次通过,第 6 次被拦截。
    #[tokio::test]
    async fn bruteforce_blocks_after_max_attempts() {
        let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
        let config = BruteForceConfig {
            max_attempts: 5,
            window_seconds: 60,
            lock_seconds: 300,
        };
        let strategy = BruteForceStrategy::new(config, dao);
        let ctx = FirewallContext::new("192.168.1.1");

        for i in 1..=5 {
            assert!(strategy.check(&ctx).await.is_ok(), "第 {} 次应通过", i);
        }

        let result = strategy.check(&ctx).await;
        assert!(
            matches!(result, Err(GarrisonError::FirewallBlocked(_))),
            "第 6 次应返回 FirewallBlocked,实际: {:?}",
            result
        );
    }

    /// 验证锁定后的 IP 被持续拦截(BanStorage.save 后所有请求均被 `is_banned` 拦截)。
    #[tokio::test]
    async fn bruteforce_lock_persists_after_trigger() {
        let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
        let config = BruteForceConfig {
            max_attempts: 3,
            window_seconds: 60,
            lock_seconds: 300,
        };
        let strategy = BruteForceStrategy::new(config, dao);
        let ctx = FirewallContext::new("10.0.0.1");

        // 触发锁定(第 4 次超阈值)
        for _ in 0..4 {
            let _ = strategy.check(&ctx).await;
        }

        // 后续 5 次请求全部被拦截(BanStorage is_banned 生效)
        for i in 1..=5 {
            let result = strategy.check(&ctx).await;
            assert!(
                matches!(result, Err(GarrisonError::FirewallBlocked(_))),
                "锁定后第 {} 次请求应被拦截",
                i
            );
        }
    }

    /// 验证不同 IP 的计数互不干扰(key 隔离正确性)。
    #[tokio::test]
    async fn bruteforce_counts_isolated_per_ip() {
        let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
        let config = BruteForceConfig {
            max_attempts: 3,
            window_seconds: 60,
            lock_seconds: 300,
        };
        let strategy = BruteForceStrategy::new(config, dao);

        let ctx_a = FirewallContext::new("192.168.1.100");
        for _ in 0..4 {
            let _ = strategy.check(&ctx_a).await;
        }

        // IP-B 应不受影响
        let ctx_b = FirewallContext::new("192.168.1.200");
        assert!(
            strategy.check(&ctx_b).await.is_ok(),
            "不同 IP 的计数不应互相影响"
        );
    }

    /// is_blocked 不计数——重复调用不会触发封禁(区别于 check)。
    #[tokio::test]
    async fn is_blocked_does_not_count() {
        let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
        let config = BruteForceConfig {
            max_attempts: 3,
            window_seconds: 60,
            lock_seconds: 300,
        };
        let strategy = BruteForceStrategy::new(config, dao);
        let ctx = FirewallContext::new("10.1.1.1");

        // 大量 is_blocked 调用都应返回 false(不计数、不封禁)
        for _ in 0..10 {
            assert!(
                !strategy.is_blocked(&ctx).await.unwrap(),
                "未失败前不应封禁"
            );
        }
    }

    /// record_failure 达阈值后 is_blocked 返回 true(仅失败计数模型)。
    #[tokio::test]
    async fn record_failure_bans_after_threshold_then_is_blocked() {
        let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
        let config = BruteForceConfig {
            max_attempts: 3,
            window_seconds: 60,
            lock_seconds: 300,
        };
        let strategy = BruteForceStrategy::new(config, dao);
        let ctx = FirewallContext::new("10.2.2.2");

        // 前 3 次失败:未超阈值,尚未封禁
        for _ in 0..3 {
            strategy.record_failure(&ctx).await.unwrap();
            assert!(!strategy.is_blocked(&ctx).await.unwrap());
        }
        // 第 4 次失败:超阈值 → 封禁
        strategy.record_failure(&ctx).await.unwrap();
        assert!(
            strategy.is_blocked(&ctx).await.unwrap(),
            "超过 max_attempts 次失败后应被封禁"
        );
    }
}