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:
cflmy committed 2026-11-20 13:08:56 +08:00
1 parent 47a2e1883f
commit 0f01a69048
11 files changed
+720 -64

No files matched your search

+93
View File
@@ -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"));
}
+19 -3
View File
@@ -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,
+104 -28
View File
@@ -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:?}"
);
}
+118 -19
View File
@@ -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
View File
@@ -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 -1
View File
@@ -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
+90
View File
@@ -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.
+18
View File
@@ -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
View File
@@ -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
+99
View File
@@ -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);
}