futu_rest/routes/trd/

unlock.rs

//! REST trade unlock helper functions.

use std::net::SocketAddr;
use std::sync::Arc;

use axum::extract::{ConnectInfo, Extension, Json, State};
use axum::http::StatusCode;
use serde_json::Value;

use futu_auth::KeyRecord;
use futu_core::proto_id;
use futu_proto::trd_unlock_trade;

use super::ApiResult;
use crate::adapter::{self, RestState};

/// POST /api/unlock-trade — 解锁交易
///
/// v1.4.27 修（BUG-1）：服务端返回"交易密码输入错误"时，自动在 `ret_msg`
/// 追加一句提醒"交易密码 ≠ 登录密码"，避免用户因为不知道这个差异而连续
/// 错 10 次导致账户被锁（需联系券商客服恢复）。加拿大同事 v1.4.26 回归
/// 测试时踩到这个坑。
///
/// v1.4.96 BUG #008 hotfix (external reviewer double-tester report 2026-04-26): MCP tool
/// schema 的 OTP 字段叫 `otp` (别名 `token` / `one_time_password`), REST
/// 只认 `sec_otp`. 用户按 MCP doc 调 REST 时 silent drop, daemon log
/// `has_otp=false`, 用户误以为账户 2FA 没绑反复排查 (实际 daemon schema 错).
/// 本版加 REST 端 alias 兼容: `otp` / `token` / `one_time_password` → `sec_otp`.
pub async fn unlock_trade(
    State(state): State<RestState>,
    rec: Option<Extension<Arc<KeyRecord>>>,
    peer: Option<Extension<ConnectInfo<SocketAddr>>>,
    Json(mut body): Json<Value>,
) -> ApiResult {
    let peer_addr = peer.map(|Extension(ConnectInfo(addr))| addr);
    if !unlock_transport_is_trusted(peer_addr) {
        return Err((
            StatusCode::FORBIDDEN,
            Json(serde_json::json!({
                "error": "remote plaintext REST unlock is forbidden",
                "diagnostic_key": "rest.unlock_trade.local_transport_required",
                "action": "call /api/unlock-trade from loopback, or terminate TLS in a same-host reverse proxy that forwards to the loopback REST listener"
            })),
        ));
    }

    // BUG #008 alias: `otp` / `token` / `one_time_password` → `sec_otp`
    apply_unlock_trade_otp_aliases(&mut body);

    // v1.4.104 codex round 1 F1 (P1) fix: REST handler-level acc_ids
    // whitelist enforcement (受限 key 不能解锁 unauthorized acc_ids; 空
    // acc_ids + 受限 key = ambiguous unlock-all → fail-closed reject).
    //
    // 为什么不在 middleware/pipeline body_aware 跑: REST middleware 阶段
    // body 还是 raw JSON, proto_id=None 不跑 body_aware. handler 这里
    // body 已 parse 但还没 proto encode, 取 c2s.acc_ids 即可. 与 v1.4.104
    // 阶段 7-5 MCP futu_unlock_trade special path 行为对齐.
    if let Some(Extension(rec_ref)) = rec.as_ref()
        && let Some(allowed) = &rec_ref.allowed_acc_ids
        && !allowed.is_empty()
    {
        let acc_ids = match extract_unlock_trade_acc_ids(&body) {
            Ok(Some(acc_ids)) => acc_ids,
            Ok(None) => Vec::new(),
            Err(reason) => {
                return Err((
                    StatusCode::BAD_REQUEST,
                    Json(serde_json::json!({
                        "error": format!("/api/unlock-trade: {reason}")
                    })),
                ));
            }
        };
        if acc_ids.is_empty() {
            // ambiguous unlock-all under restricted key → reject fail-closed
            return Err((
                StatusCode::FORBIDDEN,
                Json(serde_json::json!({
                    "error": format!(
                        "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_ref.id
                    ),
                    "hint": "pass acc_ids: [<your-allowed-acc-id>] in request body c2s",
                })),
            ));
        }
        for id in &acc_ids {
            if !allowed.contains(id) {
                futu_auth::audit::reject(
                    "rest",
                    "/api/unlock-trade",
                    &rec_ref.id,
                    &format!("acc_id {id} not in allowed list"),
                );
                return Err((
                    StatusCode::FORBIDDEN,
                    Json(serde_json::json!({ "error": "forbidden" })),
                ));
            }
        }
    }

    let resp = adapter::proto_request::<trd_unlock_trade::Request, trd_unlock_trade::Response>(
        &state,
        proto_id::TRD_UNLOCK_TRADE,
        Some(body),
    )
    .await?;

    // 拆出 JSON 看 ret_msg 是否含"交易密码"关键词 → 追加引导提示
    let Json(mut v) = resp;
    let is_err = v
        .get("ret_type")
        .and_then(|t| t.as_i64())
        .map(|t| t != 0)
        .unwrap_or(false);
    if is_err && let Some(msg) = v.get("ret_msg").and_then(|m| m.as_str()) {
        // 服务端中文 msg 里密码错误一般含 "交易密码" 或 "密码错误"
        if msg.contains("交易密码") || msg.contains("密码错误") || msg.contains("密码输入")
        {
            let hint = "[提示] 交易密码与登录密码独立；如未设置，先用 \
                            `futucli set-trade-pwd` 存入 OS keychain，重复错密码后券商会锁账户。";
            let new_msg = format!("{msg} {hint}");
            if let Some(obj) = v.as_object_mut() {
                obj.insert("ret_msg".to_string(), Value::String(new_msg));
            }
        }
    }
    Ok(Json(v))
}

pub(crate) fn unlock_transport_is_trusted(peer: Option<SocketAddr>) -> bool {
    // Production axum serving always injects ConnectInfo. `None` is retained
    // for embedded/in-process Router tests where no network transport exists.
    peer.is_none_or(|addr| addr.ip().is_loopback())
}

fn extract_unlock_trade_acc_ids(body: &Value) -> Result<Option<Vec<u64>>, String> {
    let Some(c2s) = body.get("c2s") else {
        return Ok(None);
    };
    let Some(raw) = c2s.get("acc_ids").or_else(|| c2s.get("accIds")) else {
        return Ok(None);
    };
    let Some(items) = raw.as_array() else {
        return Err("c2s.acc_ids must be an array of positive integer acc_id values".to_string());
    };

    let mut acc_ids = Vec::with_capacity(items.len());
    for (idx, value) in items.iter().enumerate() {
        let Some(acc_id) = value.as_u64() else {
            return Err(format!(
                "c2s.acc_ids[{idx}] must be a positive integer acc_id"
            ));
        };
        if acc_id == 0 {
            return Err(format!(
                "c2s.acc_ids[{idx}] contains zero — call /api/accounts to discover real acc_id values"
            ));
        }
        acc_ids.push(acc_id);
    }
    Ok(Some(acc_ids))
}

/// v1.4.96 BUG #008 helper (external reviewer MCP/REST OTP 字段不一致 silent drop fix).
///
/// MCP tool schema 用 `otp` / `token` / `one_time_password` 作为 OTP 字段名
/// (3 alias). REST `/api/unlock-trade` 只认 `sec_otp` / `secOtp`. 用户按 MCP
/// doc 调 REST 时 silent drop, 用户误以为账户 2FA 没绑.
///
/// 本 helper 把 body 顶层 (含 `c2s` 嵌套) 的 alias key (`otp` / `token` /
/// `one_time_password` / `oneTimePassword`) rename 为 `sec_otp`. 优先级:
/// 用户显式传 `sec_otp` 或 `secOtp` (任一 canonical form) 都优先, alias 仅作
/// strip — 不覆盖.
///
/// v1.4.97 codex P2 #2 fix (audit feedback 2026-04-27): 之前 helper 只把
/// `sec_otp` (snake_case) 当 canonical, 把 `secOtp` (camelCase) 当未知字段.
/// 用户传 `{secOtp: "explicit", otp: "alias"}` 会被 helper promote
/// `otp → sec_otp`, 之后 normalize_json_keys_snake_case 把 secOtp 也转成
/// sec_otp 与 alias-promoted 值碰撞 — 后者 wins, 显式 secOtp 被 alias 覆盖,
/// 违反 "explicit field 优先, alias 仅作兼容" 契约.
///
/// 修后规则: `sec_otp` OR `secOtp` 任一存在 → 仅 strip alias, 保留 explicit;
/// 同样新增 `oneTimePassword` (camelCase) 作为 alias (与 `one_time_password`
/// 等价).
pub(crate) fn apply_unlock_trade_otp_aliases(body: &mut Value) {
    /// alias key 全清单. snake_case + camelCase 双写 (helper 在 normalize 之前
    /// 跑, 所以 camelCase form 必须显式 enum). canonical form (`sec_otp` /
    /// `secOtp`) 不在此列表 — 它们走 has_canonical 分支保留.
    const ALIAS_KEYS: &[&str] = &["otp", "token", "one_time_password", "oneTimePassword"];

    fn rename_alias_in_object(map: &mut serde_json::Map<String, Value>) {
        // v1.4.97 codex P2 #2: 同时识别 `sec_otp` (snake_case) AND `secOtp`
        // (camelCase) 两种 canonical form. 任一存在即 "用户显式给了 OTP",
        // 仅 strip alias key, 不 promote (避免后续 normalize 阶段碰撞覆盖).
        let has_canonical = map.contains_key("sec_otp") || map.contains_key("secOtp");
        if has_canonical {
            // 仅 strip alias keys, 保留用户显式 canonical (sec_otp / secOtp)
            for alias in ALIAS_KEYS {
                map.remove(*alias);
            }
            return;
        }
        // 没显式 canonical: 取首个非空 alias rename 为 sec_otp, strip 其余
        let mut renamed = false;
        for alias in ALIAS_KEYS {
            if let Some(v) = map.remove(*alias)
                && !renamed
            {
                map.insert("sec_otp".to_string(), v);
                renamed = true;
            }
            // 若 renamed 已 true, 当前 alias (若存在) 已 remove, 不重新插入
        }
    }
    if let Some(map) = body.as_object_mut() {
        rename_alias_in_object(map);
    }
    if let Some(c2s) = body.get_mut("c2s").and_then(|c| c.as_object_mut()) {
        rename_alias_in_object(c2s);
    }
}

#[cfg(test)]
mod acc_ids_tests;

#[cfg(test)]
mod otp_alias_tests;

#[cfg(test)]
mod transport_tests;