futu_auth/

key.rs

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

use std::collections::HashSet;

use chrono::{DateTime, NaiveTime, Utc};
use rand::Rng;
use serde::{Deserialize, Deserializer, Serialize, Serializer, de};
use sha2::{Digest, Sha256};

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

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

    pub allowed_markets: Option<HashSet<String>>,
    pub allowed_symbols: Option<HashSet<String>>,
    pub max_order_value: Option<f64>,
    pub max_daily_value: Option<f64>,
    /// "HH:MM-HH:MM" 服务器本地时区；跨午夜用 "22:00-04:00"
    pub hours_window: Option<String>,
    /// 每 60s 最多下单次数（滑动窗口，None 表示不限）
    pub max_orders_per_minute: Option<u32>,
    /// 允许的交易方向，例如 `["SELL"]`；None 不限
    pub allowed_trd_sides: Option<HashSet<String>>,
    /// v1.4.35：per-key acc_id 白名单。详见 [`Limits::allowed_acc_ids`]。
    /// None / 空集 → 不限（向后兼容老 key）。
    pub allowed_acc_ids: Option<HashSet<u64>>,
    /// v1.4.103 (B10): per-key card_num 白名单 (string format).
    ///
    /// 字符串格式接受:
    /// - 完整 16 位 card_num: `"1001100100800000"` (与 backend `card_number` 字段一致)
    /// - 末 4 位 suffix: `"7680"` (App 显示的 "保证金综合账户(7680)" 末 4 位)
    ///
    /// daemon 启动后调 GetAccList → 把 card_num 列表 resolve 成 acc_id, **合并**
    /// 进 `allowed_acc_ids` (内部 storage 仍 u64). 多 suffix 撞 → log warn + skip
    /// 该条 (loud, 不静默接受). 找不到 → log warn + skip (用户后续 cache load
    /// 后可补回, 不 abort 防影响其他 keys).
    ///
    /// **设计动机** (用户 2026-04-29 反馈): App 显示的是 card_num 末 4 位
    /// "保证金综合账户(7680)" / 完整 16 位 `1001100100800000`, 用户看不到内部
    /// `acc_id` (e.g. 900001). 若 keys.json 只接受 acc_id, 用户必须
    /// 先调 /api/accounts 拿映射 → 认知负担. 加 allowed_card_nums 后用户可直接
    /// 写 App 看到的 4 位 / 16 位.
    ///
    /// **None / 空 → 不限** (与 allowed_acc_ids 一致语义, 向后兼容).
    pub allowed_card_nums: Option<Vec<String>>,
    pub expires_at: Option<DateTime<Utc>>,
    pub created_at: DateTime<Utc>,
    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 的指纹不同。
    pub allowed_machines: Option<Vec<String>>,

    /// **v1.4.106 F-P2-D**: runtime-only — keys.json 文件源里**原始**
    /// `allowed_acc_ids` 集合 (load_file 后立即 snapshot, sentinel 注入 + card_num
    /// expansion 都不影响本字段).
    ///
    /// 用途: `expand_allowed_card_nums` 每次重新计算 resolved set 时从本字段
    /// 起步, 而不是从已 mutate 的 `allowed_acc_ids` 起步. 这样若 keys.json
    /// 没动但 cache 里某个 acc 不再可见, 重 expand 会自然不再含旧 resolved acc_id.
    ///
    /// `None` = 文件源没设 `allowed_acc_ids` (与 file `Option<HashSet>` 区分:
    /// `Some(empty_set)` 表示文件源显式空, `None` 表示文件源没字段).
    ///
    /// 自定义 serializer 不把该 runtime 字段写入 keys.json；只用它恢复文件源
    /// `limits.allowed_acc_ids`，避免 sentinel / card-number expansion 泄漏回配置。
    pub raw_explicit_acc_ids: Option<HashSet<u64>>,
}

#[derive(Debug, Default)]
enum FieldPresence<T> {
    #[default]
    Missing,
    Present(Option<T>),
}

impl<'de, T> Deserialize<'de> for FieldPresence<T>
where
    T: Deserialize<'de>,
{
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        Option::<T>::deserialize(deserializer).map(Self::Present)
    }
}

#[derive(Debug, Default, Deserialize)]
#[serde(deny_unknown_fields)]
struct KeyLimitsWire {
    #[serde(default)]
    allowed_markets: FieldPresence<HashSet<String>>,
    #[serde(default)]
    allowed_symbols: FieldPresence<HashSet<String>>,
    #[serde(default)]
    max_order_value: FieldPresence<f64>,
    #[serde(default)]
    max_daily_value: FieldPresence<f64>,
    #[serde(default)]
    hours_window: FieldPresence<String>,
    #[serde(default)]
    max_orders_per_minute: FieldPresence<u32>,
    #[serde(default)]
    allowed_trd_sides: FieldPresence<HashSet<String>>,
    #[serde(default)]
    allowed_acc_ids: FieldPresence<HashSet<u64>>,
    #[serde(default)]
    allowed_card_nums: FieldPresence<Vec<String>>,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct KeyRecordWire {
    id: String,
    hash: String,
    scopes: HashSet<Scope>,
    #[serde(default)]
    limits: FieldPresence<KeyLimitsWire>,
    #[serde(default)]
    allowed_markets: FieldPresence<HashSet<String>>,
    #[serde(default)]
    allowed_symbols: FieldPresence<HashSet<String>>,
    #[serde(default)]
    max_order_value: FieldPresence<f64>,
    #[serde(default)]
    max_daily_value: FieldPresence<f64>,
    #[serde(default)]
    hours_window: FieldPresence<String>,
    #[serde(default)]
    max_orders_per_minute: FieldPresence<u32>,
    #[serde(default)]
    allowed_trd_sides: FieldPresence<HashSet<String>>,
    #[serde(default)]
    allowed_acc_ids: FieldPresence<HashSet<u64>>,
    #[serde(default)]
    allowed_card_nums: FieldPresence<Vec<String>>,
    #[serde(default)]
    expires_at: Option<DateTime<Utc>>,
    created_at: DateTime<Utc>,
    #[serde(default)]
    note: Option<String>,
    #[serde(default)]
    allowed_machines: Option<Vec<String>>,
}

fn merge_limit_field<T, E>(
    name: &'static str,
    flat: FieldPresence<T>,
    nested: FieldPresence<T>,
) -> Result<Option<T>, E>
where
    E: de::Error,
{
    match (flat, nested) {
        (FieldPresence::Present(_), FieldPresence::Present(_)) => Err(E::custom(format!(
            "duplicate limit field {name:?}: configure it either at the key root (legacy) or in limits, not both"
        ))),
        (FieldPresence::Present(value), FieldPresence::Missing)
        | (FieldPresence::Missing, FieldPresence::Present(value)) => Ok(value),
        (FieldPresence::Missing, FieldPresence::Missing) => Ok(None),
    }
}

impl<'de> Deserialize<'de> for KeyRecord {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        let wire = KeyRecordWire::deserialize(deserializer)?;
        let nested = match wire.limits {
            FieldPresence::Missing | FieldPresence::Present(None) => KeyLimitsWire::default(),
            FieldPresence::Present(Some(limits)) => limits,
        };
        let allowed_markets = merge_limit_field::<_, D::Error>(
            "allowed_markets",
            wire.allowed_markets,
            nested.allowed_markets,
        )?;
        let allowed_symbols = merge_limit_field::<_, D::Error>(
            "allowed_symbols",
            wire.allowed_symbols,
            nested.allowed_symbols,
        )?;
        let max_order_value = merge_limit_field::<_, D::Error>(
            "max_order_value",
            wire.max_order_value,
            nested.max_order_value,
        )?;
        let max_daily_value = merge_limit_field::<_, D::Error>(
            "max_daily_value",
            wire.max_daily_value,
            nested.max_daily_value,
        )?;
        let hours_window = merge_limit_field::<_, D::Error>(
            "hours_window",
            wire.hours_window,
            nested.hours_window,
        )?;
        let max_orders_per_minute = merge_limit_field::<_, D::Error>(
            "max_orders_per_minute",
            wire.max_orders_per_minute,
            nested.max_orders_per_minute,
        )?;
        let allowed_trd_sides = merge_limit_field::<_, D::Error>(
            "allowed_trd_sides",
            wire.allowed_trd_sides,
            nested.allowed_trd_sides,
        )?;
        let allowed_acc_ids = merge_limit_field::<_, D::Error>(
            "allowed_acc_ids",
            wire.allowed_acc_ids,
            nested.allowed_acc_ids,
        )?;
        let allowed_card_nums = merge_limit_field::<_, D::Error>(
            "allowed_card_nums",
            wire.allowed_card_nums,
            nested.allowed_card_nums,
        )?;
        let raw_explicit_acc_ids = allowed_acc_ids.clone();

        Ok(Self {
            id: wire.id,
            hash: wire.hash,
            scopes: wire.scopes,
            allowed_markets,
            allowed_symbols,
            max_order_value,
            max_daily_value,
            hours_window,
            max_orders_per_minute,
            allowed_trd_sides,
            allowed_acc_ids,
            allowed_card_nums,
            expires_at: wire.expires_at,
            created_at: wire.created_at,
            note: wire.note,
            allowed_machines: wire.allowed_machines,
            raw_explicit_acc_ids,
        })
    }
}

#[derive(Serialize)]
struct KeyLimitsOut<'a> {
    #[serde(skip_serializing_if = "Option::is_none")]
    allowed_markets: Option<&'a HashSet<String>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    allowed_symbols: Option<&'a HashSet<String>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    max_order_value: Option<f64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    max_daily_value: Option<f64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    hours_window: Option<&'a String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    max_orders_per_minute: Option<u32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    allowed_trd_sides: Option<&'a HashSet<String>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    allowed_acc_ids: Option<&'a HashSet<u64>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    allowed_card_nums: Option<&'a Vec<String>>,
}

impl KeyLimitsOut<'_> {
    fn is_empty(&self) -> bool {
        self.allowed_markets.is_none()
            && self.allowed_symbols.is_none()
            && self.max_order_value.is_none()
            && self.max_daily_value.is_none()
            && self.hours_window.is_none()
            && self.max_orders_per_minute.is_none()
            && self.allowed_trd_sides.is_none()
            && self.allowed_acc_ids.is_none()
            && self.allowed_card_nums.is_none()
    }
}

#[derive(Serialize)]
struct KeyRecordOut<'a> {
    id: &'a str,
    hash: &'a str,
    scopes: &'a HashSet<Scope>,
    #[serde(skip_serializing_if = "Option::is_none")]
    limits: Option<KeyLimitsOut<'a>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    expires_at: Option<DateTime<Utc>>,
    created_at: DateTime<Utc>,
    #[serde(skip_serializing_if = "Option::is_none")]
    note: Option<&'a String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    allowed_machines: Option<&'a Vec<String>>,
}

impl Serialize for KeyRecord {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        let limits = KeyLimitsOut {
            allowed_markets: self.allowed_markets.as_ref(),
            allowed_symbols: self.allowed_symbols.as_ref(),
            max_order_value: self.max_order_value,
            max_daily_value: self.max_daily_value,
            hours_window: self.hours_window.as_ref(),
            max_orders_per_minute: self.max_orders_per_minute,
            allowed_trd_sides: self.allowed_trd_sides.as_ref(),
            allowed_acc_ids: self.raw_explicit_acc_ids.as_ref(),
            allowed_card_nums: self.allowed_card_nums.as_ref(),
        };
        let limits = (!limits.is_empty()).then_some(limits);
        KeyRecordOut {
            id: &self.id,
            hash: &self.hash,
            scopes: &self.scopes,
            limits,
            expires_at: self.expires_at,
            created_at: self.created_at,
            note: self.note.as_ref(),
            allowed_machines: self.allowed_machines.as_ref(),
        }
        .serialize(serializer)
    }
}

impl KeyRecord {
    /// 生成新 key：返回 (plaintext, record)
    ///
    /// plaintext 只会返回给调用方一次，必须立即展示给用户；record 落盘。
    #[must_use = "丢弃生成结果会丢失 plaintext; 调用方必须立即展示给用户"]
    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`
    #[must_use = "丢弃生成结果会丢失 plaintext; 调用方必须立即展示给用户"]
    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::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();
        // v1.4.106 F-P2-D: snapshot 原始 allowed_acc_ids 作 raw 起步集合
        let raw_explicit_acc_ids = limits.allowed_acc_ids.clone();
        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,
            allowed_acc_ids: limits.allowed_acc_ids,
            allowed_card_nums: limits.allowed_card_nums,
            expires_at,
            created_at: Utc::now(),
            note,
            allowed_machines,
            raw_explicit_acc_ids,
        };
        (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 是否一致
    #[must_use]
    pub fn matches(&self, plaintext: &str) -> bool {
        let computed = hash_plaintext(plaintext);
        self.matches_hash(&computed)
    }

    pub(crate) fn matches_hash(&self, computed: &str) -> bool {
        constant_time_eq_str(&self.hash, computed)
    }

    /// 当前 `futucli gen-key` 生成的 plaintext 契约：32 字节随机数的 lowercase
    /// hex 表示。KeyStore::verify 用它做 cheap preflight，避免明显无效输入进入
    /// SHA-256 和全量 key scan。
    pub(crate) fn is_generated_plaintext_shape(plaintext: &str) -> bool {
        plaintext.len() == 64
            && plaintext
                .bytes()
                .all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b))
    }

    /// 是否已过期
    #[must_use]
    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`]
    #[must_use]
    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(),
            allowed_acc_ids: self.allowed_acc_ids.clone(),
            allowed_card_nums: self.allowed_card_nums.clone(),
        }
    }
}

impl crate::limits::LimitPolicy for KeyRecord {
    fn allowed_markets(&self) -> Option<&HashSet<String>> {
        self.allowed_markets.as_ref()
    }

    fn allowed_symbols(&self) -> Option<&HashSet<String>> {
        self.allowed_symbols.as_ref()
    }

    fn max_order_value(&self) -> Option<f64> {
        self.max_order_value
    }

    fn max_daily_value(&self) -> Option<f64> {
        self.max_daily_value
    }

    fn hours_window(&self) -> Option<&str> {
        self.hours_window.as_deref()
    }

    fn max_orders_per_minute(&self) -> Option<u32> {
        self.max_orders_per_minute
    }

    fn allowed_trd_sides(&self) -> Option<&HashSet<String>> {
        self.allowed_trd_sides.as_ref()
    }

    fn allowed_acc_ids(&self) -> Option<&HashSet<u64>> {
        self.allowed_acc_ids.as_ref()
    }

    fn allowed_card_nums(&self) -> Option<&[String]> {
        self.allowed_card_nums.as_deref()
    }
}

fn constant_time_eq_str(a: &str, b: &str) -> bool {
    let a = a.as_bytes();
    let b = b.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
}

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

#[cfg(test)]
mod tests;