feat(m0.6-r3): generic external CLI Tool Protocol v1
- add tool install/list/remove and unknown-command dispatch without hardcoded tool names or clap variants - validate and copy local tool packages atomically, reject entrypoint escapes and symlinks, record and re-verify SHA-256 - forward OsString args, stdio, cwd and exit status without a shell; never execute PATH programs implicitly - add black-box tests for arbitrary names, Unicode args, built-in conflicts, traversal, version mismatch, tampering and PATH hijacking - add ADR-0013 and mark R3 complete
This commit is contained in:
1 parent
7797d78d86
commit
25a1faa6ef
7 files changed
+859
-3
No files matched your search
@@ -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),
|
||||
|
||||
@@ -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<OsString>),
|
||||
}
|
||||
|
||||
#[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);
|
||||
}
|
||||
@@ -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<String>,
|
||||
#[serde(default)]
|
||||
analysis: Option<Vec<u32>>,
|
||||
#[serde(default)]
|
||||
trace: Option<Vec<u32>>,
|
||||
}
|
||||
|
||||
#[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<String>,
|
||||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||||
analysis: Option<Vec<u32>>,
|
||||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||||
trace: Option<Vec<u32>>,
|
||||
}
|
||||
|
||||
/// `marqdo tool install <manifest-or-directory>`.
|
||||
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<ToolRecord, String> {
|
||||
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<Self, String> {
|
||||
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<PathBuf, String> {
|
||||
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 <command>`.
|
||||
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 <tool.json>`"
|
||||
);
|
||||
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<Vec<ToolRecord>, 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<ToolRecord, String> {
|
||||
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<PathBuf, String> {
|
||||
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<String, String> {
|
||||
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))
|
||||
}
|
||||
@@ -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"));
|
||||
}
|
||||
+1
-1
@@ -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 | — |
|
||||
|
||||
@@ -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 <command>` 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-<name>` 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.
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user