futu_backend/auth/

types.rs

//! v1.4.110+ Tier 1 split (from `auth/mod.rs`): 顶层类型 + 2 const.
//!
//! - `UserAttribution` compatibility re-export (owned by `futu-domain-auth`)
//! - `AuthConfig` (输入: account / pwd / device_id / client_type)
//! - `AuthResult` (输出: client_sig / client_key / auth_code_list / svr_time_offset / web_sig / ...)
//! - `BrokerAuthCode` (auth_code_list 单元)
//! - `AUTH_SERVER_PROD` / `TGTGT_VALIDITY_SECS` 顶层 const
//!
//! 不含业务逻辑 — 业务 fn 仍在 mod.rs.

use crate::conn::BackendProtocolIdentity;
use async_trait::async_trait;
use futu_core::error::Result;
pub use futu_domain_auth::UserAttribution;
use futu_domain_auth::{
    AuthChallengeCommand, AuthChallengeKind, AuthChallengeSnapshot, InputCompletion,
};

/// 默认认证服务器——CN / HK 归属地账号用这个。
/// 海外账号（US/SG/AU/JP）实际请求时会按 `UserAttribution::auth_domain()` 切换。
pub const AUTH_SERVER_PROD: &str = "https://auth.futunn.com";

/// v1.4.71: TGTGT 票据有效期（30 天），对齐 C++ `auth_cryptor.cpp:135`
/// `CreateNewTgtgt` 里 `InvalidTime = RefreshTime + 30 * 24 * 3600`。
///
/// **绝对不 hardcode**：之前 `30 * 24 * 3600` 魔法数散落在 2 处（`handle_device_verify`
/// + `tgtgt_payload_structure_ftnn_aligns_cpp_spec` test），改动需同步。提为 const 保一致。
pub const TGTGT_VALIDITY_SECS: u32 = 30 * 24 * 3600;

pub struct AuthChallengeWork {
    generation: u64,
    command: Option<AuthChallengeCommand>,
    response: tokio::sync::oneshot::Sender<Result<AuthChallengeSnapshot>>,
}

impl AuthChallengeWork {
    pub fn new(
        generation: u64,
        command: AuthChallengeCommand,
        response: tokio::sync::oneshot::Sender<Result<AuthChallengeSnapshot>>,
    ) -> Self {
        Self {
            generation,
            command: Some(command),
            response,
        }
    }

    pub fn generation(&self) -> u64 {
        self.generation
    }

    pub fn take_command(&mut self) -> Option<AuthChallengeCommand> {
        self.command.take()
    }

    pub fn respond(self, result: Result<AuthChallengeSnapshot>) {
        let _ = self.response.send(result);
    }
}

#[async_trait]
pub trait AuthChallengePort: Send + Sync {
    async fn publish_initial_requested(
        &self,
        kind: AuthChallengeKind,
        masked_target: Option<String>,
    ) -> Result<AuthChallengeSnapshot>;

    async fn wait_for_work(&self) -> Result<AuthChallengeWork>;

    fn complete_request(&self, generation: u64) -> Result<AuthChallengeSnapshot>;

    /// Validate request-generation ownership and publish its external artifact
    /// in one linearization boundary. Production runtimes override this to
    /// hold their generation lock while `publish` runs.
    fn complete_request_with(
        &self,
        generation: u64,
        publish: &mut dyn FnMut() -> Result<()>,
    ) -> Result<AuthChallengeSnapshot> {
        self.snapshot(generation)?;
        publish()?;
        self.complete_request(generation)
    }

    fn fail_request(&self, generation: u64) -> Result<AuthChallengeSnapshot>;

    fn complete_input(
        &self,
        generation: u64,
        completion: InputCompletion,
    ) -> Result<AuthChallengeSnapshot>;

    fn snapshot(&self, generation: u64) -> Result<AuthChallengeSnapshot>;
}

/// Cached credentials ticket age summary for daemon diagnostics.
///
/// This exposes only timestamps / derived age, never `tgtgt`, rand key,
/// device sig, web sig, account, or uid. `None` values mean legacy credentials
/// did not carry `tgtgt_saved_at` yet.
#[derive(Debug, Clone, serde::Serialize)]
pub struct CredentialTicketStatus {
    pub saved_at: Option<u64>,
    pub age_days: Option<u64>,
    pub expires_in_days: Option<i64>,
    pub expiry_warning: Option<String>,
}

/// v1.4.19：`ZeroizeOnDrop` 让 `AuthConfig` drop 时自动把 `password` 字段的
/// 堆内存清零，减少进程 core dump / `/proc/<pid>/mem` 读到明文的窗口。
/// 其他字段（auth_server / account / device_id）不是秘密，`#[zeroize(skip)]`
/// 跳过。注意 `Clone` 每次复制都会产生新堆分配，drop 时各自 zeroize。
#[derive(Clone, zeroize::ZeroizeOnDrop)]
pub struct AuthConfig {
    #[zeroize(skip)]
    pub auth_server: String,
    #[zeroize(skip)]
    pub account: String,
    /// 密码：`password_is_md5 = false` 时是明文（内部做 MD5）；
    /// `password_is_md5 = true` 时是 32 位小写 hex 的 MD5（直接使用）。
    /// drop 时自动 zeroize。
    pub password: String,
    /// 是否为预哈希 MD5；`false` 时按明文处理
    #[zeroize(skip)]
    pub password_is_md5: bool,
    #[zeroize(skip)]
    pub device_id: String,
    /// C++ `AppConfig` protocol header identity.
    ///
    /// 对齐 C++ `NNBase_Define_Enum.h:1113-1114`：
    /// - `40` = `NN_ClientType_FutuOpenD`（牛牛 FTNN）
    /// - `60` = `NN_ClientType_FutuOpenDMooMoo`（moomoo FTMM）
    ///
    /// v1.4.15：moomoo 的 `auth.moomoo.com` 对 client-type=40 直接拒绝
    /// （返回 `error_code=2`），必须用 60。由 `--platform` flag 决定。
    #[zeroize(skip)]
    pub protocol_identity: BackendProtocolIdentity,
}

impl std::fmt::Debug for AuthConfig {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let account_fp = crate::auth::redact::account_log_fingerprint(&self.account);
        let device_id_fp = crate::auth::redact::device_id_log_fingerprint(&self.device_id);
        let redacted_password = format!("<REDACTED len={}>", self.password.len());

        f.debug_struct("AuthConfig")
            .field("auth_server", &self.auth_server)
            .field("account_fp", &account_fp)
            .field("password", &redacted_password)
            .field("password_is_md5", &self.password_is_md5)
            .field("device_id_fp", &device_id_fp)
            .field("client_type", &self.protocol_identity.client_type())
            .field("lang_id", &self.protocol_identity.lang_id())
            .finish()
    }
}

/// `auth_code_list` 响应条目——每个 broker 一项。
/// 对齐 C++ `FTLogin/Src/ftlogin/auth/impl/auth_impl.cpp:3504`（`ParseAuthCodeList`）
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct BrokerAuthCode {
    pub broker_id: u32,
    pub auth_code: String,
    pub invalid_time: u64,
}

#[derive(Debug, Clone)]
pub struct AuthResult {
    pub user_id: u64,
    pub client_sig: Vec<u8>,
    pub client_key: Vec<u8>,
    /// 从 salt 响应拿到的归属地，TCP 登录时会用来派生 conn_identity
    pub user_attribution: UserAttribution,
    /// HTTP auth 响应的 `auth_code_list`——每个已授权 broker 的票据，
    /// 用来后续向 `/broker_auth/client_auth` 换取 broker_client_sig / broker_client_key
    pub auth_code_list: Vec<BrokerAuthCode>,
    /// 原始 rand_key（解密用）——broker_auth 响应里的 `broker_client_key` 也是
    /// 用这个 rand_key 加密过的，需要它做 `aes_cbc_md5_decrypt_var` 解开
    pub rand_key: Vec<u8>,
    /// v1.4.22：**服务端时间 - 本机时间**（秒）—— salt 响应时捕获。
    ///
    /// 用于让后续 TOTP / time-based token 用"服务端时间"而不是本机时间。
    /// 机器时钟飘了 > 30s 的场景下 TOTP 会被服务端拒，offset 校正后可免。
    /// 对齐 C++ `INNBiz_SvrTime::GetSvrTimeStamp()` 机制。
    ///
    /// 使用方式：`let server_now = local_now + svr_time_offset;`
    /// 首次 salt 时 offset < 0 说明本机时钟比服务端快，反之则慢。0 = 没取到。
    pub svr_time_offset: i64,
    /// v1.4.93 G3 (CLAUDE.md C4 audit): `web_sig` from `/authority/` 响应里的
    /// `web_sig_new` 字段（对齐 C++ `auth_impl.cpp:3193,3260`
    /// `account.web_sig_`）。
    ///
    /// **用途**：G2 [`crate::auth::repull::repull_auth_code`] 把它作 POST
    /// `/authority/repull_auth_code` body 字段（C++ `auth_impl.cpp:738-748`），
    /// broker auth_code 过期时拉新 auth_code，让 broker channel self-heal
    /// 不必重启 daemon。
    ///
    /// 缺失 → 空字符串（旧 v1.4.92 及之前的凭据 / device-verify shell 路径
    /// 没此字段）。空时调用方应跳过 repull, fallback 走 platform refresh。
    pub web_sig: String,
    /// v1.4.93 G1 (CLAUDE.md C4 audit P1): client_sig 失效的本地时戳 (秒, UTC epoch).
    /// 对齐 C++ `auth_impl.cpp:3245-3247` 解 `cltsig_invalidtime`
    /// (服务端绝对过期 epoch)，再按
    /// `(cltsig_invalidtime - svr_time) + local_now` 得本地时间, 写到
    /// `account.client_sig_invalid_local_time_s_`.
    ///
    /// **用途**: 记录服务端下发的 client_sig 失效时间。当前 auth 模块只负责
    /// 解析/持久化该字段，不启动 proactive timer；长跑 daemon 的 client_sig
    /// 更新走 reconnect 失败后的 reactive remember-login refresh 路径。
    ///
    /// **缺失 (老 backend / 旧 credentials shell)**: 0 (不触发 proactive refresh).
    pub client_sig_invalid_local_time_s: u64,
    /// v1.4.94 G6 (P2 protocol gap): `moomoo_client_sig` from `/authority/`
    /// 响应里的 `moomoo_client_sig` 字段, **base64 已解码**.
    ///
    /// 对齐 C++ `auth_impl.cpp:3195` `ParseJsonString(jval_result, "moomoo_client_sig", mm_sig);`
    /// 映射到 `account.us_client_sig_`. 用于 moomoo / US 路径独立于
    /// `client_sig` 的 broker channel 鉴权 — 当账号 attribution = US/SG/AU/JP/CA
    /// 时, broker_auth_code 换 client_sig 走的是 `moomoo_client_sig` 而不是
    /// 主 `client_sig`.
    ///
    /// 缺失 (futunn HK 账号 / 老 backend) → 空 Vec (handler 检查 `is_empty()`
    /// 决定 fallback 主 `client_sig`).
    ///
    /// ## ⚠️ v1.4.96 BUG #010 doctrine fix (external reviewer double-tester 2026-04-26):
    ///
    /// 真机 verify 发现 backend 对 **futunn 账号也下发 moomoo_client_sig**
    /// (mm_sig_len=128). 字段名 `moomoo_*` **不**意味着账号是 moomoo 系.
    ///
    /// **不要**基于 `moomoo_client_sig.is_empty()` 判账号 broker path. 真正
    /// 的 broker path 判断用 `broker_id` (1001/1007=Futu HK/US, 6xxx=moomoo).
    pub moomoo_client_sig: Vec<u8>,
    /// v1.4.94 G6 (P2 protocol gap): `moomoo_client_key` 解密后的 client key
    /// (对应 moomoo path), 与 `client_key` 平级. 缺失 → 空 Vec.
    ///
    /// 对齐 C++ `auth_impl.cpp:3196,3260` `account.us_client_key_` (经
    /// `UpdateRandKey` 解密).
    pub moomoo_client_key: Vec<u8>,
    /// v1.4.94 G6 (P2 protocol gap): `moomoo_web_sig_new` from `/authority/`
    /// 响应. 对齐 C++ `auth_impl.cpp:3197,3260` `account.us_web_sig_`. 用于
    /// moomoo path repull_auth_code (类似 `web_sig` 之于主 path). 缺失 →
    /// 空字符串.
    pub moomoo_web_sig: String,
}

/// Initial authentication result plus the pre-login site-config runtime state
/// that must be handed to the authenticated Gateway lifecycle exactly once.
///
/// Keeping this wrapper separate prevents reactive credential refreshes from
/// replacing the already-running authenticated site-config actor/store.
#[derive(Debug, Clone)]
pub struct AuthSession {
    pub auth_result: AuthResult,
    pub bootstrap_site_config: crate::auth::site_config::SharedSiteConfig,
}

#[cfg(test)]
mod tests;