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#[derive(Debug, thiserror::Error)]
32#[non_exhaustive]
33pub enum MachineError {
34    #[error("platform not supported for machine binding (only macOS/Linux)")]
35    Unsupported,
36    #[error("failed to read machine id: {0}")]
37    Io(String),
38    #[error("machine id empty or malformed")]
39    Malformed,
40    #[error("key bound to different machine")]
41    Mismatch,
42}
43
44/// 获取本机原始 machine-id（每进程只调用一次，后续走缓存）
45pub fn raw_machine_id() -> Result<String, MachineError> {
46    static CACHE: OnceLock<Result<String, String>> = OnceLock::new();
47    match CACHE.get_or_init(|| read_raw_machine_id().map_err(|e| e.to_string())) {
48        Ok(s) => Ok(s.clone()),
49        Err(e) => Err(map_cached_err(e)),
50    }
51}
52
53fn map_cached_err(s: &str) -> MachineError {
54    if s == "platform not supported for machine binding (only macOS/Linux)" {
55        MachineError::Unsupported
56    } else if s == "machine id empty or malformed" {
57        MachineError::Malformed
58    } else {
59        MachineError::Io(s.to_string())
60    }
61}
62
63#[cfg(target_os = "linux")]
64fn read_raw_machine_id() -> Result<String, MachineError> {
65    for path in ["/etc/machine-id", "/var/lib/dbus/machine-id"] {
66        if let Ok(s) = std::fs::read_to_string(path) {
67            let trimmed = s.trim();
68            if !trimmed.is_empty() {
69                return Ok(trimmed.to_string());
70            }
71        }
72    }
73    Err(MachineError::Io("/etc/machine-id not readable".to_string()))
74}
75
76#[cfg(target_os = "macos")]
77fn read_raw_machine_id() -> Result<String, MachineError> {
78    let out = std::process::Command::new("ioreg")
79        .args(["-rd1", "-c", "IOPlatformExpertDevice"])
80        .output()
81        .map_err(|e| MachineError::Io(format!("ioreg: {e}")))?;
82    if !out.status.success() {
83        return Err(MachineError::Io(format!("ioreg exit {}", out.status)));
84    }
85    let text = String::from_utf8_lossy(&out.stdout);
86    for line in text.lines() {
87        if let Some((_before, after)) = line.split_once("\"IOPlatformUUID\"") {
88            // 格式: "IOPlatformUUID" = "XXXX-XXXX-..."
89            let after_eq = after.split_once('=').map(|x| x.1).unwrap_or("");
90            let start = after_eq.find('"').map(|i| i + 1);
91            let end = start.and_then(|s| after_eq[s..].find('"').map(|e| s + e));
92            if let (Some(s), Some(e)) = (start, end) {
93                let uuid = &after_eq[s..e];
94                if !uuid.is_empty() {
95                    return Ok(uuid.to_string());
96                }
97            }
98        }
99    }
100    Err(MachineError::Malformed)
101}
102
103#[cfg(not(any(target_os = "linux", target_os = "macos")))]
104fn read_raw_machine_id() -> Result<String, MachineError> {
105    Err(MachineError::Unsupported)
106}
107
108/// 计算指定 key_id 在本机的指纹哈希（64 位 hex）
109pub fn fingerprint_for(key_id: &str) -> Result<String, MachineError> {
110    let raw = raw_machine_id()?;
111    Ok(fingerprint_from_raw(key_id, &raw))
112}
113
114/// 纯函数版本（方便单元测试）
115#[must_use]
116pub fn fingerprint_from_raw(key_id: &str, raw: &str) -> String {
117    let mut h = Sha256::new();
118    h.update(b"futu-machine-bind:v1:");
119    h.update(key_id.as_bytes());
120    h.update(b":");
121    h.update(raw.as_bytes());
122    hex::encode(h.finalize())
123}
124
125/// 检查本机指纹是否在白名单里
126///
127/// - `allowed` 为 `None` → 视为未启用机器绑定，始终通过
128/// - `allowed` 为空列表 → 视为禁止所有机器（用于"临时冻结"某 key）
129/// - 取不到 machine-id（平台不支持 / 文件缺失）→ 视为 Mismatch（宁紧勿松）
130pub fn check(key_id: &str, allowed: Option<&[String]>) -> Result<(), MachineError> {
131    let Some(list) = allowed else {
132        return Ok(());
133    };
134    let fp = fingerprint_for(key_id)?;
135    if list.iter().any(|x| x == &fp) {
136        Ok(())
137    } else {
138        Err(MachineError::Mismatch)
139    }
140}
141
142#[cfg(test)]
143mod tests;
futu_auth/machine.rs

futu_auth/
machine.rs
