futu_auth/
machine.rs

1//! 软机器绑定（soft machine binding）
2//!
3//! 将 API Key 与一个稳定的机器指纹绑定，防止 keys.json 被整体复制到别的机器后仍可用。
4//!
5//! ## 强度说明 — 这是"软"绑定，不是硬件锁
6//!
7//! - Linux: 读 `/etc/machine-id`（world-readable，只需文件读权限即可拿到）
8//! - macOS: 解析 `ioreg` 输出拿 `IOPlatformUUID`（任何用户都能跑 ioreg）
9//! - Windows / 其他平台: 当前没有 raw machine-id reader；未启用绑定时不限，
10//!   一旦 key 配置了 `allowed_machines`，`Unsupported` 会 fail closed
11//!
12//! 能挡住：
13//! - 把 `keys.json` 整个拷到别的开发机 / VM / Docker 镜像里直接用
14//! - 密钥不小心进了 git，clone 到别的机器也跑不起来
15//!
16//! 挡不住：
17//! - 攻击者已经登上目标机器 → 他能读到 machine-id，就能伪造指纹
18//! - 真要强绑定得走 TPM / Secure Enclave，需要独立安全设计，不属于当前软绑定模型
19//!
20//! ## 指纹公式
21//!
22//! `SHA-256("futu-machine-bind:v1:" || key_id || ":" || raw_machine_id)` → 64 位 hex
23//!
24//! key_id 混入哈希的目的是：同一台机器上不同 key 的指纹不同，泄漏一个 key 的指纹
25//! 不会暴露别的 key 绑定的是不是同一台机器。
26
27use std::sync::OnceLock;
28
29use sha2::{Digest, Sha256};
30
31#[cfg(any(target_os = "macos", test))]
32// macOS system ioreg binary. Use the absolute path to avoid PATH hijack in the
33// local soft-machine-binding reader; this is OS integration, not Futu protocol.
34const MACOS_IOREG_PATH: &str = "/usr/sbin/ioreg";
35#[cfg(any(target_os = "macos", test))]
36// ioreg output for IOPlatformExpertDevice is normally tiny. Keep a generous
37// local cap so a malformed/hijacked subprocess cannot feed unbounded stdout.
38const MAX_MACOS_IOREG_STDOUT_BYTES: usize = 64 * 1024;
39
40#[derive(Debug, Clone, thiserror::Error)]
41#[non_exhaustive]
42pub enum MachineError {
43    #[error("platform not supported for machine binding (only macOS/Linux)")]
44    Unsupported,
45    #[error("failed to read machine id: {0}")]
46    Io(String),
47    #[error("machine id empty or malformed")]
48    Malformed,
49    #[error("key bound to different machine")]
50    Mismatch,
51}
52
53/// 获取本机原始 machine-id（每进程只调用一次，后续走缓存）
54pub fn raw_machine_id() -> Result<String, MachineError> {
55    static CACHE: OnceLock<Result<String, MachineError>> = OnceLock::new();
56    CACHE.get_or_init(read_raw_machine_id).clone()
57}
58
59#[cfg(target_os = "linux")]
60fn read_raw_machine_id() -> Result<String, MachineError> {
61    for path in ["/etc/machine-id", "/var/lib/dbus/machine-id"] {
62        if let Ok(s) = std::fs::read_to_string(path) {
63            let trimmed = s.trim();
64            if !trimmed.is_empty() {
65                return Ok(trimmed.to_string());
66            }
67        }
68    }
69    Err(MachineError::Io("/etc/machine-id not readable".to_string()))
70}
71
72#[cfg(target_os = "macos")]
73fn read_raw_machine_id() -> Result<String, MachineError> {
74    let out = std::process::Command::new(MACOS_IOREG_PATH)
75        .args(["-rd1", "-c", "IOPlatformExpertDevice"])
76        .output()
77        .map_err(|e| MachineError::Io(format!("ioreg: {e}")))?;
78    if !out.status.success() {
79        return Err(MachineError::Io(format!("ioreg exit {}", out.status)));
80    }
81    parse_macos_ioreg_uuid(&out.stdout)
82}
83
84#[cfg(any(target_os = "macos", test))]
85fn parse_macos_ioreg_uuid(stdout: &[u8]) -> Result<String, MachineError> {
86    if stdout.len() > MAX_MACOS_IOREG_STDOUT_BYTES {
87        return Err(MachineError::Io(format!(
88            "ioreg output too large: {} bytes",
89            stdout.len()
90        )));
91    }
92
93    let text = String::from_utf8_lossy(stdout);
94    for line in text.lines() {
95        if let Some((_before, after)) = line.split_once("\"IOPlatformUUID\"") {
96            // 格式: "IOPlatformUUID" = "XXXX-XXXX-..."
97            let after_eq = after.split_once('=').map(|x| x.1).unwrap_or("");
98            let start = after_eq.find('"').map(|i| i + 1);
99            let end = start.and_then(|s| after_eq[s..].find('"').map(|e| s + e));
100            if let (Some(s), Some(e)) = (start, end) {
101                let uuid = &after_eq[s..e];
102                if is_valid_platform_uuid(uuid) {
103                    return Ok(uuid.to_string());
104                }
105                return Err(MachineError::Malformed);
106            }
107        }
108    }
109    Err(MachineError::Malformed)
110}
111
112#[cfg(any(target_os = "macos", test))]
113fn is_valid_platform_uuid(value: &str) -> bool {
114    let bytes = value.as_bytes();
115    if bytes.len() != 36 {
116        return false;
117    }
118    for (idx, byte) in bytes.iter().enumerate() {
119        match idx {
120            8 | 13 | 18 | 23 => {
121                if *byte != b'-' {
122                    return false;
123                }
124            }
125            _ => {
126                if !byte.is_ascii_hexdigit() {
127                    return false;
128                }
129            }
130        }
131    }
132    true
133}
134
135#[cfg(not(any(target_os = "linux", target_os = "macos")))]
136fn read_raw_machine_id() -> Result<String, MachineError> {
137    Err(MachineError::Unsupported)
138}
139
140/// 计算指定 key_id 在本机的指纹哈希（64 位 hex）
141pub fn fingerprint_for(key_id: &str) -> Result<String, MachineError> {
142    let raw = raw_machine_id()?;
143    Ok(fingerprint_from_raw(key_id, &raw))
144}
145
146/// 纯函数版本（方便单元测试）
147#[must_use]
148pub fn fingerprint_from_raw(key_id: &str, raw: &str) -> String {
149    let mut h = Sha256::new();
150    h.update(b"futu-machine-bind:v1:");
151    h.update(key_id.as_bytes());
152    h.update(b":");
153    h.update(raw.as_bytes());
154    hex::encode(h.finalize())
155}
156
157/// 检查本机指纹是否在白名单里
158///
159/// - `allowed` 为 `None` → 视为未启用机器绑定，始终通过
160/// - `allowed` 为空列表 → 视为禁止所有机器（用于"临时冻结"某 key）
161/// - 取不到 machine-id（平台不支持 / 文件缺失）→ 视为 Mismatch（宁紧勿松）
162pub fn check(key_id: &str, allowed: Option<&[String]>) -> Result<(), MachineError> {
163    let Some(list) = allowed else {
164        return Ok(());
165    };
166    let fp = fingerprint_for(key_id)?;
167    if list.iter().any(|x| x == &fp) {
168        Ok(())
169    } else {
170        Err(MachineError::Mismatch)
171    }
172}
173
174#[cfg(test)]
175mod tests;
futu_auth/machine.rs

futu_auth/
machine.rs
