//! `mpc link` —— 会话级链路层(EasyTier)命令行。 //! //! # 为什么不挂在 `mpc tee up` 上 //! //! `mpc hostd` 的 e2b 兼容面只管 **TEE 实例**。链路有独立的凭据、独立的进程 //! 生命周期、独立的撤销路径;把它塞成 `tee up --link-policy` 的一个字段, //! 只会得到一个「参数传进去了、但没人据此起进程」的假接口 —— //! 而这类假接口比没有更危险,因为运维会以为组网已经按档位生效。 //! //! 这里沿用项目已有的分层:`mpc tee plan --argv` → `deploy/tee/launch.sh` exec, //! 链路同理:**`mpc link plan --argv` 产出 argv,长驻进程由部署层 exec**。 //! 框架只做判定与参数生成,不替部署层决定怎么托管进程。 //! //! # 凭据私钥的边界 //! //! `--credential` 等价于高敏感密码。它**绝不做命令行参数**(会进 `ps` 和 shell //! history),只从 `--credential-file` 读;`plan` 默认输出脱敏摘要, //! 只有显式 `--argv` 才输出含私钥的真实 argv 供部署层消费,并往 stderr 打警告。 //! `credential issue` 把私钥写进 0600 文件,stdout 只报 `credential_id`。 use mpc_hostd::json; use mpc_hostd::link::{ parse_peer_output, with_configured_relay_network, CliCredentialIssuer, EasyTierSpec, CORE_BIN, }; use mpc_tee::link::{ aggregate_observations, link_admit, CredentialRequest, LinkCredential, LinkPolicy, }; use std::collections::{HashMap, HashSet}; use std::fs; use std::path::Path; use std::time::{SystemTime, UNIX_EPOCH}; /// 命令入口。 pub fn cmd_link(args: &[String]) -> Result<(), String> { match args.first().map(String::as_str) { Some("plan") => cmd_plan(&args[1..]), Some("verdict") => cmd_verdict(&args[1..]), Some("credential") => cmd_credential(&args[1..]), _ => Err(LINK_USAGE.to_string()), } } const LINK_USAGE: &str = "用法: mpc link plan 生成 easytier-core argv(--argv 输出真实 argv 供部署层 exec) mpc link verdict 策略 × easytier-cli peer 输出 → link= 判定与绑定摘要 mpc link credential issue|revoke 向联盟管理节点签发 / 撤销会话凭据 plan: --policy open|allowlist|p2p-only (必填,不设默认:静默默认会混淆「没配」与「选了开放」) --network NAME (默认 union) --peer URI (可重复,至少一次) --rpc HOST:PORT (默认 127.0.0.1:15888,只允许回环) --ipv4 ADDR / --dev-name NAME (不给则不建 TUN) --instance NAME (默认 mpc-) --whitelist NAME (可重复;allowlist 档必填且非空) --relay-network NAME (宿主配置声明的中继网名,见 verdict 的诚实边界) --credential-file PATH (必填;私钥只走文件) --no-private-mode / --disable-sym-hole-punching --argv (输出真实 argv JSON 数组,含私钥;stderr 会警告) --argv-redacted (输出脱敏 argv,用于展示与对拍) verdict: --policy / --whitelist / --relay-network / --credential-file 同上 --peer-output PATH (easytier-cli peer 的输出文本,必填) --user-data-first32 HEX (证明绑定值前 32 字节,64 位十六进制,必填) --now UNIX_SECS (可选,默认当前时刻;给了便于对账复现) credential issue: --ttl SECS / --session-id HEX / --out PATH (三个必填) --allow-relay (显式允许本节点为他人中继,默认 false) --cli PATH / --rpc HOST:PORT (easytier-cli 路径与管理 RPC) --now UNIX_SECS credential revoke: --id CREDENTIAL_ID / --cli PATH / --rpc HOST:PORT"; /// 已解析的选项。**未知参数直接报错** —— 拼错 flag 被静默忽略, /// 结果是拿一份和预期不同的配置去起网络,这类错误很难在事后查出来。 struct Opts { values: HashMap>, flags: HashSet, } impl Opts { fn one(&self, k: &str) -> Option<&str> { self.values.get(k).and_then(|v| v.last()).map(String::as_str) } fn need(&self, k: &str) -> Result<&str, String> { self.one(k) .ok_or_else(|| format!("缺少必填参数 --{k};\n{LINK_USAGE}")) } fn many(&self, k: &str) -> Vec { self.values.get(k).cloned().unwrap_or_default() } fn has(&self, k: &str) -> bool { self.flags.contains(k) } fn u64(&self, k: &str) -> Result, String> { match self.one(k) { None => Ok(None), Some(v) => v .parse::() .map(Some) .map_err(|_| format!("--{k} 不是合法整数: {v:?}")), } } fn policy(&self) -> Result { let raw = self.need("policy")?; LinkPolicy::parse(raw).ok_or_else(|| { format!("--policy 不认识的值 {raw:?}(只接受 open / allowlist / p2p-only)") }) } } /// 解析 `--key value` 与 `--flag`,并核对白名单。 fn parse_opts(args: &[String], value_keys: &[&str], bool_flags: &[&str]) -> Result { let mut values: HashMap> = HashMap::new(); let mut flags = HashSet::new(); let mut i = 0; while i < args.len() { let a = args[i].as_str(); if !a.starts_with("--") { return Err(format!("不认识的位置参数 {a:?};\n{LINK_USAGE}")); } let key = &a[2..]; if bool_flags.contains(&key) { flags.insert(key.to_string()); i += 1; continue; } if !value_keys.contains(&key) { return Err(format!("不认识的参数 --{key};\n{LINK_USAGE}")); } if i + 1 >= args.len() { return Err(format!("--{key} 缺少值")); } values .entry(key.to_string()) .or_default() .push(args[i + 1].clone()); i += 2; } Ok(Opts { values, flags }) } const PLAN_VALUE_KEYS: &[&str] = &[ "policy", "network", "peer", "rpc", "ipv4", "dev-name", "instance", "whitelist", "relay-network", "credential-file", ]; const PLAN_BOOL_FLAGS: &[&str] = &[ "no-private-mode", "disable-sym-hole-punching", "argv", "argv-redacted", ]; fn cmd_plan(args: &[String]) -> Result<(), String> { let o = parse_opts(args, PLAN_VALUE_KEYS, PLAN_BOOL_FLAGS)?; let policy = o.policy()?; let cred = load_credential(o.need("credential-file")?)?; let peers = o.many("peer"); if peers.is_empty() { return Err(String::from("至少要给一个 --peer")); } let session_hex = to_hex(&cred.session_id); let instance = o.one("instance").map(String::from).unwrap_or_else(|| { format!("mpc-{}", &session_hex[..8.min(session_hex.len())]) }); let spec = EasyTierSpec { network_name: o.one("network").unwrap_or("union").to_string(), peers, rpc_portal: o.one("rpc").unwrap_or("127.0.0.1:15888").to_string(), ipv4: o.one("ipv4").map(String::from), dev_name: o.one("dev-name").map(String::from), instance_name: instance, policy, relay_whitelist: o.many("whitelist"), credential: cred.clone(), private_mode: !o.has("no-private-mode"), disable_sym_hole_punching: o.has("disable-sym-hole-punching"), relay_network: o.one("relay-network").map(String::from), }; let argv = spec.argv().map_err(|e| e.to_string())?; if o.has("argv") || o.has("argv-redacted") { // 真实 argv 供部署层 exec;脱敏版供展示与对拍。 let redact = !o.has("argv"); let items: Vec = argv .iter() .map(|x| { if redact && x == &cred.secret { // 必须是合法 JSON 字符串,否则 --argv-redacted 没法被对拍脚本解析。 String::from("\"\"") } else { format!("\"{}\"", json_escape(x)) } }) .collect(); println!("[{}]", items.join(", ")); if !redact { eprintln!("警告: 上面的 argv 含会话凭据私钥,别写进日志、别贴进工单;文件权限与传输通道自行把关。"); } return Ok(()); } note!("policy={}", policy.as_str()); note!("binary={CORE_BIN}"); note!("network={} instance={}", spec.network_name, spec.instance_name); note!("peers={:?}", spec.peers); note!("rpc={} rpc_whitelist=127.0.0.1/32", spec.rpc_portal); note!("credential_id={} expires_at={} allow_relay={}", cred.credential_id, cred.expires_at, cred.allow_relay); note!("argv_items={} network_secret=absent", argv.len()); note!("未起任何进程。部署层请用 `mpc link plan --argv` 取真实 argv 后自行 exec(长驻托管不归框架管)。"); Ok(()) } const VERDICT_VALUE_KEYS: &[&str] = &[ "policy", "whitelist", "relay-network", "credential-file", "peer-output", "user-data-first32", "now", ]; fn cmd_verdict(args: &[String]) -> Result<(), String> { let o = parse_opts(args, VERDICT_VALUE_KEYS, &[])?; let policy = o.policy()?; let cred = load_credential(o.need("credential-file")?)?; let peer_text = fs::read_to_string(o.need("peer-output")?) .map_err(|e| format!("读 --peer-output 失败: {e}"))?; let observations = parse_peer_output(&peer_text); if observations.is_empty() { return Err(String::from("peer 输出里没有可解析的数据行,拒绝给出链路结论")); } // ★ 全部 peer 一起判,不是只取第一行(见 aggregate_observations 的回归探针)。 let obs = with_configured_relay_network( aggregate_observations(&observations), o.one("relay-network"), ); let ud = hex32(o.need("user-data-first32")?)?; let now = o.u64("now")?.unwrap_or_else(now_secs); let wl = o.many("whitelist"); let v = link_admit(policy, &obs, &wl, &cred, &ud, now).map_err(|e| e.to_string())?; note!("link={}", v.link_field); note!("relay_visible={}", v.relay_visible); note!("credential_id={}", cred.credential_id); note!("peer={}", obs.peer); note!("binding={}", to_hex(&v.binding)); note!("{}", v.note); if obs.kind == mpc_tee::link::LinkKind::Relay && obs.relay_network.is_some() { note!("注意: 中继网名来自 --relay-network 的宿主配置声明,不是 easytier-cli peer 的观测值;真机需补 RPC 观测源后才能算「实际路径已核对」。"); } Ok(()) } fn cmd_credential(args: &[String]) -> Result<(), String> { match args.first().map(String::as_str) { Some("issue") => credential_issue(&args[1..]), Some("revoke") => credential_revoke(&args[1..]), _ => Err(String::from("用法: mpc link credential issue|revoke")), } } const ISSUE_VALUE_KEYS: &[&str] = &["ttl", "session-id", "out", "cli", "rpc", "now"]; const ISSUE_BOOL_FLAGS: &[&str] = &["allow-relay"]; fn credential_issue(args: &[String]) -> Result<(), String> { let o = parse_opts(args, ISSUE_VALUE_KEYS, ISSUE_BOOL_FLAGS)?; let ttl: u64 = o .need("ttl")? .parse() .map_err(|_| String::from("--ttl 必须是正整数秒"))?; let session_id = hex32(o.need("session-id")?)?; let now = o.u64("now")?.unwrap_or_else(now_secs); let req = CredentialRequest { session_id, policy: LinkPolicy::Open, // 签发与档位无关:档位管「我经不经中继」,见 link.rs 说明 ttl_secs: ttl, now, allow_relay: o.has("allow-relay"), }; let issuer = CliCredentialIssuer { cli_bin: o.one("cli").unwrap_or(mpc_hostd::link::CLI_BIN).to_string(), rpc_portal: o.one("rpc").map(String::from), }; let cred = mpc_tee::link::issue_link_credential(&req, Some(&issuer)) .map_err(|e| e.to_string())?; save_credential(Path::new(o.need("out")?), &cred)?; // ★ 只报 id 与过期时刻,私钥绝不进 stdout。 note!("credential_id={}", cred.credential_id); note!("expires_at={} ttl={} allow_relay={}", cred.expires_at, ttl, cred.allow_relay); note!("私钥已写入 {}(0600),未输出到终端。", o.need("out")?); Ok(()) } const REVOKE_VALUE_KEYS: &[&str] = &["id", "cli", "rpc"]; fn credential_revoke(args: &[String]) -> Result<(), String> { let o = parse_opts(args, REVOKE_VALUE_KEYS, &[])?; let issuer = CliCredentialIssuer { cli_bin: o.one("cli").unwrap_or(mpc_hostd::link::CLI_BIN).to_string(), rpc_portal: o.one("rpc").map(String::from), }; mpc_tee::link::CredentialProvider::revoke(&issuer, o.need("id")?) .map_err(|e| e.to_string())?; note!("credential_id={} 已撤销", o.need("id")?); Ok(()) } /// 凭据文件(JSON)。私钥只从这里进出,不经过命令行。 fn load_credential(path: &str) -> Result { let text = fs::read_to_string(path).map_err(|e| format!("读凭据文件 {path:?} 失败: {e}"))?; let j = json::parse(&text).map_err(|e| format!("凭据文件不是合法 JSON: {e}"))?; let get = |k: &str| -> Result<&str, String> { j.get_str(k) .ok_or_else(|| format!("凭据文件缺少 {k:?}")) }; let expires_at = j .get_int("expires_at") .ok_or_else(|| String::from("凭据文件缺少 expires_at"))?; if expires_at < 0 { return Err(String::from("expires_at 不能为负")); } let cred = LinkCredential { credential_id: get("credential_id")?.to_string(), secret: get("credential_secret")?.to_string(), expires_at: expires_at as u64, allow_relay: j.get_bool("allow_relay").unwrap_or(false), session_id: hex32(get("session_id")?)?, }; cred.validate_shape().map_err(|e| e.to_string())?; Ok(cred) } fn save_credential(path: &Path, c: &LinkCredential) -> Result<(), String> { let body = format!( "{{\"credential_id\":\"{}\",\"credential_secret\":\"{}\",\"expires_at\":{},\"allow_relay\":{},\"session_id\":\"{}\"}}\n", json_escape(&c.credential_id), json_escape(&c.secret), c.expires_at, c.allow_relay, to_hex(&c.session_id), ); #[cfg(unix)] { use std::io::Write; use std::os::unix::fs::OpenOptionsExt; let mut f = fs::OpenOptions::new() .create(true) .truncate(true) .write(true) .mode(0o600) .open(path) .map_err(|e| format!("写凭据文件 {path:?} 失败: {e}"))?; f.write_all(body.as_bytes()) .map_err(|e| format!("写凭据文件失败: {e}"))?; } #[cfg(not(unix))] fs::write(path, &body).map_err(|e| format!("写凭据文件 {path:?} 失败: {e}"))?; Ok(()) } fn hex32(s: &str) -> Result<[u8; 32], String> { if s.len() != 64 { return Err(format!("需要 64 位十六进制,拿到 {} 位", s.len())); } let mut out = [0u8; 32]; for i in 0..32 { out[i] = u8::from_str_radix(&s[i * 2..i * 2 + 2], 16) .map_err(|_| format!("非法的十六进制: {s:?}"))?; } Ok(out) } fn to_hex(bytes: &[u8]) -> String { let mut s = String::with_capacity(bytes.len() * 2); for b in bytes { s.push_str(&format!("{b:02x}")); } s } fn json_escape(s: &str) -> String { let mut out = String::with_capacity(s.len()); for c in s.chars() { match c { '"' => out.push_str("\\\""), '\\' => out.push_str("\\\\"), '\n' => out.push_str("\\n"), '\r' => out.push_str("\\r"), '\t' => out.push_str("\\t"), c if c.is_control() => out.push_str(&format!("\\u{:04x}", c as u32)), c => out.push(c), } } out } fn now_secs() -> u64 { SystemTime::now() .duration_since(UNIX_EPOCH) .map(|d| d.as_secs()) .unwrap_or(0) }