futucli/cmd/

unlock.rs

//! `futucli unlock-trade` — 解锁 / 锁回交易
//!
//! 对 gateway 执行一次 UnlockTrade。成功后 gateway 进程级缓存会持有 cipher，
//! 后续所有客户端（futucli / futu-mcp / Python）的下单都能自动拿到 cipher，
//! **直到 gateway 重启**。
//!
//! 密码来源优先级：
//! 1. `--from-stdin`：从 stdin 读一整行（脚本友好）
//! 2. 环境变量 `FUTU_TRADE_PWD`
//! 3. 账号级 OS keychain（`futucli set-trade-pwd --account <login-account>`）
//! 4. legacy OS keychain（v1.4.109 前全局 `trade-password` 条目）
//! 5. 交互式 tty prompt（无回显）
//!
//! 明文密码不会出现在命令行参数里，避免 shell history / `/proc/*/cmdline` 泄露。
//! MD5 在本地计算后再发送。

use std::io::{self, BufRead};

use anyhow::{Context, Result, bail};
use serde::Serialize;

use crate::common::connect_gateway;

/// CLI 端的 SecurityFirm 枚举：clap ValueEnum 同时接受官方名称（FutuHK / FutuUS）
/// 和短别名（hk / us）。值映射到 proto `Trd_Common.SecurityFirm` int32。
#[derive(Debug, Clone, Copy, clap::ValueEnum)]
#[non_exhaustive]
pub enum SecurityFirmArg {
    #[value(name = "FutuHK", alias = "hk", alias = "futu-hk", alias = "1")]
    FutuHK,
    #[value(
        name = "FutuUS",
        alias = "us",
        alias = "futu-us",
        alias = "2",
        alias = "moomoo",
        alias = "mm"
    )]
    FutuUS,
    #[value(name = "FutuSG", alias = "sg", alias = "futu-sg", alias = "3")]
    FutuSG,
    #[value(name = "FutuAU", alias = "au", alias = "futu-au", alias = "4")]
    FutuAU,
    #[value(name = "FutuCA", alias = "ca", alias = "futu-ca", alias = "5")]
    FutuCA,
    #[value(name = "FutuMY", alias = "my", alias = "futu-my", alias = "6")]
    FutuMY,
    #[value(name = "FutuJP", alias = "jp", alias = "futu-jp", alias = "7")]
    FutuJP,
}

impl SecurityFirmArg {
    pub fn as_i32(self) -> i32 {
        match self {
            Self::FutuHK => 1,
            Self::FutuUS => 2,
            Self::FutuSG => 3,
            Self::FutuAU => 4,
            Self::FutuCA => 5,
            Self::FutuMY => 6,
            Self::FutuJP => 7,
        }
    }
}

pub async fn run(
    gateway: &str,
    lock: bool,
    from_stdin: bool,
    trade_pwd_account: Option<&str>,
    otp: Option<String>,
    security_firm: Option<SecurityFirmArg>,
    // v1.4.34: 只解锁这些 acc_ids（空 = 不 per-account filter）。和 security_firm
    // 同时传时是交集。解决同 broker 内影子账户拖垮主账户的场景。
    acc_ids: Vec<u64>,
    // v1.4.98 external reviewer BUG-005 fix (P2, 2026-04-27): 加 format param 让 lock/unlock
    // 路径都能 honor `-o json` (脚本/agent 用).
    format: crate::output::OutputFormat,
) -> Result<()> {
    let (client, _push_rx) = connect_gateway(gateway, "futucli-unlock").await?;

    if lock {
        // lock 时 pwd_md5 不参与校验，传空串即可
        futu_trd::account::unlock_trade(
            &client,
            "",
            false,
            None,
            security_firm.map(|s| s.as_i32()),
            acc_ids,
        )
        .await
        .context("lock trade failed")?;
        match format {
            crate::output::OutputFormat::Json | crate::output::OutputFormat::Jsonl => {
                let outcome = futu_trd::account::UnlockTradeOutcome {
                    total_requested: 0,
                    total_unlocked: 0,
                    need_otp: false,
                    failed_accounts: vec![],
                    message: None,
                };
                println!(
                    "{}",
                    render_unlock_trade_output(format, "lock", gateway, &outcome)?
                );
            }
            _ => {
                println!("Trade locked on gateway {gateway}.");
            }
        }
        return Ok(());
    }

    let pwd = read_password(from_stdin, trade_pwd_account)?;
    if pwd.is_empty() {
        bail!("empty password");
    }
    let pwd_md5 = format!("{:x}", md5::compute(pwd.as_bytes()));

    let outcome = futu_trd::account::unlock_trade(
        &client,
        &pwd_md5,
        true,
        otp.as_deref(),
        security_firm.map(|s| s.as_i32()),
        acc_ids,
    )
    .await
    .context("unlock trade failed")?;

    // v1.4.31: 显示 per-broker per-account 结果
    if matches!(
        format,
        crate::output::OutputFormat::Json | crate::output::OutputFormat::Jsonl
    ) {
        println!(
            "{}",
            render_unlock_trade_output(format, "unlock", gateway, &outcome)?
        );
        return Ok(());
    }

    if outcome.need_otp {
        println!(
            "⚠️  服务端要求 OTP / 令牌动态密码。失败账户：{:?}",
            outcome.failed_accounts
        );
        println!(
            "  重试：`futucli unlock-trade --otp REPLACE_WITH_6DIGIT_OTP`（保留相同密码来源）"
        );
        println!(
            "  ⚠️  把 `REPLACE_WITH_6DIGIT_OTP` 换成富途令牌 app 里当前显示的 6 位动态密码，别原样粘贴"
        );
        return Ok(());
    }
    println!(
        "Trade unlock: {}/{} accounts unlocked.",
        outcome.total_unlocked, outcome.total_requested
    );
    if outcome.total_unlocked < outcome.total_requested {
        println!(
            "⚠️  失败账户（常见原因：该账户品种权限未开通 / 影子子账户）：{:?}",
            outcome.failed_accounts
        );
        if let Some(msg) = &outcome.message {
            println!("  daemon 信息：{msg}");
        }
    }
    println!("Cipher is cached in the gateway process; will expire when gateway restarts.");
    Ok(())
}

#[derive(Serialize)]
struct UnlockTradeCliOutput<'a> {
    ok: bool,
    action: &'a str,
    gateway: &'a str,
    total_requested: usize,
    total_unlocked: usize,
    need_otp: bool,
    failed_accounts: &'a [u64],
    #[serde(skip_serializing_if = "Option::is_none")]
    message: Option<&'a str>,
    cipher_cached: bool,
}

fn render_unlock_trade_output(
    format: crate::output::OutputFormat,
    action: &str,
    gateway: &str,
    outcome: &futu_trd::account::UnlockTradeOutcome,
) -> Result<String> {
    let output = UnlockTradeCliOutput {
        ok: !outcome.need_otp && outcome.total_unlocked == outcome.total_requested,
        action,
        gateway,
        total_requested: outcome.total_requested,
        total_unlocked: outcome.total_unlocked,
        need_otp: outcome.need_otp,
        failed_accounts: &outcome.failed_accounts,
        message: outcome.message.as_deref(),
        cipher_cached: action == "unlock" && !outcome.need_otp && outcome.total_unlocked > 0,
    };

    match format {
        crate::output::OutputFormat::Json => {
            serde_json::to_string_pretty(&output).map_err(Into::into)
        }
        crate::output::OutputFormat::Jsonl => serde_json::to_string(&output).map_err(Into::into),
        crate::output::OutputFormat::Table | crate::output::OutputFormat::Markdown => Ok(format!(
            "Trade {action}: {}/{} accounts unlocked.",
            outcome.total_unlocked, outcome.total_requested
        )),
    }
}

fn read_password(from_stdin: bool, trade_pwd_account: Option<&str>) -> Result<String> {
    if from_stdin {
        let mut line = String::new();
        io::stdin()
            .lock()
            .read_line(&mut line)
            .context("read password from stdin")?;
        return Ok(trim_stdin_password_line(&line));
    }

    let trade_pwd_account_env = std::env::var("FUTU_TRADE_PWD_ACCOUNT").ok();
    let futu_account_env = std::env::var("FUTU_ACCOUNT").ok();
    let env_pwd = std::env::var("FUTU_TRADE_PWD").ok();

    if let Some(p) = trade_password_from_sources(
        trade_pwd_account,
        trade_pwd_account_env.as_deref(),
        futu_account_env.as_deref(),
        env_pwd.as_deref(),
        read_keyring_password_entry,
    ) {
        return Ok(p);
    }

    rpassword::prompt_password("Trade password: ").context("read password from tty")
}

fn non_empty_trimmed(s: &str) -> Option<String> {
    let s = s.trim();
    (!s.is_empty()).then(|| s.to_string())
}

fn trade_pwd_account_from(
    explicit: Option<&str>,
    trade_pwd_account_env: Option<&str>,
    futu_account_env: Option<&str>,
) -> Option<String> {
    explicit
        .and_then(non_empty_trimmed)
        .or_else(|| trade_pwd_account_env.and_then(non_empty_trimmed))
        .or_else(|| futu_account_env.and_then(non_empty_trimmed))
}

fn read_keyring_password_entry(username: &str) -> Option<String> {
    if let Ok(entry) = keyring::Entry::new(futu_auth::KEYRING_SERVICE, username)
        && let Ok(pwd) = entry.get_password()
        && !pwd.is_empty()
    {
        return Some(pwd);
    }
    None
}

fn trade_password_from_sources(
    account_hint: Option<&str>,
    trade_pwd_account_env: Option<&str>,
    futu_account_env: Option<&str>,
    env_pwd: Option<&str>,
    mut read_keyring: impl FnMut(&str) -> Option<String>,
) -> Option<String> {
    if let Some(pwd) = env_pwd.and_then(non_empty_trimmed) {
        return Some(pwd);
    }

    if let Some(account) =
        trade_pwd_account_from(account_hint, trade_pwd_account_env, futu_account_env)
    {
        let scoped_username = futu_auth::keyring_username_for_trade_pwd(&account);
        if let Some(pwd) = read_keyring(&scoped_username) {
            return Some(pwd);
        }
    }

    read_keyring(futu_auth::KEYRING_USERNAME_TRADE_PWD)
}

fn trim_stdin_password_line(line: &str) -> String {
    line.trim_end_matches(['\n', '\r']).to_string()
}

fn read_keychain_password(kind: &str, from_stdin: bool) -> Result<String> {
    if from_stdin {
        let mut line = String::new();
        io::stdin()
            .lock()
            .read_line(&mut line)
            .with_context(|| format!("read {kind} password from stdin"))?;
        let password = trim_stdin_password_line(&line);
        if password.is_empty() {
            bail!("empty password");
        }
        return Ok(password);
    }

    let pwd1 = rpassword::prompt_password(format!("{kind} password: "))
        .context("read password from tty")?;
    if pwd1.is_empty() {
        bail!("empty password");
    }
    let pwd2 = rpassword::prompt_password("Confirm password: ").context("read confirm from tty")?;
    if pwd1 != pwd2 {
        bail!("passwords do not match");
    }
    Ok(pwd1)
}

/// `futucli set-trade-pwd --account <id>` —— 把交易密码写入 OS keychain。
///
/// 每个登录账号一条独立条目（username = `trade-password.<account>`），避免
/// 多账号互相覆盖。`futucli unlock-trade` / `futu-mcp` 读取时通过
/// `--trade-pwd-account` / `FUTU_TRADE_PWD_ACCOUNT` 选择对应条目。
pub async fn set_trade_pwd(account: &str, from_stdin: bool) -> Result<()> {
    let account = account.trim();
    if account.is_empty() {
        bail!("--account is required");
    }
    let pwd = read_keychain_password("Trade", from_stdin)?;
    let username = futu_auth::keyring_username_for_trade_pwd(account);
    let entry = keyring::Entry::new(futu_auth::KEYRING_SERVICE, &username)
        .context("create keyring entry")?;
    entry
        .set_password(&pwd)
        .context("write password to OS keychain")?;
    println!(
        "✓ trade password saved to OS keychain (service={}, account={})",
        futu_auth::KEYRING_SERVICE,
        username
    );
    println!(
        "  futucli unlock-trade / futu-mcp read it with --trade-pwd-account {account} \
         (or FUTU_TRADE_PWD_ACCOUNT={account})."
    );
    Ok(())
}

/// `futucli clear-trade-pwd --account <id>` —— 从 OS keychain 删除某账号的交易密码。
pub async fn clear_trade_pwd(account: &str) -> Result<()> {
    let account = account.trim();
    if account.is_empty() {
        bail!("--account is required");
    }
    let username = futu_auth::keyring_username_for_trade_pwd(account);
    let entry = keyring::Entry::new(futu_auth::KEYRING_SERVICE, &username)
        .context("create keyring entry")?;
    match entry.delete_credential() {
        Ok(()) => println!("✓ trade password removed from OS keychain (account={account})"),
        Err(keyring::Error::NoEntry) => println!("(no entry existed; nothing to remove)"),
        Err(e) => return Err(anyhow::anyhow!("delete from keychain failed: {e}")),
    }
    Ok(())
}

/// `futucli set-login-pwd --account <id>` —— 把登录密码写入 OS keychain（v1.4.18+）。
///
/// 每个账号一条独立条目（username = `login-password.<account>`），避免多账号
/// 互相覆盖。`futu-opend` 启动时如果没传 `--login-pwd` / `FUTU_PWD`，会从
/// 这里读取对应 account 的密码。
///
/// 这是推荐的密码存储方式 —— 明文不进 `ps aux` / `~/.bash_history` /
/// 配置文件 backup。
pub async fn set_login_pwd(account: &str, from_stdin: bool) -> Result<()> {
    if account.is_empty() {
        bail!("--account is required");
    }
    let pwd = read_keychain_password("Login", from_stdin)?;
    let username = futu_auth::keyring_username_for_login_pwd(account);
    let entry = keyring::Entry::new(futu_auth::KEYRING_SERVICE, &username)
        .context("create keyring entry")?;
    entry
        .set_password(&pwd)
        .context("write password to OS keychain")?;
    println!(
        "✓ login password saved to OS keychain (service={}, account={})",
        futu_auth::KEYRING_SERVICE,
        username
    );
    println!("  futu-opend will read it automatically when --login-pwd / FUTU_PWD is not set.");
    Ok(())
}

/// `futucli clear-login-pwd --account <id>` —— 从 OS keychain 删除某账号的登录密码。
pub async fn clear_login_pwd(account: &str) -> Result<()> {
    if account.is_empty() {
        bail!("--account is required");
    }
    let username = futu_auth::keyring_username_for_login_pwd(account);
    let entry = keyring::Entry::new(futu_auth::KEYRING_SERVICE, &username)
        .context("create keyring entry")?;
    match entry.delete_credential() {
        Ok(()) => println!("✓ login password removed from OS keychain (account={account})"),
        Err(keyring::Error::NoEntry) => println!("(no entry existed; nothing to remove)"),
        Err(e) => return Err(anyhow::anyhow!("delete from keychain failed: {e}")),
    }
    Ok(())
}

#[cfg(test)]
mod tests;