futu_auth/

machine.rs

//! 软机器绑定（soft machine binding）
//!
//! 将 API Key 与一个稳定的机器指纹绑定，防止 keys.json 被整体复制到别的机器后仍可用。
//!
//! ## 强度说明 — 这是"软"绑定，不是硬件锁
//!
//! - Linux: 读 `/etc/machine-id`（world-readable，只需文件读权限即可拿到）
//! - macOS: 解析 `ioreg` 输出拿 `IOPlatformUUID`（任何用户都能跑 ioreg）
//! - Windows / 其他平台: 当前没有 raw machine-id reader；未启用绑定时不限，
//!   一旦 key 配置了 `allowed_machines`，`Unsupported` 会 fail closed
//!
//! 能挡住：
//! - 把 `keys.json` 整个拷到别的开发机 / VM / Docker 镜像里直接用
//! - 密钥不小心进了 git，clone 到别的机器也跑不起来
//!
//! 挡不住：
//! - 攻击者已经登上目标机器 → 他能读到 machine-id，就能伪造指纹
//! - 真要强绑定得走 TPM / Secure Enclave，需要独立安全设计，不属于当前软绑定模型
//!
//! ## 指纹公式
//!
//! `SHA-256("futu-machine-bind:v1:" || key_id || ":" || raw_machine_id)` → 64 位 hex
//!
//! key_id 混入哈希的目的是：同一台机器上不同 key 的指纹不同，泄漏一个 key 的指纹
//! 不会暴露别的 key 绑定的是不是同一台机器。

use std::sync::OnceLock;

use sha2::{Digest, Sha256};

#[cfg(any(target_os = "macos", test))]
// macOS system ioreg binary. Use the absolute path to avoid PATH hijack in the
// local soft-machine-binding reader; this is OS integration, not Futu protocol.
const MACOS_IOREG_PATH: &str = "/usr/sbin/ioreg";
#[cfg(any(target_os = "macos", test))]
// ioreg output for IOPlatformExpertDevice is normally tiny. Keep a generous
// local cap so a malformed/hijacked subprocess cannot feed unbounded stdout.
const MAX_MACOS_IOREG_STDOUT_BYTES: usize = 64 * 1024;

#[derive(Debug, Clone, thiserror::Error)]
#[non_exhaustive]
pub enum MachineError {
    #[error("platform not supported for machine binding (only macOS/Linux)")]
    Unsupported,
    #[error("failed to read machine id: {0}")]
    Io(String),
    #[error("machine id empty or malformed")]
    Malformed,
    #[error("key bound to different machine")]
    Mismatch,
}

/// 获取本机原始 machine-id（每进程只调用一次，后续走缓存）
pub fn raw_machine_id() -> Result<String, MachineError> {
    static CACHE: OnceLock<Result<String, MachineError>> = OnceLock::new();
    cached_raw_machine_id(&CACHE, read_raw_machine_id)
}

fn cached_raw_machine_id(
    cache: &OnceLock<Result<String, MachineError>>,
    reader: impl FnOnce() -> Result<String, MachineError>,
) -> Result<String, MachineError> {
    cache.get_or_init(reader).clone()
}

#[cfg(target_os = "linux")]
fn read_raw_machine_id() -> Result<String, MachineError> {
    for path in ["/etc/machine-id", "/var/lib/dbus/machine-id"] {
        if let Ok(s) = std::fs::read_to_string(path) {
            let trimmed = s.trim();
            if !trimmed.is_empty() {
                return Ok(trimmed.to_string());
            }
        }
    }
    Err(MachineError::Io("/etc/machine-id not readable".to_string()))
}

#[cfg(target_os = "macos")]
fn read_raw_machine_id() -> Result<String, MachineError> {
    let out = std::process::Command::new(MACOS_IOREG_PATH)
        .args(["-rd1", "-c", "IOPlatformExpertDevice"])
        .output()
        .map_err(|e| MachineError::Io(format!("ioreg: {e}")))?;
    if !out.status.success() {
        return Err(MachineError::Io(format!("ioreg exit {}", out.status)));
    }
    parse_macos_ioreg_uuid(&out.stdout)
}

#[cfg(any(target_os = "macos", test))]
fn parse_macos_ioreg_uuid(stdout: &[u8]) -> Result<String, MachineError> {
    if stdout.len() > MAX_MACOS_IOREG_STDOUT_BYTES {
        return Err(MachineError::Io(format!(
            "ioreg output too large: {} bytes",
            stdout.len()
        )));
    }

    let text = String::from_utf8_lossy(stdout);
    for line in text.lines() {
        if let Some((_before, after)) = line.split_once("\"IOPlatformUUID\"") {
            // 格式: "IOPlatformUUID" = "XXXX-XXXX-..."
            let after_eq = after.split_once('=').map(|x| x.1).unwrap_or("");
            let start = after_eq.find('"').map(|i| i + 1);
            let end = start.and_then(|s| after_eq[s..].find('"').map(|e| s + e));
            if let (Some(s), Some(e)) = (start, end) {
                let uuid = &after_eq[s..e];
                if is_valid_platform_uuid(uuid) {
                    return Ok(uuid.to_string());
                }
                return Err(MachineError::Malformed);
            }
        }
    }
    Err(MachineError::Malformed)
}

#[cfg(any(target_os = "macos", test))]
fn is_valid_platform_uuid(value: &str) -> bool {
    let bytes = value.as_bytes();
    if bytes.len() != 36 {
        return false;
    }
    for (idx, byte) in bytes.iter().enumerate() {
        match idx {
            8 | 13 | 18 | 23 => {
                if *byte != b'-' {
                    return false;
                }
            }
            _ => {
                if !byte.is_ascii_hexdigit() {
                    return false;
                }
            }
        }
    }
    true
}

#[cfg(not(any(target_os = "linux", target_os = "macos")))]
fn read_raw_machine_id() -> Result<String, MachineError> {
    Err(MachineError::Unsupported)
}

/// 计算指定 key_id 在本机的指纹哈希（64 位 hex）
pub fn fingerprint_for(key_id: &str) -> Result<String, MachineError> {
    let raw = raw_machine_id()?;
    Ok(fingerprint_from_raw(key_id, &raw))
}

/// 纯函数版本（方便单元测试）
#[must_use]
pub fn fingerprint_from_raw(key_id: &str, raw: &str) -> String {
    let mut h = Sha256::new();
    h.update(b"futu-machine-bind:v1:");
    h.update(key_id.as_bytes());
    h.update(b":");
    h.update(raw.as_bytes());
    hex::encode(h.finalize())
}

/// 检查本机指纹是否在白名单里
///
/// - `allowed` 为 `None` → 视为未启用机器绑定，始终通过
/// - `allowed` 为空列表 → 视为禁止所有机器（用于"临时冻结"某 key）
/// - 取不到 machine-id（平台不支持 / 文件缺失）→ 视为 Mismatch（宁紧勿松）
pub fn check(key_id: &str, allowed: Option<&[String]>) -> Result<(), MachineError> {
    let Some(list) = allowed else {
        return Ok(());
    };
    let fp = fingerprint_for(key_id)?;
    if list.iter().any(|x| x == &fp) {
        Ok(())
    } else {
        Err(MachineError::Mismatch)
    }
}

#[cfg(test)]
mod tests;