garrison 0.9.0

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

//! 安全模块,提供 TOTP / 签名 / Basic / Digest 验证。
//!
//! 该模块在启用任一 `secure-*` 特性时编译(见 `lib.rs` 的 `#[cfg(any(...))]`)。

use crate::error::{GarrisonError, GarrisonResult};

/// TOTP 验证器 trait,定义动态验证码校验抽象(`totp-rs` crate 实现基于时间的一次性密码)。
///
/// # ⚠️ 与 `TotpHandler` 的关系(务必阅读)
///
/// **`totp::TotpHandler` 并未实现本 trait**,本 crate 中也不存在任何 `impl TotpVerifier for ...`:
/// `TotpVerifier` 为无参自取时间的可替换抽象(`generate_totp` / `verify_totp`),
/// `TotpHandler` 为自带 now 参数的具体实现 API(`generate` / `validate`,便于测试与多时钟源)。
/// 文档中提及 `TotpHandler` 仅指能力对应关系,不代表类型实现关系。
///
/// # 默认实现的安全语义
///
/// `verify_totp` / `generate_totp` 的默认实现**返回 `Err(GarrisonError::NotImplemented)`**
/// (fail-closed:未实现时拒绝而非放行,不会 fail-open)。带默认实现允许按需实现子集,代价是
/// 无编译期强制——忘记覆盖只会在运行期报错,实现方**必须**覆盖 `verify_totp`,建议调用方装配期探针校验。
pub trait TotpVerifier {
    /// 校验 TOTP 验证码;默认返回 `Err(GarrisonError::NotImplemented)`(fail-closed,见 trait 文档)。
    fn verify_totp(&self, _code: &str) -> GarrisonResult<bool> {
        Err(GarrisonError::NotImplemented(
            "secure-verify-totp-not-implemented::".to_string(),
        ))
    }

    /// 生成当前 TOTP 验证码;默认返回 `Err(GarrisonError::NotImplemented)`(fail-closed,见 trait 文档)。
    fn generate_totp(&self) -> GarrisonResult<String> {
        Err(GarrisonError::NotImplemented(
            "secure-generate-totp-not-implemented::".to_string(),
        ))
    }
}

/// 签名验证器 trait,定义请求签名校验抽象(`sha2` / `hmac` / `base64` 实现网关签名认证)。
///
/// # ⚠️ 与 `Signer` 的关系(务必阅读)
///
/// **`SignVerifier` 与 `sign::Signer` 是两套独立抽象,本 crate 中不存在任何 `impl SignVerifier for Signer`。**
/// 本 trait 面向**文本协议**场景(data/secret 均为 `&str`,如 HTTP 网关签名);`sign::Signer`
/// 面向**字节流**场景(`&[u8]`,如二进制载荷签名)。若需用 `Signer` 实现本 trait,须自行做
/// `&str` → `&[u8]` 适配(`as_bytes()`)并确认 secret 字节编码一致;`secret: &str` 不得写入日志或错误消息。
///
/// # 默认实现的安全语义
///
/// `verify_sign` / `create_sign` 的默认实现**返回 `Err(GarrisonError::NotImplemented)`**
/// (fail-closed:未实现时拒绝而非放行);默认实现允许按需实现子集,代价是无编译期强制
/// ——忘记覆盖只会在运行期报错,实现方**必须**覆盖这两个方法,建议调用方装配期主动探针校验。
#[cfg(feature = "secure-sign")]
pub trait SignVerifier {
    /// 校验请求签名;默认返回 `Err(GarrisonError::NotImplemented)`(fail-closed,见 trait 文档)。
    fn verify_sign(&self, _data: &str, _sign: &str, _secret: &str) -> GarrisonResult<bool> {
        Err(GarrisonError::NotImplemented(
            "secure-verify-sign-not-implemented::".to_string(),
        ))
    }

    /// 生成请求签名;默认返回 `Err(GarrisonError::NotImplemented)`(fail-closed,见 trait 文档)。
    fn create_sign(&self, _data: &str, _secret: &str) -> GarrisonResult<String> {
        Err(GarrisonError::NotImplemented(
            "secure-create-sign-not-implemented::".to_string(),
        ))
    }
}

// 安全子模块(特性门控)

/// TOTP 子模块,时间一次性密码实现。
#[cfg(feature = "secure-totp")]
pub mod totp;

/// 签名子模块,请求签名校验实现。
#[cfg(feature = "secure-sign")]
pub mod sign;

/// HTTP Basic 认证子模块。
#[cfg(feature = "protocol-httpbasic")]
pub mod httpbasic;

/// HTTP Digest 认证子模块。
#[cfg(feature = "protocol-httpdigest")]
pub mod httpdigest;

/// Unicode 同形异义字检测子模块。
///
/// 提供 [`check_confusable`](confusable::check_confusable);启用 `secure-confusable` feature 后 `PermissionRegistry::register` 自动检测可疑 permission name。
#[cfg(feature = "secure-confusable")]
pub mod confusable;

/// 敏感数据脱敏子模块。
///
/// 提供 [`SensitiveDataMasker`](masking::SensitiveDataMasker) 对手机号 / 身份证 / 邮箱 / 银行卡等敏感字段脱敏,支持 `serde_json::Value` 递归脱敏。
#[cfg(feature = "secure-masking")]
pub mod masking;

/// XSS 防护子模块。
///
/// 提供 [`XssProtector`](xss::XssProtector) 对 HTML 输入转义/白名单过滤防 XSS;零外部依赖。
#[cfg(feature = "secure-xss")]
pub mod xss;

/// 泛型双窗口限速内核子模块(sms/email 验证码限速共用)。
///
/// 以 limiteron `QuotaStorage` 账本承载 hour/day 双窗口判定与补偿,sms/email 收敛为薄包装(normalize/validate + key 命名空间 + 错误变体)。
#[cfg(any(feature = "sms-rate-limit", feature = "email-verification"))]
pub(crate) mod dual_window;

/// SMS 验证码渐进式限速子模块。
///
/// 提供 [`SmsVerificationService`](sms::SmsVerificationService) 三层抽象:`SmsSender` trait(业务方实现短信发送)、`SmsRateLimiter`(双窗口限速:小时 + 天)、`SmsVerificationService`(发送/验证/异常发送检测)。
#[cfg(feature = "sms-rate-limit")]
pub mod sms;

/// 邮箱验证码子模块。
///
/// 提供 [`EmailVerificationService`](email::EmailVerificationService) 三层抽象:`EmailSender` trait(业务方实现邮件发送,`email-verification-smtp` feature 提供内置 SMTP 实现)、`EmailRateLimiter`(双窗口限速:小时 + 天,含邮箱规范化)、`EmailVerificationService`(发送/验证/异常发送检测)。
#[cfg(feature = "email-verification")]
pub mod email;

/// 通用输入消毒子模块。
///
/// `sanitize::sanitize_input` 移除 null 字节与控制字符、trim 空白并限制长度;零外部依赖。
#[cfg(feature = "secure-sanitize")]
pub mod sanitize;

/// 常量时间比较原语子模块(CWE-208 防御)。
///
/// 提供 `crate::secure::ct_eq::constant_time_eq`,基于 `subtle::ConstantTimeEq` 实现字节级常量时间比较防时序侧信道;消费者清单见模块内文档(单一事实源)。
#[cfg(feature = "secure-ct-eq")]
pub mod ct_eq;

/// 落库敏感字段静态加密子模块(AES-256-GCM at-rest encryption)。
///
/// 提供 [`CryptoValue`](encryption::CryptoValue) 编解码、[`FieldCipher`](encryption::FieldCipher) 加解密(多 key_id 取钥、迁移期双读)与 [`FieldEncryptionDao`](encryption::FieldEncryptionDao) DAO 透明加解密装饰器;`field-encryption` feature 下编译。
#[cfg(feature = "field-encryption")]
pub mod encryption;

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn totp_verifier_default_verify_returns_not_implemented() {
        struct MockTotpVerifier;
        impl TotpVerifier for MockTotpVerifier {}
        let v = MockTotpVerifier;
        let result = v.verify_totp("123456");
        assert!(matches!(result, Err(GarrisonError::NotImplemented(_))));
    }

    #[test]
    fn totp_verifier_default_generate_returns_not_implemented() {
        struct MockTotpVerifier;
        impl TotpVerifier for MockTotpVerifier {}
        let v = MockTotpVerifier;
        let result = v.generate_totp();
        assert!(matches!(result, Err(GarrisonError::NotImplemented(_))));
    }

    #[cfg(feature = "secure-sign")]
    #[test]
    fn sign_verifier_default_verify_returns_not_implemented() {
        struct MockSignVerifier;
        impl SignVerifier for MockSignVerifier {}
        let v = MockSignVerifier;
        let result = v.verify_sign("data", "sign", "secret");
        assert!(matches!(result, Err(GarrisonError::NotImplemented(_))));
    }

    #[cfg(feature = "secure-sign")]
    #[test]
    fn sign_verifier_default_create_returns_not_implemented() {
        struct MockSignVerifier;
        impl SignVerifier for MockSignVerifier {}
        let v = MockSignVerifier;
        let result = v.create_sign("data", "secret");
        assert!(matches!(result, Err(GarrisonError::NotImplemented(_))));
    }
}