crawlrs 0.2.0

crawlrs - Enterprise-grade web scraping and crawling platform built with Rust
Documentation
// Copyright (c) 2025-2026 Kirky.X🌠
// SPDX-License-Identifier: Apache-2.0

//! API Key 哈希与验证模块
//!
//! 提供 API Key 的安全哈希存储与验证功能:
//! - [`hash_api_key`]:使用 bcrypt(cost = `DEFAULT_COST`)进行密码学安全哈希
//! - [`verify_api_key`]:验证 API Key 是否匹配 bcrypt 哈希
//! - [`hash_api_key_sha256`]:SHA-256 摘要,用于缓存键(**非**密码存储)
//! - [`is_legacy_sha256_hash`]:检测旧版 SHA-256 哈希格式以便迁移
//!
//! # 设计原则
//!
//! - bcrypt 哈希用于存储 API Key(带随机盐,抵抗彩虹表与暴力破解)
//! - SHA-256 仅用于缓存键等非密码学场景,**禁止**用于密码存储
//! - 旧版 SHA-256 哈希通过 [`is_legacy_sha256_hash`] 识别,验证成功后
//!   应由调用方触发迁移到 bcrypt
//!
//! # 安全说明
//!
//! - bcrypt `DEFAULT_COST`(12)在 2025 年硬件下提供合理的暴力破解防护
//! - `verify_api_key` 使用 `unwrap_or(false)` — 验证失败与解析失败均返回
//!   `false`,避免泄露哈希格式信息

use anyhow::{anyhow, Context, Result};
use bcrypt::{hash, verify, DEFAULT_COST};
use hex::encode;
use sha2::{Digest, Sha256};

/// 计算 API Key 的 bcrypt 哈希值
///
/// 使用 bcrypt 对 API Key 进行哈希处理,提供强大的暴力破解防护。
/// 每次调用产生不同的哈希值(随机盐),需通过 [`verify_api_key`] 验证。
///
/// # 参数
///
/// * `api_key` - 原始 API Key 字符串
///
/// # 返回值
///
/// * `Ok(String)` - bcrypt 哈希字符串(以 `$2b$` 开头)
/// * `Err` - bcrypt 哈希失败(如 API Key 过长)
///
/// # 示例
///
/// ```ignore
/// use crawlrs::infrastructure::security::hash_api_key;
///
/// let key = "my_secret_api_key";
/// let hash = hash_api_key(key).unwrap;
/// assert!(hash.starts_with("$2b$"));
/// ```
pub fn hash_api_key(api_key: &str) -> Result<String> {
    hash(api_key, DEFAULT_COST)
        .context("Failed to hash API key")
        .map_err(|e| anyhow!("Hashing failed: {}", e))
}

/// 验证 API Key 是否匹配 bcrypt 哈希值
///
/// # 参数
///
/// * `api_key` - 原始 API Key 字符串
/// * `key_hash` - bcrypt 哈希字符串(由 [`hash_api_key`] 产生)
///
/// # 返回值
///
/// * `true` - 验证成功
/// * `false` - 验证失败或哈希格式无效
///
/// # 安全说明
///
/// 验证失败与哈希格式错误均返回 `false`,不向调用方区分失败原因,
/// 避免泄露哈希格式信息。
pub fn verify_api_key(api_key: &str, key_hash: &str) -> bool {
    verify(api_key, key_hash).unwrap_or(false)
}

/// 检测 API Key 哈希是否为旧版 SHA-256 格式
///
/// 旧版格式为纯十六进制字符串(64 字符),新版 bcrypt 哈希以 `$2b$` 开头。
/// 调用方检测到旧版哈希后应在验证成功时触发迁移到 bcrypt。
///
/// # 参数
///
/// * `key_hash` - 要检测的哈希值
///
/// # 返回值
///
/// * `true` - 是旧版 SHA-256 格式(64 字符纯十六进制)
/// * `false` - 是新版 bcrypt 格式(以 `$` 开头)
pub fn is_legacy_sha256_hash(key_hash: &str) -> bool {
    // bcrypt 哈希以 "$2b$", "$2y$", or "$2a$" 开头
    // 旧版 SHA-256 是纯十六进制,64字符
    !key_hash.starts_with('$') && key_hash.len() == 64
}

/// 计算 API Key 的 SHA-256 哈希值(用于缓存键)
///
/// 使用 SHA-256 生成一致的哈希值,适用于缓存键和数据库查询。
///
/// # 安全警告
///
/// **这不是 bcrypt,不能用于密码存储。** SHA-256 是快速哈希,对暴力破解
/// 无防护能力。仅用于需要确定性、固定长度摘要的非密码学场景。
///
/// # 参数
///
/// * `api_key` - 原始 API Key 字符串
///
/// # 返回值
///
/// * 十六进制编码的 SHA-256 哈希字符串(64 字符)
pub fn hash_api_key_sha256(api_key: &str) -> String {
    let mut hasher = Sha256::new();
    hasher.update(api_key.as_bytes());
    encode(hasher.finalize())
}

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

    #[test]
    fn test_hash_api_key_sha256() {
        let key = "test_api_key_12345";
        let hash1 = hash_api_key_sha256(key);
        let hash2 = hash_api_key_sha256(key);

        // SHA-256 是确定性的,相同的输入应该产生相同的输出
        assert_eq!(hash1, hash2);
        assert_eq!(hash1.len(), 64); // SHA-256 十六进制是 64 字符

        // 不同的输入应该产生不同的哈希
        let hash3 = hash_api_key_sha256("different_key");
        assert_ne!(hash1, hash3);
    }

    #[test]
    fn test_sha256_hash_format() {
        let key = "my_secret_key";
        let hash = hash_api_key_sha256(key);

        // 应该是纯十六进制字符串
        assert!(hash.chars().all(|c| c.is_ascii_hexdigit()));
        assert_eq!(hash.len(), 64);
    }

    #[test]
    fn test_verify_api_key() {
        let key = "test_api_key_12345";
        let hash = hash_api_key(key).unwrap();

        // 正确的密钥应该验证成功
        assert!(verify_api_key(key, &hash));

        // 错误的密钥应该验证失败
        assert!(!verify_api_key("wrong_key", &hash));
    }

    #[test]
    fn test_hash_is_deterministic() {
        let key = "consistent_key";
        let hash1 = hash_api_key(key).unwrap();
        let hash2 = hash_api_key(key).unwrap();

        // bcrypt 每次生成不同的哈希(随机盐),这是预期行为
        // 正确的测试:验证两者都能通过同一个 key
        assert_ne!(hash1, hash2); // 不同的哈希值
        assert!(verify_api_key(key, &hash1)); // 都能验证通过
        assert!(verify_api_key(key, &hash2));
    }

    #[test]
    fn test_legacy_hash_detection() {
        // 旧版 SHA-256 格式
        let legacy_hash = "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2";
        assert!(is_legacy_sha256_hash(legacy_hash));

        // 新版 bcrypt 格式
        let new_hash = "$2b$12$LQv3c1yqBWVHxkd0LHAkCOYz6TtxMQJqhN8/X4aFTTGq9dKjfSJOy";
        assert!(!is_legacy_sha256_hash(new_hash));
    }

    #[test]
    fn test_verify_rejects_wrong_key() {
        let key = "secure_api_key_xyz";
        let hash = hash_api_key(key).unwrap();

        assert!(!verify_api_key("wrong_key_123", &hash));
        assert!(!verify_api_key("", &hash));
        assert!(!verify_api_key(key, "invalid_hash"));
    }
}