diff --git a/README.md b/README.md index 7e4a7d3..aad0cf1 100644 --- a/README.md +++ b/README.md @@ -179,7 +179,7 @@ tests/ conformance/negative corpus (see tests/README.md) * [`docs/adr/`](docs/adr/) — accepted decisions (crate graph, inert executables, `ref` ambiguity, strict refusal, AST normalization, CLI contract, BigInt/wire, package identity, callable resolution, plugin export routing, capability - broker, kernel providers). + broker, kernel providers, generic CLI tools, plugin-handle authority). * Specs: [`markdown-profile.md`](spec/markdown-profile.md), [`mapping.md`](spec/mapping.md), [`expression.ebnf`](spec/expression.ebnf), [`evaluation.md`](spec/evaluation.md), [`references.md`](spec/references.md), diff --git a/crates/cli/src/main.rs b/crates/cli/src/main.rs index ebc63b7..53cc44e 100644 --- a/crates/cli/src/main.rs +++ b/crates/cli/src/main.rs @@ -8,7 +8,9 @@ mod args; mod commands; mod loader; mod output; +mod tool; +use std::ffi::OsString; use std::path::PathBuf; use clap::{Args, Parser, Subcommand}; @@ -49,6 +51,11 @@ enum Command { Lock(LockArgs), /// Verify that path dependencies match the lockfile. Sync(SyncArgs), + /// Manage and dispatch generic external CLI tools. + Tool(ToolArgs), + /// Unknown top-level command: dispatch to a registered external tool. + #[command(external_subcommand)] + External(Vec), } #[derive(Args)] @@ -251,6 +258,47 @@ struct LockArgs { json: bool, } +#[derive(Args)] +struct ToolArgs { + #[command(subcommand)] + command: ToolCommand, +} + +#[derive(Subcommand)] +enum ToolCommand { + /// Install a tool from a local tool.json (or its directory). + Install(ToolInstallArgs), + /// List installed external tools. + List(ToolListArgs), + /// Remove an installed external tool. + Remove(ToolRemoveArgs), +} + +#[derive(Args)] +struct ToolInstallArgs { + /// Path to tool.json or the tool package directory. + manifest: PathBuf, + /// Machine readable JSON output. + #[arg(long)] + json: bool, +} + +#[derive(Args)] +struct ToolListArgs { + /// Machine readable JSON output. + #[arg(long)] + json: bool, +} + +#[derive(Args)] +struct ToolRemoveArgs { + /// Tool command to remove. + command: String, + /// Machine readable JSON output. + #[arg(long)] + json: bool, +} + #[derive(Args)] struct SyncArgs { /// Fail instead of silently updating when the lockfile is stale. @@ -315,6 +363,12 @@ fn main() { Command::Remove(args) => commands::remove(&args.name, args.json), Command::Lock(args) => commands::lock(args.json), Command::Sync(args) => commands::sync(args.locked, args.json), + Command::Tool(args) => match args.command { + ToolCommand::Install(args) => tool::install(&args.manifest, args.json), + ToolCommand::List(args) => tool::list(args.json), + ToolCommand::Remove(args) => tool::remove(&args.command, args.json), + }, + Command::External(args) => tool::dispatch(&args), }; std::process::exit(code); } diff --git a/crates/cli/src/tool.rs b/crates/cli/src/tool.rs new file mode 100644 index 0000000..54ce866 --- /dev/null +++ b/crates/cli/src/tool.rs @@ -0,0 +1,543 @@ +//! 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. + +use std::collections::BTreeMap; +use std::ffi::OsString; +use std::path::{Component, Path, PathBuf}; +use std::process::Command as ProcessCommand; + +use serde::{Deserialize, Serialize}; +use sha2::{Digest, Sha256}; + +const SCHEMA: &str = "marqdo.cli-tool"; +const PROTOCOL_VERSION: u32 = 1; +const BUILTIN_COMMANDS: &[&str] = &[ + "init", "run", "call", "check", "inspect", "fmt", "plugin", "add", "remove", "lock", "sync", + "tool", "help", +]; + +#[derive(Debug, Clone, Deserialize)] +struct ToolManifest { + schema: String, + schema_version: u32, + name: String, + version: String, + command: String, + entrypoint: PathBuf, + #[serde(default)] + compatibility: Compatibility, +} + +#[derive(Debug, Clone, Default, Deserialize)] +struct Compatibility { + #[serde(default)] + marqdo: Option, + #[serde(default)] + analysis: Option>, + #[serde(default)] + 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")] + marqdo: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + analysis: Option>, + #[serde(default, skip_serializing_if = "Option::is_none")] + trace: Option>, +} + +/// `marqdo tool install `. +pub fn install(manifest_path: &Path, json: bool) -> i32 { + match install_inner(manifest_path) { + Ok(record) => { + if json { + println!( + "{}", + serde_json::json!({ + "command": "tool.install", + "success": true, + "tool": record.command, + "version": record.version, + }) + ); + } else { + println!( + "installed tool `{}` version {} ({})", + record.command, record.version, record.name + ); + } + 0 + } + Err(error) => { + if json { + println!( + "{}", + serde_json::json!({"command":"tool.install","success":false,"error":error}) + ); + } else { + eprintln!("error: {error}"); + } + 1 + } + } +} + +fn install_inner(manifest_path: &Path) -> Result { + let manifest_file = if manifest_path.is_dir() { + manifest_path.join("tool.json") + } else { + manifest_path.to_path_buf() + }; + let package_dir = manifest_file + .parent() + .ok_or_else(|| "manifest has no parent directory".to_string())? + .canonicalize() + .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)?; + let home = tool_home()?; + std::fs::create_dir_all(&home) + .map_err(|error| format!("cannot create tool home `{}`: {error}", home.display()))?; + let target = home.join(&manifest.command); + if target.exists() { + return Err(format!( + "tool command `{}` is already installed; remove it first", + manifest.command + )); + } + let staging = home.join(format!( + ".staging-{}-{}", + std::process::id(), + unique_suffix() + )); + if staging.exists() { + let _ = std::fs::remove_dir_all(&staging); + } + 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(); + let record = ToolRecord { + command: manifest.command.clone(), + name: manifest.name.clone(), + version: manifest.version.clone(), + entrypoint: relative.clone(), + sha256: sha256.clone(), + source: manifest_file.display().to_string(), + schema_version: PROTOCOL_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) + .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(()) + })(); + if result.is_err() { + let _ = std::fs::remove_dir_all(&staging); + } + result.and_then(|()| load_record(&target)) +} + +impl ToolManifest { + fn from_path(path: &Path) -> Result { + let text = std::fs::read_to_string(path) + .map_err(|error| format!("cannot read `{}`: {error}", path.display()))?; + let manifest: Self = + serde_json::from_str(&text).map_err(|error| format!("invalid tool.json: {error}"))?; + Ok(manifest) + } +} + +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 { + return Err(format!( + "unsupported tool schema_version {} (expected {PROTOCOL_VERSION})", + manifest.schema_version + )); + } + if !is_valid_command(&manifest.command) { + return Err(format!( + "tool command `{}` must match ^[a-z][a-z0-9-]*$", + manifest.command + )); + } + if BUILTIN_COMMANDS.contains(&manifest.command.as_str()) { + return Err(format!( + "tool command `{}` conflicts with a built-in command", + 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 let Some(range) = &manifest.compatibility.marqdo { + if !version_matches(env!("CARGO_PKG_VERSION"), range) { + return Err(format!( + "tool requires marqdo `{range}`, this core is {}", + env!("CARGO_PKG_VERSION") + )); + } + } + Ok(()) +} + +fn is_valid_command(command: &str) -> bool { + let mut bytes = command.bytes(); + matches!(bytes.next(), Some(byte) if byte.is_ascii_lowercase()) + && bytes.all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'-') +} + +fn safe_entrypoint(package_dir: &Path, entrypoint: &Path) -> Result { + if entrypoint.is_absolute() { + return Err("tool entrypoint must be package-relative".to_string()); + } + for component in entrypoint.components() { + match component { + Component::Normal(_) => {} + Component::CurDir => {} + _ => return Err("tool entrypoint must not escape the package".to_string()), + } + } + let candidate = package_dir.join(entrypoint); + let canonical = candidate.canonicalize().map_err(|error| { + format!( + "tool entrypoint `{}` cannot be opened: {error}", + candidate.display() + ) + })?; + if !canonical.starts_with(package_dir) { + return Err("tool entrypoint resolves outside the package".to_string()); + } + if !canonical.is_file() { + return Err("tool entrypoint is not a file".to_string()); + } + #[cfg(unix)] + { + use std::os::unix::fs::PermissionsExt; + if std::fs::metadata(&canonical) + .map(|metadata| metadata.permissions().mode() & 0o111 == 0) + .unwrap_or(true) + { + return Err("tool entrypoint is not executable".to_string()); + } + } + Ok(canonical) +} + +fn copy_package(source: &Path, target: &Path) -> Result<(), String> { + for entry in walkdir::WalkDir::new(source).follow_links(false) { + 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.file_type().is_symlink() { + return Err(format!( + "tool package contains a symlink `{}`; symlinks are not installed", + entry.path().display() + )); + } + 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() + ) + })?; + } + } + Ok(()) +} + +/// `marqdo tool list`. +pub fn list(json: bool) -> i32 { + match installed_records() { + Ok(records) => { + if json { + println!( + "{}", + serde_json::json!({"command":"tool.list","success":true,"tools":records}) + ); + } else if records.is_empty() { + println!("no tools installed"); + } else { + for record in records { + println!("{} {} ({})", record.command, record.version, record.name); + } + } + 0 + } + Err(error) => { + eprintln!("error: {error}"); + 1 + } + } +} + +/// `marqdo tool remove `. +pub fn remove(command: &str, json: bool) -> i32 { + let result = (|| -> Result<(), String> { + if !is_valid_command(command) { + return Err(format!("invalid tool command `{command}`")); + } + let home = tool_home()?; + let target = home.join(command); + 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}"))?; + let canonical_target = target + .canonicalize() + .map_err(|error| format!("cannot open tool installation: {error}"))?; + 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) + .map_err(|error| format!("cannot remove tool `{command}`: {error}"))?; + Ok(()) + })(); + match result { + Ok(()) => { + if json { + println!( + "{}", + serde_json::json!({"command":"tool.remove","success":true,"tool":command}) + ); + } else { + println!("removed tool `{command}`"); + } + 0 + } + Err(error) => { + if json { + println!( + "{}", + serde_json::json!({"command":"tool.remove","success":false,"error":error}) + ); + } else { + eprintln!("error: {error}"); + } + 1 + } + } +} + +/// Dispatch an unknown top-level command to a registered tool. +pub fn dispatch(args: &[OsString]) -> i32 { + let Some(first) = args.first() else { + eprintln!("error: missing command"); + return 2; + }; + let command = first.to_string_lossy(); + if BUILTIN_COMMANDS.contains(&command.as_ref()) { + eprintln!("error: internal dispatch error for built-in command `{command}`"); + return 2; + } + let home = match tool_home() { + Ok(home) => home, + Err(error) => { + eprintln!("error: {error}"); + return 2; + } + }; + let dir = home.join(command.as_ref()); + let record = match load_record(&dir) { + Ok(record) => record, + Err(_) => { + eprintln!( + "error: unknown command `{command}`; install a tool with `marqdo tool install `" + ); + return 2; + } + }; + let entrypoint = dir.join(&record.entrypoint); + if !entrypoint.starts_with(&dir) { + eprintln!("error: tool entrypoint escapes its installation"); + return 1; + } + let actual = match hash_file(&entrypoint) { + Ok(hash) => hash, + Err(error) => { + eprintln!("error: {error}"); + return 1; + } + }; + if actual != record.sha256 { + eprintln!("error: tool `{command}` executable hash mismatch; 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"); + match process.status() { + Ok(status) => status.code().unwrap_or(1), + Err(error) => { + eprintln!("error: cannot start tool `{command}`: {error}"); + 1 + } + } +} + +fn installed_records() -> Result, String> { + let home = tool_home()?; + if !home.is_dir() { + return Ok(Vec::new()); + } + let mut records = BTreeMap::new(); + let entries = std::fs::read_dir(&home) + .map_err(|error| format!("cannot read tool home `{}`: {error}", home.display()))?; + for entry in entries { + let entry = entry.map_err(|error| format!("cannot read tool entry: {error}"))?; + if !entry.file_type().map(|kind| kind.is_dir()).unwrap_or(false) { + continue; + } + if entry.file_name().to_string_lossy().starts_with('.') { + continue; + } + if let Ok(record) = load_record(&entry.path()) { + records.insert(record.command.clone(), record); + } + } + Ok(records.into_values().collect()) +} + +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}")) +} + +fn tool_home() -> Result { + if let Some(path) = std::env::var_os("MARQDO_TOOL_HOME") { + return Ok(PathBuf::from(path)); + } + let base = if cfg!(windows) { + std::env::var_os("APPDATA") + .map(PathBuf::from) + .ok_or_else(|| "APPDATA is not set; set MARQDO_TOOL_HOME".to_string())? + } else { + std::env::var_os("XDG_CONFIG_HOME") + .map(PathBuf::from) + .or_else(|| std::env::var_os("HOME").map(|home| PathBuf::from(home).join(".config"))) + .ok_or_else(|| "HOME is not set; set MARQDO_TOOL_HOME".to_string())? + }; + Ok(base.join("marqdo").join("tools")) +} + +fn hash_file(path: &Path) -> Result { + let bytes = std::fs::read(path) + .map_err(|error| format!("cannot read `{}`: {error}", path.display()))?; + let mut hasher = Sha256::new(); + hasher.update(&bytes); + Ok(hex::encode(hasher.finalize())) +} + +fn unique_suffix() -> u128 { + std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .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 new file mode 100644 index 0000000..7507f14 --- /dev/null +++ b/crates/cli/tests/tool_protocol.rs @@ -0,0 +1,184 @@ +//! External CLI Tool Protocol v1 black-box tests (spec/tool-v1.md). +#![cfg(unix)] + +use std::path::{Path, PathBuf}; +use std::process::{Command, Output}; +use std::sync::atomic::{AtomicU32, Ordering}; + +static COUNTER: AtomicU32 = AtomicU32::new(0); + +struct TempDir(PathBuf); + +impl TempDir { + fn new(tag: &str) -> Self { + let id = COUNTER.fetch_add(1, Ordering::Relaxed); + let path = std::env::temp_dir().join(format!( + "marqdo-tool-test-{}-{id}-{tag}", + std::process::id() + )); + std::fs::create_dir_all(&path).unwrap(); + Self(path) + } + + fn path(&self) -> &Path { + &self.0 + } +} + +impl Drop for TempDir { + fn drop(&mut self) { + let _ = std::fs::remove_dir_all(&self.0); + } +} + +fn binary() -> &'static str { + env!("CARGO_BIN_EXE_marqdo") +} + +fn cli(home: &Path, args: &[&str]) -> Output { + Command::new(binary()) + .args(args) + .env("MARQDO_TOOL_HOME", home) + .output() + .expect("run marqdo") +} + +fn write_tool(dir: &Path, command: &str, script: &str) -> PathBuf { + let package = dir.join(format!("{command}-pkg")); + std::fs::create_dir_all(package.join("bin")).unwrap(); + let entry = package.join("bin").join(command); + std::fs::write(&entry, script).unwrap(); + #[cfg(unix)] + { + use std::os::unix::fs::PermissionsExt; + let mut permissions = std::fs::metadata(&entry).unwrap().permissions(); + permissions.set_mode(0o755); + std::fs::set_permissions(&entry, permissions).unwrap(); + } + let manifest = package.join("tool.json"); + std::fs::write( + &manifest, + format!( + r#"{{"schema":"marqdo.cli-tool","schema_version":1,"name":"demo.{command}","version":"0.1.0","command":"{command}","entrypoint":"bin/{command}","compatibility":{{"marqdo":">=0.1,<1"}}}}"# + ), + ) + .unwrap(); + manifest +} + +fn stderr(output: &Output) -> String { + String::from_utf8_lossy(&output.stderr).to_string() +} + +fn stdout(output: &Output) -> String { + String::from_utf8_lossy(&output.stdout).to_string() +} + +#[test] +fn install_dispatch_list_remove_without_core_knowledge_of_the_name() { + let dir = TempDir::new("roundtrip"); + let home = dir.path().join("home"); + let manifest = write_tool( + dir.path(), + "benchmark", + "#!/bin/sh\nfor a in \"$@\"; do printf 'arg=%s\\n' \"$a\"; done\nprintf 'protocol=%s\\n' \"$MARQDO_TOOL_PROTOCOL\"\nexit 7\n", + ); + + let install = cli(&home, &["tool", "install", manifest.to_str().unwrap()]); + assert_eq!(install.status.code(), Some(0), "{}", stderr(&install)); + + let listed = cli(&home, &["tool", "list"]); + assert!(stdout(&listed).contains("benchmark 0.1.0")); + + let output = cli(&home, &["benchmark", "run", ".", "空格"]); + assert_eq!(output.status.code(), Some(7)); + let text = stdout(&output); + assert!(text.contains("arg=run")); + assert!(text.contains("arg=.")); + assert!(text.contains("arg=空格")); + assert!(text.contains("protocol=1")); + + let removed = cli(&home, &["tool", "remove", "benchmark"]); + assert_eq!(removed.status.code(), Some(0)); + let unknown = cli(&home, &["benchmark"]); + assert_eq!(unknown.status.code(), Some(2)); + assert!(stderr(&unknown).contains("unknown command")); +} + +#[test] +fn invalid_manifests_and_path_escapes_are_rejected() { + let dir = TempDir::new("invalid"); + let home = dir.path().join("home"); + let manifest = write_tool(dir.path(), "lintx", "#!/bin/sh\nexit 0\n"); + + let builtin = std::fs::read_to_string(&manifest) + .unwrap() + .replace("\"command\":\"lintx\"", "\"command\":\"run\""); + let builtin_manifest = dir.path().join("builtin.json"); + std::fs::write(&builtin_manifest, builtin).unwrap(); + let output = cli( + &home, + &["tool", "install", builtin_manifest.to_str().unwrap()], + ); + assert_eq!(output.status.code(), Some(1)); + assert!(stderr(&output).contains("built-in")); + + let traversal = std::fs::read_to_string(&manifest) + .unwrap() + .replace("bin/lintx", "../outside"); + let traversal_manifest = dir.path().join("traversal.json"); + std::fs::write(&traversal_manifest, traversal).unwrap(); + let output = cli( + &home, + &["tool", "install", traversal_manifest.to_str().unwrap()], + ); + assert_eq!(output.status.code(), Some(1)); + + let incompatible = std::fs::read_to_string(&manifest) + .unwrap() + .replace(">=0.1,<1", ">=99.0"); + let incompatible_manifest = dir.path().join("incompatible.json"); + std::fs::write(&incompatible_manifest, incompatible).unwrap(); + let output = cli( + &home, + &["tool", "install", incompatible_manifest.to_str().unwrap()], + ); + assert_eq!(output.status.code(), Some(1)); + assert!(stderr(&output).contains("requires marqdo")); +} + +#[test] +fn tampered_binary_and_path_hijack_are_not_executed() { + let dir = TempDir::new("security"); + let home = dir.path().join("home"); + let manifest = write_tool(dir.path(), "custom-abc", "#!/bin/sh\nexit 0\n"); + assert_eq!( + cli(&home, &["tool", "install", manifest.to_str().unwrap()]) + .status + .code(), + Some(0) + ); + let installed = home.join("custom-abc").join("bin").join("custom-abc"); + std::fs::write(&installed, "#!/bin/sh\nexit 99\n").unwrap(); + let tampered = cli(&home, &["custom-abc"]); + assert_eq!(tampered.status.code(), Some(1)); + assert!(stderr(&tampered).contains("hash mismatch")); + + // A PATH program with the marqdo prefix is not implicitly a tool. + let path_dir = dir.path().join("path"); + std::fs::create_dir_all(&path_dir).unwrap(); + let hijack = path_dir.join("marqdo-hijack"); + std::fs::write(&hijack, "#!/bin/sh\nexit 42\n").unwrap(); + use std::os::unix::fs::PermissionsExt; + let mut permissions = std::fs::metadata(&hijack).unwrap().permissions(); + permissions.set_mode(0o755); + std::fs::set_permissions(&hijack, permissions).unwrap(); + let output = Command::new(binary()) + .arg("hijack") + .env("MARQDO_TOOL_HOME", &home) + .env("PATH", &path_dir) + .output() + .unwrap(); + assert_eq!(output.status.code(), Some(2)); + assert!(stderr(&output).contains("unknown command")); +} diff --git a/docs/STATUS.md b/docs/STATUS.md index 4fc8f62..600d66b 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -42,7 +42,7 @@ providers). | R0 baseline + ADRs | **Done** | this section; `docs/adr/0008`–`0012`; full workspace gate | | R1 package-aware identity + callable registry | **Done for statics** | `ModuleId { instance, relative_path }`; `PackageResolver` path sources; `lock_version: 2` with v1 migration; `CallableRegistry` for builtins/marqdo/declared ABI exports; external manifest wiring is R2 | | R2 ABI/Kernel/Broker | **In progress** | `KernelRegistry` external providers; complete-name plugin export routing; `CapabilityBroker` with vendor policy; static `check --plugin` signatures; multi-export C test; provider tests. Isolated worker and handle table still pending | -| R3 Tool Protocol | Not started | — | +| 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 | | R4 Analysis/Trace v1 | Not started | — | | R5 environment/isolation | Not started | — | | R6 release/consumers | Not started | — | diff --git a/docs/adr/0013-generic-cli-tool-protocol.md b/docs/adr/0013-generic-cli-tool-protocol.md new file mode 100644 index 0000000..50ba729 --- /dev/null +++ b/docs/adr/0013-generic-cli-tool-protocol.md @@ -0,0 +1,75 @@ +# ADR-0013: Generic external CLI Tool Protocol v1 + +Status: **Accepted** +Date: 2026-11-20 + +## Context + +M0.6 must let external tools (`view`, `knowledge`, `prove`, or arbitrary +third-party programs) become `marqdo ` entries without changing the +core source or command enum. The CLI currently has a closed `clap` enum and no +generic distribution path. C ABI plugins and foreign kernels are unrelated +trust models: a Tool is a user-invoked native process. + +## Decision + +`spec/tool-v1.md` is implemented as follows: + +* new top-level commands are limited to + `tool install/list/remove` plus fallback for unknown top-level commands; +* `tool.json` (schema `marqdo.cli-tool`, schema_version 1) declares + `name`, `version`, `command`, `entrypoint` and optional compatibility; the + core does not contain any tool name, download URL or business argument; +* install requires a local manifest, validates the command (lowercase ASCII, + no built-in conflict), rejects absolute/`..`/symlink-escaping entrypoints, + copies the package without following symlinks into a user-controlled tool + home, re-verifies the executable SHA-256, writes a registry record, and + publishes atomically via rename; +* dispatch checks the registry record, re-verifies the executable hash, starts + the entrypoint directly with `OsString` arguments (no shell), inherits + stdin/stdout/stderr and cwd, sets `MARQDO_BIN`/`MARQDO_TOOL_PROTOCOL=1`, and + propagates the exit code; +* a missing registration is an unknown command; a `marqdo-` on PATH is + never executed implicitly; +* uninstall removes only the exact controlled installation directory. + +The tool home defaults to the platform config directory and can be redirected +with `MARQDO_TOOL_HOME` for tests/enterprise deployment. + +## Alternatives + +1. Add a `clap` variant per known tool. Rejected by the audit (E01/E12). +2. Auto-discover `marqdo-*` from PATH (Cargo-style). Rejected: implicit + execution and PATH hijacking; M0.6 requires explicit installation. +3. Use the C ABI plugin registry. Rejected: different lifecycle, protocol and + security boundary. +4. Implement a remote registry first. Rejected: local manifest installation is + the required closed loop; name-based installs are a future optional index. + +## Compatibility + +This adds one new top-level command (`tool`) and an unknown-command fallback. +Built-in commands always win. Future core commands that collide with an +installed tool are a breaking change and need an ADR/migration policy. The +manifest is versioned; unknown optional fields are ignored in v1 but never +imply authorization. + +## Security + +A Tool is a normal process run as the user, not inside the `.mq.md` sandbox. +It does not automatically receive Marqdo capabilities, secrets or plugin +handles. Install never runs the tool. The executable hash detects post-install +tampering, not a malicious publisher; local source selection is the trust +decision. Symlinks are rejected during package copy. + +## Testing + +`crates/cli/tests/tool_protocol.rs` covers arbitrary command names, +install/list/remove, argument/exit-code forwarding, Unicode args, built-in +conflict, traversal, version mismatch, binary tampering and PATH hijacking. +`spec/tool-v1.md` lists the full black-box matrix. + +## Migration & rollout + +R3 adds the command surface. R4 can expose Analysis/Trace compatibility through +the manifest's optional fields; no tool business logic enters the core. diff --git a/docs/contributor-guide.md b/docs/contributor-guide.md index 9a66e41..f10704f 100644 --- a/docs/contributor-guide.md +++ b/docs/contributor-guide.md @@ -18,7 +18,7 @@ marqdo-cli/ │ ├── EXTENSIBILITY_AUDIT.md source-backed E01–E16 audit for M0.6 │ ├── STATUS.md implementation matrix (P0–P7) │ ├── contributor-guide.md this file -│ └── adr/0001..0012-*.md accepted decisions +│ └── adr/0001..0014-*.md accepted decisions ├── spec/ │ ├── markdown-profile.md frozen parser profile `marqdo.md.v1` │ ├── mapping.md AST → program roles