futu_backend/auth/

repull.rs

//! v1.4.93 G2 (CLAUDE.md C4 audit): 实装 POST `/authority/repull_auth_code`，
//! 对齐 C++ FTLogin `auth_impl.cpp:715-754` `RepullAuthCode` +
//! `auth_impl.cpp:3308-3376` `ParseRepullAuthCodeResponse`。
//!
//! ## 触发场景
//!
//! - **broker auth_code 过期**：[`super::BrokerAuthCode::invalid_time`] 在认证
//!   响应里给的 expiry。daemon 长跑（典型 30 天）触发，原本 broker channel
//!   失效不 self-heal、必须重启 daemon —— 本 fn 让 `bridge` 拉新 auth_code
//!   重做 `broker_auth` HTTP + CMD 1001 重登 broker, **避免重启**。
//! - **broker `kAuthNoValidCid` (error_code=20029)**：C++ 在
//!   `ParseRepullAuthCodeResponse` 见此码会 `ClearBrokerAccountInfo` 然后重新
//!   走整 RepullAuthCode 流程 —— 本 fn 仅做"拉新 auth_code"那一步，
//!   `ClearBrokerAccountInfo` 等价物（清 cipher / customer_id）由 caller 决定
//!   要不要做（v1.4.93 不主动清，v1.4.94+ 视真机行为再决定）。
//!
//! ## 协议层 (对齐 C++)
//!
//! ```text
//! POST https://{auth_domain}/authority/repull_auth_code
//! body = {
//!   "uid":       <u64>,            // 当前账户 uid
//!   "device_id": "<16-hex>",       // 设备 ID (持久化)
//!   "web_sig":   "<str>",          // /authority/ 响应里 web_sig_new (持久化)
//!   "broker_id": <i32>             // 单 broker
//! }
//! ```
//!
//! Response result 单 broker:
//! ```text
//! { "result": { "uid":<u64>, "broker_id":<i32>, "auth_code":"<str>",
//!   "invalid_time":<u64> } }
//! ```
//!
//! 错误响应 result 缺失，error.error_code 给具体错码。
//! `error_code=20029` (`kAuthNoValidCid`) 是特定可识别状态。
//!
//! ## Failure fallback
//!
//! - `web_sig` 空（v1.4.92 凭据 / device-verify shell 没此字段）→ caller 跳过
//!   repull，fallback 走 platform refresh（重 POST /authority/）然后再 retry
//! - HTTP 失败 / web_sig 过期 → caller log + 不重试本轮 → 等下次 broker
//!   reconnect 触发或 platform refresh
//!
//! ## CLAUDE.md pitfalls 关联
//!
//! - **#34** Agent 调研结论 ≠ 真机正确性: 本实装基于 C++ 源码 `auth_impl.cpp`
//!   完整对照, 但 backend 实际 wire (是否 reject 'web_sig over-frequent
//!   refresh', error_code 准确含义) 仍需真机 verify
//! - **#42** Backend-semantic 风险: error_code=20029 是否真触发 + repull 后
//!   的 broker channel 重建是否 work, 需真机
//! - **#45** Silent-success: 函数返 `Ok(BrokerAuthCode)` 必须基于响应
//!   `result.auth_code` + `invalid_time` 都非空, 否则返 Err

use futu_core::error::{FutuError, Result};
use futu_domain_broker_reconnect::{
    BrokerRepullAuthCodeRequestFacts, BrokerRepullAuthCodeRequestReject,
    BrokerRepullAuthCodeSuccessFacts, BrokerRepullAuthCodeSuccessReject,
    validate_broker_repull_auth_code_request, validate_broker_repull_auth_code_success,
};

use super::redact::uid_log_fingerprint;
use super::{BrokerAuthCode, UserAttribution};

/// `RepullAuthCode` URL 路径常量, 对齐 C++ `auth_impl.cpp:28`
/// `AUTH_REPULL_AUTHCODE = "/authority/repull_auth_code"`.
const REPULL_AUTH_CODE_PATH: &str = "/authority/repull_auth_code";

/// C++ `kAuthNoValidCid` 错码（broker cid 失效）。当 backend 返此码时，
/// 调用方应当清 broker cipher cache + 触发 broker channel 重建（C++ 行为
/// `ClearBrokerAccountInfo`）。本 fn 不做副作用，只透传给 caller 决定。
pub const ERROR_CODE_NO_VALID_CID: i64 = 20029;

/// 请求新的 broker auth_code，对齐 C++ `RepullAuthCode`.
///
/// # 参数
///
/// - `http`: 复用 bridge 创建的 reqwest::Client（含 webpki-roots TLS 配置）
/// - `attribution`: 当前账户 user_attribution (决定 auth_domain)
/// - `uid`: 当前账户 uid (== AuthResult.user_id)
/// - `web_sig`: 持久化的 web_sig (来自 SavedCredentials.web_sig 或
///   AuthResult.web_sig)。**空字符串 → 直接 Err**（向后兼容旧凭据无此字段
///   的场景，调用方应跳过 repull、fallback 走 platform refresh）。
/// - `device_id`: 设备 ID (16-hex)
/// - `broker_id`: 目标 broker (1001 / 1007 / 1008 / 1009 / 1012 / 1017 / 1019)
///
/// # 返回
///
/// 成功: `BrokerAuthCode { broker_id, auth_code, invalid_time }` —— 与
/// `parse_auth_code_list` 解出的元素同结构, caller 可直接走 `broker_auth`
/// HTTP + `broker_tcp_login` 流程。
///
/// 失败: `Err(FutuError::*)`. 见模块文档 fallback 策略.
pub async fn repull_auth_code(
    http: &reqwest::Client,
    attribution: UserAttribution,
    uid: u64,
    web_sig: &str,
    device_id: &str,
    broker_id: u32,
) -> Result<BrokerAuthCode> {
    // Backward-compatible public wrapper: callers created before v1.4.112 did
    // not pass OpenD's app client type. Internal bridge code should call the
    // precise helper below because it already owns `AuthState.client_type`.
    let client_type = match attribution {
        UserAttribution::Cn | UserAttribution::Hk => 40,
        _ => 60,
    };
    repull_auth_code_with_client_type(
        http,
        client_type,
        attribution,
        uid,
        web_sig,
        device_id,
        broker_id,
    )
    .await
}

/// 请求新的 broker auth_code, 显式使用 OpenD client_type 构造 C++ 形态
/// FTAuthImpl business headers。
pub async fn repull_auth_code_with_client_type(
    http: &reqwest::Client,
    client_type: u8,
    attribution: UserAttribution,
    uid: u64,
    web_sig: &str,
    device_id: &str,
    broker_id: u32,
) -> Result<BrokerAuthCode> {
    let request = validate_broker_repull_auth_code_request(BrokerRepullAuthCodeRequestFacts {
        uid,
        web_sig,
        broker_id,
    })
    .map_err(repull_request_reject_error)?;
    let uid = request.uid;
    let web_sig = request.web_sig;
    let broker_id = request.broker_id;

    let url = repull_auth_code_url(attribution);

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

    let uid_fp = uid_log_fingerprint(uid);
    tracing::info!(
        broker_id,
        uid_fp = %uid_fp,
        url = %url,
        attribution = ?attribution,
        "v1.4.93 G2: POST /authority/repull_auth_code (broker auth_code refresh)"
    );

    // 注意: 不打印 body (含 web_sig) — 走 redact_auth_body 才能 log,
    // 这里只 info url + broker_id; 失败场景下走 error/warn 仍只透出 ret_type
    let headers = super::http_client::auth_business_headers(client_type, device_id)?;
    let resp: serde_json::Value = http
        .post(&url)
        .headers(headers)
        .json(&body)
        .send()
        .await
        .map_err(|e| FutuError::Network(std::io::Error::other(e.to_string())))?
        .json()
        .await
        .map_err(|e| FutuError::Codec(format!("repull_auth_code: response not JSON: {e}")))?;

    // 错误分支 (对齐 C++ ParseRepullAuthCodeResponse:3340-3358)
    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 {
            tracing::warn!(
                broker_id,
                uid_fp = %uid_fp,
                error_code = code,
                error_msg = %msg,
                no_valid_cid = code == ERROR_CODE_NO_VALID_CID,
                "v1.4.93 G2: RepullAuthCode failed"
            );
            return Err(FutuError::ServerError {
                ret_type: code as i32,
                msg: format!("repull_auth_code broker_id={broker_id}: {msg}"),
            });
        }
    }

    let result = resp
        .get("result")
        .and_then(|r| r.as_object())
        .ok_or_else(|| {
            FutuError::Codec("repull_auth_code: missing result + missing error".into())
        })?;

    parse_repull_success_response(result, uid, broker_id)
}

fn repull_request_reject_error(reject: BrokerRepullAuthCodeRequestReject) -> FutuError {
    match reject {
        BrokerRepullAuthCodeRequestReject::EmptyWebSig => FutuError::Codec(
            "repull_auth_code: web_sig empty (legacy credentials before v1.4.93 G3 \
             or device-verify shell path) — caller should fallback to platform refresh"
                .into(),
        ),
        BrokerRepullAuthCodeRequestReject::ZeroUid => {
            FutuError::Codec("repull_auth_code: uid is 0 (invalid)".into())
        }
        BrokerRepullAuthCodeRequestReject::UnsupportedBrokerId { broker_id } => {
            FutuError::Codec(format!("repull_auth_code: unknown broker_id {broker_id}"))
        }
    }
}

fn repull_auth_code_url(attribution: UserAttribution) -> String {
    // `auth_domain()` already returns a complete base URL with scheme. All
    // other primary-auth call sites use it as-is; do not prepend another
    // `https://`.
    format!("{}{}", attribution.auth_domain(), REPULL_AUTH_CODE_PATH)
}

fn parse_repull_success_response(
    result: &serde_json::Map<String, serde_json::Value>,
    uid: u64,
    broker_id: u32,
) -> Result<BrokerAuthCode> {
    // 对齐 C++ ParseRepullAuthCodeResponse:3325-3338 字段抽取 + 校验
    let validated = validate_broker_repull_auth_code_success(BrokerRepullAuthCodeSuccessFacts {
        expected_uid: uid,
        expected_broker_id: broker_id,
        response_uid: result.get("uid").and_then(|v| v.as_u64()),
        response_broker_id: result.get("broker_id").and_then(|v| v.as_u64()),
        auth_code: result.get("auth_code").and_then(|v| v.as_str()),
        invalid_time: result.get("invalid_time").and_then(|v| v.as_u64()),
    })
    .map_err(repull_success_reject_error)?;

    let auth_code = validated.auth_code.to_string();
    let invalid_time = validated.invalid_time;

    tracing::info!(
        broker_id,
        uid_fp = %uid_log_fingerprint(uid),
        invalid_time,
        auth_code_len = auth_code.len(),
        "v1.4.93 G2: RepullAuthCode success — broker auth_code refreshed"
    );

    Ok(BrokerAuthCode {
        broker_id: validated.broker_id,
        auth_code,
        invalid_time,
    })
}

fn repull_success_reject_error(reject: BrokerRepullAuthCodeSuccessReject) -> FutuError {
    match reject {
        BrokerRepullAuthCodeSuccessReject::UidMismatch {
            expected_uid,
            response_uid,
        } => {
            let expected_uid_fp = uid_log_fingerprint(expected_uid);
            let got_uid_fp = uid_log_fingerprint(response_uid);
            FutuError::Codec(format!(
                "repull_auth_code: response uid mismatch (expected {expected_uid_fp}, \
                 got {got_uid_fp})"
            ))
        }
        BrokerRepullAuthCodeSuccessReject::MissingBrokerId => {
            FutuError::Codec("repull_auth_code: response broker_id invalid".into())
        }
        BrokerRepullAuthCodeSuccessReject::InvalidBrokerId { response_broker_id } => {
            FutuError::Codec(format!(
                "repull_auth_code: response broker_id invalid (got {response_broker_id})"
            ))
        }
        BrokerRepullAuthCodeSuccessReject::BrokerIdMismatch {
            expected_broker_id,
            response_broker_id,
        } => FutuError::Codec(format!(
            "repull_auth_code: response broker_id mismatch (expected {expected_broker_id}, \
             got {response_broker_id})"
        )),
        BrokerRepullAuthCodeSuccessReject::EmptyAuthCodeOrInvalidTime {
            auth_code_len,
            invalid_time,
        } => FutuError::Codec(format!(
            "repull_auth_code: empty auth_code or invalid_time (auth_code_len={auth_code_len}, \
             invalid_time={invalid_time})"
        )),
    }
}

#[cfg(test)]
mod tests;