futu_backend/auth/

broker.rs

//! Broker 通道鉴权
//!
//! 平台登录成功后，给每个已授权 broker（Futu HK/US/SG/AU/JP/MY/CA）发一个
//! `POST https://{broker_auth_domain}/broker_auth/client_auth` 请求，换取
//! `broker_client_sig` + `broker_client_key` + `customer_id`。这些 broker
//! 级凭据是 broker TCP 通道 CMD 1001 登录的输入。
//!
//! 对齐 C++：
//! - `FTLogin/Src/ftlogin/config/impl/broker_config.cpp:9-18`（broker_id 映射表）
//! - `FTLogin/Src/ftlogin/config/impl/env_config.cpp:41-46`（7 个 broker 的 auth_domain）
//! - `FTLogin/Src/ftlogin/config/impl/env_config.cpp:163-167`（HK auth_domain 本地替换）
//! - `FTLogin/Src/ftlogin/auth/impl/auth_impl.cpp:2415-2422`（InitRequest 先走 GetReplacedDomain）
//! - `FTLogin/Src/ftlogin/auth/impl/auth_impl.cpp:2439-2565`（HTTP/WebTCP 失败后走 retry domain / retry IP）
//! - `FTLogin/Src/ftlogin/auth/impl/auth_ip_list.cpp:75-190,427-516`（broker auth retry IP 池）
//! - `FTLogin/Src/ftlogin/auth/impl/auth_impl.cpp:640-674` `RefreshBrokerClientSig`
//! - `FTLogin/Src/ftlogin/auth/impl/auth_impl.cpp:3378-3480` `ParseBrokerAuthResponse`

use std::{
    net::{IpAddr, SocketAddr},
    sync::{Arc, Mutex},
};

use futu_core::error::{FutuError, Result};
use futu_core::log_redact::endpoint_log_fingerprint;

use super::auth_ip_list;
use super::commconfig::AuthGuaranteedDomainMap;
use super::redact::uid_log_fingerprint;

mod retry_ip;
use retry_ip::fetch_broker_auth_retry_ip_snapshot;
pub(crate) use retry_ip::{broker_auth_retry_ip_candidates, broker_auth_retry_ips};
#[cfg(test)]
pub(crate) use retry_ip::{
    broker_auth_retry_ip_list_url, broker_auth_retry_ip_request_headers,
    parse_broker_auth_retry_ip_snapshot,
};

/// 单个 broker 通道的配置 —— broker_id → (名字 / conn_identity / broker auth HTTP 域名)
///
/// 对齐 C++：
/// - `FTLogin/Src/ftlogin/config/impl/broker_config.cpp:9-18`（broker_id → chn_type + auth_domain 键）
/// - `FTLogin/Src/ftlogin/config/impl/env_config.cpp:41-43`（auth_domain 字符串）
/// - `FTLogin/Src/ftlogin/channel/impl/proto/FTConnCmn.proto:27-40`（conn_identity 值）
#[derive(Debug, Clone, Copy)]
pub struct BrokerConfig {
    pub broker_id: u32,
    pub name: &'static str,
    /// 登录协议 CMD 1001 LoginReq.encrypt_data.conn_identity
    pub conn_identity: u32,
    /// broker_auth HTTP POST 的域名前缀（不含 scheme）
    pub auth_domain: &'static str,
}

/// C++ `broker_config.cpp:9-18` 静态表里的 broker_id。
///
/// 注意：1022 AirStar 在 C++ 表里存在，但 auth_domain 为空字符串。Rust 当前
/// broker-auth 只能为有 auth_domain 的 broker 建通道；1022 需要先找到 C++
/// 空 auth_domain 下的真实鉴权路径，不能用空域名硬拼 HTTP 请求。
pub fn is_cpp_known_broker_id(broker_id: u32) -> bool {
    matches!(
        broker_id,
        1001 | 1007 | 1008 | 1009 | 1012 | 1017 | 1019 | 1022
    )
}

/// broker_id → `BrokerConfig` 映射，对齐 C++ `broker_config.cpp:9-18` 中
/// auth_domain 非空、Rust 可建立 broker-auth 通道的子集。
/// 未知 / 当前不可建通道的 broker_id 返回 `None`（路由时 skip）。
///
/// 域名来源：C++ `env_config.cpp:41-46`（kDomainBroker{Hk/Us/Sg/Au/Jp/My/Ca}Auth）。
/// `conn_identity` 来源：C++ `FTConnCmn.proto:27-35` `CONN_BROKER_FUTU_*`。
///
/// Futu AirStar (1022) 在 C++ `broker_config.cpp:17` 的 auth_domain 字段为空字符串，
/// 跳过。
pub fn broker_config(broker_id: u32) -> Option<BrokerConfig> {
    Some(match broker_id {
        1001 => BrokerConfig {
            broker_id: 1001,
            name: "Futu HK",
            conn_identity: 1001,
            auth_domain: "authority.futuhk.com",
        },
        1007 => BrokerConfig {
            broker_id: 1007,
            name: "Futu US",
            conn_identity: 1007,
            auth_domain: "authority.us.moomoo.com",
        },
        1008 => BrokerConfig {
            broker_id: 1008,
            name: "Futu SG",
            conn_identity: 1008,
            auth_domain: "authority.sg.moomoo.com",
        },
        1009 => BrokerConfig {
            broker_id: 1009,
            name: "Futu AU",
            conn_identity: 1009,
            auth_domain: "authority.au.moomoo.com",
        },
        1012 => BrokerConfig {
            broker_id: 1012,
            name: "Futu JP",
            conn_identity: 1012,
            auth_domain: "authority.jp.moomoo.com",
        },
        1017 => BrokerConfig {
            broker_id: 1017,
            name: "Futu MY",
            conn_identity: 1017,
            auth_domain: "authority.my.moomoo.com",
        },
        1019 => BrokerConfig {
            broker_id: 1019,
            name: "Futu CA",
            conn_identity: 1019,
            auth_domain: "authority.ca.moomoo.com",
        },
        _ => return None,
    })
}

/// broker_auth HTTP 响应里提取出的 broker-specific 凭据
#[derive(Debug, Clone)]
pub struct BrokerAuth {
    pub broker_id: u32,
    pub customer_id: u64,
    pub broker_client_sig: Vec<u8>,
    pub broker_client_key: Vec<u8>,
}

/// C++ `FTAuthImpl::AuthReqStage` 的 broker-auth transport 阶段。
///
/// Ref:
/// - `FTLogin/Src/ftlogin/auth/impl/auth_impl.h:15-21`
/// - `FTLogin/Src/ftlogin/auth/impl/auth_impl.cpp:2512-2641`
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum BrokerAuthStage {
    WebTcp,
    Http,
    RetryDomain,
    RetryIp,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum BrokerAuthWebTcpSkipReason {
    StageNotWebTcp,
    NoAddrs,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) struct BrokerAuthTransportPlan {
    pub(crate) start_stage: BrokerAuthStage,
    pub(crate) webtcp_attempted: bool,
    pub(crate) webtcp_skip_reason: Option<BrokerAuthWebTcpSkipReason>,
}

pub(crate) fn broker_auth_transport_plan(
    start_stage: BrokerAuthStage,
    web_tcp_addr_count: usize,
) -> BrokerAuthTransportPlan {
    let webtcp_skip_reason = match (start_stage, web_tcp_addr_count) {
        (BrokerAuthStage::WebTcp, 1..) => None,
        (BrokerAuthStage::WebTcp, 0) => Some(BrokerAuthWebTcpSkipReason::NoAddrs),
        _ => Some(BrokerAuthWebTcpSkipReason::StageNotWebTcp),
    };
    BrokerAuthTransportPlan {
        start_stage,
        webtcp_attempted: webtcp_skip_reason.is_none(),
        webtcp_skip_reason,
    }
}

#[derive(Debug, Default)]
struct BrokerAuthRouteCacheInner {
    last_request_original_domain: String,
    last_success_stage: Option<BrokerAuthStage>,
    last_success_retry_ip: Option<String>,
}

/// C++ `FTAuthImpl` 的 broker-auth 成功阶段缓存。
///
/// 这是一个单槽缓存，不是 per-domain map：C++ 只保存
/// `last_request_original_domain_` / `last_success_stage_` /
/// `last_success_retry_ip_` 三个字段。相同 original domain 的后续请求会直接
/// 从上次成功阶段开始；不同 domain 仍按 init 路径走。
#[derive(Debug, Clone, Default)]
pub struct BrokerAuthRouteCache {
    inner: Arc<Mutex<BrokerAuthRouteCacheInner>>,
}

impl BrokerAuthRouteCache {
    pub(crate) fn preferred_stage(&self, original_domain: &str) -> Option<BrokerAuthStage> {
        let guard = self
            .inner
            .lock()
            .unwrap_or_else(|poisoned| poisoned.into_inner());
        (guard.last_request_original_domain == original_domain)
            .then_some(guard.last_success_stage)
            .flatten()
    }

    pub(crate) fn cached_retry_ip(&self, original_domain: &str) -> Option<String> {
        let guard = self
            .inner
            .lock()
            .unwrap_or_else(|poisoned| poisoned.into_inner());
        (guard.last_request_original_domain == original_domain)
            .then(|| guard.last_success_retry_ip.clone())
            .flatten()
    }

    pub(crate) fn record_success(
        &self,
        original_domain: &str,
        stage: BrokerAuthStage,
        retry_ip: Option<String>,
    ) {
        let mut guard = self
            .inner
            .lock()
            .unwrap_or_else(|poisoned| poisoned.into_inner());
        guard.last_request_original_domain = original_domain.to_string();
        guard.last_success_stage = Some(stage);
        guard.last_success_retry_ip = retry_ip;
    }
}

/// C++ `auth_cryptor.cpp:9-10` 的两把默认 key —— broker_auth 响应里的
/// `broker_client_key` 是用这把 key 而**不是** rand_key 做 AES 加密的。
/// 先试 AES-256（新版），失败兜底 AES-128（旧版）。
/// 对齐 C++ `FTAuthCryptor::DecryptByRandKey(data, nullptr)` 分支（line 324-332）。
const AUTH_DEFAULT_KEY_32: &[u8] = b"5_B8tYqx^@aVJ6Vra2fi858@(5BGVYcJ";
const AUTH_DEFAULT_KEY_16: &[u8] = b"@bsOj)h$ZHJx*TDI";

/// C++ FTLogin `EnvConfig::GetReplacedDomain` 的本地 broker-auth 规则。
///
/// 证据：
/// - `env_config.cpp:163-167`: `authority.futuhk.com` 本地替换到
///   `authfthk.futuhn.com`
/// - `auth_impl.cpp:2415-2422`: 构造 broker auth URL 前先调用
///   `GetReplacedDomain(domain)`
///
/// 这里不是业务 hardcode，而是 FTLogin wire 层内置域名替换。漏掉它会让 Rust
/// 直接打 `authority.futuhk.com`，external reviewer 真机反馈该域名在外部环境 TLS reset。
fn broker_auth_replaced_domain(domain: &str) -> String {
    match domain {
        "authority.futuhk.com" => "authfthk.futuhn.com".to_string(),
        _ => domain.to_string(),
    }
}

/// broker auth 域名候选。首选 FTLogin 的 replaced domain；失败后才带上 C++
/// `GetRetryDomain` 的 guaranteed domain。retry IP 阶段由调用方单独处理。
///
/// 证据：
/// - `auth_impl.cpp:2491-2527`: WebTcp/HTTP 失败后依次重试 retry domain / retry IP
/// - `auth_impl.cpp:2464-2487`: HK 本地兜底域名按 AppType 选 futunn / moomoo
/// - `env_config.cpp:50-51`: `authfthk.futunn.com` / `authfthk.moomoo.com`
pub(crate) fn broker_auth_domain_candidates(
    cfg: BrokerConfig,
    client_type: u8,
    auth_guaranteed_domains: &AuthGuaranteedDomainMap,
    auth_guaranteed_domains_configured: bool,
) -> Vec<String> {
    let mut domains = Vec::with_capacity(4);

    let replaced = broker_auth_replaced_domain(cfg.auth_domain);
    domains.push(replaced.clone());

    if let Some(retry_domain) = auth_guaranteed_domains
        .get(cfg.auth_domain)
        .filter(|domain| !domain.is_empty())
    {
        domains.push(broker_auth_replaced_domain(retry_domain));
    } else if !auth_guaranteed_domains_configured && cfg.auth_domain == "authority.futuhk.com" {
        domains.push(if client_type == 60 {
            "authfthk.moomoo.com".to_string()
        } else {
            "authfthk.futunn.com".to_string()
        });
    }

    domains.dedup();
    domains
}

enum BrokerAuthAttemptError {
    Transport(String),
    Json(String),
}

async fn post_broker_auth_json(
    http: &reqwest::Client,
    client_type: u8,
    url: &str,
    body: &serde_json::Value,
    device_id: &str,
) -> std::result::Result<serde_json::Value, BrokerAuthAttemptError> {
    let headers = super::http_client::auth_business_headers(client_type, device_id)
        .map_err(|e| BrokerAuthAttemptError::Json(format!("broker_auth headers: {e}")))?;
    let response = http
        .post(url)
        .headers(headers)
        .json(body)
        .send()
        .await
        .map_err(|e| BrokerAuthAttemptError::Transport(e.to_string()))?;
    response
        .json::<serde_json::Value>()
        .await
        .map_err(|e| BrokerAuthAttemptError::Json(e.to_string()))
}

pub(crate) async fn broker_auth_init_stage_from_site_config(
    web_tcp_identity: u32,
    url: &str,
    site_config: Option<&super::site_config::SharedSiteConfig>,
) -> BrokerAuthStage {
    let Some(site_config) = site_config else {
        return BrokerAuthStage::WebTcp;
    };
    let parsed = match reqwest::Url::parse(url) {
        Ok(parsed) => parsed,
        Err(e) => {
            tracing::warn!(url, error = %e, "broker_auth site_config URL parse failed; selecting HTTP");
            return BrokerAuthStage::Http;
        }
    };
    let Some(host) = parsed.host_str() else {
        tracing::warn!(
            url,
            "broker_auth site_config URL has no host; selecting HTTP"
        );
        return BrokerAuthStage::Http;
    };

    let Some(config) = super::site_config::wait_latest(site_config).await else {
        tracing::warn!(
            web_identity = web_tcp_identity,
            url,
            "broker_auth site_config not loaded before C++ wait deadline; selecting HTTP"
        );
        return BrokerAuthStage::Http;
    };

    match config.query(web_tcp_identity, host, parsed.path()) {
        super::site_config::WebChannelConfigType::Http => BrokerAuthStage::Http,
        super::site_config::WebChannelConfigType::WebTcpShort
        | super::site_config::WebChannelConfigType::WebTcpLong => BrokerAuthStage::WebTcp,
    }
}

/// 向 broker auth 域名发 `/broker_auth/client_auth` POST 请求，换取
/// `broker_client_sig` + `broker_client_key`。
///
/// 对齐 C++ `auth_impl.cpp:640-674`（`RefreshBrokerClientSig`）+
/// `auth_impl.cpp:3378-3480`（`ParseBrokerAuthResponse`）：
/// - URL：`POST https://{broker_auth_domain}/broker_auth/client_auth`
/// - Body：`{"uid", "auth_code", "device_id", "broker_id"}`
/// - 响应 result 里的 `broker_client_key` 是 base64 编码 + AES-CBC-MD5 加密过的
///
/// ⚠️ 解密不是用 `rand_key`！对齐 `auth_impl.cpp:3434` —— 该处调用
/// `DecryptByRandKey(&broker_client_key, nullptr)`，nullptr 触发
/// `auth_cryptor.cpp:324-332` 分支：**用固定默认 key 解密**（先试 AES-256
/// `AUTH_DEFAULT_KEY_32`，失败兜底 AES-128 `AUTH_DEFAULT_KEY`），**不是**
/// Platform client_key 用的 rand_key。
pub struct BrokerAuthRequest<'a> {
    pub http: &'a reqwest::Client,
    pub client_type: u8,
    pub uid: u64,
    pub broker_id: u32,
    pub auth_code: &'a str,
    pub device_id: &'a str,
    pub web_tcp_identity: u32,
    pub web_tcp_addrs: &'a [(String, u16)],
    pub site_config: Option<&'a super::site_config::SharedSiteConfig>,
    pub auth_guaranteed_domains: &'a AuthGuaranteedDomainMap,
    pub auth_guaranteed_domains_configured: bool,
    pub route_cache: Option<&'a BrokerAuthRouteCache>,
}

pub async fn broker_auth(input: BrokerAuthRequest<'_>) -> Result<BrokerAuth> {
    let BrokerAuthRequest {
        http,
        client_type,
        uid,
        broker_id,
        auth_code,
        device_id,
        web_tcp_identity,
        web_tcp_addrs,
        site_config,
        auth_guaranteed_domains,
        auth_guaranteed_domains_configured,
        route_cache,
    } = input;

    let cfg = broker_config(broker_id).ok_or_else(|| {
        FutuError::Codec(format!(
            "broker_auth: unknown broker_id {broker_id} (not in broker_config map)"
        ))
    })?;

    let body = serde_json::json!({
        "uid": uid,
        "auth_code": auth_code,
        "device_id": device_id,
        "broker_id": broker_id,
    });

    let domains = broker_auth_domain_candidates(
        cfg,
        client_type,
        auth_guaranteed_domains,
        auth_guaranteed_domains_configured,
    );
    let primary_domain = broker_auth_replaced_domain(cfg.auth_domain);
    let primary_url = format!("https://{primary_domain}/broker_auth/client_auth");
    let (start_stage, start_stage_source) = match route_cache
        .and_then(|cache| cache.preferred_stage(cfg.auth_domain))
    {
        Some(stage) => (stage, "route_cache"),
        None => (
            broker_auth_init_stage_from_site_config(web_tcp_identity, &primary_url, site_config)
                .await,
            "site_config",
        ),
    };
    let transport_plan = broker_auth_transport_plan(start_stage, web_tcp_addrs.len());
    if start_stage != BrokerAuthStage::WebTcp {
        tracing::debug!(
            broker_id,
            original_domain = cfg.auth_domain,
            stage = ?start_stage,
            source = start_stage_source,
            "broker_auth starting from selected FTLogin stage"
        );
    } else if transport_plan.webtcp_skip_reason == Some(BrokerAuthWebTcpSkipReason::NoAddrs) {
        tracing::warn!(
            broker_id,
            original_domain = cfg.auth_domain,
            web_identity = web_tcp_identity,
            source = start_stage_source,
            "broker_auth WebTCP-short selected but no WebTCP addresses are loaded; falling back to HTTP domain"
        );
    }
    let mut last_network_err: Option<String> = None;
    let mut resp: Option<(serde_json::Value, BrokerAuthStage, Option<String>)> = None;

    // C++ order: WebTCP-short -> HTTP domain -> retry IP, unless the route
    // cache or site-config moves the init stage forward. The WebTCP stage uses
    // server-provided IP pools and avoids fragile system DNS, while retry IP is
    // only a final floor.
    if transport_plan.webtcp_attempted {
        tracing::debug!(
            broker_id,
            uid_fp = %uid_log_fingerprint(uid),
            web_identity = web_tcp_identity,
            addrs = web_tcp_addrs.len(),
            url = %primary_url,
            "POST /broker_auth/client_auth via WebTCP-short"
        );
        match super::webtcp::post_json_via_webtcp(
            client_type,
            web_tcp_identity,
            web_tcp_addrs,
            &primary_url,
            &body,
            device_id,
        )
        .await
        {
            Ok(value) => {
                resp = Some((value, BrokerAuthStage::WebTcp, None));
            }
            Err(e) => {
                let allows_http_fallback = e.allows_http_fallback();
                last_network_err = Some(format!("webtcp identity {web_tcp_identity}: {e}"));
                if allows_http_fallback {
                    tracing::warn!(
                        broker_id,
                        web_identity = web_tcp_identity,
                        addrs = web_tcp_addrs.len(),
                        error = %e,
                        "broker_auth WebTCP-short failed; falling back to HTTP domain"
                    );
                } else {
                    tracing::warn!(
                        broker_id,
                        web_identity = web_tcp_identity,
                        addrs = web_tcp_addrs.len(),
                        error = %e,
                        "broker_auth WebTCP-short failed with no-fallback response"
                    );
                    return Err(e.into_futu_error());
                }
            }
        }
    }

    let domain_start = match start_stage {
        BrokerAuthStage::WebTcp | BrokerAuthStage::Http => 0,
        BrokerAuthStage::RetryDomain => 1,
        BrokerAuthStage::RetryIp => domains.len(),
    };
    for (idx, domain) in domains.iter().enumerate().skip(domain_start) {
        if resp.is_some() {
            break;
        }
        let stage = if idx == 0 {
            BrokerAuthStage::Http
        } else {
            BrokerAuthStage::RetryDomain
        };
        let url = format!("https://{domain}/broker_auth/client_auth");
        tracing::debug!(
            broker_id,
            uid_fp = %uid_log_fingerprint(uid),
            url = %url,
            original_domain = cfg.auth_domain,
            stage = ?stage,
            "POST /broker_auth/client_auth"
        );

        match post_broker_auth_json(http, client_type, &url, &body, device_id).await {
            Ok(value) => {
                resp = Some((value, stage, None));
            }
            Err(BrokerAuthAttemptError::Transport(e)) => {
                last_network_err = Some(format!("{domain}: {e}"));
                tracing::warn!(
                    broker_id,
                    domain,
                    error = %e,
                    "broker_auth transport failed; trying next domain if available"
                );
                continue;
            }
            Err(BrokerAuthAttemptError::Json(e)) => {
                return Err(FutuError::Codec(format!(
                    "broker_auth json from {domain}: {e}"
                )));
            }
        }
    }

    let retry_domain = broker_auth_replaced_domain(cfg.auth_domain);
    let cached_retry_ip = if start_stage == BrokerAuthStage::RetryIp {
        route_cache.and_then(|cache| cache.cached_retry_ip(cfg.auth_domain))
    } else {
        None
    };
    let dynamic_retry_ip_snapshot = if resp.is_none() && cached_retry_ip.is_none() {
        fetch_broker_auth_retry_ip_snapshot(http, client_type).await
    } else {
        None
    };
    let retry_ip_candidates: Vec<String> = if let Some(ip) = cached_retry_ip {
        vec![ip]
    } else if let Some(snapshot) = dynamic_retry_ip_snapshot.as_ref() {
        broker_auth_retry_ip_candidates(broker_id, Some(snapshot))
    } else {
        auth_ip_list::load_default_or_hardcoded_snapshot().broker_retry_ip_candidates(broker_id)
    };
    for ip in &retry_ip_candidates {
        if resp.is_some() {
            break;
        }
        let ip_addr = ip.parse::<IpAddr>().map_err(|e| {
            FutuError::Codec(format!(
                "invalid hardcoded broker_auth retry ip broker_id={broker_id} ip={ip}: {e}"
            ))
        })?;
        let addr = SocketAddr::new(ip_addr, 443);
        let ip_http = super::build_http_client_with_resolve(
            client_type,
            Some((retry_domain.as_str(), addr)),
        )?;
        let url = format!("https://{retry_domain}/broker_auth/client_auth");
        tracing::debug!(
            broker_id,
            uid_fp = %uid_log_fingerprint(uid),
            tls_domain = retry_domain,
            target_ip_fp = %endpoint_log_fingerprint(ip),
            "POST /broker_auth/client_auth via C++ retry IP"
        );
        match post_broker_auth_json(&ip_http, client_type, &url, &body, device_id).await {
            Ok(value) => {
                resp = Some((value, BrokerAuthStage::RetryIp, Some(ip.clone())));
                break;
            }
            Err(BrokerAuthAttemptError::Transport(e)) => {
                last_network_err = Some(format!(
                    "{retry_domain}@{}:443: {e}",
                    endpoint_log_fingerprint(ip)
                ));
                tracing::warn!(
                    broker_id,
                    tls_domain = retry_domain,
                    target_ip_fp = %endpoint_log_fingerprint(ip),
                    error = %e,
                    "broker_auth transport failed over retry IP; trying next IP/domain if available"
                );
            }
            Err(BrokerAuthAttemptError::Json(e)) => {
                return Err(FutuError::Codec(format!(
                    "broker_auth json from {retry_domain}@{}:443: {e}",
                    endpoint_log_fingerprint(ip)
                )));
            }
        }
    }

    let retry_ip_fps: Vec<String> = retry_ip_candidates
        .iter()
        .map(|ip| endpoint_log_fingerprint(ip))
        .collect();
    let resp = resp.ok_or_else(|| {
        FutuError::Network(std::io::Error::other(format!(
            "broker_auth transport failed for broker_id={broker_id}; attempted_webtcp_addrs={web_tcp_addrs:?}; attempted domains={domains:?}; attempted retry_ip_fps={retry_ip_fps:?}; last_error={}",
            last_network_err.unwrap_or_else(|| "none".to_string())
        )))
    })?;
    let (resp, success_stage, success_retry_ip) = resp;
    if let Some(cache) = route_cache {
        cache.record_success(cfg.auth_domain, success_stage, success_retry_ip.clone());
    }

    // 错误分支
    if let Some(err) = resp.get("error").and_then(|e| e.as_object()) {
        let code = err.get("error_code").and_then(|v| v.as_i64()).unwrap_or(-1);
        let msg = err
            .get("error_msg")
            .and_then(|v| v.as_str())
            .unwrap_or("unknown");
        if code != 0 {
            return Err(FutuError::ServerError {
                ret_type: code as i32,
                msg: format!("broker_auth broker_id={broker_id}: {msg}"),
            });
        }
    }

    let result = resp
        .get("result")
        .and_then(|r| r.as_object())
        .ok_or_else(|| FutuError::Codec("broker_auth: missing result".into()))?;

    let sig_b64 = result
        .get("broker_client_sig")
        .and_then(|v| v.as_str())
        .ok_or_else(|| FutuError::Codec("broker_auth: missing broker_client_sig".into()))?;
    let key_b64 = result
        .get("broker_client_key")
        .and_then(|v| v.as_str())
        .ok_or_else(|| FutuError::Codec("broker_auth: missing broker_client_key".into()))?;
    let customer_id = result.get("cid").and_then(|v| v.as_u64()).unwrap_or(0);
    if customer_id == 0 {
        return Err(FutuError::Codec(
            "broker_auth: cid missing or zero in response".into(),
        ));
    }

    use base64::Engine;
    let broker_client_sig = base64::engine::general_purpose::STANDARD
        .decode(sig_b64)
        .map_err(|e| FutuError::Codec(format!("broker_client_sig decode: {e}")))?;
    let ck_enc = base64::engine::general_purpose::STANDARD
        .decode(key_b64)
        .map_err(|e| FutuError::Codec(format!("broker_client_key decode: {e}")))?;

    // 对齐 C++ `DecryptByRandKey(data, nullptr)` 分支：先试 AES-256 默认 key，
    // 解密失败兜底 AES-128 —— broker 后端可能还在用旧版 16 字节默认 key
    let broker_client_key =
        match futu_net::encrypt::aes_cbc_md5_decrypt_var(AUTH_DEFAULT_KEY_32, &ck_enc) {
            Ok(k) => {
                tracing::debug!(
                    broker_id,
                    "broker_client_key decrypted with AUTH_DEFAULT_KEY_32 (AES-256)"
                );
                k
            }
            Err(e_256) => {
                tracing::debug!(
                    broker_id,
                    error = %e_256,
                    "AES-256 default key failed, fallback to AES-128"
                );
                futu_net::encrypt::aes_cbc_md5_decrypt_var(AUTH_DEFAULT_KEY_16, &ck_enc).map_err(
                    |e_128| {
                        FutuError::Codec(format!(
                            "broker_client_key decrypt failed with both default keys: \
                         AES-256={e_256}, AES-128={e_128}"
                        ))
                    },
                )?
            }
        };

    tracing::info!(
        broker_id,
        broker = cfg.name,
        customer_id_fp = %uid_log_fingerprint(customer_id),
        success_stage = ?success_stage,
        success_retry_ip_fp = success_retry_ip
            .as_deref()
            .map(endpoint_log_fingerprint)
            .unwrap_or_else(|| "none".to_string()),
        start_stage = ?transport_plan.start_stage,
        start_stage_source,
        webtcp_attempted = transport_plan.webtcp_attempted,
        webtcp_skip_reason = ?transport_plan.webtcp_skip_reason,
        webtcp_addrs = web_tcp_addrs.len(),
        web_identity = web_tcp_identity,
        client_sig_len = broker_client_sig.len(),
        client_key_len = broker_client_key.len(),
        "broker_auth success"
    );
    Ok(BrokerAuth {
        broker_id,
        customer_id,
        broker_client_sig,
        broker_client_key,
    })
}