futu_backend/auth/

device.rs

//! device_id 持久化 + credentials 文件管理
//!
//! 统一存储根目录 `~/.futu-opend-rs/`（对齐 C++ `~/.com.futunn.FutuOpenD/`）。
//! v1.4.17 起把 credentials 从 cwd 下的 `.futu_credentials_{account}` 搬过来，
//! 并把 device_id 单独持久化到 `device-<hash>.dat`。
//!
//! 生命周期（见 CLAUDE.md "device_id 生命周期"）：
//! - 首次启动 → 随机生成 16-hex → 写文件
//! - 后续启动 → 读文件
//! - `--device-id <hex>` → 覆盖文件 + 用这个值
//! - `--reset-device` → 删 device + credentials 文件
//! - SMS `error_code=21` → `authenticate_with_callback` 自动 reset + 重试

use super::{
    CredentialTicketStatus, TGTGT_VALIDITY_SECS, UserAttribution, normalize_phone_account,
};

mod credentials_store;
mod storage;

#[cfg(test)]
use credentials_store::save_credentials_to_path;
pub(in crate::auth) use credentials_store::{CredentialsStoreError, save_credentials};
use storage::{
    DirEnforceError, cleanup_remove_file, try_credentials_path, try_device_id_path,
    write_secret_file_best_effort,
};
pub(super) use storage::{try_futu_opend_dir, write_secret_file};

#[cfg(test)]
pub(super) use storage::{
    account_key, credentials_path, device_id_path, ensure_dir_0700, futu_opend_dir,
};

#[cfg(all(test, unix))]
pub(super) use storage::cleanup_set_permissions_0600;

pub(super) const CURRENT_CREDENTIALS_SCHEMA_VERSION: u32 = 1;

fn legacy_credentials_schema_version() -> u32 {
    0
}

/// 保存的凭据结构 —— `~/.futu-opend-rs/credentials-<hash>.json` 的 schema。
///
/// v1.4.5+ 新增 `user_attribution` 字段（必填，无 `serde(default)`）：旧格式
/// 凭据反序列化失败 → `load_credentials` 返回 None → 自动回落到密码登录。这是
/// 故意的：旧凭据基于 CN cipher，不能直接套 moomoo 域名切换逻辑。
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub(super) struct SavedCredentials {
    /// Credentials schema version. Missing means legacy v0.
    ///
    /// v1.4.111 codex legacy deep-dive follow-up: earlier schema evolution relied
    /// solely on `#[serde(default)]`, which made it hard to distinguish legacy
    /// credentials from current ones during future migrations. New writes always
    /// persist [`CURRENT_CREDENTIALS_SCHEMA_VERSION`]; load upgrades v0 files
    /// in-place after account safety checks pass.
    #[serde(default = "legacy_credentials_schema_version")]
    pub(super) schema_version: u32,
    /// v1.4.67 Bug #1 (external reviewer P0): 持久化 login account 字符串到文件内容，load 时
    /// 校验文件的 account 字段必须与 expected account 一致，防止 cross-account
    /// corruption（external reviewer 报告 `credentials-<hashA>.json` 里存了 uid_B 的情况导致
    /// unlock 用错密码验证别人身份 → 风险跨账户交易）
    ///
    /// Backward compat (v1.4.70 hotfix): 旧 v1.4.66 及之前的文件没这字段 →
    /// serde default 空字符串 → load 时**静默升级** populate + 写回，不再强制
    /// 删文件重 SMS（v1.4.68 Bug #1 副作用：强制 SMS 累积触发 Futu 后端限流）
    #[serde(default)]
    pub(super) account: String,
    pub(super) device_id: String,
    pub(super) device_sig: String,
    pub(super) tgtgt: String,
    /// Unix seconds when the current cached `tgtgt` was written.
    ///
    /// The service-side ticket validity is 30 days from creation
    /// ([`TGTGT_VALIDITY_SECS`]). Older credential files did not persist this
    /// timestamp; `0` means unknown and status surfaces should ask users to
    /// refresh credentials once rather than pretending the ticket is fresh.
    #[serde(default)]
    pub(super) tgtgt_saved_at: u64,
    pub(super) rand_key_b64: String,
    pub(super) uid: u64,
    pub(super) user_attribution: UserAttribution,
    /// v1.4.72 BUG-009 Fix 9a (external reviewer v1.4.69 P1): 持久化最近一次的
    /// `device_verify_sig`（由 `/authority/` 响应 error.device_verify_sig
    /// 提供，短 TTL ~5 分钟），避免 daemon 启动重 POST `/authority/` 触发新
    /// SMS + 失效旧码 → 用户输旧码 → code=21 → 累计失败触发 cause #4 账户锁。
    ///
    /// **用法**：`authenticate_with_callback` 入口检测 SavedCredentials 的
    /// dvs 是否 < 5min，若是 → log WARN 警告用户"刚收到过 SMS 不要重复触发"，
    /// 并 hint 使用 `--verify-code <已收到的 SMS>` 避免新 SMS。
    ///
    /// **存储时刻**：post_auth / remember_login 两路径从 error 抽出 dvs 后。
    /// Backward compat: Optional 字段，v1.4.71 及之前的文件没此字段 → serde
    /// default None → 不影响现有用户。
    #[serde(default)]
    pub(super) device_verify_sig: Option<String>,
    #[serde(default)]
    pub(super) device_verify_sig_ts: Option<u64>,
    /// v1.4.81 BUG-009 Fix 9a Option B (replaces Option A 方向错):
    /// 持久化 `req_device_code` 响应里的 `device_code_sig`（SMS 一次有效、对应
    /// 一条 SMS 码）。Option A 只 cache dvs 跳 authority POST，但 req_device_code
    /// 仍发新 SMS 覆盖老码（v1.4.75 真机 verify 推翻 Risk 2 假设）。
    /// Option B **同时 cache device_code_sig** → Fix 9a 路径**跳过 req_device_code
    /// 整步**直接 verify_device_code with cached dcs + --verify-code X。
    ///
    /// **存储时刻**：`handle_device_verify` 内部 req_device_code 响应返回后立即
    /// persist（即在 prompt_input 之前）—— 这样 daemon 在 stdin atty fail
    /// 非交互退出之前，dcs 已落盘。
    ///
    /// **TTL**：同 dvs 5min（后端窗口未文档化，保守取 dvs 相同 TTL；真机 verify
    /// 后可调）。
    #[serde(default)]
    pub(super) device_code_sig: Option<String>,
    #[serde(default)]
    pub(super) device_code_sig_ts: Option<u64>,
    /// v1.4.93 G3 (CLAUDE.md C4 audit): 持久化 `web_sig`，对齐 C++
    /// `FTLogin/Src/ftlogin/auth/impl/auth_impl.cpp:3193,3260`
    /// （`web_sig_new` 解到 `account.web_sig_`）。
    ///
    /// **用途**：G2 `RepullAuthCode` 需要 `web_sig` 作 POST body 字段
    /// （对齐 C++ `auth_impl.cpp:738-748`），broker auth_code 过期或
    /// `kAuthNoValidCid` 时用来拉新 auth_code，避免必须重启 daemon。
    ///
    /// **存储时刻**：`save_credentials_from_response` 解 result.web_sig_new
    /// 后落盘。
    ///
    /// Backward compat: `#[serde(default)]` 兼容 v1.4.92 及之前的文件
    /// （没此字段 → 空字符串 → repull 路径调用前 check empty 跳过, fallback
    /// 走 platform refresh）。
    #[serde(default)]
    pub(super) web_sig: String,
    /// v1.4.94 G6 (P2 protocol gap): `moomoo_client_sig` (base64-encoded)
    /// 持久化, 对齐 C++ `auth_impl.cpp:3195,3260` `account.us_client_sig_`.
    ///
    /// **用途**: moomoo / US 路径 broker channel 鉴权 — attribution =
    /// US/SG/AU/JP/CA 时 broker_auth_code 换 client_sig 走的是
    /// `moomoo_client_sig` 而不是主 `client_sig`. 持久化让 daemon restart 后
    /// 不必重新 password auth 也能用 moomoo path.
    ///
    /// Backward compat: `#[serde(default)]` 兼容 v1.4.93 及之前的文件
    /// (空 → fallback 主 client_sig).
    #[serde(default)]
    pub(super) moomoo_client_sig: String,
    /// v1.4.94 G6: `moomoo_web_sig_new` 持久化, 对齐 C++ `auth_impl.cpp:3197,3260`
    /// `account.us_web_sig_`. 用于 moomoo path repull_auth_code.
    /// 缺失 → 空字符串 fallback 主 `web_sig`.
    #[serde(default)]
    pub(super) moomoo_web_sig: String,
}

/// v1.4.72 BUG-009 Fix 9a: device_verify_sig TTL (秒)
///
/// 对齐 Futu 后端 SMS 窗口 (~5 分钟内输入有效)。超此时间 backend 会主动
/// invalidate dvs，此时即使 cached 也需要重新 POST /authority 触发新 SMS。
pub(super) const DEVICE_VERIFY_SIG_TTL_SECS: u64 = 5 * 60;

/// v1.4.81 BUG-009 Fix 9a Option B: device_code_sig TTL (秒)
///
/// 对齐 Futu 后端 SMS 窗口 (~5 分钟，和 dvs 一致作保守假设，v1.4.82+ 按真机
/// verify 调整)。超此时间 backend 会主动 invalidate → verify_device_code
/// 返 code=21，此时必须重跑 req_device_code 拿新 dcs + 新 SMS。
pub(super) const DEVICE_CODE_SIG_TTL_SECS: u64 = 5 * 60;

#[derive(Debug)]
pub enum DeviceStoreError {
    Dir(String),
}

impl std::fmt::Display for DeviceStoreError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            DeviceStoreError::Dir(message) => write!(f, "{message}"),
        }
    }
}

impl std::error::Error for DeviceStoreError {}

fn device_store_dir_error(err: DirEnforceError) -> DeviceStoreError {
    DeviceStoreError::Dir(err.to_string())
}

fn dir_enforce_to_io_error(err: DirEnforceError) -> std::io::Error {
    std::io::Error::other(err.to_string())
}

/// 启动时扫 `~/.futu-opend-rs/` 把已存在的 secret 文件 (credentials-*.json
/// / device-*.dat) 收紧到 0600. v1.4.101 及以前版本可能创建了 0644 文件,
/// 此 fn 是迁移路径.
///
/// 由 `init_auth_state` (或类似入口) 在 daemon 启动早期调用. 失败 best-effort
/// (warn but don't fail), 因为 chmod 失败 != 凭据本身失效.
pub fn tighten_secret_files_at_startup() {
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        let dir = match try_futu_opend_dir() {
            Ok(dir) => dir,
            Err(err) => {
                tracing::warn!(
                    error = %err,
                    "auth secret-file permission tightening skipped because store dir is unavailable"
                );
                return;
            }
        };
        let Ok(entries) = std::fs::read_dir(&dir) else {
            return;
        };
        for entry in entries.flatten() {
            let path = entry.path();
            let Some(name) = path.file_name().and_then(|n| n.to_str()) else {
                continue;
            };
            // 仅收紧 secret 文件: credentials-<hash>.json / device-<hash>.dat.
            // 不收紧 keys.json (用户可能想 ACL 给 systemd group), 不收紧 logs/ etc.
            //
            // v1.4.104 external reviewer P2-004 (P2) fix: 扩展到 sidecar 文件 (`.backup` / `.bak` /
            // `.tmp` / `.swp`). 编辑器 vim / git rebase / external backup tool 等
            // 可能创建 `credentials-<hash>.json.backup` 0644 文件, 同样含 secret
            // 不能放任. 任何 name 以 `credentials-` 或 `device-` 开头都收紧.
            let is_secret = name.starts_with("credentials-") || name.starts_with("device-");
            if !is_secret {
                continue;
            }
            let Ok(meta) = entry.metadata() else { continue };
            let mode = meta.permissions().mode() & 0o777;
            if mode != 0o600 {
                tracing::warn!(
                    path = %path.display(),
                    actual_mode = format!("0{:o}", mode),
                    "v1.4.102 BUG-012 fix: secret file has loose permissions; tightening to 0600"
                );
                if let Err(e) =
                    std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o600))
                {
                    tracing::warn!(
                        path = %path.display(),
                        error = %e,
                        "failed to tighten secret file permissions; please chmod 0600 manually"
                    );
                }
            }
        }
    }
    #[cfg(not(unix))]
    {
        // Windows: ACL 模型不同, 此 fn 不展开.
    }
}

/// 读取 device_id；文件不存在则生成新的 16-hex 随机值并持久化。
///
/// 如果 `override_value` 是 `Some(hex)`（来自 `--device-id` CLI 参数），
/// 直接用并更新文件。
pub fn read_or_generate_device_id(
    account: &str,
    override_value: Option<&str>,
) -> Result<String, DeviceStoreError> {
    let path = try_device_id_path(account).map_err(device_store_dir_error)?;

    if let Some(explicit) = override_value {
        // 用户显式指定 —— 更新持久化文件 (v1.4.102 BUG-012: 0600 secret-file)
        if write_secret_file(&path, explicit.as_bytes()).is_err() {
            tracing::warn!(path = %path.display(), "failed to persist --device-id override");
        } else {
            // v1.4.106 codex 0558 F2: log fingerprint, 不写 raw device_id
            tracing::info!(
                path = %path.display(),
                device_id_fp = %super::redact::device_id_log_fingerprint(explicit),
                "device_id overridden by --device-id and persisted"
            );
        }
        return Ok(explicit.to_string());
    }

    // 文件已存在 → 读取
    if let Ok(content) = std::fs::read_to_string(&path) {
        let trimmed = content.trim().to_string();
        if trimmed.len() == 16 && trimmed.chars().all(|c| c.is_ascii_hexdigit()) {
            tracing::debug!(path = %path.display(), "loaded existing device_id");
            return Ok(trimmed);
        }
        tracing::warn!(
            path = %path.display(),
            "device_id file contents invalid, regenerating"
        );
    }

    // 首次运行 / 文件损坏 → 生成随机 16-hex
    let device_id = {
        let bytes: [u8; 8] = rand::random();
        format!("{:x}", u64::from_ne_bytes(bytes))
            .chars()
            .chain(std::iter::repeat('0'))
            .take(16)
            .collect::<String>()
    };
    // v1.4.102 BUG-012: device_id 也是 secret (用于设备识别), 0600
    if write_secret_file(&path, device_id.as_bytes()).is_err() {
        tracing::warn!(path = %path.display(), "failed to persist device_id");
    } else {
        // v1.4.106 codex 0558 F2: log fingerprint, 不写 raw device_id
        tracing::info!(
            path = %path.display(),
            device_id_fp = %super::redact::device_id_log_fingerprint(&device_id),
            "generated and persisted new device_id"
        );
    }
    Ok(device_id)
}

/// 删除 device_id 文件 + credentials 文件（`--reset-device` 使用）。
///
/// device_id 被服务端锁定后必须换新的 —— 单纯改密码无法恢复。
pub fn reset_device_state(account: &str) -> std::io::Result<()> {
    let dev_path = try_device_id_path(account).map_err(dir_enforce_to_io_error)?;
    let cred_path = try_credentials_path(account).map_err(dir_enforce_to_io_error)?;
    let mut removed = Vec::new();
    if dev_path.exists() {
        std::fs::remove_file(&dev_path)?;
        removed.push(dev_path.display().to_string());
    }
    if cred_path.exists() {
        std::fs::remove_file(&cred_path)?;
        removed.push(cred_path.display().to_string());
    }
    if removed.is_empty() {
        tracing::info!("reset_device: no existing device/credentials files to remove");
    } else {
        tracing::info!(files = ?removed, "reset_device: removed device and credentials files");
    }
    Ok(())
}

pub(super) fn load_credentials(account: &str) -> Option<SavedCredentials> {
    let path = match try_credentials_path(account) {
        Ok(path) => path,
        Err(err) => {
            tracing::warn!(
                error = %err,
                "credentials file path unavailable; caller will see no cached credentials"
            );
            return None;
        }
    };
    // v1.4.17 迁移：如果新路径不存在但 cwd 下有老文件，自动迁移
    if !path.exists() {
        let legacy = std::path::PathBuf::from(format!(".futu_credentials_{account}"));
        if legacy.exists() {
            if let Err(e) = std::fs::rename(&legacy, &path) {
                tracing::warn!(error = %e, "failed to migrate legacy credentials");
            } else {
                tracing::info!(
                    from = %legacy.display(),
                    to = %path.display(),
                    "migrated legacy credentials file"
                );
            }
        }
    }
    // v1.4.104 external reviewer S-004 (P1): 之前 `.ok()?` silently swallow IO / deserialize
    // 错误, 让 caller 看到 "no cached credentials" 但实际是 "file exists 读不
    // 出来" / "JSON 损坏". longrun bug 难定位. 现在 loud warn 让 daemon log
    // 留有真因.
    //
    // v1.4.104 codex round 2 F1 (P1) fix: 不能写 raw account / first_64_bytes
    // 因 credentials file 起始即 device_sig / tgtgt / rand_key_b64 / web_sig
    // / moomoo_client_sig 等敏感字段, partial-write 时这些可能在 first 64
    // bytes 里. 改用 hash + len + serde 位置错误描述.
    let path_basename = path
        .file_name()
        .and_then(|s| s.to_str())
        .unwrap_or("<unnamed>");
    let account_digest = {
        use sha2::{Digest, Sha256};
        let mut h = Sha256::new();
        h.update(account.as_bytes());
        let d = h.finalize();
        // codex round 3 polish: 用 02x zero-pad 保证固定 8 hex 字符 (之前
        // {:x} 会丢前导零, 让 ops 看 log 时长度不一致). 4 bytes ≈ 1/2^32 碰
        // 撞概率, 对单机 daemon 足够区分不同 account.
        format!("{:02x}{:02x}{:02x}{:02x}", d[0], d[1], d[2], d[3])
    };
    let data = match std::fs::read_to_string(&path) {
        Ok(s) => s,
        Err(e) => {
            tracing::warn!(
                error = %e,
                error_kind = ?e.kind(),
                path_basename,
                account_digest,
                "credentials file read failed (e.g. NotFound, PermissionDenied, IsADirectory). \
                 caller will see 'no cached credentials'. account hashed to avoid \
                 PII; full path elided."
            );
            return None;
        }
    };
    let mut cred: SavedCredentials = match serde_json::from_str(&data) {
        Ok(c) => c,
        Err(e) => {
            // codex round 2 F1: 计算 SHA256 of credential bytes (前 8 字节 hex)
            // 用作 fingerprint 区分不同 corruption 实例, 不暴露原文.
            let blob_digest = {
                use sha2::{Digest, Sha256};
                let mut h = Sha256::new();
                h.update(data.as_bytes());
                let d = h.finalize();
                // codex round 3 polish: 02x zero-pad fixed 8 hex
                format!("{:02x}{:02x}{:02x}{:02x}", d[0], d[1], d[2], d[3])
            };
            tracing::error!(
                error = %e,
                line = e.line(),
                column = e.column(),
                path_basename,
                account_digest,
                data_len = data.len(),
                blob_digest,
                "credentials JSON deserialize failed — file likely corrupted (partial write \
                 / disk error / version skew). user may need to re-auth via \
                 password + SMS. raw bytes elided (含 device_sig / tgtgt / \
                 rand_key_b64 等敏感字段); 用 blob_digest 区分不同 corruption."
            );
            return None;
        }
    };

    // v1.4.70 hotfix — 修 v1.4.68 Bug #1 副作用（强制 re-SMS 触发 Futu 限流）
    //
    // v1.4.68 Bug #1 引入 `cred.account != account` 强校验（防 cross-account
    // corruption，安全 P0），但两种 **合法场景**被误杀，导致升级用户强制 SMS：
    //
    //   (1) Legacy v1.4.66 及之前文件：`cred.account` 空（serde default）
    //       → 本 hotfix：**静默升级** populate + 写回，不删文件
    //   (2) Phone 格式变体：`+86-13900000000` vs `13900000000` 归一化后哈希
    //       相同（同一文件），但 `cred.account` 字符串不同
    //       → 本 hotfix：**比较 normalize 后的值**，接受同账号不同写法
    //
    // 安全目标（Bug #1）保留：**normalize 之后真不等** = 真 cross-account 污染
    // → 仍然删文件走 SMS（见下方 else 分支）
    let (normalized_expected, _) = normalize_phone_account(account);

    if cred.account.is_empty() {
        // Legacy <=v1.4.66 文件：静默升级 account 字段 + 写回，让下次 load 直接命中
        // v1.4.106 codex 0558 F2: log fingerprint, 不写 raw account
        tracing::info!(
            file = %path.display(),
            account_fp = %super::redact::account_log_fingerprint(&normalized_expected),
            "legacy credentials file — silently upgrading account field (v1.4.70 hotfix)"
        );
        cred.account = normalized_expected.clone();
        cred.schema_version = CURRENT_CREDENTIALS_SCHEMA_VERSION;
        // 写回是 best-effort：失败不影响当前 load（下次启动再试）
        // v1.4.102 BUG-012: 0600 secret-file
        if let Ok(json) = serde_json::to_string_pretty(&cred) {
            write_secret_file_best_effort(&path, json.as_bytes(), "legacy_account_upgrade");
        }
        return Some(cred);
    }

    let (normalized_got, _) = normalize_phone_account(&cred.account);
    if normalized_got != normalized_expected {
        // Normalize 后仍不等 = 真 cross-account 污染（md5 16-hex 碰撞概率 ~2^-64）
        // v1.4.106 codex 0558 F2+F3: 用 fingerprint 替代 raw account/uid
        // (cross-account corruption 时仍能比对两个 fp 不同, 但不泄漏真账号号 / uid).
        tracing::warn!(
            file = %path.display(),
            expected_account_fp = %super::redact::account_log_fingerprint(account),
            got_account_fp = %super::redact::account_log_fingerprint(&cred.account),
            got_uid_fp = %super::redact::uid_log_fingerprint(cred.uid),
            "credentials cross-account corruption detected — removing poisoned file, \
             will re-authenticate via password + SMS (v1.4.67 Bug #1 defense)"
        );
        cleanup_remove_file(&path, "load_credentials cross-account cleanup");
        return None;
    }

    if cred.schema_version < CURRENT_CREDENTIALS_SCHEMA_VERSION {
        tracing::info!(
            file = %path.display(),
            from_schema_version = cred.schema_version,
            to_schema_version = CURRENT_CREDENTIALS_SCHEMA_VERSION,
            account_fp = %super::redact::account_log_fingerprint(&normalized_expected),
            "legacy credentials schema detected — migrating in place"
        );
        cred.schema_version = CURRENT_CREDENTIALS_SCHEMA_VERSION;
        // Best-effort: current auth flow can continue with migrated in-memory
        // credentials even if the rewrite fails; next startup will try again.
        if let Ok(json) = serde_json::to_string_pretty(&cred) {
            write_secret_file_best_effort(&path, json.as_bytes(), "legacy_schema_migration");
        }
    }

    Some(cred)
}

/// v1.4.72 BUG-009 Fix 9a: 在现有 credentials 文件里 upsert `device_verify_sig`
/// 和时间戳。Daemon 收到 `/authority/` code=20 响应后调一次，保留 dvs 供下次
/// daemon 重启时探测"5min 内已有 dvs → 不要重 POST /authority 避免新 SMS"。
///
/// 如果 credentials 文件不存在（首次 auth），不做任何事（dvs 会在完整 auth
/// 成功后由 `save_credentials_from_response` 以完整 cred 形式写入；但 post-auth
/// 流程完成后 dvs 已用过，persist 其实不必要 —— 仅 remember_login → code=20
/// 的 retry scenario 需要本 helper）。
/// v1.4.81 BUG-009 Fix 9a gap: first-auth context for shell credentials write.
///
/// 当 credentials 文件尚不存在时（首次登录 / `rm credentials` 后），
/// 调用方应传入此 context，让 `persist_device_verify_sig` 能写一个最小壳
/// （account + device_id + uid + rand_key_b64 + attribution + dvs + dvs_ts），
/// 使下次启动能走 Fix 9a cached-dvs 路径（跳过 re-POST /authority/，避免新 SMS
/// 覆盖老 SMS 码）。
///
/// **不传 ctx（= None）** 保持 v1.4.72 原语义（credentials 不存在直接 return）。
pub(super) struct FirstAuthContext<'a> {
    pub uid: u64,
    pub rand_key_b64: &'a str,
    pub user_attribution: UserAttribution,
    pub device_id: &'a str,
}

pub(super) fn persist_device_verify_sig(
    account: &str,
    dvs: &str,
    first_auth_ctx: Option<FirstAuthContext<'_>>,
) {
    let path = match try_credentials_path(account) {
        Ok(path) => path,
        Err(err) => {
            tracing::warn!(
                error = %err,
                "persist_device_verify_sig skipped because credentials path is unavailable"
            );
            return;
        }
    };
    let now = auth_device_now_secs_or_zero("persist_device_verify_sig");

    // Case A (v1.4.72 原语义): credentials 已存在 → upsert dvs/ts
    if let Ok(data) = std::fs::read_to_string(&path) {
        match serde_json::from_str::<SavedCredentials>(&data) {
            Ok(mut cred) => {
                if let Some(ctx) = first_auth_ctx.as_ref() {
                    // Existing credentials can be stale when password auth is
                    // re-entered after remember-login rejection. The new DVS
                    // belongs to the freshly generated TGTGT/rand_key branch,
                    // so keep a pending-verify shell instead of pairing the
                    // new DVS/DCS with old tgtgt/rand_key material.
                    cred.uid = ctx.uid;
                    cred.rand_key_b64 = ctx.rand_key_b64.to_string();
                    cred.user_attribution = ctx.user_attribution;
                    cred.device_id = ctx.device_id.to_string();
                    cred.device_sig.clear();
                    cred.tgtgt.clear();
                    cred.web_sig.clear();
                    cred.moomoo_client_sig.clear();
                    cred.moomoo_web_sig.clear();
                }
                cred.device_verify_sig = Some(dvs.to_string());
                cred.device_verify_sig_ts = Some(now);
                // A new DVS invalidates any previously cached DCS, because
                // device_code_sig is tied to one req_device_code/DVS branch.
                cred.device_code_sig = None;
                cred.device_code_sig_ts = None;
                if let Ok(json) = serde_json::to_string_pretty(&cred)
                    && write_secret_file_best_effort(
                        &path,
                        json.as_bytes(),
                        "persist_device_verify_sig_upsert",
                    )
                {
                    tracing::info!(
                        path = %path.display(),
                        dvs_len = dvs.len(),
                        "v1.4.72 BUG-009 Fix 9a: device_verify_sig cached (5min TTL, upsert)"
                    );
                }
                return;
            }
            Err(_) => {
                tracing::warn!(
                    path = %path.display(),
                    "persist_device_verify_sig: 现有 credentials 解析失败，尝试用 shell 覆盖"
                );
                // fallthrough to Case B (若 caller 提供 ctx)
            }
        }
    }

    // Case B (v1.4.81 新增): credentials 不存在 OR 解析失败，且 caller 提供
    // first-auth context → 写最小壳以启用下次启动的 Fix 9a 路径
    let Some(ctx) = first_auth_ctx else {
        // Caller 未提供 ctx（旧调用路径或不关心 Fix 9a gap）→ 保持 v1.4.72 原语义
        return;
    };
    debug_assert!(
        !account.is_empty(),
        "persist_device_verify_sig shell: account must be populated (v1.4.67 guard)"
    );
    let shell = SavedCredentials {
        schema_version: CURRENT_CREDENTIALS_SCHEMA_VERSION,
        account: account.to_string(),
        device_id: ctx.device_id.to_string(),
        device_sig: String::new(),
        tgtgt: String::new(),
        tgtgt_saved_at: 0,
        rand_key_b64: ctx.rand_key_b64.to_string(),
        uid: ctx.uid,
        user_attribution: ctx.user_attribution,
        device_verify_sig: Some(dvs.to_string()),
        device_verify_sig_ts: Some(now),
        device_code_sig: None,
        device_code_sig_ts: None,
        // v1.4.93 G3: shell 路径写一个空 web_sig（首次 auth 还没收到 web_sig_new；
        // /authority/ POST 成功路径会 upsert 到完整 cred。RepullAuthCode 调用前
        // check empty 跳过 → 此场景 fallback 走 platform refresh）。
        web_sig: String::new(),
        // v1.4.94 G6 默认空 (parse.rs server-side fields populated separately)
        moomoo_client_sig: String::new(),
        moomoo_web_sig: String::new(),
    };
    if let Ok(json) = serde_json::to_string_pretty(&shell)
        && write_secret_file_best_effort(&path, json.as_bytes(), "persist_device_verify_sig_shell")
    {
        // v1.4.106 codex 0558 F3: log fingerprint 替代 raw uid
        tracing::info!(
            path = %path.display(),
            dvs_len = dvs.len(),
            uid_fp = %super::redact::uid_log_fingerprint(ctx.uid),
            "v1.4.81 BUG-009 Fix 9a gap: first-auth credentials shell persisted \
             (enables Fix 9a cached-dvs path on next startup; tgtgt/device_sig empty, \
             handle_device_verify only needs dvs+uid+rand_key)"
        );
    }
}

/// v1.4.72 BUG-009 Fix 9a: 检查 SavedCredentials 里的 `device_verify_sig` 是否
/// 在 `DEVICE_VERIFY_SIG_TTL_SECS` 内未过期。
///
/// 返 `Some(dvs)` 若 cached dvs 仍新鲜（用户可能刚收到过 SMS，手里的码还有效）。
/// 返 `None` 若缺 dvs 或已过期 → daemon 应走正常 /authority POST 流程。
pub(super) fn fresh_cached_device_verify_sig(cred: &SavedCredentials) -> Option<&str> {
    let dvs = cred.device_verify_sig.as_deref()?;
    let ts = cred.device_verify_sig_ts?;
    let now = auth_device_now_secs_or_zero("fresh_cached_device_verify_sig");
    let age = now.saturating_sub(ts);
    if age < DEVICE_VERIFY_SIG_TTL_SECS {
        Some(dvs)
    } else {
        None
    }
}

/// v1.4.81 BUG-009 Fix 9a Option B: 检查 SavedCredentials 里的
/// `device_code_sig` 是否在 `DEVICE_CODE_SIG_TTL_SECS` 内未过期。
///
/// 返 `Some(dcs)` 若 cached dcs 仍新鲜 → Fix 9a Option B 路径可跳
/// `req_device_code` 整步，直接用 cached dcs + 用户传入的 `--verify-code`
/// 调 `verify_device_code`。
pub(super) fn fresh_cached_device_code_sig(cred: &SavedCredentials) -> Option<&str> {
    let dcs = cred.device_code_sig.as_deref()?;
    let ts = cred.device_code_sig_ts?;
    let now = auth_device_now_secs_or_zero("fresh_cached_device_code_sig");
    let age = now.saturating_sub(ts);
    if age < DEVICE_CODE_SIG_TTL_SECS {
        Some(dcs)
    } else {
        None
    }
}

/// v1.4.81 BUG-009 Fix 9a Option B: upsert `device_code_sig` + ts 到已存在的
/// credentials 文件。credentials 不存在时返 —— Option B 必然在 shell-persist
/// 之后调用（Step 1 `persist_device_verify_sig(Some(ctx))` 已写 shell）。
pub(super) fn persist_device_code_sig(account: &str, dcs: &str) {
    let path = match try_credentials_path(account) {
        Ok(path) => path,
        Err(err) => {
            tracing::warn!(
                error = %err,
                "persist_device_code_sig skipped because credentials path is unavailable"
            );
            return;
        }
    };
    let Ok(data) = std::fs::read_to_string(&path) else {
        tracing::warn!(
            path = %path.display(),
            "persist_device_code_sig: credentials 文件不存在，跳过 dcs 持久化 \
             (Option B 前置不满足，需先跑 persist_device_verify_sig shell path)"
        );
        return;
    };
    let Ok(mut cred) = serde_json::from_str::<SavedCredentials>(&data) else {
        tracing::warn!(
            path = %path.display(),
            "persist_device_code_sig: credentials 解析失败，跳过 dcs 持久化"
        );
        return;
    };
    let now = auth_device_now_secs_or_zero("persist_device_code_sig");
    cred.device_code_sig = Some(dcs.to_string());
    cred.device_code_sig_ts = Some(now);
    // v1.4.102 BUG-012: 0600 secret-file
    if let Ok(json) = serde_json::to_string_pretty(&cred)
        && write_secret_file_best_effort(&path, json.as_bytes(), "persist_device_code_sig")
    {
        tracing::info!(
            path = %path.display(),
            dcs_len = dcs.len(),
            "v1.4.81 BUG-009 Fix 9a Option B: device_code_sig cached (5min TTL)"
        );
    }
}

fn auth_device_now_secs_or_zero(context: &'static str) -> u64 {
    match std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH) {
        Ok(duration) => duration.as_secs(),
        Err(err) => {
            tracing::warn!(
                context,
                error = ?err,
                "auth device wall clock is before UNIX_EPOCH; falling back to zero timestamp"
            );
            0
        }
    }
}

pub(super) fn credential_ticket_status(account: &str) -> Option<CredentialTicketStatus> {
    let cred = load_credentials(account)?;
    Some(credential_ticket_status_from_saved(
        cred.tgtgt_saved_at,
        auth_device_now_secs_or_zero("credential_ticket_status"),
    ))
}

fn credential_ticket_status_from_saved(saved_at: u64, now: u64) -> CredentialTicketStatus {
    if saved_at == 0 {
        return CredentialTicketStatus {
            saved_at: None,
            age_days: None,
            expires_in_days: None,
            expiry_warning: Some(
                "cached tgtgt age is unknown; run futucli daemon-reload once to refresh metadata"
                    .to_string(),
            ),
        };
    }
    let age_secs = now.saturating_sub(saved_at);
    let age_days = age_secs / 86_400;
    let expires_at = saved_at.saturating_add(u64::from(TGTGT_VALIDITY_SECS));
    let remaining_secs = i128::from(expires_at) - i128::from(now);
    let expires_in_days = remaining_secs.div_euclid(86_400) as i64;
    let expiry_warning = if remaining_secs <= 0 {
        Some(
            "cached tgtgt is expired; restart with password/SMS or refresh credentials".to_string(),
        )
    } else if expires_in_days < 5 {
        Some(format!(
            "cached tgtgt expires in {expires_in_days} days; run futucli daemon-reload before expiry"
        ))
    } else {
        None
    };
    CredentialTicketStatus {
        saved_at: Some(saved_at),
        age_days: Some(age_days),
        expires_in_days: Some(expires_in_days),
        expiry_warning,
    }
}

#[cfg(test)]
mod tests;