futu_mcp/tools/

trade_unlock.rs

//! MCP trade unlock tool.

use rmcp::{
    RoleServer, handler::server::wrapper::Parameters, service::RequestContext, tool, tool_router,
};

use crate::guard;
use crate::tool_args::*;
use crate::tool_auth::{http_bearer_token, outcome_key_id_from_snapshot};

use super::FutuServer;

pub(crate) fn validate_unlock_trade_acc_ids(acc_ids: Option<&[u64]>) -> Result<(), String> {
    if let Some(ids) = acc_ids
        && let Some((idx, _)) = ids.iter().enumerate().find(|(_, id)| **id == 0)
    {
        return Err(format!(
            "futu_unlock_trade: acc_ids[{idx}] must be a positive non-zero acc_id; got 0"
        ));
    }
    Ok(())
}

#[tool_router(router = trade_unlock_tool_router, vis = "pub(crate)")]
impl FutuServer {
    #[tool(
        description = "⚠️ Opens a trade window for subsequent `futu_place_order` / `futu_modify_order` / `futu_cancel_order` / `futu_reconfirm_order` calls. Password is read from account-scoped OS keychain (via `futucli set-trade-pwd --account <login-account>` plus futu-mcp `--trade-pwd-account <login-account>`) or FUTU_TRADE_PWD env — NEVER pass it via tool args. Requires `trade:unlock` scope. **Lifetime**: once unlocked, all subsequent trade calls succeed without re-authenticating until gateway restart or an explicit `unlock=false` lock-back. Do NOT call this on every trade (server-side anti-abuse may throttle)."
    )]
    async fn futu_unlock_trade(
        &self,
        Parameters(req): Parameters<UnlockTradeReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        let args_hash = guard::args_short_hash(&req);
        tracing::warn!(
            target: futu_auth::audit::TARGET,
            iface = "mcp",
            endpoint = "futu_unlock_trade",
            unlock = req.unlock,
            args_hash = %args_hash,
            outcome = "request",
            "unlock_trade request received"
        );
        // v1.4.103 codex F5.3 (P1) round 5: 切到 caller-specific scope check.
        // 之前 require_tool_scope 只看 startup key, 受限 Bearer 仍可用 startup
        // key 的 trade:unlock scope 解锁所有账户.
        //
        // v1.4.104 阶段 7-5: 走 pipeline 做 caller-specific scope check + expiry
        // + audit. acc_ids 多元素白名单 enforcement 仍在本地 inline (special
        // semantic: 多 acc_id loop + "no acc_ids + restriction" reject; pipeline
        // 单一 explicit_acc_id 不足以覆盖).
        //
        // 流程:
        //   1. resolve caller credential (Bearer → verify, fail-closed; 无
        //      Bearer → fall back startup key PreVerified).
        //   2. pipeline: scope=TradeUnlock + audit_emit=true + commit_rate=false.
        //      Reject → return JSON error.
        //   3. inline per-acc_id whitelist enforcement (本节专属语义).
        let bearer_token = http_bearer_token(&req_ctx);
        let credential: futu_auth_pipeline::Credential<'_> = match bearer_token
            .as_deref()
            .filter(|s| !s.is_empty())
        {
            Some(t) => match self.state.key_store().verify(t) {
                Some(rec) => futu_auth_pipeline::Credential::PreVerified(rec),
                None => {
                    // codex F4 fail-closed: invalid Bearer → reject, 不 fall back
                    futu_auth::audit::reject(
                        "mcp",
                        "futu_unlock_trade",
                        "<bearer-invalid>",
                        "invalid Bearer (v1.4.103 audit F5.3 fail-closed)",
                    );
                    return Err(serde_json::json!({
                            "error": "futu_unlock_trade: invalid Bearer token (v1.4.103 audit F5.3 fail-closed)",
                            "status": "error",
                        })
                        .to_string());
                }
            },
            // v1.4.106 codex 0608 F2 (P1): startup fallback 用
            // `get_by_id_for_current_machine` 替代裸 `get_by_id`, 让 SIGHUP 收紧
            // allowed_machines 后能立即 reject (与 Bearer 路径 verify 行为对称).
            None => match self
                .state
                .authed_key()
                .and_then(|k| self.state.key_store().get_by_id_for_current_machine(&k.id))
            {
                Some(rec) => futu_auth_pipeline::Credential::PreVerified(rec),
                None => futu_auth_pipeline::Credential::None,
            },
        };

        let unlock_env = futu_auth_pipeline::AuthEnvelope {
            surface: futu_auth_pipeline::SurfaceId::Mcp,
            endpoint: futu_auth_pipeline::Endpoint::McpTool("futu_unlock_trade"),
            needed_scope: Some(futu_auth::Scope::TradeUnlock),
            credential,
            proto_id: None,
            body: &[],
            explicit_acc_id: None, // multi-acc 白名单单独 inline enforce
            explicit_ctx: None,
            commit_rate: false, // unlock 不计 rate
            audit_emit: true,
        };
        let caller_key_for_unlock = match futu_auth_pipeline::authenticate_request(
            self.state.key_store(),
            self.state.counters(),
            unlock_env,
        ) {
            futu_auth_pipeline::AuthDecision::Allow { rec, .. } => rec,
            futu_auth_pipeline::AuthDecision::Reject {
                kind,
                reason,
                audit_key_id,
            } => {
                use futu_auth_pipeline::RejectKind;
                let err_msg = match kind {
                    RejectKind::Unauthenticated => {
                        format!("futu_unlock_trade: API key required or expired ({reason})")
                    }
                    RejectKind::Forbidden => format!(
                        "futu_unlock_trade: API key {audit_key_id:?} forbidden — needs trade:unlock scope ({reason})"
                    ),
                    _ => reason.clone(),
                };
                return Err(serde_json::json!({
                    "error": err_msg,
                    "status": "error",
                })
                .to_string());
            }
        };
        if let Err(err) = validate_unlock_trade_acc_ids(req.acc_ids.as_deref()) {
            return Err(serde_json::json!({
                "error": err,
                "status": "error",
            })
            .to_string());
        }
        // 若 caller 的 key 有 allowed_acc_ids 限制 + caller 显式传 acc_ids:
        //   每个 acc_id 必须 ∈ allowed_acc_ids
        // 若 caller 显式 acc_ids 为 None / empty + key 有限制:
        //   reject (ambiguous — 不让"unlock all" silent 解锁未授权账户)
        if let Some(ref rec) = caller_key_for_unlock
            && let Some(ref allowed) = rec.allowed_acc_ids
            && !allowed.is_empty()
        {
            match req.acc_ids.as_ref() {
                Some(ids) if !ids.is_empty() => {
                    for id in ids {
                        if !allowed.contains(id) {
                            futu_auth::audit::reject(
                                "mcp",
                                "futu_unlock_trade",
                                &rec.id,
                                &format!("acc_id {id} not in allowed list"),
                            );
                            return Err(serde_json::json!({
                                "error": format!(
                                    "futu_unlock_trade: API key {:?} not allowed to unlock acc_id {id} (allowed_acc_ids restriction)",
                                    rec.id
                                ),
                                "status": "error",
                            })
                            .to_string());
                        }
                    }
                }
                _ => {
                    // 没传 acc_ids + key 有限制 → 不允许 silent unlock all
                    return Err(serde_json::json!({
                        "error": format!(
                            "futu_unlock_trade: API key {:?} has allowed_acc_ids restriction \
                             but acc_ids not specified. Restricted keys must explicitly pass \
                             acc_ids; unlock-all is rejected to prevent unauthorized broker \
                             unlock side effects.",
                            rec.id
                        ),
                        "status": "error",
                        "hint": "pass acc_ids: [<your-allowed-acc-id>]",
                    })
                    .to_string());
                }
            }
        }

        // lock 不需要密码，unlock 要从账号级 keychain/env 读。
        // MCP 只连接 gateway，不能从本进程可靠推断 daemon login account；
        // 因此账号 hint 来自 `--trade-pwd-account` / FUTU_TRADE_PWD_ACCOUNT。
        let pwd_md5 = if req.unlock {
            match crate::trade_pwd::get_trade_password_md5_for_account(
                self.state.trade_pwd_account(),
            ) {
                Ok(md5) => md5,
                Err(e) => {
                    let err = format!("unlock failed: {e}");
                    tracing::warn!(
                        target: futu_auth::audit::TARGET,
                        iface = "mcp",
                        endpoint = "futu_unlock_trade",
                        outcome = "failure",
                        reason = %err,
                        "unlock failed: no password source"
                    );
                    return Self::tool_err(err);
                }
            }
        } else {
            String::new()
        };

        let client = self.client_or_err().await?;
        let result = match futu_trd::account::unlock_trade(
            &client,
            &pwd_md5,
            req.unlock,
            req.otp.as_deref(),
            req.security_firm,
            req.acc_ids.clone().unwrap_or_default(),
        )
        .await
        {
            Ok(outcome) => {
                if outcome.need_otp {
                    // HIGH-2 修（code review）：need_otp=true 是 unlock 失败的错误
                    // 状态（用户需带 OTP 重试），应 set is_error=true 让 agent 通过
                    // top-level envelope 感知，不需要 parse JSON `ok` 字段。
                    // MED-NEW-1（2nd review）：加 `error` field 让 emit_trade_outcome
                    // 按 "failure" 记 audit log（之前 need_otp 会被错记 success）
                    Err(serde_json::json!({
                        "error": "unlock requires OTP (2FA token); pass otp= and retry",
                        "need_otp": true,
                        "message": outcome.message.unwrap_or_else(||
                            "此账号开启了令牌动态密码（2FA）。\
                             请重新调用 futu_unlock_trade 带 `otp` 参数（明文 OTP）".into()),
                        "failed_accounts": outcome.failed_accounts,
                        "status": "need_otp_retry",
                    })
                    .to_string())
                } else if !req.unlock {
                    Ok(
                        serde_json::json!({ "ok": true, "message": "trade locked on gateway" })
                            .to_string(),
                    )
                } else {
                    let msg = if outcome.total_unlocked < outcome.total_requested {
                        format!(
                            "部分账户解锁成功（{}/{}）。\
                             失败账户：{:?}（常见原因：品种权限未开通 / 影子子账户）",
                            outcome.total_unlocked,
                            outcome.total_requested,
                            outcome.failed_accounts
                        )
                    } else {
                        format!(
                            "trade unlocked ({} accounts); cipher cached until gateway restarts",
                            outcome.total_unlocked
                        )
                    };
                    if outcome.total_unlocked > 0 {
                        Ok(serde_json::json!({
                            "ok": true,
                            "need_otp": false,
                            "total_requested": outcome.total_requested,
                            "total_unlocked": outcome.total_unlocked,
                            "failed_accounts": outcome.failed_accounts,
                            "message": msg,
                        })
                        .to_string())
                    } else {
                        // MED-NEW-1（2nd review）：总失败时加 `error` 让 audit log 按
                        // failure 记录（不含则 emit_trade_outcome 错判 success）
                        Err(serde_json::json!({
                            "ok": false,
                            "error": "all accounts failed to unlock",
                            "need_otp": false,
                            "total_requested": outcome.total_requested,
                            "total_unlocked": outcome.total_unlocked,
                            "failed_accounts": outcome.failed_accounts,
                            "message": msg,
                        })
                        .to_string())
                    }
                }
            }
            Err(e) => Err(format!("unlock_trade RPC failed: {e}")),
        };
        // codex round 1 F5 (P2) v1.4.105 + v1.4.106 F4 alignment:
        // emit_trade_outcome 用 caller_key_for_unlock 的 key id (pipeline Allow
        // 时的 KeyRecord), **不**调 self.current_key_id(None) 重新 verify —
        // 防 HTTP per-request Bearer 调 unlock 时 outcome 被错归 startup key
        // (F5 root cause), 同时也防 SIGHUP race (F4 同模式 — dispatch 中途
        // SIGHUP revoke caller key, snapshot 仍 hold 住).
        //
        // legacy mode (caller_key_for_unlock = None, scope mode 关闭) → 退化
        // 到 startup authed_key (与 v1.4.103 兼容). authed_key 取 precheck 时
        // 的 ref (snapshot), 同样不重新查 KeyStore.
        let startup_key = self.state.authed_key();
        let outcome_key_id =
            outcome_key_id_from_snapshot(caller_key_for_unlock.as_ref(), startup_key.as_ref());
        guard::emit_trade_outcome(
            "futu_unlock_trade",
            outcome_key_id,
            &args_hash,
            Self::result_as_str(&result),
        );
        result
    }
}