From 9bceac910ba8f3971068620e9dd9018e238e7f1c Mon Sep 17 00:00:00 2001 From: cflmy Date: Fri, 20 Nov 2026 13:02:55 +0800 Subject: [PATCH] feat(tool): negotiate protocols and verify the whole tool bundle (B-09 B-10) - replace the hand-rolled version matcher with semver; require valid tool versions and marqdo ranges - declare SupportedProtocols (tool 1, analysis 2, trace 2) and negotiate tool Analysis/Trace declarations at install and dispatch; disjoint/empty sets fail closed with tool.protocol_incompatible - record a v2 whole-bundle manifest (path/size/sha256 + deterministic bundle digest), copy exactly that bundle into staging, re-verify it, and recompute it before every dispatch - reject auxiliary-file, extra-file, missing-file and entrypoint tampering, record/command mismatches, traversal and a source root record.json - remove tools by detaching with rename before deletion - expose negotiated protocol environment variables to declared tools - update tool-v1 and STATUS; add negotiation/bundle tests --- Cargo.lock | 7 + Cargo.toml | 1 + crates/cli/Cargo.toml | 1 + crates/cli/src/tool.rs | 428 +++++++++++++++++++++--------- crates/cli/tests/tool_protocol.rs | 96 +++++++ docs/STATUS.md | 23 +- spec/tool-v1.md | 23 +- 7 files changed, 449 insertions(+), 130 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 995fe0b..c0f13d2 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -339,6 +339,7 @@ dependencies = [ "marqdo-sandbox", "marqdo-span", "marqdo-value", + "semver", "serde", "serde_json", "sha2", @@ -680,6 +681,12 @@ dependencies = [ "winapi-util", ] +[[package]] +name = "semver" +version = "1.0.28" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd" + [[package]] name = "serde" version = "1.0.229" diff --git a/Cargo.toml b/Cargo.toml index f4f24e7..718902d 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -48,6 +48,7 @@ num-bigint = { version = "0.4", features = ["serde"] } num-rational = { version = "0.4", features = ["serde"] } num-traits = "0.2" sha2 = "0.10" +semver = "1" hex = "0.4" libloading = "0.8" tempfile = "3" diff --git a/crates/cli/Cargo.toml b/crates/cli/Cargo.toml index dabd6ff..f4867eb 100644 --- a/crates/cli/Cargo.toml +++ b/crates/cli/Cargo.toml @@ -28,6 +28,7 @@ serde_json = { workspace = true } walkdir = { workspace = true } hex = { workspace = true } sha2 = { workspace = true } +semver = { workspace = true } [[bin]] name = "marqdo" diff --git a/crates/cli/src/tool.rs b/crates/cli/src/tool.rs index 54ce866..d791af3 100644 --- a/crates/cli/src/tool.rs +++ b/crates/cli/src/tool.rs @@ -1,20 +1,40 @@ //! Generic external CLI tool protocol (spec/tool-v1.md). //! //! The core never knows a tool's name. It validates a user-supplied -//! `tool.json`, copies the package into a controlled user directory, and -//! dispatches unknown top-level commands to the registered executable. This is -//! deliberately separate from C ABI plugins and foreign kernels. +//! `tool.json`, verifies protocol compatibility, copies the whole bundle into a +//! controlled user directory and dispatches unknown top-level commands to the +//! registered executable. This is deliberately separate from C ABI plugins and +//! foreign kernels. use std::collections::BTreeMap; use std::ffi::OsString; use std::path::{Component, Path, PathBuf}; use std::process::Command as ProcessCommand; +use semver::{Version, VersionReq}; use serde::{Deserialize, Serialize}; use sha2::{Digest, Sha256}; const SCHEMA: &str = "marqdo.cli-tool"; const PROTOCOL_VERSION: u32 = 1; +const RECORD_VERSION: u32 = 2; +const MAX_BUNDLE_FILES: usize = 4096; +const MAX_BUNDLE_BYTES: u64 = 256 * 1024 * 1024; + +/// Protocols this core can provide to tools. +#[derive(Debug, Clone, Copy)] +struct SupportedProtocols { + tool: u32, + analysis: &'static [u32], + trace: &'static [u32], +} + +const SUPPORTED: SupportedProtocols = SupportedProtocols { + tool: PROTOCOL_VERSION, + analysis: &[2], + trace: &[2], +}; + const BUILTIN_COMMANDS: &[&str] = &[ "init", "run", "call", "check", "inspect", "fmt", "plugin", "add", "remove", "lock", "sync", "tool", "help", @@ -42,19 +62,6 @@ struct Compatibility { trace: Option>, } -#[derive(Debug, Clone, Serialize, Deserialize)] -struct ToolRecord { - command: String, - name: String, - version: String, - entrypoint: PathBuf, - sha256: String, - source: String, - schema_version: u32, - #[serde(default)] - compatibility: RecordedCompatibility, -} - #[derive(Debug, Clone, Default, Serialize, Deserialize)] struct RecordedCompatibility { #[serde(default, skip_serializing_if = "Option::is_none")] @@ -65,6 +72,38 @@ struct RecordedCompatibility { trace: Option>, } +impl RecordedCompatibility { + fn as_compatibility(&self) -> Compatibility { + Compatibility { + marqdo: self.marqdo.clone(), + analysis: self.analysis.clone(), + trace: self.trace.clone(), + } + } +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +struct BundleEntry { + path: String, + size: u64, + sha256: String, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +struct ToolRecord { + record_version: u32, + command: String, + name: String, + version: String, + entrypoint: PathBuf, + bundle: Vec, + bundle_sha256: String, + source: String, + schema_version: u32, + #[serde(default)] + compatibility: RecordedCompatibility, +} + /// `marqdo tool install `. pub fn install(manifest_path: &Path, json: bool) -> i32 { match install_inner(manifest_path) { @@ -77,6 +116,7 @@ pub fn install(manifest_path: &Path, json: bool) -> i32 { "success": true, "tool": record.command, "version": record.version, + "bundle_files": record.bundle.len(), }) ); } else { @@ -114,8 +154,17 @@ fn install_inner(manifest_path: &Path) -> Result { .map_err(|error| format!("cannot open `{}`: {error}", manifest_file.display()))?; let manifest = ToolManifest::from_path(&manifest_file)?; validate_manifest(&manifest)?; - let entrypoint = safe_entrypoint(&package_dir, &manifest.entrypoint)?; - let sha256 = hash_file(&entrypoint)?; + if package_dir.join("record.json").exists() { + return Err("tool package must not contain a root record.json".to_string()); + } + let entrypoint_path = safe_entrypoint(&package_dir, &manifest.entrypoint)?; + let entrypoint = relative_string(&package_dir, &entrypoint_path)?; + let bundle = collect_bundle(&package_dir, false)?; + if !bundle.iter().any(|entry| entry.path == entrypoint) { + return Err("tool entrypoint is not part of the verified bundle".to_string()); + } + let bundle_sha256 = bundle_digest(&bundle); + let home = tool_home()?; std::fs::create_dir_all(&home) .map_err(|error| format!("cannot create tool home `{}`: {error}", home.display()))?; @@ -137,32 +186,31 @@ fn install_inner(manifest_path: &Path) -> Result { std::fs::create_dir_all(&staging) .map_err(|error| format!("cannot create staging directory: {error}"))?; let result = (|| -> Result<(), String> { - copy_package(&package_dir, &staging)?; - let relative = manifest.entrypoint.clone(); + copy_bundle(&package_dir, &staging, &bundle)?; + let copied = collect_bundle(&staging, false)?; + if copied != bundle || bundle_digest(&copied) != bundle_sha256 { + return Err("copied tool bundle does not match the source bundle".to_string()); + } let record = ToolRecord { + record_version: RECORD_VERSION, command: manifest.command.clone(), name: manifest.name.clone(), version: manifest.version.clone(), - entrypoint: relative.clone(), - sha256: sha256.clone(), + entrypoint: PathBuf::from(&entrypoint), + bundle: bundle.clone(), + bundle_sha256: bundle_sha256.clone(), source: manifest_file.display().to_string(), - schema_version: PROTOCOL_VERSION, + schema_version: manifest.schema_version, compatibility: RecordedCompatibility { marqdo: manifest.compatibility.marqdo.clone(), analysis: manifest.compatibility.analysis.clone(), trace: manifest.compatibility.trace.clone(), }, }; - let record_path = staging.join("record.json"); let record_json = serde_json::to_string_pretty(&record) .map_err(|error| format!("cannot serialize record: {error}"))?; - std::fs::write(&record_path, record_json) + std::fs::write(staging.join("record.json"), record_json) .map_err(|error| format!("cannot write record: {error}"))?; - // Re-verify the copied entrypoint before publishing. - let copied = staging.join(&relative); - if hash_file(&copied)? != sha256 { - return Err("copied tool entrypoint hash mismatch".to_string()); - } std::fs::rename(&staging, &target) .map_err(|error| format!("cannot publish tool installation: {error}"))?; Ok(()) @@ -187,10 +235,10 @@ fn validate_manifest(manifest: &ToolManifest) -> Result<(), String> { if manifest.schema != SCHEMA { return Err(format!("unsupported tool schema `{}`", manifest.schema)); } - if manifest.schema_version != PROTOCOL_VERSION { + if manifest.schema_version != SUPPORTED.tool { return Err(format!( - "unsupported tool schema_version {} (expected {PROTOCOL_VERSION})", - manifest.schema_version + "unsupported tool schema_version {} (expected {})", + manifest.schema_version, SUPPORTED.tool )); } if !is_valid_command(&manifest.command) { @@ -205,17 +253,55 @@ fn validate_manifest(manifest: &ToolManifest) -> Result<(), String> { manifest.command )); } - if manifest.name.trim().is_empty() || manifest.version.trim().is_empty() { - return Err("tool name and version must not be empty".to_string()); + if manifest.name.trim().is_empty() { + return Err("tool name must not be empty".to_string()); } - if let Some(range) = &manifest.compatibility.marqdo { - if !version_matches(env!("CARGO_PKG_VERSION"), range) { + Version::parse(&manifest.version).map_err(|error| { + format!( + "tool version `{}` is not valid SemVer: {error}", + manifest.version + ) + })?; + negotiate(&manifest.version, &manifest.compatibility) +} + +fn negotiate(tool_version: &str, compatibility: &Compatibility) -> Result<(), String> { + Version::parse(tool_version) + .map_err(|error| format!("tool version `{tool_version}` is not valid SemVer: {error}"))?; + let core_version = Version::parse(env!("CARGO_PKG_VERSION")) + .map_err(|error| format!("core version is not valid SemVer: {error}"))?; + if let Some(range) = &compatibility.marqdo { + let requirement = VersionReq::parse(range) + .map_err(|error| format!("invalid marqdo compatibility range `{range}`: {error}"))?; + if !requirement.matches(&core_version) { return Err(format!( "tool requires marqdo `{range}`, this core is {}", env!("CARGO_PKG_VERSION") )); } } + negotiate_protocol( + "analysis", + compatibility.analysis.as_deref(), + SUPPORTED.analysis, + )?; + negotiate_protocol("trace", compatibility.trace.as_deref(), SUPPORTED.trace)?; + Ok(()) +} + +fn negotiate_protocol( + name: &str, + requested: Option<&[u32]>, + supported: &[u32], +) -> Result<(), String> { + let Some(requested) = requested else { + return Ok(()); + }; + if requested.is_empty() || !requested.iter().any(|version| supported.contains(version)) { + return Err(format!( + "tool.protocol_incompatible: tool requires {name} version(s) {requested:?}, this core supports {supported:?}" + )); + } Ok(()) } @@ -225,6 +311,27 @@ fn is_valid_command(command: &str) -> bool { && bytes.all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'-') } +fn relative_string(root: &Path, path: &Path) -> Result { + let relative = path + .strip_prefix(root) + .map_err(|_| "tool package path escaped its root".to_string())?; + let mut parts = Vec::new(); + for component in relative.components() { + match component { + Component::Normal(part) => parts.push( + part.to_str() + .ok_or_else(|| "tool package path is not valid UTF-8".to_string())? + .to_string(), + ), + _ => return Err("tool package path is not normalized".to_string()), + } + } + if parts.is_empty() { + return Err("tool package path is empty".to_string()); + } + Ok(parts.join("/")) +} + fn safe_entrypoint(package_dir: &Path, entrypoint: &Path) -> Result { if entrypoint.is_absolute() { return Err("tool entrypoint must be package-relative".to_string()); @@ -262,14 +369,27 @@ fn safe_entrypoint(package_dir: &Path, entrypoint: &Path) -> Result Result<(), String> { - for entry in walkdir::WalkDir::new(source).follow_links(false) { +fn collect_bundle(root: &Path, exclude_record: bool) -> Result, String> { + if !root.is_dir() { + return Err(format!( + "tool package `{}` is not a directory", + root.display() + )); + } + let mut entries = Vec::new(); + let mut total = 0u64; + for entry in walkdir::WalkDir::new(root) + .follow_links(false) + .sort_by_file_name() + { let entry = entry.map_err(|error| format!("cannot walk tool package: {error}"))?; - let relative = entry - .path() - .strip_prefix(source) - .map_err(|_| "tool package path escaped its root".to_string())?; - let destination = target.join(relative); + if entry.depth() == 0 { + continue; + } + let path = relative_string(root, entry.path())?; + if exclude_record && path == "record.json" { + continue; + } if entry.file_type().is_symlink() { return Err(format!( "tool package contains a symlink `{}`; symlinks are not installed", @@ -277,21 +397,67 @@ fn copy_package(source: &Path, target: &Path) -> Result<(), String> { )); } if entry.file_type().is_dir() { - std::fs::create_dir_all(&destination) - .map_err(|error| format!("cannot create `{}`: {error}", destination.display()))?; - } else if entry.file_type().is_file() { - if let Some(parent) = destination.parent() { - std::fs::create_dir_all(parent) - .map_err(|error| format!("cannot create `{}`: {error}", parent.display()))?; - } - std::fs::copy(entry.path(), &destination).map_err(|error| { - format!( - "cannot copy `{}` to `{}`: {error}", - entry.path().display(), - destination.display() - ) - })?; + continue; } + if !entry.file_type().is_file() { + return Err(format!( + "tool package contains special file `{}`", + entry.path().display() + )); + } + let size = entry + .metadata() + .map_err(|error| format!("cannot inspect `{}`: {error}", entry.path().display()))? + .len(); + total = total + .checked_add(size) + .ok_or_else(|| "tool bundle size overflowed".to_string())?; + if total > MAX_BUNDLE_BYTES { + return Err(format!( + "tool bundle exceeds the maximum size of {MAX_BUNDLE_BYTES} bytes" + )); + } + if entries.len() >= MAX_BUNDLE_FILES { + return Err(format!( + "tool bundle exceeds the maximum of {MAX_BUNDLE_FILES} files" + )); + } + entries.push(BundleEntry { + path, + size, + sha256: hash_file(entry.path())?, + }); + } + entries.sort_by(|a, b| a.path.cmp(&b.path)); + Ok(entries) +} + +fn bundle_digest(entries: &[BundleEntry]) -> String { + let mut hasher = Sha256::new(); + for entry in entries { + hasher.update(entry.path.as_bytes()); + hasher.update([0u8]); + hasher.update(entry.size.to_le_bytes()); + hasher.update(entry.sha256.as_bytes()); + hasher.update(b"\n"); + } + hex::encode(hasher.finalize()) +} + +fn copy_bundle(source: &Path, target: &Path, bundle: &[BundleEntry]) -> Result<(), String> { + for entry in bundle { + let destination = target.join(&entry.path); + if let Some(parent) = destination.parent() { + std::fs::create_dir_all(parent) + .map_err(|error| format!("cannot create `{}`: {error}", parent.display()))?; + } + std::fs::copy(source.join(&entry.path), &destination).map_err(|error| { + format!( + "cannot copy `{}` to `{}`: {error}", + source.join(&entry.path).display(), + destination.display() + ) + })?; } Ok(()) } @@ -301,9 +467,21 @@ pub fn list(json: bool) -> i32 { match installed_records() { Ok(records) => { if json { + let tools: Vec = records + .iter() + .map(|record| { + serde_json::json!({ + "command": record.command, + "name": record.name, + "version": record.version, + "bundle_files": record.bundle.len(), + "compatibility": record.compatibility, + }) + }) + .collect(); println!( "{}", - serde_json::json!({"command":"tool.list","success":true,"tools":records}) + serde_json::json!({"command":"tool.list","success":true,"tools":tools}) ); } else if records.is_empty() { println!("no tools installed"); @@ -332,7 +510,6 @@ pub fn remove(command: &str, json: bool) -> i32 { if !target.is_dir() { return Err(format!("tool `{command}` is not installed")); } - // The target must be a direct child of the controlled home. let canonical_home = home .canonicalize() .map_err(|error| format!("cannot open tool home: {error}"))?; @@ -342,7 +519,11 @@ pub fn remove(command: &str, json: bool) -> i32 { if canonical_target.parent() != Some(canonical_home.as_path()) { return Err("refusing to remove a path outside the tool home".to_string()); } - std::fs::remove_dir_all(&canonical_target) + let trash = + canonical_home.join(format!(".trash-{}-{}", std::process::id(), unique_suffix())); + std::fs::rename(&canonical_target, &trash) + .map_err(|error| format!("cannot detach tool `{command}`: {error}"))?; + std::fs::remove_dir_all(&trash) .map_err(|error| format!("cannot remove tool `{command}`: {error}"))?; Ok(()) })(); @@ -400,28 +581,64 @@ pub fn dispatch(args: &[OsString]) -> i32 { return 2; } }; - let entrypoint = dir.join(&record.entrypoint); - if !entrypoint.starts_with(&dir) { - eprintln!("error: tool entrypoint escapes its installation"); + if record.command != command { + eprintln!("error: tool record does not match command `{command}`; reinstall it"); return 1; } - let actual = match hash_file(&entrypoint) { - Ok(hash) => hash, + if let Err(error) = negotiate(&record.version, &record.compatibility.as_compatibility()) { + eprintln!("error: tool `{command}` is not compatible with this core: {error}"); + return 1; + } + if record.record_version != RECORD_VERSION { + eprintln!("error: tool `{command}` uses an old record; reinstall it"); + return 1; + } + let bundle = match collect_bundle(&dir, true) { + Ok(bundle) => bundle, Err(error) => { eprintln!("error: {error}"); return 1; } }; - if actual != record.sha256 { - eprintln!("error: tool `{command}` executable hash mismatch; reinstall it"); + if bundle != record.bundle || bundle_digest(&bundle) != record.bundle_sha256 { + eprintln!("error: tool `{command}` bundle hash mismatch; reinstall it"); return 1; } + let entrypoint = match safe_record_entrypoint(&record).and_then(|relative| { + if bundle.iter().any(|entry| entry.path == relative) { + Ok(dir.join(relative)) + } else { + Err("tool entrypoint is not part of the verified bundle".to_string()) + } + }) { + Ok(entrypoint) => entrypoint, + Err(error) => { + eprintln!("error: {error}; reinstall it"); + return 1; + } + }; let mut process = ProcessCommand::new(&entrypoint); process.args(&args[1..]); if let Ok(bin) = std::env::current_exe() { process.env("MARQDO_BIN", bin); } process.env("MARQDO_TOOL_PROTOCOL", "1"); + if record + .compatibility + .analysis + .as_ref() + .is_some_and(|versions| versions.contains(&2)) + { + process.env("MARQDO_PROTOCOL_ANALYSIS", "2"); + } + if record + .compatibility + .trace + .as_ref() + .is_some_and(|versions| versions.contains(&2)) + { + process.env("MARQDO_PROTOCOL_TRACE", "2"); + } match process.status() { Ok(status) => status.code().unwrap_or(1), Err(error) => { @@ -431,6 +648,24 @@ pub fn dispatch(args: &[OsString]) -> i32 { } } +fn safe_record_entrypoint(record: &ToolRecord) -> Result { + let path = record + .entrypoint + .to_str() + .ok_or_else(|| "tool record entrypoint is not valid UTF-8".to_string())?; + if record.entrypoint.is_absolute() || path.is_empty() { + return Err("tool record entrypoint must be package-relative".to_string()); + } + let mut parts = Vec::new(); + for component in record.entrypoint.components() { + match component { + Component::Normal(part) => parts.push(part.to_str().unwrap_or_default()), + _ => return Err("tool record entrypoint must not escape the package".to_string()), + } + } + Ok(parts.join("/")) +} + fn installed_records() -> Result, String> { let home = tool_home()?; if !home.is_dir() { @@ -457,7 +692,12 @@ fn installed_records() -> Result, String> { fn load_record(dir: &Path) -> Result { let text = std::fs::read_to_string(dir.join("record.json")) .map_err(|error| format!("tool record is missing: {error}"))?; - serde_json::from_str(&text).map_err(|error| format!("invalid tool record: {error}")) + let record: ToolRecord = + serde_json::from_str(&text).map_err(|error| format!("invalid tool record: {error}"))?; + if record.record_version != RECORD_VERSION { + return Err("tool record is from an older protocol; reinstall it".to_string()); + } + Ok(record) } fn tool_home() -> Result { @@ -491,53 +731,3 @@ fn unique_suffix() -> u128 { .map(|duration| duration.as_nanos()) .unwrap_or(0) } - -/// Minimal version/range check for the `compatibility.marqdo` field. -fn version_matches(version: &str, range: &str) -> bool { - let Some(parsed) = parse_version(version) else { - return false; - }; - range.split(',').all(|part| { - let part = part.trim(); - if part.is_empty() { - return true; - } - let (op, raw) = if let Some(rest) = part.strip_prefix(">=") { - (">=", rest) - } else if let Some(rest) = part.strip_prefix("<=") { - ("<=", rest) - } else if let Some(rest) = part.strip_prefix('>') { - (">", rest) - } else if let Some(rest) = part.strip_prefix('<') { - ("<", rest) - } else if let Some(rest) = part.strip_prefix('=') { - ("=", rest) - } else { - ("=", part) - }; - let Some(expected) = parse_version(raw.trim()) else { - return false; - }; - match op { - ">=" => parsed >= expected, - "<=" => parsed <= expected, - ">" => parsed > expected, - "<" => parsed < expected, - _ => parsed == expected, - } - }) -} - -fn parse_version(value: &str) -> Option<(u64, u64, u64)> { - let mut parts = value.split('.'); - let major = parts.next()?.parse().ok()?; - let minor = parts.next().unwrap_or("0").parse().ok()?; - let patch = parts - .next() - .unwrap_or("0") - .split('-') - .next()? - .parse() - .ok()?; - Some((major, minor, patch)) -} diff --git a/crates/cli/tests/tool_protocol.rs b/crates/cli/tests/tool_protocol.rs index 7507f14..7bcf2ba 100644 --- a/crates/cli/tests/tool_protocol.rs +++ b/crates/cli/tests/tool_protocol.rs @@ -182,3 +182,99 @@ fn tampered_binary_and_path_hijack_are_not_executed() { assert_eq!(output.status.code(), Some(2)); assert!(stderr(&output).contains("unknown command")); } + +#[test] +fn protocol_negotiation_accepts_declared_versions_and_rejects_disjoint_ones() { + let dir = TempDir::new("protocols"); + let home = dir.path().join("home"); + let manifest = write_tool( + dir.path(), + "proto", + "#!/bin/sh\nprintf 'analysis=%s\\ntrace=%s\\n' \"$MARQDO_PROTOCOL_ANALYSIS\" \"$MARQDO_PROTOCOL_TRACE\"\n", + ); + let text = std::fs::read_to_string(&manifest).unwrap().replace( + "\"marqdo\":\">=0.1,<1\"", + "\"marqdo\":\">=0.1,<1\",\"analysis\":[2],\"trace\":[2]", + ); + std::fs::write(&manifest, text).unwrap(); + let install = cli(&home, &["tool", "install", manifest.to_str().unwrap()]); + assert_eq!(install.status.code(), Some(0), "{}", stderr(&install)); + let output = cli(&home, &["proto"]); + assert_eq!(output.status.code(), Some(0), "{}", stderr(&output)); + let text = stdout(&output); + assert!(text.contains("analysis=2"), "{text}"); + assert!(text.contains("trace=2"), "{text}"); + + for (compat, tag) in [ + ("\"analysis\":[99]", "analysis-disjoint"), + ("\"analysis\":[]", "analysis-empty"), + ("\"trace\":[9]", "trace-disjoint"), + ] { + let command = format!("bad-{tag}"); + let manifest = write_tool(dir.path(), &command, "#!/bin/sh\nexit 0\n"); + let text = std::fs::read_to_string(&manifest).unwrap().replace( + "\"marqdo\":\">=0.1,<1\"", + &format!("\"marqdo\":\">=0.1,<1\",{compat}"), + ); + std::fs::write(&manifest, text).unwrap(); + let output = cli(&home, &["tool", "install", manifest.to_str().unwrap()]); + assert_eq!(output.status.code(), Some(1), "{tag}"); + assert!( + stderr(&output).contains("protocol_incompatible"), + "{tag}: {}", + stderr(&output) + ); + } +} + +#[test] +fn tampering_any_bundle_file_or_adding_an_unlisted_file_is_rejected() { + let dir = TempDir::new("bundle"); + let home = dir.path().join("home"); + let manifest = write_tool(dir.path(), "bundletool", "#!/bin/sh\nprintf 'entry\\n'\n"); + let package = manifest.parent().unwrap(); + std::fs::create_dir_all(package.join("lib")).unwrap(); + std::fs::write(package.join("lib/helper.sh"), "echo helper\n").unwrap(); + + let install = cli(&home, &["tool", "install", manifest.to_str().unwrap()]); + assert_eq!(install.status.code(), Some(0), "{}", stderr(&install)); + let installed = home.join("bundletool"); + + // Tamper with a non-entry file only. + std::fs::write(installed.join("lib/helper.sh"), "echo tampered\n").unwrap(); + let run = cli(&home, &["bundletool"]); + assert_eq!(run.status.code(), Some(1)); + assert!( + stderr(&run).contains("bundle hash mismatch"), + "{}", + stderr(&run) + ); + + // Reinstall, then add an unlisted file. + assert_eq!( + cli(&home, &["tool", "remove", "bundletool"]).status.code(), + Some(0) + ); + let install = cli(&home, &["tool", "install", manifest.to_str().unwrap()]); + assert_eq!(install.status.code(), Some(0)); + std::fs::write(installed.join("lib/extra.sh"), "echo extra\n").unwrap(); + let run = cli(&home, &["bundletool"]); + assert_eq!(run.status.code(), Some(1)); + assert!( + stderr(&run).contains("bundle hash mismatch"), + "{}", + stderr(&run) + ); +} + +#[test] +fn a_root_record_json_in_the_source_package_is_rejected() { + let dir = TempDir::new("reserved-record"); + let home = dir.path().join("home"); + let manifest = write_tool(dir.path(), "reserved", "#!/bin/sh\nexit 0\n"); + let package = manifest.parent().unwrap(); + std::fs::write(package.join("record.json"), "{}").unwrap(); + let output = cli(&home, &["tool", "install", manifest.to_str().unwrap()]); + assert_eq!(output.status.code(), Some(1)); + assert!(stderr(&output).contains("must not contain a root record.json")); +} diff --git a/docs/STATUS.md b/docs/STATUS.md index edeee83..9d2713a 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -150,6 +150,26 @@ Trace v2 (`spec/trace-v2.md`, `spec/schemas/trace-v2.schema.json`): * Tests: event module ownership, 20-event truncation of a 500-iteration loop, worker frame round-trip/EOF/partial/oversized/truncated cases. +### S3-A/H2-C Tool protocol record (current) + +Tool Protocol hardening (`spec/tool-v1.md`): + +* `semver` replaces the hand-rolled matcher. Tool versions and `marqdo` + requirements must parse; malformed ranges/versions are rejected. +* The core declares `SupportedProtocols { tool: 1, analysis: [2], trace: [2] }`. + Declared Analysis/Trace lists are negotiated at both install and dispatch; + empty or disjoint lists fail with `tool.protocol_incompatible`. Absent + declarations remain valid and are not forced. +* Installed records are `record_version: 2` with a whole-bundle file manifest + (path, size, SHA-256) and a deterministic bundle digest. Dispatch recomputes + the full bundle, rejects entrypoint/auxiliary/extra/missing-file tampering, + requires the record command to match and the entrypoint to be listed. +* Install copies exactly the verified bundle into staging, re-verifies it, and + rejects a source package that ships a root `record.json`. Removal detaches + the directory by rename before deleting it. +* Tests cover accepted/rejected protocol declarations, auxiliary-file/extra-file + tampering, entrypoint tampering and reserved `record.json`. + ### M0.6 implementation progress | Step | State | Evidence | @@ -159,10 +179,11 @@ Trace v2 (`spec/trace-v2.md`, `spec/schemas/trace-v2.schema.json`): | S2-A/H1-B source locations | **Done** | ADR-0017; `RuntimeError`/`CallFrame` carry `module_id`; callsite origin; CLI module-aware resolution with no entry fallback (see §S2-A/H1-B) | | S2-B/H2-A Analysis v2 | **Done** | logical project identity, resources array, machine-path-free diagnostics, emitted-bytes digest, v2 schema + independent consumer (see §S2-B/H2-A) | | S2-C/H2-B Trace v2 | **Done** | logical root/digest, module-owned events, bounded/truncated trace, independent consumer, hardened worker frames (see §S2-C/H2-B) | +| S3-A/H2-C Tool protocol | **Done** | SemVer negotiation at install+dispatch, whole-bundle manifest/digest verification, atomic install/remove, reserved record file (see §S3-A/H2-C) | | R0 baseline + ADRs | **Done** | this section; `docs/adr/0008`–`0012`; full workspace gate | | R1 package-aware identity + callable registry | **Done for statics; superseded by S1 lock v3** | `ModuleId { instance, relative_path }`; `PackageResolver` path sources; lock v3 transitive graph (ADR-0016) replaces the flat v2 lock; `CallableRegistry` for builtins/marqdo/declared ABI exports; external manifest wiring is R2 | | R2 ABI/Kernel/Broker | **Done (worker = crash isolation)** | `KernelRegistry` external providers; complete-name export routing; `CapabilityBroker`; static `check --plugin`; multi-export C test; isolated worker with timeout/crash tests; host handle table. Native/worker are not an OS sandbox | -| R3 Tool Protocol | **Done** | `tool install/list/remove`; unknown-command fallback; atomic local install; SHA/tamper checks; black-box tests for arbitrary names, Unicode args, conflicts, traversal and PATH hijacking | +| R3 Tool Protocol | **Done (S3 hardened)** | `tool install/list/remove`; unknown-command fallback; SemVer + Analysis/Trace negotiation; whole-bundle digest verification; staged install and rename-based removal; black-box tests for arbitrary names, Unicode args, conflicts, traversal, PATH hijacking and bundle tampering | | R4 Analysis/Trace v2 | **Done** | `check --emit` Analysis v2 and `run/call --trace-file` Trace v2 with logical identity, resources, module-owned events, capacity bounds, schemas and independent Python consumers; stale-artifact removal; value redaction | | R5 environment/isolation | **Partial** | Pinned Git fetch with verified cache markers, transitive `@alias` resolution, full-closure atomic `.marqdo/env` materialization, foreign process-group cleanup. Strict OS isolation remains explicitly unavailable (fail-closed) | | R6 release/consumers | **Done for Linux** | examples for unknown-name Tool, multi-export plugin, external kernel and multi-version packages; Analysis/Trace/Tool JSON Schemas; CI Linux gate + Windows/macOS `cargo check`; R6 example tests | diff --git a/spec/tool-v1.md b/spec/tool-v1.md index 9fb318f..204f9b8 100644 --- a/spec/tool-v1.md +++ b/spec/tool-v1.md @@ -24,30 +24,30 @@ "entrypoint": "bin/marqdo-benchmark", "compatibility": { "marqdo": ">=0.1,<1", - "analysis": [1] + "analysis": [2] } } ``` -类型:`schema` 固定字符串,`schema_version` 正整数(首版仅 1),`name`/`version`/`command`/`entrypoint` 非空字符串,`compatibility.marqdo` 是可解析版本范围,`analysis`、`trace` 为可选的正整数数组;仅当工具使用该数据协议时声明。未来可以增加可选字段,但不得改变现有字段含义。 +类型:`schema` 固定字符串,`schema_version` 正整数(首版仅 1),`name`/`version`/`command`/`entrypoint` 非空字符串,`version` 必须是合法 SemVer,`compatibility.marqdo` 必须是可解析的 SemVer 范围,`analysis`、`trace` 为可选的非空正整数数组;仅当工具使用该数据协议时声明。当前核心提供 Analysis v2 与 Trace v2,因此声明 `[1]`(或与 `[2]` 无交集)会在安装/分发时被拒绝。未来可以增加可选字段,但不得改变现有字段含义。 `command`:建议 `^[a-z][a-z0-9-]*$`,不得与任何内置命令或保留参数冲突;同一注册表中命令唯一,名字冲突拒绝且不覆盖。`entrypoint`:包内受控相对路径,不能是绝对路径、`.`/`..` 跳出根目录、符号链接逃逸或可直接解释的任意 shell 片段。真实文件应可执行并与目标平台匹配;若扩展名或平台格式与 OS 不兼容应显式失败。 ## 3. 注册与验证 -本地安装流程:读取用户指定的 `tool.json` → 校验 schema 与平台、版本 → 校验 entrypoint 不越界 → 检查内置/已注册命令冲突 → 用户确认/明确请求的信任决策 → 将工具与清单以临时目录方式拷入受控安装根 → 计算可执行文件真实 SHA-256 → 原子发布注册信息。失败时回滚且不留下可执行入口。 +本地安装流程:读取用户指定的 `tool.json` → 校验 schema、SemVer 与协议交集 → 校验 entrypoint 不越界 → 检查内置/已注册命令冲突 → 收集**整包**规范化文件清单(相对路径、大小、SHA-256,拒绝符号链接/特殊文件/非 UTF-8 路径,限制文件数与总字节)→ 以临时目录按同一清单复制 → 对 staging 重新计算清单并要求逐项一致 → 写入记录并原子 rename 发布。失败时清理 staging,不留下半安装。 -注册记录最少包含 `command`、`name`、`version`、`entrypoint_absolute_path`、`sha256`、`source`、`schema_version`、`compatibility`。注册不是来源认证;SHA 校验只能检查文件未被改变。对互联网下载必须额外有可信索引给出的摘要/签名;禁止在用户未同意前自动从网络下载。 +注册记录(`record_version: 2`)包含 `command`、`name`、`version`、`entrypoint`(包内相对路径)、`bundle[]`(每文件 path/size/sha256)、`bundle_sha256`、`source`、`schema_version`、`compatibility`。`bundle_sha256` 是排序后 `path\0size\0sha256\n` 的 SHA-256。注册不是来源认证;摘要只能检查安装后未被改变。对互联网下载必须额外有可信索引给出的摘要/签名;禁止在用户未同意前自动从网络下载。 -运行时必须校验记录的版本/平台/摘要;任何不一致拒绝而非尝试降级。实现优先使用正确的跨平台配置目录 API,不要把 `~` 当成可移植的用户目录。多个用户/多个版本并存属于独立目录隔离;同一个命令只能解析到一个注册项,除非未来另有显式版本选择规范。 +运行时在启动前重新计算磁盘上的整包清单,与记录逐项比较(排除根 `record.json`),并验证 entrypoint 属于该清单、记录命令与请求命令一致、版本/协议仍兼容。任何不一致拒绝而非降低校验强度。旧记录版本不复用,提示重新安装。实现优先使用正确的跨平台配置目录 API,不要把 `~` 当成可移植的用户目录。多个用户/多个版本并存属于独立目录隔离;同一个命令只能解析到一个注册项,除非未来另有显式版本选择规范。 ## 4. 分发算法 -输入 `marqdo `,先检查内置命令,内置优先;否则从已安装的只读注册映射查找 ``。找到则验证 Tool Protocol 与程序文件,使用 `Command::new(entrypoint).args(args)` **直接启动**,从调用者原样保留 `cwd`、`stdin/stdout/stderr` 和可保留的环境(敏感环境变量策略另行安全审计),原样传播退出状态;绝不调用 `sh -c`、不拼接命令字符串。 +输入 `marqdo `,先检查内置命令,内置优先;否则从已安装的只读注册映射查找 ``。找到则重新协商 Tool/分析/追踪协议,验证整包清单与 entrypoint,使用 `Command::new(entrypoint).args(args)` **直接启动**,从调用者原样保留 `cwd`、`stdin/stdout/stderr` 和可保留的环境(敏感环境变量策略另行安全审计),原样传播退出状态;绝不调用 `sh -c`、不拼接命令字符串。 工具负责自己的命令层级与帮助,如 `marqdo benchmark run .`、`marqdo benchmark --help`。CLI 不读取或修改工具业务选项。Rust `clap` 可通过单一 `external_subcommand` 捕获未知子命令,但必须保留 `OsString` 原样传参;不能让工具要求 CLI 添加 `Command::View` 等专门枚举项。不要求工具在处理 `--help` 时调用核心。未知命令时报错;即使 PATH 中存在 `marqdo-`,**没有显式注册也不能执行它**。 -可选辅助环境:`MARQDO_BIN`(当前核心 CLI 的绝对路径),`MARQDO_TOOL_PROTOCOL=1`。工具通过此路径运行 `marqdo check ... --emit ...` 和 `marqdo run ... --trace-file ...`,不拥有额外宿主内部 API。不得自动将密钥、项目能力授予记录、ABI 插件加载句柄或用户外联会话传给工具。 +可选辅助环境:`MARQDO_BIN`(当前核心 CLI 的绝对路径),`MARQDO_TOOL_PROTOCOL=1`;仅当工具声明并协商了对应协议时,额外设置 `MARQDO_PROTOCOL_ANALYSIS=2` 与/或 `MARQDO_PROTOCOL_TRACE=2`。工具通过此路径运行 `marqdo check ... --emit ...` 和 `marqdo run ... --trace-file ...`,不拥有额外宿主内部 API。不得自动将密钥、项目能力授予记录、ABI 插件加载句柄或用户外联会话传给工具。 ## 5. 三个独立安全域 @@ -57,7 +57,7 @@ ## 6. 向后兼容 -`schema_version` 不支持或 `marqdo` 版本范围不匹配应以稳定错误码拒绝执行;可忽略的未知扩展字段允许透传,但不能被视为隐含授权。公共 Analysis/Trace 协议单独版本管理;有工具声明 `[1]` 才参与对应版本检查,没有声明不强迫工具使用任何数据协议。 +`schema_version` 不支持、`marqdo` 范围不匹配、工具版本不是合法 SemVer,或声明的 Analysis/Trace 列表与核心支持集(当前 `analysis: [2]`、`trace: [2]`)无交集时,安装与分发都必须以稳定错误拒绝;错误信息包含 `tool.protocol_incompatible`。可忽略的未知扩展字段允许透传,但不能被视为隐含授权。没有声明数据协议的工具不受该检查约束,也不会收到协议环境变量。 原生命令集合是保留命名空间;未来新增与社区工具冲突的新核心顶层命令属于破坏性变化,必须经过 ADR、迁移期诊断和工具冲突统计,不能静默覆盖已有已注册工具。 @@ -68,10 +68,13 @@ | `tool install` 本地清单 `benchmark` 后调用 `marqdo benchmark run .` | 无需 CLI 源码改动,可原样传参并传播退出码 | | 将工具名改成 `lintx`,重建外部程序但不重建 CLI | 能直接注册和调用 | | 工具没有 `analysis/trace` 兼容字段 | 可以独立使用;不强制创建分析或运行记录 | -| 工具声明不支持 Analysis v1 或核心版本 | 在需要该协议时拒绝,不回退猜测 | +| 工具声明 `analysis:[2]`/`trace:[2]` | 安装并分发,环境变量反映协商结果 | +| 工具声明 `analysis:[1]`、`[]` 或与支持集无交集 | 安装/分发拒绝,错误含 `tool.protocol_incompatible`,不回退猜测 | | 工具注册名冲突 `run` 或另一已安装工具 | 拒绝,不覆盖 | | PATH 中存在同名 `marqdo-benchmark` 但未注册 | 未知命令错误,不执行 PATH 程序 | -| 篡改已安装二进制的一个字节 | 拒绝启动,指明摘要不匹配 | +| 篡改已安装二进制的一个字节 | 拒绝启动,指明整包摘要不匹配 | +| 仅篡改辅助脚本、增加未列文件或删除文件 | 拒绝启动,整包清单不一致 | +| 源包包含根 `record.json` | 安装拒绝(记录文件由核心保留) | | `entrypoint` 是 `../outside`、绝对路径或越界符号链接 | 安装失败,无残留注册 | | 安装时被杀/写盘失败/并发安装 | 不留下半安装或不一致的注册 | | `marqdo tool remove benchmark` | 注册与受控安装制品删除;其他工具正常 |