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 credential store（macOS 发布包仅兼容读取旧条目）
//! 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 futu_auth::secret_store::{DeleteOutcome, PasswordLookup, SecretStoreError};
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,
    )
    .map_err(keyring_read_error)?
    {
        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,
) -> std::result::Result<Option<String>, SecretStoreError> {
    match futu_auth::secret_store::read_password(username) {
        Ok(PasswordLookup::Found(password)) => Ok(Some(password)),
        Ok(PasswordLookup::Empty | PasswordLookup::NoEntry) => Ok(None),
        // Preserve the existing fallback for ordinary backend errors. A timeout
        // or dead worker is different: treating it as NoEntry would hide the
        // Issue #31 startup/CLI stall and might prompt for another secret.
        Err(SecretStoreError::Backend { .. }) => Ok(None),
        Err(error) => Err(error),
    }
}

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) -> std::result::Result<Option<String>, SecretStoreError>,
) -> std::result::Result<Option<String>, SecretStoreError> {
    if let Some(pwd) = env_pwd.and_then(non_empty_trimmed) {
        return Ok(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 Ok(Some(pwd));
        }
    }

    read_keyring(futu_auth::KEYRING_USERNAME_TRADE_PWD)
}

fn keyring_read_error(error: SecretStoreError) -> anyhow::Error {
    anyhow::anyhow!(
        "OS keychain trade-password lookup failed within the {}-second safety boundary: {error}. \
         Use FUTU_TRADE_PWD or `futucli unlock-trade --from-stdin`. {}",
        futu_auth::secret_store::KEYRING_OPERATION_TIMEOUT.as_secs(),
        keyring_platform_detail()
    )
}

#[cfg(target_os = "macos")]
fn keyring_platform_detail() -> &'static str {
    "Packaged cross-binary Keychain sharing is not supported."
}

#[cfg(not(target_os = "macos"))]
fn keyring_platform_detail() -> &'static str {
    "The platform credential-store operation did not finish safely."
}

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)
}

fn read_password_for_keychain_write(
    kind: &str,
    from_stdin: bool,
    read: impl FnOnce(&str, bool) -> Result<String>,
) -> Result<String> {
    ensure_cross_binary_keychain_write_supported(kind)?;
    read(kind, from_stdin)
}

#[cfg(target_os = "macos")]
fn ensure_cross_binary_keychain_write_supported(kind: &str) -> Result<()> {
    let alternative = if kind == "Login" {
        "store the password in a mode-0600 file and start futu-opend with --login-pwd-file"
    } else {
        "use FUTU_TRADE_PWD or futucli unlock-trade --from-stdin"
    };
    bail!(
        "{kind} password was not read: packaged macOS futucli/futu-opend/futu-mcp binaries \
         have distinct ad-hoc signing identities, so cross-binary Keychain sharing is not \
         supported; {alternative}"
    )
}

#[cfg(not(target_os = "macos"))]
fn ensure_cross_binary_keychain_write_supported(_kind: &str) -> Result<()> {
    Ok(())
}

fn secret_store_write_error(kind: &str, error: SecretStoreError) -> anyhow::Error {
    anyhow::anyhow!(
        "write {kind} password to OS credential store failed within the {}-second safety \
         boundary: {error}. {}",
        futu_auth::secret_store::KEYRING_OPERATION_TIMEOUT.as_secs(),
        mutation_outcome_note(&error)
    )
}

fn secret_store_delete_error(kind: &str, error: SecretStoreError) -> anyhow::Error {
    anyhow::anyhow!(
        "delete {kind} password from OS credential store failed within the {}-second safety \
         boundary: {error}. {} On macOS, retry manually with `security delete-generic-password \
         -s futu-opend-rs -a '{kind}-password.<account>'`.",
        futu_auth::secret_store::KEYRING_OPERATION_TIMEOUT.as_secs(),
        mutation_outcome_note(&error)
    )
}

fn mutation_outcome_note(error: &SecretStoreError) -> &'static str {
    match error {
        SecretStoreError::Timeout { .. } | SecretStoreError::WorkerDisconnected { .. } => {
            "The operation outcome is unknown; verify the credential store before retrying cleanup."
        }
        SecretStoreError::OperationInFlight
        | SecretStoreError::CircuitOpen
        | SecretStoreError::Backend { .. } => "No successful mutation was confirmed.",
    }
}

/// `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_password_for_keychain_write("Trade", from_stdin, read_keychain_password)?;
    let username = futu_auth::keyring_username_for_trade_pwd(account);
    futu_auth::secret_store::set_password(&username, &pwd)
        .map_err(|error| secret_store_write_error("trade", error))?;
    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);
    match futu_auth::secret_store::delete_credential(&username) {
        Ok(DeleteOutcome::Deleted) => {
            println!("✓ trade password removed from OS keychain (account={account})")
        }
        Ok(DeleteOutcome::NoEntry) => println!("(no entry existed; nothing to remove)"),
        Err(error) => return Err(secret_store_delete_error("trade", error)),
    }
    Ok(())
}

/// `futucli set-login-pwd --account <id>` —— 把登录密码写入 OS keychain（v1.4.18+）。
///
/// 每个账号一条独立条目（username = `login-password.<account>`），避免多账号
/// 互相覆盖。`futu-opend` 启动时如果没传 `--login-pwd` / `FUTU_PWD`，会从
/// 这里读取对应 account 的密码。
///
/// macOS 发布包的三个 binary 使用不同 ad-hoc signing identity，因此该命令
/// 在读取密码前 fail-closed；Linux / Windows 继续使用原生 credential store。
pub async fn set_login_pwd(account: &str, from_stdin: bool) -> Result<()> {
    if account.is_empty() {
        bail!("--account is required");
    }
    let pwd = read_password_for_keychain_write("Login", from_stdin, read_keychain_password)?;
    let username = futu_auth::keyring_username_for_login_pwd(account);
    futu_auth::secret_store::set_password(&username, &pwd)
        .map_err(|error| secret_store_write_error("login", error))?;
    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);
    match futu_auth::secret_store::delete_credential(&username) {
        Ok(DeleteOutcome::Deleted) => {
            println!("✓ login password removed from OS keychain (account={account})")
        }
        Ok(DeleteOutcome::NoEntry) => println!("(no entry existed; nothing to remove)"),
        Err(error) => return Err(secret_store_delete_error("login", error)),
    }
    Ok(())
}

#[cfg(test)]
mod tests;