futu_backend/auth/

mod.rs

// HTTP 认证模块 — 移植自成功项目 futuopend-rs
//
// 流程: salt → tgtgt → POST auth → (可能设备验证) → client_sig + client_key

use base64::Engine;
use futu_core::error::{FutuError, Result};

mod auth_ip_list;
mod broker;
pub mod redact;
/// v1.4.92 P1-D Tier A1: in-process relogin trigger (AuthRefresher trait + DefaultAuthRefresher).
pub mod refresh;
/// v1.4.93 G2 (CLAUDE.md C4 audit): RepullAuthCode broker auth_code self-heal.
/// Triggered when broker auth_code expires (typical 30-day window) or
/// `kAuthNoValidCid` (20029); avoids requiring a daemon restart.
pub mod repull;
#[doc(hidden)]
pub mod site_config;
mod webtcp;
pub use broker::{
    BrokerAuth, BrokerAuthRequest, BrokerAuthRouteCache, BrokerConfig, broker_auth, broker_config,
    is_cpp_known_broker_id,
};
pub use refresh::{AuthRefresher, DefaultAuthRefresher, REFRESH_TIMEOUT};
pub use repull::{ERROR_CODE_NO_VALID_CID, repull_auth_code, repull_auth_code_with_client_type};
pub use webtcp::install_default_rustls_crypto_provider;
pub mod commconfig;
mod parse;
mod util;

/// Platform 通道后端连接点，按 `UserAttribution` 分池。
///
/// 完整对齐 C++ `FTLogin/Src/ftlogin/channel/impl/address.cpp:495-557`
/// `LoadHardcodeAddress()` 里 `CONN_PLATFORM_*` 的条目。每个 IP 后面是 C++
/// 源里的 `Region::kRegion*` 字段（gz/sh/hk/us/sg/au/jp），仅作注释。
///
/// v1.4.11 前只有 CN 12 个 IP，海外账号（HK/US/SG/AU/JP）首选 IP 命中 CN 池
/// → 非大陆网络连不通 → 进 offline mode。v1.4.10 的 fallback 逻辑即使有也只
/// 会 fallback 到其他 CN IP，依然死路。修复方式是按 `user_attribution` 选池。
///
/// 端口 9595 是 C++ 硬编码的标准端口。
pub mod conn_points;
// v1.4.110+ Tier 1 split: 顶层类型 + 2 const 抽到 types.rs (无业务逻辑).
mod types;
pub use types::{
    AUTH_SERVER_PROD, AuthConfig, AuthResult, BrokerAuthCode, TGTGT_VALIDITY_SECS, UserAttribution,
};
// v1.4.110+ Tier 1 split: reqwest HTTP client builder 抽到 http_client.rs.
mod http_client;
pub use http_client::build_http_client;
pub(crate) use http_client::build_http_client_with_resolve;

mod phone;
use phone::normalize_phone_account;

mod device;
use device::{
    DEVICE_CODE_SIG_TTL_SECS, DEVICE_VERIFY_SIG_TTL_SECS, fresh_cached_device_code_sig,
    fresh_cached_device_verify_sig, load_credentials, save_credentials,
};
pub use device::{read_or_generate_device_id, reset_device_state, tighten_secret_files_at_startup};

// v1.4.106 codex 0558 F2+F3: PII fingerprint helpers — log 不再放 raw account/uid.
use redact::{account_log_fingerprint, uid_log_fingerprint};

/// v1.4.102 BUG-009 root-cause fix (codex 24 F6 抽 helper, 让 test 覆盖生产
/// path): pre-flight 决策 — cached `dvs+dcs` 都 fresh 且 user 提供
/// `--verify-code` 时, 跳过 `remember_login` + authority POST + req_device_code,
/// 直接 verify_device_code with cached values.
///
/// 输入: 3 个 bool — `dvs_fresh` / `dcs_fresh` / `has_verify_cb`.
/// 输出: true = pre-flight skip; false = fall through 现有 remember_login 流.
///
/// 详见 pitfall #59 + `authenticate_with_callback` 的 wire site.
pub(super) fn should_skip_remember_login_for_cached_sms(
    dvs_fresh: bool,
    dcs_fresh: bool,
    has_verify_cb: bool,
) -> bool {
    dvs_fresh && dcs_fresh && has_verify_cb
}

pub(super) fn should_fallback_to_password_auth_after_remember_error(err: &FutuError) -> bool {
    !matches!(
        err,
        FutuError::ServerError { ret_type: 20, msg }
            if msg.starts_with("remember-login device verification did not complete:")
    )
}

fn decode_saved_rand_key_b64(rand_key_b64: &str) -> Result<Vec<u8>> {
    let rand_key = base64::engine::general_purpose::STANDARD
        .decode(rand_key_b64)
        .map_err(|e| FutuError::Codec(format!("rand_key base64 decode: {e}")))?;
    parse::validate_account_rand_key_len("cached credentials rand_key_b64", &rand_key)?;
    Ok(rand_key)
}

/// v1.4.34: daemon-reload 升级（A' 方案）的产出。
///
/// 走一次 `remember_login` 用缓存凭据刷新 tgtgt，**只写回磁盘 credentials 文件**
/// 不动 bridge 内存状态。下次 Platform / broker TCP 断线重连时自动读新 tgtgt。
#[derive(Debug, Clone)]
pub struct RefreshCredentialsReport {
    /// 是否把新凭据成功写回了 credentials 文件
    pub credentials_refreshed: bool,
    /// 服务端返回的新 uid（大部分场景等于旧 uid，拿来 sanity check）
    pub uid: u64,
}

/// v1.4.34: 给 `daemon-reload` 升级用——用磁盘缓存的 `(uid, tgtgt, device_sig,
/// rand_key)` 走一次 `remember_login`，成功则把新 tgtgt 写回 credentials 文件。
///
/// **安全边界**：
/// - 不保留 plaintext 密码（输入参数里没有 password）
/// - 不动 bridge 内存 auth_result（不穿透 Bridge 字段可变性）
/// - 只作用于磁盘文件
///
/// **失败场景**：
/// - credentials 文件不存在 → `Err`（调用方应回退 "shutdown + restart"）
/// - tgtgt 过期（服务端拒）→ `Err`（同上）
/// - 服务端返 code=20（重新 SMS 验证）→ `Err`（daemon 运行中不可能交互 SMS）
pub async fn refresh_credentials_on_disk(
    http: &reqwest::Client,
    account: &str,
    device_id: &str,
    client_type: u8,
    region_code: Option<&str>,
    attribution: UserAttribution,
) -> std::result::Result<RefreshCredentialsReport, FutuError> {
    let cred = load_credentials(account).ok_or_else(|| {
        FutuError::Codec(format!(
            "no cached credentials for account '{}' to refresh; you likely \
             need to shutdown + restart opend to re-auth from password",
            account
        ))
    })?;
    // 构造最小 AuthConfig——remember_login 内部用 account + client_type。
    // client_type 必须沿真实平台传递：C++ TGTGT / User-Agent / AuthIPList
    // 均使用 `AppConfig::GetClientTypeValue()` 的 40/60。
    let minimal_config = AuthConfig {
        auth_server: String::new(),
        account: account.to_string(),
        password: String::new(),
        password_is_md5: false,
        device_id: device_id.to_string(),
        client_type,
    };
    // SavedCredentials 里存的是 base64 的 rand_key_b64，remember_login 需要
    // 裸字节 —— 对齐 authenticate_with_callback 里的做法解码。
    let rand_key = decode_saved_rand_key_b64(&cred.rand_key_b64)?;

    // remember_login 对成功会返回 (AuthResult, Some(SavedCredentials))——
    // 我们拿 SavedCredentials 写回文件，AuthResult 丢弃。
    let (_auth_result, new_cred_opt) = remember_login(
        http,
        RememberLoginInput {
            config: &minimal_config,
            region_code,
            attribution,
            uid: cred.uid,
            device_id,
            device_sig: &cred.device_sig,
            tgtgt: &cred.tgtgt,
            rand_key: &rand_key,
            web_sig: &cred.web_sig,
            moomoo_web_sig: &cred.moomoo_web_sig,
            verify_cb: None,
            primary_webtcp: None,
        },
    )
    .await?;
    let credentials_refreshed = if let Some(new_cred) = new_cred_opt {
        let uid = new_cred.uid;
        // v1.4.106 codex 0558 F1: write IO 错 propagate, 不 silent drop
        save_credentials(account, &new_cred).map_err(|e| {
            FutuError::Codec(format!(
                "admin reload: save_credentials failed — {e} (cred not on disk; \
                 next startup will re-auth via password)"
            ))
        })?;
        // v1.4.106 codex 0558 F2+F3: log fingerprint 替代 raw account/uid
        tracing::info!(
            account_fp = %account_log_fingerprint(account),
            uid_fp = %uid_log_fingerprint(uid),
            "admin reload: credentials refreshed on disk"
        );
        true
    } else {
        // 服务端成功但没返新凭据——老的仍然有效，算不刷
        tracing::debug!(
            account_fp = %account_log_fingerprint(account),
            "admin reload: remember_login ok but no fresh credentials (still valid)"
        );
        false
    };
    Ok(RefreshCredentialsReport {
        credentials_refreshed,
        uid: cred.uid,
    })
}

/// v1.4.94 G4: 用持久化 credentials 重做 remember-login, 拿到 fresh `AuthResult`
/// (含新 `client_sig` / `client_key`).
///
/// ## 用途
///
/// G4 reactive client_sig refresh 路径: 当 reconnect tcp_login 持续失败暗示
/// `client_sig` 失效时, 调用方:
/// 1. 先调 `AuthRefresher::refresh_qot_login()` (refresh disk creds via
///    `refresh_credentials_on_disk`)
/// 2. **再调本 fn** 用更新后的 disk creds 重做 remember-login → fresh AuthResult
/// 3. 用 fresh AuthResult 替换 reconnect monitor 的本地 `auth_result` 变量
/// 4. 下一轮 tcp_login 用 fresh `client_sig`
///
/// ## 与 `refresh_credentials_on_disk` 的区别
///
/// `refresh_credentials_on_disk` 只更新 disk creds + LoginCache, 不返
/// `AuthResult`. 本 fn 复用其后端 logic 但额外**返 fresh AuthResult** 给调用方
/// 用. 不重复 refresh disk (调用方已先调 refresh_qot_login).
///
/// ## Failure modes
///
/// - `load_credentials` 失败 (disk file 缺) → `Err`
/// - `rand_key_b64` decode 失败 (磁盘 file 损坏) → `Err`
/// - `remember_login` 失败 (服务端拒新 tgtgt / 反刷限流 / network) → `Err`
///
/// 任何失败 caller fallback 到旧行为 (continue with stale `client_sig`,
/// 等下次 reconnect / G1 timer trigger / user 手动 admin reload).
pub async fn reauth_via_remember_login(
    http: &reqwest::Client,
    account: &str,
    device_id: &str,
    client_type: u8,
    attribution: UserAttribution,
) -> std::result::Result<AuthResult, FutuError> {
    let cred = device::load_credentials(account).ok_or_else(|| {
        FutuError::Codec(format!(
            "v1.4.94 G4 reauth: no cached credentials for account '{account}' (cannot \
             reload AuthResult; daemon needs admin reload / restart)"
        ))
    })?;
    // 派生 region_code (对齐 v1.4.13 phone account 拆分逻辑) — 与首登时
    // `authenticate_with_callback` 入口同源, 保证 remember_login 收到的
    // region_code 跟首登一致.
    let (normalized_account, region_code_opt) = normalize_phone_account(account);
    let minimal_config = AuthConfig {
        auth_server: String::new(),
        account: normalized_account,
        password: String::new(),
        password_is_md5: false,
        device_id: device_id.to_string(),
        client_type,
    };
    let rand_key = decode_saved_rand_key_b64(&cred.rand_key_b64)?;
    let (auth_result, _new_cred_opt) = remember_login(
        http,
        RememberLoginInput {
            config: &minimal_config,
            region_code: region_code_opt.as_deref(),
            attribution,
            uid: cred.uid,
            device_id,
            device_sig: &cred.device_sig,
            tgtgt: &cred.tgtgt,
            rand_key: &rand_key,
            web_sig: &cred.web_sig,
            moomoo_web_sig: &cred.moomoo_web_sig,
            verify_cb: None,
            primary_webtcp: None,
        },
    )
    .await?;
    // v1.4.106 codex 0558 F2+F3: log fingerprint 替代 raw account/uid
    tracing::info!(
        account_fp = %account_log_fingerprint(account),
        uid_fp = %uid_log_fingerprint(auth_result.user_id),
        client_sig_len = auth_result.client_sig.len(),
        "v1.4.94 G4: reauth_via_remember_login produced fresh AuthResult"
    );
    Ok(auth_result)
}

/// 验证码获取回调类型
///
/// 当需要短信验证码时调用此回调。返回 Some(code) 表示用户输入了验证码，
/// 返回 None 表示用户取消。
pub type VerifyCodeCallback = Box<dyn Fn() -> Option<String> + Send + Sync>;

/// 完整密码鉴权（优先用保存的凭据跳过验证码）
///
/// CLI 模式使用 `authenticate()` 从 stdin 读取验证码；
/// GUI 模式使用 `authenticate_with_callback()` 通过回调获取。
pub async fn authenticate(config: &AuthConfig) -> Result<AuthResult> {
    authenticate_with_callback(config, None).await
}

/// 完整密码鉴权（带自定义验证码回调）
pub async fn authenticate_with_callback(
    config: &AuthConfig,
    verify_cb: Option<VerifyCodeCallback>,
) -> Result<AuthResult> {
    // v1.4.84 SEC-001: 首次 auth 启动时 stderr warn debug log 安全风险.
    // OnceLock dedup 避免 retry 或 daemon-reload 重复打.
    redact::emit_debug_log_security_warn_once();

    let http = build_http_client(config.client_type)?;
    let primary_webtcp = endpoints::primary_auth_webtcp_context_for_auth_server(
        config.client_type,
        &config.auth_server,
    );
    let _primary_webtcp_prefetch = primary_webtcp.as_ref().map(|context| {
        endpoints::spawn_primary_auth_site_config_prefetch(context, 0, &config.device_id)
    });

    // v1.4.13：把 `+86-13900000000` 这种带区号的输入拆成 account 本体 + region_code。
    // 不拆的话 moomoo 服务端按 `13900000000` 查存的 pwd_md5 对不上我们 tgtgt 里
    // 发的整串 `+86-13900000000`，报 `error_code=2 账号密码不匹配`。对齐 C++
    // `BasicAccountAuthInfo` 的字段约定（`auth_impl.cpp:267`）。
    let (normalized_account, region_code) = normalize_phone_account(&config.account);
    if region_code.is_some() {
        // v1.4.106 codex 0558 F2: log fingerprint, 不写 raw account / phone
        tracing::info!(
            original_fp = %account_log_fingerprint(&config.account),
            account_fp = %account_log_fingerprint(&normalized_account),
            region_no = %region_code.as_deref().unwrap_or(""),
            "parsed phone account with region code"
        );
    }
    // 构造本地 effective config —— `account` 字段已归一化，后续所有流程都用它
    let mut effective_config = config.clone();
    effective_config.account = normalized_account;

    // 尝试 remember login（用保存的凭据）
    if let Some(cred) = load_credentials(&effective_config.account) {
        tracing::info!("found saved credentials, trying remember-login");

        // ★ rand_key 在 salt32 非空路径是 32 字节（AES-256），不能截断到 16。
        // 截到 16 字节后用 AES-128 解密 AES-256 加密的 client_key / rand_key_new
        // 必定失败（表现：`cbc_md5_var: last_block_size 127 > 15`）。
        let rand_key = match decode_saved_rand_key_b64(&cred.rand_key_b64) {
            Ok(rand_key) => rand_key,
            Err(e) => {
                tracing::warn!(
                    error = %e,
                    account_fp = %account_log_fingerprint(&effective_config.account),
                    "cached credentials rand_key_b64 invalid; skipping remember-login and falling back to password auth"
                );
                return password_auth(
                    &effective_config,
                    region_code.as_deref(),
                    &http,
                    verify_cb.as_deref(),
                    primary_webtcp.as_ref(),
                )
                .await;
            }
        };

        // v1.4.102 BUG-009 真修 (root-cause fix, 用户 2026-04-28 反馈):
        //
        // **历史 saga**: BUG-009 SMS race 经过 v1.4.72/74/75/81 共 6 版迭代.
        // v1.4.81 Option B 设计是 "若 cached dvs+dcs 都 fresh, 跳
        // req_device_code 用 cached values + 用户传入 --verify-code 直接
        // verify". 但 Option B 检查放在 `remember_login` **之后** —— 每次启动
        // 都先跑 remember_login → POST /authority/ → code=20 → 拿新 dvs →
        // 进 handle_device_verify with NEW dvs (而不是 cached) → req_device_code
        // → 新 SMS 覆盖老码 → 用户输的老 SMS 失败 → code=21 累计触发账号锁.
        //
        // **真根因**: cached dvs+dcs 在 5min 窗口内是有效凭证, 任何 POST
        // /authority/ 都可能 invalidate. 必须在 cache fresh + user 提供
        // --verify-code 时 **跳过** remember_login, 直接 verify_device_code.
        //
        // **本次修法**: pre-flight 检查 — 若 cached dvs+dcs 都 fresh **AND**
        // verify_cb 存在(--verify-code 提供) → 跳过 remember_login + authority
        // POST + req_device_code, 直接 handle_device_verify(cached_dvs,
        // cached_dcs, user verify_code).
        //
        // **不破坏现有 flow**: cache 不全 fresh / 无 --verify-code → fall
        // through 到正常 remember_login (v1.4.74 及以前行为).
        //
        // **C++ 对齐**: auth_impl.cpp 没显式 "skip authority on cached SMS"
        // 路径 (C++ 客户端假设交互式输入码), 但本 fix 是 daemon 长跑场景特有 —
        // GUI app 不需要因为 SMS 是即时输入. C++ 如果有同等场景应该也这样做.
        // v1.4.102 codex 24 F6 (P2) fix: 用 should_skip_remember_login_for_cached_sms
        // 共享 decision fn (pub(super) in tests.rs). 之前生产 logic 与 test
        // helper 重复 (test 测 helper 但 helper 不 wire 到生产) — 改为共享.
        let dvs_fresh = fresh_cached_device_verify_sig(&cred);
        let dcs_fresh = fresh_cached_device_code_sig(&cred);
        let has_verify_cb = verify_cb.is_some();
        if should_skip_remember_login_for_cached_sms(
            dvs_fresh.is_some(),
            dcs_fresh.is_some(),
            has_verify_cb,
        ) && let (Some(cached_dvs), Some(cached_dcs)) = (dvs_fresh, dcs_fresh)
        {
            tracing::info!(
                dvs_len = cached_dvs.len(),
                dcs_len = cached_dcs.len(),
                ttl_secs = DEVICE_CODE_SIG_TTL_SECS,
                attribution = ?cred.user_attribution,
                "v1.4.102 BUG-009 root-cause fix: cached dvs+dcs both fresh AND \
                 user supplied --verify-code → SKIP remember_login + authority POST + \
                 req_device_code (would invalidate cached SMS); going DIRECTLY to \
                 verify_device_code with cached values"
            );
            let domain = cred.user_attribution.auth_domain();
            return handle_device_verify(
                &http,
                DeviceVerifyInput {
                    config: &effective_config,
                    attribution: cred.user_attribution,
                    domain,
                    uid: cred.uid,
                    dvs: cached_dvs,
                    rand_key: &rand_key,
                    verify_cb: verify_cb.as_deref(),
                    cached_device_code_sig: Some(cached_dcs),
                },
            )
            .await;
        }
        // Note: 任一缺失 (dvs / dcs / verify_cb) → fall through to remember_login.
        // 现有 post-fail Option B/A path 仍存在 (cred 部分新鲜场景, e.g. dvs
        // 新鲜 dcs 缺失 → Option A fallback).

        match remember_login(
            &http,
            RememberLoginInput {
                config: &effective_config,
                region_code: region_code.as_deref(),
                attribution: cred.user_attribution,
                uid: cred.uid,
                device_id: &cred.device_id,
                device_sig: &cred.device_sig,
                tgtgt: &cred.tgtgt,
                rand_key: &rand_key,
                web_sig: &cred.web_sig,
                moomoo_web_sig: &cred.moomoo_web_sig,
                verify_cb: verify_cb.as_deref(),
                primary_webtcp: primary_webtcp.as_ref(),
            },
        )
        .await
        {
            Ok((auth, new_cred)) => {
                // 更新凭据 — v1.4.106 codex 0558 F1: write IO 错 propagate
                if let Some(nc) = new_cred {
                    save_credentials(&effective_config.account, &nc).map_err(|e| {
                        FutuError::Codec(format!(
                            "remember_login: save_credentials failed — {e} (cred not on disk; \
                             daemon proceeds with in-memory creds, next restart will re-auth)"
                        ))
                    })?;
                }
                return Ok(auth);
            }
            Err(e) => {
                if !should_fallback_to_password_auth_after_remember_error(&e) {
                    tracing::warn!(
                        error = %e,
                        "remember-login reached device verification and did not complete; \
                         not falling back to password/SMS auth because that can request a \
                         second SMS and mix DVS/DCS/rand_key state. Restart with \
                         --verify-code <SMS> using the same HOME."
                    );
                    return Err(e);
                }
                tracing::warn!(
                    error = %e,
                    "remember-login failed; cached credentials may be stale/incomplete, \
                     falling back to password/SMS auth"
                );
            }
        }

        // v1.4.75 BUG-009 Fix 9a 真修（Option A "探路版"，CLAUDE.md 坑 #34 模式）：
        // 如果缓存的 device_verify_sig 仍新鲜（<5 min）→ **跳过 password_auth
        // → POST /authority/ → backend 返新 dvs 覆盖老 SMS** 的破坏流程，直接
        // 调 handle_device_verify 带 cached dvs 做 SMS 验证。
        //
        // **v1.4.72 Fix 9a（WARN-only 非真修）**：只 log 提示，仍走 password_auth。
        // 用户输的老 SMS 码绑定 old dvs，但 daemon 流程已经拿到新 dvs → 服务端
        // 对比失败 → code=21 累计失败锁账号（外部 v1.4.71 AI tester 报告 §2.5）。
        //
        // **v1.4.75 Option A 探路**：cached dvs fresh → 直接 handle_device_verify(cached_dvs)
        //
        // **agent 代码级审查确认 3/4 风险安全**（essentials/2026-04-23-1810-v1.4.75-plan.md）：
        // - Risk 1 🟢 backend 接受 cached dvs（C++ auth_impl.cpp:244/757/879 无"一次性"语义）
        // - Risk 3 🟢 rand_key AES-256 不截断（aes_cbc_md5_decrypt_var 可变长 + unit test 已 PASS）
        // - Risk 4 🟢 moomoo empty device_sig 无关（handle_device_verify 不用 device_sig）
        //
        // **v1.4.75 真机结论**：Risk 2 假设被推翻。GET
        // `/authority/req_device_code?dvs=cached_X` 仍可能触发新 SMS，
        // 所以 Option A 只能避开 authority re-POST 的反刷问题，不足以保住
        // 用户手上的旧 SMS code。
        //
        // 当前 Option A fallback 仍是纯 "add new branch"，**不破坏现有 auth 流程**：
        // cached dvs 过期 / 不存在 → fall through 到 password_auth（v1.4.74 及以前行为）
        // v1.4.81 BUG-009 Fix 9a Option B (优先) / Option A (fallback):
        //
        // - Option B (首选): cached device_code_sig + dvs 都 fresh → 跳过
        //   req_device_code 整步，直接 verify_device_code with cached dcs +
        //   用户传入 --verify-code。**这是 BUG-009 的真修**。
        // - Option A (fallback): 只有 cached dvs fresh（dcs 缺失或过期）→ 跳
        //   authority POST 避反刷，但 req_device_code 仍会触发新 SMS（v1.4.75
        //   真机 verify 推翻 Risk 2 假设后，Option A 只能避 "authority POST 反
        //   刷 15"，不能避 "新 SMS 覆盖老码"）。
        //
        // 典型 flow：
        // - Step 1（首次启动 non-tty）: password_auth → POST /authority/ code=20
        //   → persist shell (含 dvs+ts) → req_device_code (发 SMS, 拿 dcs) →
        //   persist dcs → stdin atty fail 退出
        // - Step 2（5min 内重启带 --verify-code X）: load credentials (dvs+dcs 都 fresh)
        //   → Option B 触发 → handle_device_verify(cached_dvs, cached_dcs=Some)
        //   → 跳 req_device_code → verify_device_code with X → 成功
        // v1.4.102 codex 32 F3 (P2) fix: 同时 check dvs + dcs fresh.
        // 之前只 check dcs fresh + cred.device_verify_sig.unwrap_or("") 直接
        // 用 → DCS fresh 但 DVS 过期/缺失时仍走此路径用 stale/empty DVS verify.
        // 修法: 与 pre-flight check (line 538-) 一致, 必须 both fresh.
        if let (Some(cached_dcs), Some(cached_dvs)) = (
            fresh_cached_device_code_sig(&cred),
            fresh_cached_device_verify_sig(&cred),
        ) {
            tracing::info!(
                dcs_len = cached_dcs.len(),
                dvs_len = cached_dvs.len(),
                ttl_secs = DEVICE_CODE_SIG_TTL_SECS,
                attribution = ?cred.user_attribution,
                "v1.4.81 BUG-009 Fix 9a Option B (v1.4.102 audit 32 F3 refine: \
                 both dvs+dcs fresh): using cached device_code_sig + \
                 device_verify_sig, skipping req_device_code entirely"
            );
            let domain = cred.user_attribution.auth_domain();
            return handle_device_verify(
                &http,
                DeviceVerifyInput {
                    config: &effective_config,
                    attribution: cred.user_attribution,
                    domain,
                    uid: cred.uid,
                    dvs: cached_dvs,
                    rand_key: &rand_key,
                    verify_cb: verify_cb.as_deref(),
                    cached_device_code_sig: Some(cached_dcs),
                },
            )
            .await;
        }
        if let Some(cached_dvs) = fresh_cached_device_verify_sig(&cred) {
            tracing::warn!(
                dvs_len = cached_dvs.len(),
                ttl_secs = DEVICE_VERIFY_SIG_TTL_SECS,
                attribution = ?cred.user_attribution,
                "v1.4.75 BUG-009 Fix 9a Option A fallback: cached dvs only (no \
                 fresh device_code_sig) — skipping authority re-POST but \
                 req_device_code will still fire new SMS (known half-fix; 5min \
                 window after first-SMS lost). Will work for authority rate-limit \
                 avoidance but not SMS-code preservation."
            );
            let domain = cred.user_attribution.auth_domain();
            return handle_device_verify(
                &http,
                DeviceVerifyInput {
                    config: &effective_config,
                    attribution: cred.user_attribution,
                    domain,
                    uid: cred.uid,
                    dvs: cached_dvs,
                    rand_key: &rand_key,
                    verify_cb: verify_cb.as_deref(),
                    cached_device_code_sig: None,
                },
            )
            .await;
        }
    }

    // 全新密码认证
    //
    // v1.4.17：SMS 验证码错（`error_code=21`）时自动轮换 device_id 重试，
    // 最多 MAX_SMS_RETRIES 次。
    //
    // **v1.4.57 修正（外部报告 #5 第 3 层根因）**：自动轮换 device_id 反而会触发
    // 服务端限流（"5 次不同设备 30 秒内" 硬 threshold）。同事实锤：连续 2 次
    // SMS 输错自动轮换后，正确码也被 code=1 "系统繁忙" 拒。v1.4.57 起**不再
    // 自动轮换**（MAX_SMS_RETRIES=0），让用户手动决定：
    //   - 真是验证码输错 → 重新运行 `futu-opend --setup-only` 重试一次
    //   - 需要强制换 device_id → 显式 `--reset-device --setup-only`
    //
    // **tty 检测**：prompt_input 已在非 tty 时 fail fast（见 auth/util.rs:38-51），
    // 避免空验证码毒化 device_id。v1.4.57 外部 #5 A/C 两层根因至此闭环。
    // v1.4.57 外部 #5：直接调一次 password_auth，不再自动轮换 device_id。
    // 如 SMS 输错 (ret_type=21)，把错误返给 caller，用户再手动 retry。
    //
    // v1.4.17-56 的 `MAX_SMS_RETRIES=2` 自动轮换反而触发服务端限流（同一 uid
    // "5 次不同设备 30 秒内"硬阈值），导致正确码也被 code=1 系统繁忙拒（实锤：
    // 2026-04-22 外部用户 Telegram SMS 中继场景）。
    //
    // 未来若想恢复重试（e.g., CLI flag gated），restore 原 loop + 用
    // `reset_device_state` + `read_or_generate_device_id` 轮换 device_id。
    password_auth(
        &effective_config,
        region_code.as_deref(),
        &http,
        verify_cb.as_deref(),
        primary_webtcp.as_ref(),
    )
    .await
}

// v1.4.110+ Tier 2/3 split: 5 业务 fn + 4 input struct 拆 4 子 mod.
// Orchestrator (authenticate_with_callback / refresh_credentials_on_disk) 通过
// 下方 use 仍可见 fn 和 input struct.
mod device_verify;
mod endpoints;
mod password_auth;
mod remember;

use device_verify::{DeviceVerifyInput, handle_device_verify};
use password_auth::password_auth;
use remember::{RememberLoginInput, remember_login};

#[cfg(test)]
mod tests;