futucli/cmd/

gen_key.rs

//! `futucli gen-key`: 生成新 API Key 并追加到 keys.json
//!
//! 明文 key 只会打印到 stdout 一次，用户必须立即保存；文件中只存 SHA-256 hash。

use std::collections::HashSet;
use std::path::{Path, PathBuf};

use anyhow::{Context, Result, anyhow};
use chrono::{DateTime, Duration, Utc};
use futu_auth::{KeyRecord, Limits, Scope, machine, store};

use crate::output::OutputFormat;

/// 默认 keys.json 路径：按 OS 取 dirs::config_dir() (macOS ~/Library/Application Support/futu/ / Linux ~/.config/futu/ / Windows %APPDATA%\\futu\\)
fn default_keys_path() -> Result<PathBuf> {
    let base =
        dirs::config_dir().ok_or_else(|| anyhow!("cannot resolve config dir (set --keys-file)"))?;
    Ok(base.join("futu").join("keys.json"))
}

/// 探测 `futu-mcp` 的绝对路径，生成 gen-key 输出里的 MCP 配置模板时用。
///
/// v1.4.37+ UX 改进：v1.4.36 之前模板里是 hardcode `"/abs/path/to/futu-mcp"` 占位
/// 符，加拿大同事反馈 "看起来像真路径，我直接粘贴了"。现在优先探测真实路径，
/// 让复制粘贴即可用。
///
/// 探测顺序：
/// 1. `futucli` 同目录下的 `futu-mcp`（Homebrew / cargo install / release tarball
///    几乎 100% 同路径）
/// 2. `$PATH` lookup（PATH 环境里第一个含 futu-mcp 的目录）
/// 3. 都找不到 → 返 None，调用方 fallback 到显眼占位符
fn detect_futu_mcp_path() -> Option<PathBuf> {
    let exe_name = if cfg!(windows) {
        "futu-mcp.exe"
    } else {
        "futu-mcp"
    };

    // 1. futucli 同目录
    if let Ok(cli) = std::env::current_exe()
        && let Some(dir) = cli.parent()
    {
        let candidate = dir.join(exe_name);
        if candidate.is_file() {
            return Some(candidate);
        }
    }

    // 2. $PATH lookup
    if let Some(path_env) = std::env::var_os("PATH") {
        for dir in std::env::split_paths(&path_env) {
            let candidate = dir.join(exe_name);
            if candidate.is_file() {
                return Some(candidate);
            }
        }
    }

    None
}

/// 解析 `--expires` 参数：`30d` / `24h` / `2026-06-30T23:59:59Z`
fn parse_expires(s: &str) -> Result<DateTime<Utc>> {
    let s = s.trim();
    if let Ok(t) = DateTime::parse_from_rfc3339(s) {
        return Ok(t.with_timezone(&Utc));
    }
    // 相对时长：<N>d / <N>h / <N>m
    let (num_part, unit) = s
        .chars()
        .position(|c| c.is_alphabetic())
        .map(|i| (&s[..i], &s[i..]))
        .ok_or_else(|| anyhow!("invalid expires {s:?}: expect Nd / Nh / Nm / RFC3339"))?;
    let n: i64 = num_part
        .parse()
        .map_err(|e| anyhow!("invalid number in expires {s:?}: {e}"))?;
    let dur = match unit {
        "d" => Duration::days(n),
        "h" => Duration::hours(n),
        "m" => Duration::minutes(n),
        other => return Err(anyhow!("unknown expires unit {other:?} (d|h|m)")),
    };
    Ok(Utc::now() + dur)
}

fn parse_scopes(s: &str) -> Result<HashSet<Scope>> {
    let mut out = HashSet::new();
    for part in s.split(',') {
        let part = part.trim();
        if part.is_empty() {
            continue;
        }
        let sc: Scope = part
            .parse()
            .map_err(|e| anyhow!("parse scope {part:?}: {e}"))?;
        out.insert(sc);
    }
    if out.is_empty() {
        return Err(anyhow!("--scopes cannot be empty"));
    }
    Ok(out)
}

// v1.4.106 codex 0608 F5 (P3): parse_csv (loose any-string-OK helper) 删除,
// 改为 cmd::key_enums::parse_markets_csv / parse_symbols_csv / parse_trd_sides_csv
// (strict, 拒绝未知 enum / 缺市场前缀的 symbol). 早期 reject 取代 silent stash —
// schema-runtime layer 双对齐 (pitfall #54).

/// v1.4.35: 解析 `--allowed-acc-ids 10001,10002,10003` 到 `HashSet<u64>`
///
/// 空条目跳过（方便 trailing comma）；非数字 token 直接返错（防止用户误传
/// symbol / market 到 acc-id 字段）。
fn parse_acc_ids_csv(s: &str) -> Result<HashSet<u64>> {
    let mut out = HashSet::new();
    for token in s.split(',').map(|p| p.trim()).filter(|p| !p.is_empty()) {
        let id: u64 = token.parse().map_err(|e| {
            anyhow::anyhow!(
                "invalid acc_id {token:?}: expected positive integer, got {e}. \
                 Usage: --allowed-acc-ids 10001,10002,10003"
            )
        })?;
        out.insert(id);
    }
    Ok(out)
}

pub struct GenKeyCommand {
    pub id: String,
    pub scopes: String,
    pub keys_file: Option<PathBuf>,
    pub expires: Option<String>,
    pub note: Option<String>,
    pub allowed_markets: Option<String>,
    pub allowed_symbols: Option<String>,
    pub max_order_value: Option<f64>,
    pub max_daily_value: Option<f64>,
    pub hours_window: Option<String>,
    pub max_orders_per_minute: Option<u32>,
    pub allowed_trd_sides: Option<String>,
    /// v1.4.35：per-key 允许的 acc_id 列表，逗号分隔（如 `10001,10002`）。
    /// None / 空 → 不限（向后兼容）。主要用于多 agent 隔离。
    pub allowed_acc_ids: Option<String>,
    /// v1.4.103 (B10)：per-key 允许的 card_num 列表，逗号分隔.
    /// 接受 4 位 suffix (e.g. `<card-suffix>`) 或 16 位完整 (e.g. `<full-card-num>`).
    /// 示例为 synthetic placeholder, 不是真实账户信息.
    /// daemon 启动后通过 GetAccList resolve → 合并进 allowed_acc_ids.
    pub allowed_card_nums: Option<String>,
    pub bind_this_machine: bool,
    pub bind_machines: Option<String>,
    pub output: OutputFormat,
}

pub async fn run(input: GenKeyCommand) -> Result<()> {
    let GenKeyCommand {
        id,
        scopes,
        keys_file,
        expires,
        note,
        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,
        bind_this_machine,
        bind_machines,
        output,
    } = input;

    let path = match keys_file {
        Some(p) => p,
        None => default_keys_path()?,
    };
    let scopes = parse_scopes(&scopes)?;
    let expires_at = match expires {
        Some(s) => Some(parse_expires(&s)?),
        None => None,
    };

    // 交易方向白名单：v1.4.106 F5 strict parser — 大写归一化 + 拒绝未知
    // trd_side (BUY/SELL/SELL_SHORT/BUY_BACK 4 variants 严格匹配, 不接受
    // "long" / "exit" 等 silent stash).
    let allowed_trd_sides = match allowed_trd_sides {
        Some(s) => Some(crate::cmd::key_enums::parse_trd_sides_csv(&s)?),
        None => None,
    };

    // v1.4.35: per-key acc_id 白名单，CSV 解析到 u64 HashSet
    let allowed_acc_ids = match allowed_acc_ids {
        Some(s) => Some(parse_acc_ids_csv(&s)?),
        None => None,
    };

    // v1.4.103 (B10): per-key card_num 白名单, CSV 解析到 Vec<String>.
    // 字符串形式保留 (4 位 suffix / 16 位完整), daemon 启动后 resolve.
    //
    // v1.4.104 external reviewer P2-008 (P2) fix: 显式传 "" / "  " / "," / 全空 CSV 时,
    // .filter() 后 Vec 为 [], daemon 把空 list 当 "无限制" sentinel 处理 →
    // 与用户 "完全不允许" 意图相反 (silent inverse). loud reject — 用户必须
    // 要么不传 (Option::None → 未限制) 要么传至少 1 个 card_num.
    let allowed_card_nums: Option<Vec<String>> = match allowed_card_nums {
        None => None,
        Some(s) => {
            let parsed: Vec<String> = s
                .split(',')
                .map(|p| p.trim().to_string())
                .filter(|p| !p.is_empty())
                .collect();
            if parsed.is_empty() {
                return Err(anyhow!(
                    "v1.4.104 external report P2-008 (P2) fix: --allowed-card-nums {s:?} parsed to empty \
                     list. daemon 会把空 list 当 \"无限制\" sentinel — 与你的意图相反. \
                     如要 \"不限制\" 请**不传** --allowed-card-nums; 如要 \"完全限制\" 至少 \
                     传 1 个真实 4/16 位 card_num (即使是 dummy 0000)."
                ));
            }
            Some(parsed)
        }
    };
    // 校验格式: 4 位或 16 位纯数字
    if let Some(ref nums) = allowed_card_nums {
        for cn in nums {
            if !cn.chars().all(|c| c.is_ascii_digit()) || (cn.len() != 4 && cn.len() != 16) {
                return Err(anyhow!(
                    "invalid card_num {cn:?}: expected 4-digit suffix \
                     or 16-digit full card number (synthetic example: 4-digit \
                     `<card-suffix>` or 16-digit `<full-card-num>`). \
                     Got len={}, all-digits={}",
                    cn.len(),
                    cn.chars().all(|c| c.is_ascii_digit())
                ));
            }
        }
    }

    // v1.4.106 codex 0608 F5 (P3): strict parser 替代 parse_csv —
    // - markets: official TrdMarket aliases/int whitelist, including 10.6
    //   Crypto / futures simulate / SG-MY-JP fund read scopes.
    // - symbols: MARKET.CODE 必须含 '.'; market 部分在白名单
    // 早期 reject 不合法 input, 不再 silent stash.
    let allowed_markets = match allowed_markets {
        Some(s) => Some(crate::cmd::key_enums::parse_markets_csv(&s)?),
        None => None,
    };
    let allowed_symbols = match allowed_symbols {
        Some(s) => Some(crate::cmd::key_enums::parse_symbols_csv(&s)?),
        None => None,
    };

    let limits = Limits {
        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,
    };
    let limits_for_output = limits.clone();

    // 机器绑定：--bind-this-machine 和 --bind-machines 可同时使用，最终合并去重
    let allowed_machines =
        build_allowed_machines(&id, bind_this_machine, bind_machines.as_deref())?;

    let (plaintext, record) = KeyRecord::generate_with_machines(
        id.clone(),
        scopes.clone(),
        Some(limits),
        expires_at,
        note,
        allowed_machines.clone(),
    );

    store::append_key(&path, record).with_context(|| format!("append to {}", path.display()))?;

    print_result(
        KeyPrintView {
            path: &path,
            id: &id,
            plaintext: &plaintext,
            scopes: &scopes,
            allowed_machines: allowed_machines.as_deref(),
            limits: &limits_for_output,
        },
        output,
    )?;
    Ok(())
}

/// 组装 `allowed_machines` 列表
///
/// - `bind_this_machine=true` → 读本机 machine-id，算 fingerprint_for(id)
/// - `bind_machines=Some("fp1,fp2")` → 解析逗号分隔列表
/// - 两者都没 → 返回 None（不启用绑定）
///
/// v1.4.106 codex 0608 F4 (P2): `--bind-machines ""` / `--bind-machines ", ,"`
/// 等显式传空 CSV (parse 后 0 fingerprint) 且未传 `--bind-this-machine` →
/// **loud reject** 不再 silent fall-through 到 None (None = "不启用绑定" =
/// "无限制" silent inverse). 用户必须要么不传 `--bind-machines` 要么传至少
/// 1 个真实指纹. `--freeze` 走 bind-key 独立路径 (允许显式空白名单).
///
/// v1.4.106 codex 0608 F5 (P3): fingerprint 解析改用 cmd::key_enums::
/// parse_fingerprints_csv (与 bind-key 共用), 单一 source of truth.
fn build_allowed_machines(
    id: &str,
    bind_this: bool,
    bind_others: Option<&str>,
) -> Result<Option<Vec<String>>> {
    let mut list: Vec<String> = Vec::new();
    if bind_this {
        let fp = machine::fingerprint_for(id)
            .map_err(|e| anyhow!("cannot compute this machine's fingerprint: {e}"))?;
        list.push(fp);
    }
    if let Some(raw) = bind_others {
        let parsed = crate::cmd::key_enums::parse_fingerprints_csv(raw)?;
        if parsed.is_empty() && !bind_this {
            // F4 (P2): 显式 --bind-machines ""/" ,," 但没配 --bind-this-machine →
            // list 会留空 → 返 None → daemon 解 "无限制" → silent inverse.
            // loud reject — 用户必须要么不传 --bind-machines 要么传至少 1 个 fp.
            return Err(anyhow!(
                "v1.4.106 F4: --bind-machines {raw:?} parsed to empty list \
                 (no --bind-this-machine either). 这会让 allowed_machines = None \
                 (无机器绑定限制) — 与你的意图相反. 如要 \"不启用绑定\" 请不传 \
                 --bind-machines; 如要至少 1 个机器, 传至少 1 个 64-hex 指纹 \
                 (`futucli machine-id --for-key <id>`)."
            ));
        }
        list.extend(parsed);
    }
    if list.is_empty() {
        return Ok(None);
    }
    // 去重保序
    let mut seen = HashSet::new();
    list.retain(|x| seen.insert(x.clone()));
    Ok(Some(list))
}

struct KeyPrintView<'a> {
    path: &'a Path,
    id: &'a str,
    plaintext: &'a str,
    scopes: &'a HashSet<Scope>,
    allowed_machines: Option<&'a [String]>,
    limits: &'a Limits,
}

fn print_result(view: KeyPrintView<'_>, output: OutputFormat) -> Result<()> {
    let rendered = render_result(view, output, detect_futu_mcp_path().as_deref())?;
    println!("{rendered}");
    Ok(())
}

fn render_result(
    view: KeyPrintView<'_>,
    output: OutputFormat,
    mcp_path: Option<&Path>,
) -> Result<String> {
    use std::fmt::Write as _;

    let mut scope_list: Vec<&str> = view.scopes.iter().map(|s| s.as_str()).collect();
    scope_list.sort_unstable();
    let mcp_command = mcp_path
        .map(|path| path.display().to_string())
        .unwrap_or_else(|| "REPLACE_WITH_ABSOLUTE_PATH_RUN_which_futu_mcp".to_string());

    if matches!(output, OutputFormat::Json | OutputFormat::Jsonl) {
        let limits = serde_json::json!({
            "allowed_markets": view.limits.allowed_markets,
            "allowed_symbols": view.limits.allowed_symbols,
            "max_order_value": view.limits.max_order_value,
            "max_daily_value": view.limits.max_daily_value,
            "hours_window": view.limits.hours_window,
            "max_orders_per_minute": view.limits.max_orders_per_minute,
            "allowed_trd_sides": view.limits.allowed_trd_sides,
            "allowed_acc_ids": view.limits.allowed_acc_ids,
            "allowed_card_nums": view.limits.allowed_card_nums,
        });
        let value = serde_json::json!({
            "id": view.id,
            "scopes": scope_list,
            "keys_file": view.path.display().to_string(),
            "plaintext": view.plaintext,
            "limits": limits,
            "allowed_machines": view.allowed_machines,
            "mcp_config": {
                "mcpServers": {
                    "futu": {
                        "command": mcp_command,
                        "args": ["--keys-file", view.path.display().to_string()],
                        "env": {"FUTU_MCP_API_KEY": view.plaintext}
                    }
                }
            }
        });
        return match output {
            OutputFormat::Json => serde_json::to_string_pretty(&value).map_err(Into::into),
            OutputFormat::Jsonl => serde_json::to_string(&value).map_err(Into::into),
            _ => unreachable!(),
        };
    }

    let mut rendered = String::new();
    writeln!(rendered)?;
    writeln!(rendered, "=== FutuOpenD-rs API Key ===")?;
    writeln!(rendered)?;
    writeln!(rendered, "  id     : {}", view.id)?;
    writeln!(rendered, "  scopes : {}", scope_list.join(", "))?;
    writeln!(rendered, "  path   : {}", view.path.display())?;
    if let Some(r) = view.limits.max_orders_per_minute {
        writeln!(rendered, "  rate   : {r} orders/min")?;
    }
    if let Some(sides) = view.limits.allowed_trd_sides.as_ref()
        && !sides.is_empty()
    {
        let mut v: Vec<String> = sides.iter().cloned().collect();
        v.sort();
        writeln!(rendered, "  sides  : {}", v.join(","))?;
    }
    if let Some(ms) = view.allowed_machines {
        writeln!(rendered, "  bound  : {} machine(s)", ms.len())?;
        for fp in ms {
            writeln!(rendered, "           {}", &fp[..16])?;
        }
    }
    writeln!(rendered)?;
    writeln!(
        rendered,
        "Plaintext (shown once, SAVE IT NOW — file only stores SHA-256 hash):"
    )?;
    writeln!(rendered)?;
    writeln!(rendered, "  FUTU_MCP_API_KEY={}", view.plaintext)?;
    writeln!(rendered)?;
    writeln!(
        rendered,
        "Add to your MCP client config, e.g. Claude Desktop claude_desktop_config.json:"
    )?;
    writeln!(rendered)?;
    // v1.4.37+ UX：优先探测 futu-mcp 真实路径，fallback 给显眼警告占位符。
    // 加拿大同事反馈：v1.4.36 之前的 "/abs/path/to/futu-mcp" 像真路径，容易误
    // 粘贴。现在如果 futu-mcp 和 futucli 装在一起（Homebrew / cargo install /
    // release tarball 几乎总是如此），模板里就是可用的绝对路径 —— 复制粘贴即用。
    let (mcp_command_json, post_note) = match mcp_path {
        Some(path) => (
            serde_json::to_string(&path.display().to_string())?,
            format!("(auto-detected: {})", path.display()),
        ),
        None => (
            r#""REPLACE_WITH_ABSOLUTE_PATH_RUN_which_futu_mcp""#.to_string(),
            "⚠️  futu-mcp not found in PATH or next to futucli — replace the \
                command field above with the absolute path (run: `which futu-mcp`)."
                .to_string(),
        ),
    };
    writeln!(rendered, "  {{")?;
    writeln!(rendered, "    \"mcpServers\": {{")?;
    writeln!(rendered, "      \"futu\": {{")?;
    writeln!(rendered, "        \"command\": {mcp_command_json},")?;
    writeln!(
        rendered,
        "        \"args\": [\"--keys-file\", \"{}\"],",
        view.path.display()
    )?;
    writeln!(
        rendered,
        "        \"env\": {{ \"FUTU_MCP_API_KEY\": \"{}\" }}",
        view.plaintext
    )?;
    writeln!(rendered, "      }}")?;
    writeln!(rendered, "    }}")?;
    writeln!(rendered, "  }}")?;
    writeln!(rendered)?;
    writeln!(rendered, "  command path: {post_note}")?;
    Ok(rendered)
}

#[cfg(test)]
mod tests;