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::{UserAttribution, normalize_phone_account};

/// 保存的凭据结构 —— `~/.futu-opend-rs/credentials-<hash>.json` 的 schema。
///
/// v1.4.5+ 新增 `user_attribution` 字段（必填，无 `serde(default)`）：旧格式
/// 凭据反序列化失败 → `load_credentials` 返回 None → 自动回落到密码登录。这是
/// 故意的：旧凭据基于 CN cipher，不能直接套 moomoo 域名切换逻辑。
#[derive(Debug, serde::Serialize, serde::Deserialize)]
pub(super) struct SavedCredentials {
    /// v1.4.67 Bug #1 (eli P0): 持久化 login account 字符串到文件内容，load 时
    /// 校验文件的 account 字段必须与 expected account 一致，防止 cross-account
    /// corruption（eli 报告 `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,
    pub(super) rand_key_b64: String,
    pub(super) uid: u64,
    pub(super) user_attribution: UserAttribution,
    /// v1.4.72 BUG-009 Fix 9a (eli 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;

/// v1.4.106 codex 0558 F4 (P2): 把 dir create + 0700 收紧的 pure logic 提出
/// 来便于单测 (不依赖 HOME env 修改, 避免和并行 tests race).
///
/// 返 `Ok(())` 表示 dir 已存在 + mode = 0700; `Err` 含具体失败原因 (caller
/// 决定 fail-closed: process::exit / panic / log).
#[derive(Debug)]
pub(super) enum DirEnforceError {
    Create {
        path: std::path::PathBuf,
        source: std::io::Error,
    },
    #[cfg(unix)]
    Chmod {
        path: std::path::PathBuf,
        source: std::io::Error,
    },
}

impl std::fmt::Display for DirEnforceError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            DirEnforceError::Create { path, source } => {
                write!(f, "create_dir_all {}: {source}", path.display())
            }
            #[cfg(unix)]
            DirEnforceError::Chmod { path, source } => {
                write!(f, "chmod 0700 {}: {source}", path.display())
            }
        }
    }
}

pub(super) fn ensure_dir_0700(dir: &std::path::Path) -> Result<(), DirEnforceError> {
    std::fs::create_dir_all(dir).map_err(|source| DirEnforceError::Create {
        path: dir.to_path_buf(),
        source,
    })?;
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        std::fs::set_permissions(dir, std::fs::Permissions::from_mode(0o700)).map_err(
            |source| DirEnforceError::Chmod {
                path: dir.to_path_buf(),
                source,
            },
        )?;
    }
    Ok(())
}

/// 持久化存储根目录 `~/.futu-opend-rs/`. 不存在时自动创建.
///
/// **v1.4.106 codex 0558 F4 fail-closed (P2)**: 创建后强制 chmod 0700 (rwx------).
/// 之前用 `let _ = create_dir_all` + `let _ = set_permissions` 两次都吞错, dir
/// 可能被建成 0755 (默认 umask) → 同机其他用户能 list / `cat
/// credentials-*.json`. 升级了 BUG-012 单文件 0600 但容器/dir 仍可被遍历.
///
/// **fail-closed 语义**:
///   - create_dir_all 失败 → process::exit (无写盘 = 无凭据 = daemon 无法继续)
///   - set_permissions 失败 → process::exit (有 file 但 dir 0755 = 多用户机泄漏)
///
/// **不 panic**: 用 `process::exit(1)` + eprintln 让用户立刻看到 reason; 不让
/// 异常通过 `unwrap_or_else` / `Result::ok()` 路径被 caller 当 best-effort
/// 吃掉 (历史漂移信号).
pub(super) fn futu_opend_dir() -> std::path::PathBuf {
    #[cfg(test)]
    let dir = std::env::var_os("FUTU_OPEND_TEST_DIR")
        .map(std::path::PathBuf::from)
        .unwrap_or_else(|| {
            std::env::temp_dir().join(format!("futu-opend-rs-test-{}", std::process::id()))
        });
    #[cfg(not(test))]
    let home = dirs::home_dir().unwrap_or_else(|| std::path::PathBuf::from("."));
    #[cfg(not(test))]
    let dir = home.join(".futu-opend-rs");
    if let Err(e) = ensure_dir_0700(&dir) {
        match &e {
            DirEnforceError::Create { .. } => {
                eprintln!(
                    "FATAL (v1.4.106 F4): {e}\n\
                     daemon needs writable home dir for credentials / device_id / keys.\n\
                     check: HOME env / disk space / parent dir perms."
                );
            }
            #[cfg(unix)]
            DirEnforceError::Chmod { .. } => {
                eprintln!(
                    "FATAL (v1.4.106 F4): {e}\n\
                     multi-user host: refusing to continue with 0755 dir (other users\n\
                     can list / cat credentials-*.json). check filesystem ACL / mount ro."
                );
            }
        }
        std::process::exit(1);
    }
    dir
}

/// 把账号哈希成文件名友好的字符串（16 字符 hex）—— 避免账号里的 `+` / `-` /
/// `@` / 空格打破文件系统。同时保证 `+86-xxx` 和 `xxx` 归一化后共享同一文件。
pub(super) fn account_key(account: &str) -> String {
    let (normalized, _) = normalize_phone_account(account);
    format!("{:x}", md5::compute(normalized.as_bytes()))[..16].to_string()
}

pub(super) fn credentials_path(account: &str) -> std::path::PathBuf {
    futu_opend_dir().join(format!("credentials-{}.json", account_key(account)))
}

/// device_id 文件路径。单独一个文件持久化 16-hex device_id，生命周期**比
/// credentials 长**——credentials 会因为 tgtgt 过期 / error_code=15 失效而被
/// 清空，但 device_id 除非被服务端锁定否则一直保留，避免每次登录都被服务端
/// 当作新设备而要求 SMS 验证。
///
/// 对齐 C++ `FTGTW_Inner_API.cpp:198` `GetDeviceID()` —— 首次启动随机生成
/// 16 字节 hex 写入 `~/.com.futunn.FutuOpenD/F3CNN/Device.dat`，后续启动直接
/// 读取。
pub(super) fn device_id_path(account: &str) -> std::path::PathBuf {
    futu_opend_dir().join(format!("device-{}.dat", account_key(account)))
}

// ============================================================================
// v1.4.102 BUG-012 fix: secret file write + startup permission tightening
// ============================================================================
//
// **Background**: leaf v1.4.100 报告 `~/.futu-opend-rs/credentials-*.json`
// 文件被 `std::fs::write()` 创建为 0644 (rw-r--r--), 多用户机 / CI / 共享
// 开发机上其他用户能读 tgtgt / web_sig 等敏感凭据 → P0 (multi-user) /
// P1 (single-user). 修法 3 路:
//
//   1. 任何写敏感文件 (credentials / device_id) 的路径必须用 `write_secret_file`
//      → Unix 系统下 OpenOptions(.mode(0o600)) + 显式 set_permissions (兜底,
//      OpenOptions 的 mode 仅在 create 时生效; 已存在文件 truncate 不变 mode)
//   2. 启动时扫 `~/.futu-opend-rs/` 把已存在的 credentials-*.json /
//      device-*.dat 收紧到 0600 (`tighten_secret_files_at_startup`)
//   3. 单元测试覆盖 mode 回归

/// 写敏感文件 (credentials / device_id), Unix 强制 0600 (rw-------).
///
/// **首次创建**: OpenOptions(.mode(0o600)) 直接以 0600 创建.
/// **覆写已存在**: OpenOptions truncate 不改 mode, 显式 set_permissions 收紧.
///
/// **race 窗口**: 若文件已存在且权限错的, OpenOptions 打开后内容写入到 close
/// 之间 mode 仍是旧的 (0644). 但 set_permissions 紧跟 write_all 之后, 窗口
/// 极小. 严格场景应用 tempfile + atomic rename, 当前 best-effort 已远优于
/// "完全不收紧" 的 0644 默认.
///
/// **v1.4.102 codex 27 F10 (P2) fix**: atomic write via 0600 tempfile + rename.
/// 之前 truncate + write_all + set_permissions 的 sequence 有 race window —
/// 已存在 0644 文件被 truncate 到 0 字节后, 新内容写入到 set_permissions 之
/// 间, 同机其他用户可读到部分新 secret. atomic rename 保证 set_permissions
/// 在文件可见前已生效 (临时文件以 0600 创建).
///
/// **non-Unix** (Windows): 退化为 std::fs::write (Windows ACL 模型不同, 此 fn
/// 不展开).
pub(super) fn write_secret_file(path: &std::path::Path, content: &[u8]) -> std::io::Result<()> {
    #[cfg(unix)]
    {
        use std::io::Write;
        use std::os::unix::fs::{OpenOptionsExt, PermissionsExt};

        // v1.4.102 codex 27 F10: 用 0600 tempfile + atomic rename, race-free.
        let parent = path.parent().unwrap_or_else(|| std::path::Path::new("."));
        let file_name = path
            .file_name()
            .and_then(|n| n.to_str())
            .unwrap_or("secret");
        let tmp_path = parent.join(format!(
            ".{file_name}.{pid}.{nanos}.tmp",
            pid = std::process::id(),
            nanos = std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .map(|d| d.as_nanos())
                .unwrap_or(0),
        ));

        // 创建 0600 临时文件 (mode 在 create 时生效).
        let mut f = std::fs::OpenOptions::new()
            .create_new(true)
            .write(true)
            .mode(0o600)
            .open(&tmp_path)?;
        let write_res = f.write_all(content).and_then(|_| f.sync_all());
        drop(f);

        if let Err(e) = write_res {
            let _ = std::fs::remove_file(&tmp_path);
            return Err(e);
        }

        // 防御: chmod 一次确保 mode (理论上 create_new + .mode 已 0600,
        // 防止 umask 异常 / fs override).
        let _ = std::fs::set_permissions(&tmp_path, std::fs::Permissions::from_mode(0o600));

        // atomic rename: 如果 path 已存在, 旧 inode 被替换, 新 inode 已 0600.
        // 同机其他用户在 rename 完成前看不到新内容; 完成后看到的新文件已 0600.
        match std::fs::rename(&tmp_path, path) {
            Ok(()) => Ok(()),
            Err(e) => {
                let _ = std::fs::remove_file(&tmp_path);
                Err(e)
            }
        }
    }
    #[cfg(not(unix))]
    {
        std::fs::write(path, content)
    }
}

/// 启动时扫 `~/.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 = futu_opend_dir();
        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 eli 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>) -> String {
    let path = device_id_path(account);

    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 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 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"
        );
    }
    device_id
}

/// 删除 device_id 文件 + credentials 文件（`--reset-device` 使用）。
///
/// device_id 被服务端锁定后必须换新的 —— 单纯改密码无法恢复。
pub fn reset_device_state(account: &str) -> std::io::Result<()> {
    let dev_path = device_id_path(account);
    let cred_path = credentials_path(account);
    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 = credentials_path(account);
    // 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 eli 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,
                "v1.4.104 eli S-004 (P1) [codex round2 F1 redact]: 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,
                "v1.4.104 eli S-004 (P1) [codex round2 F1 redact]: 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();
        // 写回是 best-effort：失败不影响当前 load（下次启动再试）
        // v1.4.102 BUG-012: 0600 secret-file
        if let Ok(json) = serde_json::to_string_pretty(&cred) {
            let _ = write_secret_file(&path, json.as_bytes());
        }
        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)"
        );
        let _ = std::fs::remove_file(&path);
        return None;
    }

    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 = credentials_path(account);
    let now = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|d| d.as_secs())
        .unwrap_or(0);

    // 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) => {
                cred.device_verify_sig = Some(dvs.to_string());
                cred.device_verify_sig_ts = Some(now);
                if let Ok(json) = serde_json::to_string_pretty(&cred)
                    && write_secret_file(&path, json.as_bytes()).is_ok()
                {
                    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 {
        account: account.to_string(),
        device_id: ctx.device_id.to_string(),
        device_sig: String::new(),
        tgtgt: String::new(),
        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(&path, json.as_bytes()).is_ok()
    {
        // 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 = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|d| d.as_secs())
        .unwrap_or(0);
    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 = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|d| d.as_secs())
        .unwrap_or(0);
    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 = credentials_path(account);
    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 = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|d| d.as_secs())
        .unwrap_or(0);
    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(&path, json.as_bytes()).is_ok()
    {
        tracing::info!(
            path = %path.display(),
            dcs_len = dcs.len(),
            "v1.4.81 BUG-009 Fix 9a Option B: device_code_sig cached (5min TTL)"
        );
    }
}

/// v1.4.106 codex 0558 F1 (P1): credentials store error propagated to caller.
///
/// 之前 `save_credentials` 用 `if let Ok(...) && ...is_ok()` 双层 silent drop:
/// serialize 失败 / 写盘 IO 失败都被 swallow, daemon 继续运行像 "已存盘", 但
/// 下次启动 `load_credentials` 找不到文件 → 重做 SMS / 反刷 ret_type=15. 真机
/// pitfall #43 / #44 saga 反复触发.
///
/// 修法: 返 `Result<(), CredentialsStoreError>`, caller (尤其 setup-only +
/// authenticate path) 必须显式处理. 早 fail loud > 让 daemon 静默继续跑.
#[derive(Debug)]
pub(super) enum CredentialsStoreError {
    Serialize(serde_json::Error),
    Write {
        path: std::path::PathBuf,
        source: std::io::Error,
    },
}

impl std::fmt::Display for CredentialsStoreError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            CredentialsStoreError::Serialize(e) => {
                write!(f, "credentials serialize failed: {e}")
            }
            CredentialsStoreError::Write { path, source } => {
                write!(f, "credentials write {} failed: {source}", path.display())
            }
        }
    }
}

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

/// v1.4.106 codex 0558 F1 (P1): 写凭据 + 显式 Result.
///
/// **fail-closed 语义**: serialize / write IO 错误**必须**返给 caller, 不能
/// silent drop. 之前 silent 路径让 daemon 报 "auth ok" 但凭据没存 →
/// 下次启动重 SMS, 反刷限流.
pub(super) fn save_credentials(
    account: &str,
    cred: &SavedCredentials,
) -> Result<(), CredentialsStoreError> {
    // v1.4.67 Bug #1 fix: belt-and-suspenders —— 未来任何新 save_credentials
    // 调用点若忘了填 account 字段，debug build 立即 panic；release build
    // 会写空 account → 下次 load 也会 reject（不会静默 poison）。
    debug_assert!(
        !cred.account.is_empty(),
        "SavedCredentials.account must be populated (v1.4.67 Bug #1 guard)"
    );
    debug_assert_eq!(
        cred.account, account,
        "save_credentials: account param must match cred.account (v1.4.67 Bug #1 guard)"
    );
    let path = credentials_path(account);
    save_credentials_to_path(&path, cred)
}

fn save_credentials_to_path(
    path: &std::path::Path,
    cred: &SavedCredentials,
) -> Result<(), CredentialsStoreError> {
    // v1.4.102 BUG-012: 0600 secret-file (rw-------) for credentials
    let json = serde_json::to_string_pretty(cred).map_err(CredentialsStoreError::Serialize)?;
    write_secret_file(path, json.as_bytes()).map_err(|source| CredentialsStoreError::Write {
        path: path.to_path_buf(),
        source,
    })?;
    tracing::info!(
        path = %path.display(),
        "credentials saved (future logins skip verification)"
    );
    Ok(())
}

#[cfg(test)]
mod tests;