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
This commit is contained in:
1 parent
47a2e1883f
commit
0f01a69048
11 files changed
+720
-64
No files matched your search
@@ -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"));
|
||||
}
|
||||
@@ -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,
|
||||
|
||||
@@ -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<Result<serde_json::Value, PluginError>>,
|
||||
exports: BTreeMap<String, String>,
|
||||
dead: bool,
|
||||
capability_handler: Option<CapabilityHandler>,
|
||||
}
|
||||
|
||||
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<Self, PluginError> {
|
||||
pub fn spawn(
|
||||
manifest: &PluginManifest,
|
||||
base_dir: &Path,
|
||||
capability_handler: Option<CapabilityHandler>,
|
||||
) -> Result<Self, PluginError> {
|
||||
// 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();
|
||||
|
||||
@@ -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:?}"
|
||||
);
|
||||
}
|
||||
@@ -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::<Value>(&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<Mutex<std::io::Stdout>>, 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<Mutex<std::io::Stdin>>) -> Result<Option<Value>, 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<WireResponse, PluginError> {
|
||||
let body = frame
|
||||
.get("response")
|
||||
|
||||
+10
-8
@@ -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 |
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
@@ -374,6 +374,24 @@ Worker → host responses are `{"kind":"response","response":<wire 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":"<utf-8 text>"}
|
||||
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
|
||||
|
||||
+6
-5
@@ -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
|
||||
|
||||
@@ -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 <stdio.h>
|
||||
#include <stdlib.h>
|
||||
#include <string.h>
|
||||
|
||||
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);
|
||||
}
|
||||
Reference in new issue
Block a user