From 0f01a6904894a69e8a04ee30a91852b8f27addd6 Mon Sep 17 00:00:00 2001 From: cflmy Date: Fri, 20 Nov 2026 13:08:56 +0800 Subject: [PATCH] feat(plugin): bridge worker capability requests to the host broker (H3-A) - add request-scoped capability_request/capability_reply/capability_error frames to the worker transport (ADR-0018); no C ABI change - worker routes its capability handler through stdin/stdout, the host serves requests inside the existing invoke deadline and binds identity from the spawned worker, never from frame text - both native and worker plugins now execute a granted fs.read through ProjectFs with audit; unsupported capabilities return capability.unavailable - add a real C capability plugin and CLI test for granted read and denial - document the bridge and that strict OS isolation (H3-B) is still refused --- crates/cli/tests/plugin_worker.rs | 93 ++++++++++ crates/marqdo-host/src/host.rs | 22 ++- crates/marqdo-host/src/plugin_worker.rs | 132 +++++++++++--- crates/marqdo-host/tests/capability_broker.rs | 162 ++++++++++++++++++ crates/marqdo-plugin-abi/src/worker.rs | 137 +++++++++++++-- docs/STATUS.md | 18 +- docs/adr/0011-capability-broker.md | 2 +- docs/adr/0018-worker-capability-bridge.md | 90 ++++++++++ spec/plugin-abi.md | 18 ++ spec/security.md | 11 +- tests/abi/capability_plugin.c | 99 +++++++++++ 11 files changed, 720 insertions(+), 64 deletions(-) create mode 100644 crates/marqdo-host/tests/capability_broker.rs create mode 100644 docs/adr/0018-worker-capability-bridge.md create mode 100644 tests/abi/capability_plugin.c diff --git a/crates/cli/tests/plugin_worker.rs b/crates/cli/tests/plugin_worker.rs index ce8b76a..586af55 100644 --- a/crates/cli/tests/plugin_worker.rs +++ b/crates/cli/tests/plugin_worker.rs @@ -154,3 +154,96 @@ fn worker_crash_is_isolated_from_the_host() { .unwrap(); assert_eq!(survivor.status.code(), Some(0)); } + +fn compile_capability(dir: &Path) -> PathBuf { + let output = dir.join("capability.so"); + let status = Command::new("cc") + .args(["-std=c11", "-O2", "-shared", "-fPIC"]) + .arg("-I") + .arg(repo().join("include")) + .arg(repo().join("tests/abi/capability_plugin.c")) + .arg("-o") + .arg(&output) + .status() + .expect("cc"); + assert!(status.success(), "cc failed"); + output +} + +fn write_capability_manifest(dir: &Path, sha: &str) { + std::fs::write( + dir.join("plugin.yaml"), + format!( + r#"plugin: + name: demo.capability + version: 0.1.0 + abi: "^1.0" + kind: worker + exports: + - name: capability.read + signature: "() -> Text" + requires: + - fs.read + artifacts: + - target: {} + file: capability.so + sha256: "{}" +"#, + HostTarget::current().triple(), + sha + ), + ) + .unwrap(); + std::fs::write( + dir.join("doc.mq.md"), + "## main\n\n**结果 = capability.read()**\n\n> 打印(结果)\n", + ) + .unwrap(); + std::fs::create_dir_all(dir.join("data")).unwrap(); + std::fs::write(dir.join("data/allowed.txt"), "hello-worker").unwrap(); +} + +fn run_capability(dir: &Path, allow_read: bool) -> Output { + let mut command = Command::new(env!("CARGO_BIN_EXE_marqdo")); + command.args([ + "run", + dir.join("doc.mq.md").to_str().unwrap(), + "--plugin", + dir.to_str().unwrap(), + "--allow-plugin", + "demo.capability", + ]); + if allow_read { + command.args(["--allow-read", "data/**"]); + } + command.output().unwrap() +} + +#[test] +fn worker_capability_bridge_reads_granted_file_and_denies_without_grant() { + if !have_cc() { + eprintln!("skipping: cc is unavailable"); + return; + } + let dir = TempDir::new("capability"); + let artifact = compile_capability(dir.path()); + write_capability_manifest(dir.path(), &sha256_file(&artifact).unwrap()); + + let output = run_capability(dir.path(), true); + assert_eq!( + output.status.code(), + Some(0), + "{}", + String::from_utf8_lossy(&output.stderr) + ); + assert_eq!(String::from_utf8_lossy(&output.stdout), "hello-worker\n"); + + let denied = run_capability(dir.path(), false); + assert_eq!(denied.status.code(), Some(1)); + let stderr = String::from_utf8_lossy(&denied.stderr); + assert!( + stderr.contains("permission.denied") || stderr.contains("fs.read"), + "{stderr}" + ); + assert!(!String::from_utf8_lossy(&denied.stdout).contains("hello-worker")); +} diff --git a/crates/marqdo-host/src/host.rs b/crates/marqdo-host/src/host.rs index 8ea6b09..16fbce2 100644 --- a/crates/marqdo-host/src/host.rs +++ b/crates/marqdo-host/src/host.rs @@ -284,9 +284,25 @@ impl StdHost { .map_err(map_plugin_error)?, ) } - PluginKind::Worker => PluginTransport::Worker( - WorkerPlugin::spawn(manifest, base_dir).map_err(map_plugin_error)?, - ), + PluginKind::Worker => { + let mut broker = CapabilityBroker::with_audit( + self.capabilities.clone(), + Arc::clone(&self.broker_audit), + ) + .with_fs(self.fs.clone()); + for capability in &self.vendor_capabilities { + broker.allow_vendor(capability.clone()); + } + let package = manifest.plugin.name.clone(); + let handler: marqdo_plugin_abi::CapabilityHandler = + Box::new(move |capability, request| { + broker.execute(&package, capability, request) + }); + PluginTransport::Worker( + WorkerPlugin::spawn(manifest, base_dir, Some(handler)) + .map_err(map_plugin_error)?, + ) + } PluginKind::Wasm => { return Err(RuntimeError::new( ErrorCategory::KernelUnavailable, diff --git a/crates/marqdo-host/src/plugin_worker.rs b/crates/marqdo-host/src/plugin_worker.rs index 940f40a..ca27c2e 100644 --- a/crates/marqdo-host/src/plugin_worker.rs +++ b/crates/marqdo-host/src/plugin_worker.rs @@ -13,7 +13,9 @@ use std::thread; use std::time::Duration; use marqdo_plugin_abi::worker::{read_frame, write_frame, WORKER_COMMAND}; -use marqdo_plugin_abi::{PluginError, PluginManifest, WireRequest, WireResponse}; +use marqdo_plugin_abi::{ + CapabilityHandler, PluginError, PluginManifest, WireRequest, WireResponse, +}; use serde_json::json; /// A native plugin running in an isolated worker process. @@ -23,6 +25,7 @@ pub struct WorkerPlugin { frames: Receiver>, exports: BTreeMap, dead: bool, + capability_handler: Option, } const HANDSHAKE_TIMEOUT: Duration = Duration::from_secs(30); @@ -39,7 +42,11 @@ impl std::fmt::Debug for WorkerPlugin { impl WorkerPlugin { /// Spawn a worker for `manifest` and wait for its ready frame. - pub fn spawn(manifest: &PluginManifest, base_dir: &Path) -> Result { + pub fn spawn( + manifest: &PluginManifest, + base_dir: &Path, + capability_handler: Option, + ) -> Result { // The worker receives an explicit serialized manifest, so it does not // depend on the manifest file being named `plugin.yaml`. let manifest_path = std::env::temp_dir().join(format!( @@ -185,6 +192,7 @@ impl WorkerPlugin { frames, exports, dead: false, + capability_handler, }) } @@ -205,42 +213,110 @@ impl WorkerPlugin { self.mark_dead(); return Err(error); } - let frame = match self.frames.recv_timeout(CALL_TIMEOUT) { - Ok(Ok(frame)) => frame, - Ok(Err(error)) => { - self.mark_dead(); - return Err(error); - } - Err(_) => { + let deadline = std::time::Instant::now() + CALL_TIMEOUT; + loop { + let remaining = deadline.saturating_duration_since(std::time::Instant::now()); + if remaining.is_zero() { self.mark_dead(); return Err(PluginError::invoke( "plugin.timeout", "plugin worker exceeded its invocation timeout", )); } - }; - match frame.get("kind").and_then(serde_json::Value::as_str) { - Some("response") => marqdo_plugin_abi::worker::response_from_frame(&frame), - Some("error") => Err(PluginError::invoke( - frame - .get("code") - .and_then(serde_json::Value::as_str) - .unwrap_or("plugin_call_failed"), - frame - .get("message") - .and_then(serde_json::Value::as_str) - .unwrap_or("worker reported an error"), - )), - _ => { - self.mark_dead(); - Err(PluginError::invoke( - "plugin.crashed", - "plugin worker closed or violated the frame protocol", - )) + let frame = match self.frames.recv_timeout(remaining) { + Ok(Ok(frame)) => frame, + Ok(Err(error)) => { + self.mark_dead(); + return Err(error); + } + Err(_) => { + self.mark_dead(); + return Err(PluginError::invoke( + "plugin.timeout", + "plugin worker exceeded its invocation timeout", + )); + } + }; + match frame.get("kind").and_then(serde_json::Value::as_str) { + Some("capability_request") => { + if let Err(error) = self.handle_capability_request(&frame) { + self.mark_dead(); + return Err(error); + } + } + Some("response") => { + return marqdo_plugin_abi::worker::response_from_frame(&frame); + } + Some("error") => { + return Err(PluginError::invoke( + frame + .get("code") + .and_then(serde_json::Value::as_str) + .unwrap_or("plugin_call_failed"), + frame + .get("message") + .and_then(serde_json::Value::as_str) + .unwrap_or("worker reported an error"), + )) + } + _ => { + self.mark_dead(); + return Err(PluginError::invoke( + "plugin.crashed", + "plugin worker closed or violated the frame protocol", + )); + } } } } + fn handle_capability_request(&mut self, frame: &serde_json::Value) -> Result<(), PluginError> { + let id = frame + .get("id") + .and_then(serde_json::Value::as_u64) + .ok_or_else(|| { + PluginError::wire("worker_frame_invalid", "capability request has no id") + })?; + let capability = frame + .get("capability") + .and_then(serde_json::Value::as_str) + .ok_or_else(|| { + PluginError::wire("worker_frame_invalid", "capability request has no name") + })?; + let request_value = frame.get("request").cloned().unwrap_or_else(|| json!({})); + let request_bytes = serde_json::to_vec(&request_value) + .map_err(|error| PluginError::wire("worker_encode_failed", error.to_string()))?; + let result = match &mut self.capability_handler { + Some(handler) => handler(capability, &request_bytes), + None => Err(PluginError::capability( + "capability.unavailable", + "this worker has no host capability bridge", + )), + }; + let reply = match result { + Ok(data) => match String::from_utf8(data) { + Ok(data) => json!({"kind":"capability_reply","id":id,"data":data}), + Err(_) => json!({ + "kind":"capability_error", + "id":id, + "code":"capability.reply_invalid", + "message":"capability reply is not UTF-8 text", + }), + }, + Err(error) => json!({ + "kind":"capability_error", + "id":id, + "code":error.code, + "message":error.message, + }), + }; + if let Err(error) = write_frame(&mut self.stdin, &reply) { + self.mark_dead(); + return Err(error); + } + Ok(()) + } + fn mark_dead(&mut self) { self.dead = true; let _ = self.child.kill(); diff --git a/crates/marqdo-host/tests/capability_broker.rs b/crates/marqdo-host/tests/capability_broker.rs new file mode 100644 index 0000000..72a5e42 --- /dev/null +++ b/crates/marqdo-host/tests/capability_broker.rs @@ -0,0 +1,162 @@ +//! End-to-end native plugin capability execution (H3-A). +#![cfg(unix)] + +use std::path::{Path, PathBuf}; +use std::process::Command; +use std::sync::atomic::{AtomicU32, Ordering}; + +use marqdo_host::{Capabilities, Host, HostOp, StdHost}; +use marqdo_plugin_abi::{sha256_file, HostTarget, PluginManifest}; +use marqdo_sandbox::SandboxMode; +use marqdo_value::{ErrorCategory, Value}; + +static COUNTER: AtomicU32 = AtomicU32::new(0); + +struct TempDir(PathBuf); + +impl TempDir { + fn new() -> Self { + let id = COUNTER.fetch_add(1, Ordering::Relaxed); + let path = std::env::temp_dir().join(format!( + "marqdo-host-capability-{}-{id}", + 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 repo_root() -> PathBuf { + Path::new(env!("CARGO_MANIFEST_DIR")) + .parent() + .unwrap() + .parent() + .unwrap() + .to_path_buf() +} + +fn have_cc() -> bool { + Command::new("cc") + .arg("--version") + .output() + .map(|output| output.status.success()) + .unwrap_or(false) +} + +fn build_plugin(dir: &Path) -> PathBuf { + let output = dir.join("capability.so"); + let status = Command::new("cc") + .args(["-std=c11", "-O2", "-shared", "-fPIC"]) + .arg("-I") + .arg(repo_root().join("include")) + .arg(repo_root().join("tests/abi/capability_plugin.c")) + .arg("-o") + .arg(&output) + .status() + .expect("spawn cc"); + assert!(status.success(), "cc failed"); + output +} + +fn write_manifest(dir: &Path, sha: &str) { + let yaml = format!( + r#"plugin: + name: demo.capability + version: 0.1.0 + abi: "^1.0" + kind: native + exports: + - name: capability.read + signature: "() -> Text" + requires: + - fs.read + artifacts: + - target: {} + file: capability.so + sha256: "{}" +"#, + HostTarget::current().triple(), + sha + ); + std::fs::write(dir.join("plugin.yaml"), yaml).unwrap(); +} + +#[test] +fn granted_fs_read_returns_real_bytes_and_denial_is_audited() { + if !have_cc() { + eprintln!("skipping: cc is unavailable"); + return; + } + let dir = TempDir::new(); + std::fs::create_dir_all(dir.path().join("data")).unwrap(); + std::fs::write(dir.path().join("data/allowed.txt"), "hello-from-project").unwrap(); + let artifact = build_plugin(dir.path()); + write_manifest(dir.path(), &sha256_file(&artifact).unwrap()); + let manifest = PluginManifest::load(&dir.path().join("plugin.yaml")).unwrap(); + + let capabilities = Capabilities::project() + .allow_plugin("demo.capability") + .allow_read("data/**"); + let mut host = StdHost::new(SandboxMode::Project, capabilities, dir.path()); + host.load_plugin(&manifest, dir.path(), true).unwrap(); + let ctx = host.context("root:default::test.mq.md", None); + let value = host + .invoke( + HostOp::PluginInvoke, + vec![ + Value::Text("capability.read".into()), + Value::Map(Default::default()), + ], + &ctx, + ) + .unwrap_or_else(|error| panic!("{error:?} audit={:?}", host.capability_audit())); + assert_eq!(value, Value::Text("hello-from-project".into())); + + let audit = host.capability_audit(); + assert!( + audit + .iter() + .any(|entry| entry.capability == "fs.read" && entry.decision == "granted"), + "{audit:?}" + ); + assert!( + !format!("{audit:?}").contains("hello-from-project"), + "audit must not record file contents" + ); + + // Same load, but no read grant: the broker must not return bytes. + let capabilities = Capabilities::project().allow_plugin("demo.capability"); + let mut denied_host = StdHost::new(SandboxMode::Project, capabilities, dir.path()); + denied_host + .load_plugin(&manifest, dir.path(), true) + .unwrap(); + let ctx = denied_host.context("root:default::test.mq.md", None); + let error = denied_host + .invoke( + HostOp::PluginInvoke, + vec![ + Value::Text("capability.read".into()), + Value::Map(Default::default()), + ], + &ctx, + ) + .unwrap_err(); + assert_eq!(error.category, ErrorCategory::PermissionDenied); + let audit = denied_host.capability_audit(); + assert!( + audit + .iter() + .any(|entry| entry.capability == "fs.read" && entry.decision == "denied"), + "{audit:?}" + ); +} diff --git a/crates/marqdo-plugin-abi/src/worker.rs b/crates/marqdo-plugin-abi/src/worker.rs index 9925aad..7e3082e 100644 --- a/crates/marqdo-plugin-abi/src/worker.rs +++ b/crates/marqdo-plugin-abi/src/worker.rs @@ -8,11 +8,13 @@ use std::io::{Read, Write}; use std::path::Path; +use std::sync::atomic::{AtomicU64, Ordering}; +use std::sync::{Arc, Mutex}; use serde_json::{json, Value}; use crate::error::PluginError; -use crate::loader::LoadedPlugin; +use crate::loader::{LoadOptions, LoadedPlugin}; use crate::manifest::{PluginKind, PluginManifest}; use crate::wire::{WireRequest, WireResponse}; @@ -117,7 +119,94 @@ pub fn serve(manifest_path: &Path, base_dir: &Path) -> i32 { // natively inside this child process. let mut native_manifest = manifest.clone(); native_manifest.plugin.kind = PluginKind::Native; - let mut plugin = match LoadedPlugin::open(&native_manifest, base_dir) { + + let stdin = Arc::new(Mutex::new(std::io::stdin())); + let stdout = Arc::new(Mutex::new(std::io::stdout())); + let next_request_id = Arc::new(AtomicU64::new(1)); + + let handler_stdin = Arc::clone(&stdin); + let handler_stdout = Arc::clone(&stdout); + let handler_ids = Arc::clone(&next_request_id); + let capability_handler: crate::loader::CapabilityHandler = + Box::new(move |capability, request| { + let id = handler_ids.fetch_add(1, Ordering::SeqCst); + let request_value: Value = serde_json::from_slice(request).map_err(|error| { + PluginError::capability( + "capability.request_invalid", + format!("capability request is not valid JSON: {error}"), + ) + })?; + { + let mut out = handler_stdout.lock().map_err(|_| { + PluginError::invoke("plugin.crashed", "worker stdout lock is poisoned") + })?; + write_frame( + &mut *out, + &json!({ + "kind": "capability_request", + "id": id, + "capability": capability, + "request": request_value, + }), + )?; + } + { + let frame = { + let mut input = handler_stdin.lock().map_err(|_| { + PluginError::invoke("plugin.crashed", "worker stdin lock is poisoned") + })?; + read_frame(&mut *input).map_err(|error| { + PluginError::invoke( + error.code.as_str(), + format!("worker capability reply failed: {}", error.message), + ) + })? + }; + let Some(frame) = frame else { + return Err(PluginError::invoke( + "plugin.crashed", + "host closed the worker during a capability request", + )); + }; + if frame.get("id").and_then(Value::as_u64) != Some(id) { + return Err(PluginError::wire( + "worker_frame_invalid", + "capability reply id does not match the request", + )); + } + match frame.get("kind").and_then(Value::as_str) { + Some("capability_reply") => { + let data = frame.get("data").and_then(Value::as_str).ok_or_else(|| { + PluginError::wire( + "worker_frame_invalid", + "capability reply has no text data", + ) + })?; + Ok(data.as_bytes().to_vec()) + } + Some("capability_error") => Err(PluginError::capability( + frame + .get("code") + .and_then(Value::as_str) + .unwrap_or("capability.unavailable"), + frame + .get("message") + .and_then(Value::as_str) + .unwrap_or("capability request failed") + .to_string(), + )), + _ => Err(PluginError::wire( + "worker_frame_invalid", + "expected a capability reply frame", + )), + } + } + }); + let options = LoadOptions { + host_target: crate::artifact::HostTarget::current(), + capability_handler: Some(capability_handler), + }; + let mut plugin = match LoadedPlugin::open_with(&native_manifest, base_dir, options) { Ok(plugin) => plugin, Err(error) => { eprintln!("worker: {}: {}", error.code, error.message); @@ -128,14 +217,11 @@ pub fn serve(manifest_path: &Path, base_dir: &Path) -> i32 { .exports() .map(|export| json!({"name": export.name(), "signature": export.signature()})) .collect(); - let mut stdin = std::io::stdin(); - let mut stdout = std::io::stdout(); - if let Err(error) = write_frame(&mut stdout, &json!({"kind": "ready", "exports": exports})) { - eprintln!("worker: {}: {}", error.code, error.message); + if send_frame(&stdout, &json!({"kind": "ready", "exports": exports})).is_err() { return 1; } loop { - let frame = match read_frame(&mut stdin) { + let frame = match receive_frame(&stdin) { Ok(Some(frame)) => frame, Ok(None) => return 0, Err(error) => { @@ -147,8 +233,8 @@ pub fn serve(manifest_path: &Path, base_dir: &Path) -> i32 { Some("shutdown") => return 0, Some("invoke") => { let Some(request_value) = frame.get("request") else { - let _ = write_frame( - &mut stdout, + let _ = send_frame( + &stdout, &json!({"kind":"error","code":"worker_request_invalid","message":"missing request"}), ); continue; @@ -156,8 +242,8 @@ pub fn serve(manifest_path: &Path, base_dir: &Path) -> i32 { let request_bytes = match serde_json::to_vec(request_value) { Ok(bytes) => bytes, Err(error) => { - let _ = write_frame( - &mut stdout, + let _ = send_frame( + &stdout, &json!({"kind":"error","code":"worker_request_invalid","message":error.to_string()}), ); continue; @@ -166,8 +252,8 @@ pub fn serve(manifest_path: &Path, base_dir: &Path) -> i32 { let request = match WireRequest::from_json_bytes(&request_bytes) { Ok(request) => request, Err(error) => { - let _ = write_frame( - &mut stdout, + let _ = send_frame( + &stdout, &json!({"kind":"error","code":error.code,"message":error.message}), ); continue; @@ -180,13 +266,13 @@ pub fn serve(manifest_path: &Path, base_dir: &Path) -> i32 { .ok() .and_then(|bytes| serde_json::from_slice::(&bytes).ok()) .unwrap_or_else(|| json!({"wire_version":1,"kind":"response"})); - if write_frame(&mut stdout, &json!({"kind":"response","response":body})).is_err() { + if send_frame(&stdout, &json!({"kind":"response","response":body})).is_err() { return 1; } } Err(error) => { - if write_frame( - &mut stdout, + if send_frame( + &stdout, &json!({"kind":"error","code":error.code,"message":error.message,"error_kind":error.kind.as_str()}), ) .is_err() @@ -197,8 +283,8 @@ pub fn serve(manifest_path: &Path, base_dir: &Path) -> i32 { } } _ => { - if write_frame( - &mut stdout, + if send_frame( + &stdout, &json!({"kind":"error","code":"worker_frame_invalid","message":"unknown frame kind"}), ) .is_err() @@ -210,7 +296,20 @@ pub fn serve(manifest_path: &Path, base_dir: &Path) -> i32 { } } -/// Build a successful response from an embedded wire response value. +fn send_frame(stdout: &Arc>, value: &Value) -> Result<(), PluginError> { + let mut out = stdout + .lock() + .map_err(|_| PluginError::invoke("plugin.crashed", "worker stdout lock is poisoned"))?; + write_frame(&mut *out, value) +} + +fn receive_frame(stdin: &Arc>) -> Result, PluginError> { + let mut input = stdin + .lock() + .map_err(|_| PluginError::invoke("plugin.crashed", "worker stdin lock is poisoned"))?; + read_frame(&mut *input) +} + pub fn response_from_frame(frame: &Value) -> Result { let body = frame .get("response") diff --git a/docs/STATUS.md b/docs/STATUS.md index fdb6ddc..291f412 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -203,13 +203,15 @@ Foreign provider integrity and environment metadata: * The environment fields are metadata only. uv/npm environment materialization, environment-directory hashing and lock-v3 integration are **not** implemented. -* H3-A is **partially implemented**: the native plugin broker now executes a - granted `fs.read` through `ProjectFs` and returns real bytes, with audit; - unsupported capabilities return `capability.unavailable` rather than empty - success. H3-A remains open for the worker capability bridge, live session - identity in the ABI callback and broader service operations. H3-B (OS - isolation) remains open; Worker capability requests are still denied and - `strict` is refused on every platform. No G-C claim is made. +* H3-A is **implemented for `fs.read`**: both native and worker plugins can + request a granted `fs.read` through the broker; it executes via `ProjectFs`, + returns real bytes, and records an audit decision. Unsupported capabilities + return `capability.unavailable` rather than empty success. Worker + request/reply frames are request-scoped and carry no trusted identity + (ADR-0018). +* H3-A remains open for live ABI session identity, resource budgets per + capability call, and broader executing services. H3-B (OS isolation) remains + open; `strict` is refused on every platform and no G-C claim is made. ### M0.6 implementation progress @@ -223,7 +225,7 @@ Foreign provider integrity and environment metadata: | 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) | | S4-A/B-13 B-14 quality gates | **Partial** | real schema instance validation + negative mutations in CI; Windows/macOS runtime tests for core/Analysis/Trace and strict refusal. Tool/C-ABI/worker runtime evidence remains Unix-only (see §S4-A) | | S5-A/B-12 foreign integrity | **Done for metadata/integrity** | provider digest verified at registration and before spawn; environment descriptor fields; full uv/npm materialization and H3-A/B remain open (see §S5-A/B-12) | -| S5-B/H3-A broker execution | **Partial** | native `fs.read` executes through `ProjectFs` with audit; unsupported capabilities fail unavailable. Worker bridge/session identity/H3-B OS isolation remain open and are not claimed | +| S5-B/H3-A broker execution | **Done for fs.read (native+worker)** | registered plugin capability requests execute `fs.read` through `ProjectFs` with audit; unsupported capabilities fail unavailable. Session identity breadth and H3-B OS isolation remain open and are not claimed (ADR-0018) | | 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 | diff --git a/docs/adr/0011-capability-broker.md b/docs/adr/0011-capability-broker.md index 94ca3d1..532ac6c 100644 --- a/docs/adr/0011-capability-broker.md +++ b/docs/adr/0011-capability-broker.md @@ -1,6 +1,6 @@ # ADR-0011: Capability broker and vendor-namespaced requests -Status: **Accepted** +Status: **Accepted** (extended by ADR-0018 for worker capability frames) Date: 2026-11-20 ## Context diff --git a/docs/adr/0018-worker-capability-bridge.md b/docs/adr/0018-worker-capability-bridge.md new file mode 100644 index 0000000..c949e92 --- /dev/null +++ b/docs/adr/0018-worker-capability-bridge.md @@ -0,0 +1,90 @@ +# ADR-0018: Worker capability bridge frames + +Status: **Accepted** +Date: 2026-11-20 +Extends: ADR-0011 (capability broker) and `spec/plugin-abi.md` §9.1 + +## Context + +The isolated worker transport initially supported only `ready`, `invoke`, +`shutdown` and `error` frames. The plugin loader's capability handler ran in +the host process for native plugins, but a worker was started with +`LoadOptions::default()`, so every worker capability request failed even when +the user had granted it. That made the broker's execution path unreachable for +the only transport designed to contain crashes. + +The worker frame set is a versioned transport contract. Adding frames is an +explicit protocol extension, not an implementation detail. + +## Decision + +### 1. Runtime-only capability request/reply frames + +While a worker is executing one `invoke`, it may send: + +```json +{"kind":"capability_request","id":7,"capability":"fs.read", + "request":{"path":"data/allowed.txt"}} +``` + +The host replies with exactly one frame carrying the same `id`: + +```json +{"kind":"capability_reply","id":7,"data":"file contents"} +``` + +or: + +```json +{"kind":"capability_error","id":7,"code":"permission.denied", + "message":"read access ... was not granted"} +``` + +Rules: + +* Requests carry **no trusted identity**. The host binds the package and + session from the worker it spawned; frame fields are untrusted data. +* `request` must be a JSON value; the host serializes it back to the request + bytes used by the broker. Non-JSON requests are rejected. +* Replies are text; `capability_reply.data` is returned to the plugin as raw + UTF-8 bytes. Non-UTF-8 replies become `capability_error`. +* A reply with an unknown/mismatched `id`, or a different kind, is a protocol + error. No other frames are accepted while waiting for a capability reply. +* Capability handling does not extend the invocation timeout: the host keeps a + single deadline for the whole `invoke`, including capability round-trips. +* Only the broker's executing capabilities are reachable. In this build that + means `fs.read`; everything else returns `capability.unavailable`. +* The frames do not change the C ABI or `MqHostApi`. They are an internal IPC + protocol between the host and its own worker binary. + +### 2. Worker and host implementation + +The worker routes its capability handler through the same stdin/stdout frame +channel. During plugin invocation the outer frame loop is not reading, so the +handler may synchronously send a request and wait for the reply. Reads/writes +are guarded by mutexes; clean EOF or a partial frame remains a protocol error. + +The host's `WorkerPlugin` owns an optional capability handler (the broker with +the project filesystem). It serves capability frames inside the existing invoke +deadline, writes replies, and marks/kills the worker on any transport failure +so a stale stdin is never reused. + +## Consequences + +* The worker capability bridge is no longer a stub; granted `fs.read` works in + both native and worker transports. +* Request/reply identity is bound to the spawn, not to plugin-supplied text. +* Worker capability requests still run as the user process. This is cooperative + authorization, **not** an OS sandbox; H3-B strict isolation remains required + for any untrusted-code claim. +* The frame set change requires this ADR and an updated plugin-abi spec. Frame + kinds are additive for future ABI minors; unknown frames fail closed. + +## Tests + +* `worker_capability_bridge_reads_granted_file_and_denies_without_grant` + drives a real `.mq.md` program through a C worker plugin: granted + `fs.read` returns the file contents; without the grant the run fails with a + permission error and no contents. +* Host unit tests cover granted/denied `fs.read` and `capability.unavailable` + for unsupported capabilities. diff --git a/spec/plugin-abi.md b/spec/plugin-abi.md index 2e13d83..b47994b 100644 --- a/spec/plugin-abi.md +++ b/spec/plugin-abi.md @@ -374,6 +374,24 @@ Worker → host responses are `{"kind":"response","response":}` o `{"kind":"error","code":...,"message":...}`. The worker validates that the declared manifest exports exactly match the library's registrations. +While an invoke is in flight, the worker may also request host capabilities +(ADR-0018): + +```text +worker → host {"kind":"capability_request","id":7,"capability":"fs.read", + "request":{"path":"data/allowed.txt"}} +host → worker {"kind":"capability_reply","id":7,"data":""} +host → worker {"kind":"capability_error","id":7,"code":"permission.denied", + "message":"..."} +``` + +The id must match and is request-scoped; requests carry no trusted identity +(the host binds package/session from the spawned worker). Non-JSON requests, +unknown/mismatched ids, non-text replies and other frame kinds are protocol +errors. The invoke deadline covers the whole exchange. In this build only +granted `fs.read` executes; other capabilities return `capability.unavailable`. +These frames do not change the C ABI. + ## 10. SDK usage (`crates/marqdo-plugin-sdk`) The SDK hides the raw C layout and exports the entry symbol with diff --git a/spec/security.md b/spec/security.md index d0bb469..a79ab85 100644 --- a/spec/security.md +++ b/spec/security.md @@ -276,11 +276,12 @@ Neither command executes project code. Specifically: 3. Network capability exists in the model but no host operation uses it; there is no `--allow-net` flag. 4. Write-path symlink TOCTOU (see §2.1). -5. Plugin **worker crash isolation** is implemented, but the worker capability - bridge is not: worker capability requests are still denied. Only trusted - in-process native plugins can use the broker's `fs.read` execution. No - vendor-executing handler is shipped, and broker execution is a cooperative - API contract, not an OS sandbox. +5. Plugin **worker crash isolation** and the worker capability bridge are + implemented: both native and worker plugins can reach the broker's + `fs.read` execution when granted. Other core capabilities and vendor + handlers remain unavailable. Broker execution is a cooperative API + contract, not an OS sandbox; a worker and a native plugin can still issue + direct syscalls. 6. `plugin_handle` wire values are structurally reconstructable, but host authority comes only from the `PluginHandleTable` owner/run/generation check; untrusted plugin/foreign output containing a handle is rejected diff --git a/tests/abi/capability_plugin.c b/tests/abi/capability_plugin.c new file mode 100644 index 0000000..6091c80 --- /dev/null +++ b/tests/abi/capability_plugin.c @@ -0,0 +1,99 @@ +/* + * Test-only plugin: requests `fs.read` through the host capability broker. + * + * The plugin deliberately has no JSON parser of its own: it sends a fixed + * request for `data/allowed.txt` and returns the broker's reply as a Text + * value. This exercises the real ABI -> loader -> host broker -> ProjectFs + * path, not a Rust unit shim. + */ +#include "marqdo_plugin_abi_v1.h" + +#include +#include +#include + +static const MqHostApi *g_host = NULL; + +static const char PLUGIN_METADATA[] = + "{\"name\":\"demo.capability\",\"version\":\"0.1.0\"}"; + +static const char *PATH_REQUEST = "{\"path\":\"data/allowed.txt\"}"; + +static int32_t emit(const char *json, size_t len, MqOwnedBytes *out) { + uint8_t *buffer = (uint8_t *)g_host->alloc(g_host->host_data, len); + if (buffer == NULL) { + return MQ_ERR_OUT_OF_MEMORY; + } + memcpy(buffer, json, len); + out->data = buffer; + out->len = len; + return MQ_OK; +} + +static int32_t capability_read(MqCallContext *ctx, MqBytes args_wire, + MqOwnedBytes *result_wire, + MqOwnedBytes *error_wire) { + MqBytes name; + MqBytes request; + MqOwnedBytes reply = {NULL, 0}; + char response[512]; + int written; + int32_t code; + + (void)args_wire; + if (result_wire == NULL || error_wire == NULL) { + return MQ_ERR_INVALID_ARGUMENT; + } + *result_wire = (MqOwnedBytes){NULL, 0}; + *error_wire = (MqOwnedBytes){NULL, 0}; + + name.data = (const uint8_t *)"fs.read"; + name.len = sizeof("fs.read") - 1; + request.data = (const uint8_t *)PATH_REQUEST; + request.len = strlen(PATH_REQUEST); + code = g_host->request_capability(ctx, name, request, &reply); + if (code != MQ_OK) { + static const char ERROR_JSON[] = + "{\"wire_version\":1,\"kind\":\"response\",\"error\":" + "{\"kind\":\"capability\",\"code\":\"permission.denied\"," + "\"message\":\"fs.read was denied\"}}"; + return emit(ERROR_JSON, sizeof(ERROR_JSON) - 1, error_wire) == MQ_OK + ? code + : MQ_ERR_OUT_OF_MEMORY; + } + + written = snprintf( + response, sizeof(response), + "{\"wire_version\":1,\"kind\":\"response\",\"value\":" + "{\"type\":\"text\",\"value\":\"%.*s\"}}", + (int)reply.len, (const char *)reply.data); + if (reply.data != NULL) { + g_host->free(g_host->host_data, reply.data); + } + if (written < 0 || (size_t)written >= sizeof(response)) { + return MQ_ERR_INTERNAL; + } + return emit(response, (size_t)written, result_wire); +} + +int32_t mq_plugin_entry_v1(const MqHostApi *host, MqPluginApi *plugin) { + MqBytes export_name = {(const uint8_t *)"capability.read", + sizeof("capability.read") - 1}; + MqBytes signature = { + (const uint8_t *)"{\"signature\":\"() -> Text\"}", + sizeof("{\"signature\":\"() -> Text\"}") - 1}; + + if (host == NULL || plugin == NULL || host->register_function == NULL || + host->request_capability == NULL || host->alloc == NULL || + host->free == NULL || host->abi_major != MQ_ABI_MAJOR) { + return MQ_ERR_ABI_MISMATCH; + } + g_host = host; + plugin->struct_size = (uint32_t)sizeof(MqPluginApi); + plugin->abi_major = MQ_ABI_MAJOR; + plugin->abi_minor = MQ_ABI_MINOR; + plugin->plugin_metadata_wire.data = (const uint8_t *)PLUGIN_METADATA; + plugin->plugin_metadata_wire.len = sizeof(PLUGIN_METADATA) - 1; + return host->register_function(host->host_data, export_name, signature, + capability_read); +}