futu_auth/

key.rs

//! KeyRecord: 单条 API Key 的配置 + SHA-256 校验

use std::collections::HashSet;

use chrono::{DateTime, NaiveTime, Utc};
use rand::RngCore;
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};

use crate::limits::Limits;
use crate::scope::Scope;

/// 单条 key 的持久化格式
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct KeyRecord {
    /// 人读 ID（审计日志用）
    pub id: String,
    /// "sha256:<64 hex>"
    pub hash: String,
    pub scopes: HashSet<Scope>,

    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub allowed_markets: Option<HashSet<String>>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub allowed_symbols: Option<HashSet<String>>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_order_value: Option<f64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_daily_value: Option<f64>,
    /// "HH:MM-HH:MM" 服务器本地时区；跨午夜用 "22:00-04:00"
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub hours_window: Option<String>,
    /// 每 60s 最多下单次数（滑动窗口，None 表示不限）
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_orders_per_minute: Option<u32>,
    /// 允许的交易方向，例如 `["SELL"]`；None 不限
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub allowed_trd_sides: Option<HashSet<String>>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub expires_at: Option<DateTime<Utc>>,
    pub created_at: DateTime<Utc>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub note: Option<String>,
    /// 机器绑定指纹列表（软绑定，见 `machine` 模块）
    ///
    /// - `None` → 未启用绑定，所有机器可用（向后兼容 v0.7.0 ~ v0.7.x 早期 key）
    /// - `Some(vec![])` → 强制锁定（无机器能通过），可用于临时冻结
    /// - `Some(vec!["<fingerprint_hex>", ...])` → 只允许这些机器
    ///
    /// 指纹由 `machine::fingerprint_for(key_id)` 生成，和 key_id 强耦合：
    /// 同一台机器上不同 key 的指纹不同。
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub allowed_machines: Option<Vec<String>>,
}

impl KeyRecord {
    /// 生成新 key：返回 (plaintext, record)
    ///
    /// plaintext 只会返回给调用方一次，必须立即展示给用户；record 落盘。
    pub fn generate(
        id: impl Into<String>,
        scopes: HashSet<Scope>,
        limits: Option<Limits>,
        expires_at: Option<DateTime<Utc>>,
        note: Option<String>,
    ) -> (String, KeyRecord) {
        Self::generate_with_machines(id, scopes, limits, expires_at, note, None)
    }

    /// 同 [`generate`]，但允许一次性设置 `allowed_machines`
    pub fn generate_with_machines(
        id: impl Into<String>,
        scopes: HashSet<Scope>,
        limits: Option<Limits>,
        expires_at: Option<DateTime<Utc>>,
        note: Option<String>,
        allowed_machines: Option<Vec<String>>,
    ) -> (String, KeyRecord) {
        let mut bytes = [0u8; 32];
        rand::thread_rng().fill_bytes(&mut bytes);
        let plaintext = hex::encode(bytes);
        let hash = format!(
            "sha256:{}",
            hex::encode(Sha256::digest(plaintext.as_bytes()))
        );
        let limits = limits.unwrap_or_default();
        let record = KeyRecord {
            id: id.into(),
            hash,
            scopes,
            allowed_markets: limits.allowed_markets,
            allowed_symbols: limits.allowed_symbols,
            max_order_value: limits.max_order_value,
            max_daily_value: limits.max_daily_value,
            hours_window: limits.hours_window,
            max_orders_per_minute: limits.max_orders_per_minute,
            allowed_trd_sides: limits.allowed_trd_sides,
            expires_at,
            created_at: Utc::now(),
            note,
            allowed_machines,
        };
        (plaintext, record)
    }

    /// 检查本机是否在 `allowed_machines` 白名单里（None 时始终通过）
    pub fn check_machine(&self) -> Result<(), crate::machine::MachineError> {
        crate::machine::check(&self.id, self.allowed_machines.as_deref())
    }

    /// 校验明文与当前记录的 hash 是否一致
    pub fn matches(&self, plaintext: &str) -> bool {
        let computed = hash_plaintext(plaintext);
        // 常量时间对比（防时序攻击）
        let a = self.hash.as_bytes();
        let b = computed.as_bytes();
        if a.len() != b.len() {
            return false;
        }
        let mut acc: u8 = 0;
        for (x, y) in a.iter().zip(b.iter()) {
            acc |= x ^ y;
        }
        acc == 0
    }

    /// 是否已过期
    pub fn is_expired(&self, now: DateTime<Utc>) -> bool {
        self.expires_at.map(|t| now >= t).unwrap_or(false)
    }

    /// 解析 hours_window 为 (start, end)；None 表示不限
    pub fn hours_range(&self) -> Result<Option<(NaiveTime, NaiveTime)>, String> {
        let Some(s) = &self.hours_window else {
            return Ok(None);
        };
        let (l, r) = s
            .split_once('-')
            .ok_or_else(|| format!("invalid hours_window {s:?}: expect HH:MM-HH:MM"))?;
        let parse = |p: &str| {
            NaiveTime::parse_from_str(p.trim(), "%H:%M")
                .map_err(|e| format!("invalid time {p:?}: {e}"))
        };
        Ok(Some((parse(l)?, parse(r)?)))
    }

    /// 导出为 [`Limits`]
    pub fn limits(&self) -> Limits {
        Limits {
            allowed_markets: self.allowed_markets.clone(),
            allowed_symbols: self.allowed_symbols.clone(),
            max_order_value: self.max_order_value,
            max_daily_value: self.max_daily_value,
            hours_window: self.hours_window.clone(),
            max_orders_per_minute: self.max_orders_per_minute,
            allowed_trd_sides: self.allowed_trd_sides.clone(),
        }
    }
}

/// 计算 "sha256:<hex>" 摘要
pub fn hash_plaintext(plaintext: &str) -> String {
    format!(
        "sha256:{}",
        hex::encode(Sha256::digest(plaintext.as_bytes()))
    )
}

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

    #[test]
    fn generate_and_verify() {
        let (plaintext, rec) = KeyRecord::generate(
            "test",
            [Scope::QotRead].into_iter().collect(),
            None,
            None,
            None,
        );
        assert_eq!(plaintext.len(), 64);
        assert!(rec.matches(&plaintext));
        assert!(!rec.matches("deadbeef"));
    }

    #[test]
    fn hash_deterministic() {
        assert_eq!(hash_plaintext("abc"), hash_plaintext("abc"));
        assert_ne!(hash_plaintext("abc"), hash_plaintext("abd"));
    }

    #[test]
    fn hours_range_parse() {
        let mut rec = KeyRecord {
            id: "t".into(),
            hash: hash_plaintext("x"),
            scopes: HashSet::new(),
            allowed_markets: None,
            allowed_symbols: None,
            max_order_value: None,
            max_daily_value: None,
            hours_window: Some("09:30-16:00".into()),
            max_orders_per_minute: None,
            allowed_trd_sides: None,
            expires_at: None,
            created_at: Utc::now(),
            note: None,
            allowed_machines: None,
        };
        let (a, b) = rec.hours_range().unwrap().unwrap();
        assert_eq!(a, NaiveTime::from_hms_opt(9, 30, 0).unwrap());
        assert_eq!(b, NaiveTime::from_hms_opt(16, 0, 0).unwrap());

        rec.hours_window = Some("bad".into());
        assert!(rec.hours_range().is_err());
    }

    #[test]
    fn expiration() {
        let mut rec = KeyRecord {
            id: "t".into(),
            hash: hash_plaintext("x"),
            scopes: HashSet::new(),
            allowed_markets: None,
            allowed_symbols: None,
            max_order_value: None,
            max_daily_value: None,
            hours_window: None,
            max_orders_per_minute: None,
            allowed_trd_sides: None,
            expires_at: Some(Utc::now() - chrono::Duration::seconds(1)),
            created_at: Utc::now(),
            note: None,
            allowed_machines: None,
        };
        assert!(rec.is_expired(Utc::now()));
        rec.expires_at = None;
        assert!(!rec.is_expired(Utc::now()));
    }
}