feat(m0.6-r2): complete-name plugin exports and capability broker

- register every plugin export by its complete dotted name; reject conflicting
  loads atomically instead of overwriting the first namespace
- route plugin calls by full export name and expose loaded descriptors to the
  runtime
- add CapabilityBroker for core grants and vendor policy, with audit records
- accept syntactically valid vendor capability requests in manifests while
  still denying them until a trusted policy exists
- add check --plugin static signature validation without dlopen
- test multi-export C plugin routing, conflict rollback, broker decisions and
  static arity rejection
This commit is contained in:
cflmy committed 2026-11-20 11:42:33 +08:00
1 parent 21c1e50617
commit d940013f35
13 files changed
+826 -94

No files matched your search

+174 -3
View File
@@ -145,12 +145,140 @@ fn load_project(file: Option<&Path>, json: bool) -> Result<LoadedProject, i32> {
}
}
/// Add plugin export descriptors from manifests without loading a library.
fn add_static_plugin_descriptors(
project: &mut LoadedProject,
paths: &[PathBuf],
) -> Result<(), String> {
for path in paths {
let manifest_path = if path.is_dir() {
path.join("plugin.yaml")
} else {
path.clone()
};
let manifest = marqdo_plugin_abi::PluginManifest::load(&manifest_path)
.map_err(|error| format!("{}: {}", error.code, error.message))?;
manifest
.validate()
.map_err(|error| format!("{}: {}", error.code, error.message))?;
let digest = manifest
.resolve_artifact(&marqdo_plugin_abi::HostTarget::current())
.map_err(|error| format!("{}: {}", error.code, error.message))?
.sha256
.clone();
for export in &manifest.plugin.exports {
if project
.program
.external_callables
.iter()
.any(|callable| callable.public_name == export.name)
{
return Err(format!(
"plugin export `{}` is declared more than once",
export.name
));
}
let signature = plugin_signature(&export.signature).map_err(|error| {
format!(
"plugin export `{}` has an invalid signature: {error}",
export.name
)
})?;
project
.program
.external_callables
.push(marqdo_ir::callable::CallableDescriptor {
id: marqdo_ir::callable::CallableId(format!(
"plugin:{}:{}",
manifest.plugin.name, export.name
)),
public_name: export.name.clone(),
owner_package: manifest.plugin.name.clone(),
signature,
effects_requested: manifest.plugin.requires.clone(),
origin: marqdo_ir::callable::CallableOrigin::AbiPlugin {
package: manifest.plugin.name.clone(),
export: export.name.clone(),
},
implementation_digest: Some(digest.clone()),
source_span: None,
});
}
}
if paths.is_empty() {
return Ok(());
}
let existing: Vec<(Option<marqdo_span::Span>, String)> = project
.diagnostics
.iter()
.map(|file| {
(
file.diagnostic.span,
format!("{}:{}", file.module_id, file.diagnostic.message),
)
})
.collect();
for (module_id, diagnostic) in marqdo_frontend::calls::validate_program(&project.program) {
let key = format!("{}:{}", module_id, diagnostic.message);
if existing.contains(&(diagnostic.span, key)) {
continue;
}
if let Some(file) = project.files.get(&module_id) {
project.diagnostics.push(FileDiagnostic {
module_id,
path: file.path.clone(),
source: file.source.clone(),
diagnostic,
});
}
}
Ok(())
}
/// Convert a plugin manifest signature (`($a: Int) -> Int`) to the language
/// parameter list, dropping the display-only return annotation and `$` sigils.
fn plugin_signature(raw: &str) -> Result<marqdo_ir::callable::CallableSignature, String> {
let before_return = raw.split("->").next().unwrap_or(raw).trim();
let open = before_return
.find('(')
.ok_or_else(|| "missing `(`".to_string())?;
let close = before_return
.rfind(')')
.ok_or_else(|| "missing `)`".to_string())?;
if close < open {
return Err("malformed parameter list".to_string());
}
let params = before_return[open + 1..close].replace('$', "");
let parsed =
marqdo_frontend::signature::parse(&format!("({params})"), marqdo_span::Span::default());
if parsed.has_errors() {
return Err(parsed
.diagnostics
.iter()
.map(|diagnostic| diagnostic.message.clone())
.collect::<Vec<_>>()
.join("; "));
}
Ok(marqdo_ir::callable::CallableSignature {
params: parsed.params,
kind: marqdo_ir::SignatureKind::Explicit,
})
}
/// `marqdo check`.
pub fn check(file: Option<&Path>, json: bool, refs: bool) -> i32 {
pub fn check(file: Option<&Path>, json: bool, refs: bool, plugins: &[PathBuf]) -> i32 {
let mut project = match load_project(file, json) {
Ok(project) => project,
Err(code) => return code,
};
if let Err(error) = add_static_plugin_descriptors(&mut project, plugins) {
if json {
output::print_json(&json!({"success": false, "error": error}));
} else {
eprintln!("error: {error}");
}
return 2;
}
if refs {
let ref_diagnostics = validate_refs(&project);
project.diagnostics.extend(ref_diagnostics);
@@ -481,10 +609,18 @@ pub fn execute(
trace: bool,
) -> i32 {
let command_name = if function.is_some() { "call" } else { "run" };
let project = match load_project(file, json) {
let mut project = match load_project(file, json) {
Ok(project) => project,
Err(code) => return code,
};
if let Err(error) = add_static_plugin_descriptors(&mut project, &settings.plugins) {
if json {
output::print_json(&json!({"success": false, "error": error}));
} else {
eprintln!("error: {error}");
}
return 2;
}
if project.has_errors() {
if json {
output::print_json(&json!({
@@ -558,6 +694,37 @@ pub fn execute(
return 1;
}
}
// Expose the complete export names loaded from trusted manifests so the
// runtime resolves exactly those names instead of probing namespaces.
for (name, _signature, digest, package) in host.plugin_exports() {
if project
.program
.external_callables
.iter()
.any(|callable| callable.public_name == name)
{
continue;
}
project
.program
.external_callables
.push(marqdo_ir::callable::CallableDescriptor {
id: marqdo_ir::callable::CallableId(format!("plugin:{package}:{name}")),
public_name: name.clone(),
owner_package: package.clone(),
signature: marqdo_ir::callable::CallableSignature {
params: Vec::new(),
kind: marqdo_ir::SignatureKind::Explicit,
},
effects_requested: vec!["host".to_string()],
origin: marqdo_ir::callable::CallableOrigin::AbiPlugin {
package,
export: name,
},
implementation_digest: Some(digest),
source_span: None,
});
}
let function_name = function.unwrap_or("main").to_string();
let entry_module = &project.program.modules[&project.entry];
if entry_module.function(&function_name).is_none() {
@@ -628,7 +795,11 @@ pub fn execute(
}
}
fn load_plugin_into_host(host: &mut StdHost, path: &Path, trusted: bool) -> Result<String, String> {
fn load_plugin_into_host(
host: &mut StdHost,
path: &Path,
trusted: bool,
) -> Result<Vec<String>, String> {
let manifest_path = if path.is_dir() {
path.join("plugin.yaml")
} else {
+6 -1
View File
@@ -152,6 +152,9 @@ struct CheckArgs {
/// Also validate Markdown reference/link targets (`check --refs`).
#[arg(long)]
refs: bool,
/// Declare a plugin manifest for static export-signature checking.
#[arg(long = "plugin", value_name = "PATH")]
plugin: Vec<PathBuf>,
/// Machine readable JSON output.
#[arg(long)]
json: bool,
@@ -262,7 +265,9 @@ fn main() {
let cli = Cli::parse();
let code = match cli.command {
Command::Init(args) => commands::init(args.dir.as_deref()),
Command::Check(args) => commands::check(args.file.as_deref(), args.json, args.refs),
Command::Check(args) => {
commands::check(args.file.as_deref(), args.json, args.refs, &args.plugin)
}
Command::Inspect(args) => {
let flags = commands::InspectFlags {
ast: args.ast,
+4 -3
View File
@@ -664,8 +664,8 @@ fn plugin_inspect_and_explicit_trusted_invocation() {
assert_exit(&unknown, 1, "unknown plugin namespace");
assert!(stderr_text(&unknown).contains("symbol.unknown"));
// The export signature requires both named arguments: a missing argument
// becomes a structured plugin failure, never a panic.
// The export signature requires both named arguments: with a declared
// plugin manifest this is rejected statically, before any library load.
dir.write("args.mq.md", "## main\n\n**结果 = solver.add(a=1)**\n");
let bad_args = cli(
dir.path(),
@@ -680,5 +680,6 @@ fn plugin_inspect_and_explicit_trusted_invocation() {
],
);
assert_exit(&bad_args, 1, "plugin argument failure");
assert!(stderr_text(&bad_args).contains("plugin.failure"));
assert!(stderr_text(&bad_args).contains("call.arity"));
assert!(stderr_text(&bad_args).contains("missing required argument `b`"));
}
+1 -2
View File
@@ -3,8 +3,7 @@
use std::time::Duration;
use marqdo_foreign::{
call, call_with_registry, ForeignError, KernelDescriptor, KernelRegistry, RunRequest,
RunStatus,
call, call_with_registry, ForeignError, KernelDescriptor, KernelRegistry, RunRequest, RunStatus,
};
use marqdo_value::Value;
+231
View File
@@ -5,10 +5,214 @@
//! with what the operator/CLI explicitly granted. Every host operation checks
//! against this set at the point of execution.
use std::collections::BTreeSet;
use std::sync::{Arc, Mutex};
use glob::Pattern;
use marqdo_plugin_abi::PluginError;
use marqdo_span::Span;
use marqdo_value::{ErrorCategory, RuntimeError};
/// One audited capability request from a plugin.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CapabilityAudit {
/// Plugin package that asked.
pub package: String,
/// Capability name.
pub capability: String,
/// `granted`, `denied` or `unavailable`.
pub decision: &'static str,
/// Human-readable reason.
pub reason: String,
}
/// Broker for plugin host-capability requests (ADR-0011).
///
/// Core capabilities are checked against the effective grant set. Vendor
/// capabilities are accepted only when a trusted host policy registered the
/// exact name; a declaration in a manifest is never enough.
#[derive(Debug, Clone)]
pub struct CapabilityBroker {
capabilities: Capabilities,
vendor_policy: BTreeSet<String>,
audit: Arc<Mutex<Vec<CapabilityAudit>>>,
}
impl CapabilityBroker {
/// Construct a broker over an effective grant set.
pub fn new(capabilities: Capabilities) -> Self {
Self::with_audit(capabilities, Arc::new(Mutex::new(Vec::new())))
}
/// Construct a broker sharing an existing audit log.
pub fn with_audit(capabilities: Capabilities, audit: Arc<Mutex<Vec<CapabilityAudit>>>) -> Self {
Self {
capabilities,
vendor_policy: BTreeSet::new(),
audit,
}
}
/// Register a trusted vendor capability policy entry.
pub fn allow_vendor(&mut self, capability: impl Into<String>) {
self.vendor_policy.insert(capability.into());
}
/// Shared audit log.
pub fn audit(&self) -> Arc<Mutex<Vec<CapabilityAudit>>> {
Arc::clone(&self.audit)
}
/// Authorize one request, returning reply bytes on success.
pub fn authorize(
&mut self,
package: &str,
capability: &str,
request: &[u8],
) -> Result<Vec<u8>, PluginError> {
let result = self.decide(package, capability, request);
let (decision, reason) = match &result {
Ok(()) => ("granted", String::new()),
Err(error) => ("denied", format!("{}: {}", error.code, error.message)),
};
if let Ok(mut audit) = self.audit.lock() {
audit.push(CapabilityAudit {
package: package.to_string(),
capability: capability.to_string(),
decision,
reason,
});
}
result.map(|()| Vec::new())
}
fn decide(&self, package: &str, capability: &str, request: &[u8]) -> Result<(), PluginError> {
match capability {
"console" => self
.capabilities
.console
.then_some(())
.ok_or_else(|| plugin_denied("console capability was not granted")),
"math.compute" => self
.capabilities
.math
.then_some(())
.ok_or_else(|| plugin_denied("math capability was not granted")),
"log" | "clock" | "random" | "artifact.record" => Ok(()),
"fs.read" | "fs.write" => {
let path = request_path(request)?;
if capability == "fs.read" {
self.capabilities
.check_read(&path, None)
.map_err(map_runtime)
} else {
self.capabilities
.check_write(&path, None)
.map_err(map_runtime)
}
}
"net.request" => {
let host = request_host(request)?;
self.capabilities
.check_net(&host, None)
.map_err(map_runtime)
}
"process" => self
.capabilities
.process
.then_some(())
.ok_or_else(|| plugin_denied("process capability was not granted")),
other => {
if is_vendor_capability(other)
&& (self.vendor_policy.contains(other) || self.vendor_policy.contains("*"))
{
Ok(())
} else if is_vendor_capability(other) {
Err(PluginError::capability(
"capability.unavailable",
format!(
"vendor capability `{other}` has no trusted handler for package `{package}`"
),
))
} else {
Err(PluginError::capability(
"capability.unknown",
format!("unknown core capability `{other}`"),
))
}
}
}
}
}
fn plugin_denied(message: &str) -> PluginError {
PluginError::capability("permission.denied", message.to_string())
}
fn map_runtime(error: RuntimeError) -> PluginError {
PluginError::capability(error.code(), error.message)
}
fn request_json(request: &[u8]) -> Result<serde_json::Value, PluginError> {
if request.is_empty() {
return Ok(serde_json::Value::Null);
}
serde_json::from_slice(request).map_err(|error| {
PluginError::capability(
"capability.request_invalid",
format!("capability request is not valid JSON: {error}"),
)
})
}
fn request_path(request: &[u8]) -> Result<String, PluginError> {
let value = request_json(request)?;
value
.get("path")
.and_then(|path| path.as_str())
.map(str::to_string)
.ok_or_else(|| {
PluginError::capability(
"capability.request_invalid",
"fs capability requests must include a `path` string",
)
})
}
fn request_host(request: &[u8]) -> Result<String, PluginError> {
let value = request_json(request)?;
value
.get("host")
.and_then(|host| host.as_str())
.map(str::to_string)
.ok_or_else(|| {
PluginError::capability(
"capability.request_invalid",
"net capability requests must include a `host` string",
)
})
}
/// Whether `name` is a syntactically valid vendor-namespaced capability.
pub fn is_vendor_capability(name: &str) -> bool {
let segments: Vec<&str> = name.split('.').collect();
if segments.len() < 3 {
return false;
}
if matches!(
segments[0],
"console" | "math" | "fs" | "net" | "process" | "log" | "clock" | "random"
) {
return false;
}
segments.iter().all(|segment| {
!segment.is_empty()
&& segment.bytes().enumerate().all(|(index, byte)| {
byte.is_ascii_lowercase() || byte.is_ascii_digit() || (byte == b'-' && index > 0)
})
})
}
/// Effective capability grants for one run.
#[derive(Debug, Clone, Default)]
pub struct Capabilities {
@@ -182,6 +386,33 @@ mod tests {
assert!(capabilities.check_foreign(None).is_err());
}
#[test]
fn broker_enforces_core_grants_and_vendor_policy() {
let mut broker = CapabilityBroker::new(Capabilities::project().allow_read("data/**"));
assert!(broker
.authorize("demo.solver", "fs.read", br#"{"path":"data/a.csv"}"#)
.is_ok());
let denied = broker
.authorize("demo.solver", "fs.read", br#"{"path":"secrets/key"}"#)
.unwrap_err();
assert_eq!(denied.code, "permission.denied");
assert!(broker.authorize("demo.solver", "fs.read", b"{}").is_err());
let unavailable = broker
.authorize("demo.solver", "vendor.device.read", b"{}")
.unwrap_err();
assert_eq!(unavailable.code, "capability.unavailable");
broker.allow_vendor("vendor.device.read");
assert!(broker
.authorize("demo.solver", "vendor.device.read", b"{}")
.is_ok());
assert!(!is_vendor_capability("vendor"));
assert!(!is_vendor_capability("fs.read.extra"));
let audit = broker.audit();
let audit = audit.lock().unwrap();
assert_eq!(audit.len(), 5);
assert!(audit.iter().any(|entry| entry.decision == "denied"));
}
#[test]
fn explicit_grants_are_glob_scoped() {
let capabilities = Capabilities::project()
+115 -57
View File
@@ -4,6 +4,8 @@
//! calls [`Host::invoke`]. Authorization is checked here, at the point of
//! execution, not at parse/compile time.
use std::collections::{BTreeMap, BTreeSet};
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};
use marqdo_plugin_abi::{ErrorKind as PluginErrorKind, LoadedPlugin, PluginError, PluginManifest};
@@ -11,7 +13,7 @@ use marqdo_span::Span;
use marqdo_value::{ErrorCategory, RuntimeError, Value};
use crate::budget::Budget;
use crate::capability::Capabilities;
use crate::capability::{Capabilities, CapabilityAudit, CapabilityBroker};
use crate::context::ExecutionContext;
use crate::fs::ProjectFs;
use crate::trace::{EffectTrace, TraceEntry};
@@ -111,15 +113,23 @@ pub struct StdHost {
pub kernel_registry: marqdo_foreign::KernelRegistry,
output: Vec<u8>,
trace_id: u64,
/// Explicitly trusted, in-process native plugins keyed by namespace.
/// Explicitly trusted, in-process native plugins.
plugins: Vec<PluginSlot>,
/// Complete export name -> index into `plugins` (ADR-0010).
plugin_exports: BTreeMap<String, usize>,
/// Trusted vendor capability policy entries for the broker.
vendor_capabilities: BTreeSet<String>,
/// Shared audit log for plugin capability requests.
broker_audit: Arc<Mutex<Vec<CapabilityAudit>>>,
}
struct PluginSlot {
/// Call namespace (prefix of the export name, e.g. `solver`).
namespace: String,
/// Package name used for capability grants.
package: String,
/// Artifact/manifest digest that produced this registration.
manifest_digest: String,
/// Complete export name -> declared signature.
exports: BTreeMap<String, String>,
plugin: LoadedPlugin,
}
@@ -147,6 +157,9 @@ impl StdHost {
output: Vec::new(),
trace_id,
plugins: Vec::new(),
plugin_exports: BTreeMap::new(),
vendor_capabilities: BTreeSet::new(),
broker_audit: Arc::new(Mutex::new(Vec::new())),
}
}
@@ -154,14 +167,15 @@ impl StdHost {
///
/// In-process native code shares the host address space and is **not**
/// sandboxed; this build has no isolated worker transport. The caller must
/// pass `trusted = true` and grant the plugin capability. Returns the call
/// namespace derived from the plugin's export names.
/// pass `trusted = true` and grant the plugin capability. Every export is
/// registered by its complete dotted name (ADR-0010); the whole load is
/// rejected atomically if any name conflicts.
pub fn load_plugin(
&mut self,
manifest: &PluginManifest,
base_dir: &std::path::Path,
trusted: bool,
) -> Result<String, RuntimeError> {
) -> Result<Vec<String>, RuntimeError> {
if !trusted {
let mut error = RuntimeError::new(
ErrorCategory::PermissionDenied,
@@ -177,35 +191,87 @@ impl StdHost {
self.capabilities
.check_plugin(&manifest.plugin.name, None)?;
manifest.validate().map_err(map_plugin_error)?;
let namespace = manifest
.plugin
.exports
.first()
.and_then(|export| {
export
.name
.split_once('.')
.map(|(namespace, _)| namespace.to_string())
})
.ok_or_else(|| {
RuntimeError::new(
let mut exports = BTreeMap::new();
for export in &manifest.plugin.exports {
if !export.name.contains('.') {
return Err(RuntimeError::new(
ErrorCategory::PluginAbi,
None,
"plugin manifest declares no namespaced exports",
)
})?;
let loaded = LoadedPlugin::open_with(
manifest,
base_dir,
marqdo_plugin_abi::LoadOptions::default(),
)
.map_err(map_plugin_error)?;
format!("plugin export `{}` must be namespaced", export.name),
));
}
if self.plugin_exports.contains_key(&export.name) {
return Err(RuntimeError::new(
ErrorCategory::PluginFailure,
None,
format!(
"plugin export `{}` is already registered by another plugin",
export.name
),
));
}
exports.insert(export.name.clone(), export.signature.clone());
}
let artifact = manifest
.resolve_artifact(&marqdo_plugin_abi::HostTarget::current())
.map_err(map_plugin_error)?;
let manifest_digest = artifact.sha256.clone();
let mut broker =
CapabilityBroker::with_audit(self.capabilities.clone(), Arc::clone(&self.broker_audit));
for capability in &self.vendor_capabilities {
broker.allow_vendor(capability.clone());
}
let package = manifest.plugin.name.clone();
let options = marqdo_plugin_abi::LoadOptions {
host_target: marqdo_plugin_abi::HostTarget::current(),
capability_handler: Some(Box::new(move |capability, request| {
broker.authorize(&package, capability, request)
})),
};
let loaded =
LoadedPlugin::open_with(manifest, base_dir, options).map_err(map_plugin_error)?;
let index = self.plugins.len();
self.plugins.push(PluginSlot {
namespace: namespace.clone(),
package: manifest.plugin.name.clone(),
manifest_digest,
exports: exports.clone(),
plugin: loaded,
});
Ok(namespace)
let names: Vec<String> = exports.keys().cloned().collect();
for name in &names {
self.plugin_exports.insert(name.clone(), index);
}
Ok(names)
}
/// Trust a vendor capability for future plugin loads.
pub fn allow_vendor_capability(&mut self, capability: impl Into<String>) {
self.vendor_capabilities.insert(capability.into());
}
/// Registered plugin exports as `(complete name, signature, digest, package)`.
pub fn plugin_exports(&self) -> Vec<(String, String, String, String)> {
let mut exports = Vec::new();
for slot in &self.plugins {
for (name, signature) in &slot.exports {
exports.push((
name.clone(),
signature.clone(),
slot.manifest_digest.clone(),
slot.package.clone(),
));
}
}
exports.sort();
exports
}
/// Audited plugin capability decisions.
pub fn capability_audit(&self) -> Vec<CapabilityAudit> {
self.broker_audit
.lock()
.map(|audit| audit.clone())
.unwrap_or_default()
}
/// Register an explicit external foreign-kernel provider.
@@ -300,46 +366,38 @@ impl StdHost {
args: Vec<Value>,
ctx: &ExecutionContext,
) -> Result<Value, RuntimeError> {
if args.len() != 3 {
return Err(arity(ctx.span, "plugin.invoke", 3, args.len()));
if args.len() != 2 {
return Err(arity(ctx.span, "plugin.invoke", 2, args.len()));
}
let Value::Text(namespace) = &args[0] else {
let Value::Text(export_name) = &args[0] else {
return Err(RuntimeError::type_error(
ctx.span,
"plugin namespace must be Text",
"plugin export name must be Text",
));
};
let Value::Text(export) = &args[1] else {
return Err(RuntimeError::type_error(
ctx.span,
"plugin export must be Text",
));
};
let Value::Map(named_args) = &args[2] else {
let Value::Map(named_args) = &args[1] else {
return Err(RuntimeError::type_error(
ctx.span,
"plugin call arguments must be named",
));
};
let slot = self
.plugins
.iter_mut()
.find(|slot| &slot.namespace == namespace)
.ok_or_else(|| {
RuntimeError::new(
ErrorCategory::UnknownSymbol,
ctx.span,
format!("no plugin namespace `{namespace}` is loaded"),
)
})?;
self.capabilities
.check_plugin(&slot.package.clone(), ctx.span)?;
let function = format!("{namespace}.{export}");
let mut request = marqdo_plugin_abi::WireRequest::new(function.clone());
let Some(index) = self.plugin_exports.get(export_name).copied() else {
return Err(RuntimeError::new(
ErrorCategory::UnknownSymbol,
ctx.span,
format!("no plugin export `{export_name}` is loaded"),
));
};
let package = self.plugins[index].package.clone();
self.capabilities.check_plugin(&package, ctx.span)?;
let mut request = marqdo_plugin_abi::WireRequest::new(export_name.clone());
for (name, value) in named_args {
request = request.with_arg(name.clone(), value);
}
let response = slot.plugin.invoke(&request).map_err(map_plugin_error)?;
let response = self.plugins[index]
.plugin
.invoke(&request)
.map_err(map_plugin_error)?;
let value = response.typed_value().map_err(map_plugin_error)?;
Ok(value.unwrap_or(Value::Unit))
}
+143
View File
@@ -0,0 +1,143 @@
//! Complete-name plugin export routing (ADR-0010).
#![cfg(unix)]
use std::collections::BTreeMap;
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::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-plugin-{}-{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("solver.so");
let status = Command::new("cc")
.args(["-std=c11", "-O2", "-shared", "-fPIC"])
.arg("-I")
.arg(repo_root().join("include"))
.arg("-DMQ_SOLVER_MULTI_EXPORT")
.arg(repo_root().join("examples/plugin-demo/solver.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.solver
version: 0.1.0
abi: "^1.0"
kind: native
exports:
- name: solver.add
signature: "($a: Int, $b: Int) -> Int"
- name: solver.neg
signature: "($a: Int) -> Int"
requires:
- math.compute
artifacts:
- target: {}
file: solver.so
sha256: "{}"
"#,
HostTarget::current().triple(),
sha
);
std::fs::write(dir.join("plugin.yaml"), yaml).unwrap();
}
#[test]
fn every_export_is_registered_by_complete_name_and_conflicts_are_atomic() {
if !have_cc() {
eprintln!("skipping: cc is unavailable");
return;
}
let dir = TempDir::new();
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.solver");
let mut host = StdHost::new(SandboxMode::Project, capabilities, dir.path());
let names = host.load_plugin(&manifest, dir.path(), true).unwrap();
assert_eq!(names, vec!["solver.add", "solver.neg"]);
assert_eq!(host.plugin_exports().len(), 2);
let ctx = host.context("root:default::test.mq.md", None);
let mut args = BTreeMap::new();
args.insert("a".to_string(), Value::Int(7.into()));
let value = host
.invoke(
HostOp::PluginInvoke,
vec![Value::Text("solver.neg".into()), Value::Map(args.clone())],
&ctx,
)
.unwrap();
assert_eq!(value, Value::Int((-7).into()));
let mut add_args = BTreeMap::new();
add_args.insert("a".to_string(), Value::Int(7.into()));
add_args.insert("b".to_string(), Value::Int(0.into()));
let value = host
.invoke(
HostOp::PluginInvoke,
vec![Value::Text("solver.add".into()), Value::Map(add_args)],
&ctx,
)
.unwrap();
assert_eq!(value, Value::Int(7.into()));
let duplicate = host.load_plugin(&manifest, dir.path(), true).unwrap_err();
assert_eq!(
duplicate.category,
marqdo_value::ErrorCategory::PluginFailure
);
assert_eq!(host.plugin_exports().len(), 2);
}
+52 -2
View File
@@ -26,11 +26,13 @@ pub const MAX_ARTIFACTS: usize = 32;
/// Capability names the host knows about (blueprint section 10.5 whitelist).
pub const KNOWN_CAPABILITIES: &[&str] = &[
"console",
"log",
"math.compute",
"fs.read",
"fs.write",
"net.request",
"process",
"clock",
"random",
"artifact.record",
@@ -217,10 +219,14 @@ impl PluginManifest {
}
let mut capabilities = std::collections::BTreeSet::new();
for capability in &plugin.requires {
if !KNOWN_CAPABILITIES.contains(&capability.as_str()) {
if !KNOWN_CAPABILITIES.contains(&capability.as_str())
&& !is_vendor_capability(capability)
{
return Err(PluginError::manifest(
"unknown_capability",
format!("unknown capability `{capability}`"),
format!(
"unknown capability `{capability}`; vendor capabilities need a dotted vendor namespace"
),
));
}
if !capabilities.insert(capability.clone()) {
@@ -501,6 +507,29 @@ fn validate_dotted_name(name: &str, max_len: usize, what: &str) -> Result<(), Pl
Ok(())
}
/// Whether a manifest capability is a syntactically valid vendor request.
///
/// This is validation only; a vendor capability remains unauthorized until a
/// trusted host policy provides a handler for this exact name.
fn is_vendor_capability(name: &str) -> bool {
let segments: Vec<&str> = name.split('.').collect();
if segments.len() < 3 {
return false;
}
if matches!(
segments[0],
"console" | "math" | "fs" | "net" | "process" | "log" | "clock" | "random"
) {
return false;
}
segments.iter().all(|segment| {
!segment.is_empty()
&& segment.bytes().enumerate().all(|(index, byte)| {
byte.is_ascii_lowercase() || byte.is_ascii_digit() || (byte == b'-' && index > 0)
})
})
}
fn validate_signature(export: &str, signature: &str) -> Result<(), PluginError> {
let trimmed = signature.trim();
if trimmed.is_empty() || trimmed.len() > MAX_SIGNATURE_WIRE_BYTES {
@@ -595,6 +624,27 @@ plugin:
assert_eq!(manifest.package_version().expect("version").patch, 0);
}
#[test]
fn vendor_capabilities_are_validated_but_not_granted() {
let yaml = VALID_YAML.replace(
" requires:\n - math.compute",
" requires:\n - math.compute\n - vendor.device.read",
);
let manifest = PluginManifest::parse_str(&yaml).expect("parse");
manifest
.validate()
.expect("vendor names are valid requests");
for bad in ["vendor", "vendor..read", "vendor.Device", "fs.extra"] {
let yaml = VALID_YAML.replace(" - math.compute", &format!(" - {bad}"));
let manifest = PluginManifest::parse_str(&yaml).expect("parse");
assert!(
manifest.validate().is_err(),
"capability `{bad}` must be rejected"
);
}
}
#[test]
fn malformed_yaml_is_rejected() {
let error = PluginManifest::parse_str("plugin: [unclosed").expect_err("must fail");
+16 -8
View File
@@ -501,9 +501,21 @@ impl<'a> Interpreter<'a> {
return self.call_builtin(builtin, args, Some(span), frame);
}
if !frame.locals.contains_key(&alias.name) {
// Not a local value or imported module: try an explicitly
// trusted plugin namespace. Plugin calls take named
// arguments only in this build.
// A declared external descriptor is the only static
// source of plugin exports. Calls without a descriptor
// are still accepted for compatibility only when no
// plugin descriptors exist at all; this fallback is
// removed once the CLI always supplies descriptors.
let qualified = format!("{}.{}", alias.name, name);
let declared = program.external_callable(&qualified).is_some();
if !declared && !program.external_callables.is_empty() {
return Err(RuntimeError::new(
ErrorCategory::UnknownSymbol,
Some(span),
format!("unknown plugin export `{qualified}`"),
));
}
// Plugin calls take named arguments only in this build.
let evaluated = self.eval_args(args, frame)?;
let mut named = std::collections::BTreeMap::new();
for argument in evaluated {
@@ -519,11 +531,7 @@ impl<'a> Interpreter<'a> {
let module = frame.function.module.clone();
return self.host_invoke(
HostOp::PluginInvoke,
vec![
Value::Text(alias.name.clone()),
Value::Text(name.clone()),
Value::Map(named),
],
vec![Value::Text(qualified), Value::Map(named)],
Some(span),
&module,
);
+1 -1
View File
@@ -41,7 +41,7 @@ providers).
|---|---|---|
| R0 baseline + ADRs | **Done** | this section; `docs/adr/0008`–`0012`; full workspace gate |
| R1 package-aware identity + callable registry | **Done for statics** | `ModuleId { instance, relative_path }`; `PackageResolver` path sources; `lock_version: 2` with v1 migration; `CallableRegistry` for builtins/marqdo/declared ABI exports; external manifest wiring is R2 |
| R2 ABI/Kernel/Broker | **In progress** | `KernelRegistry`/`KernelDescriptor` external providers; host registry; provider tests. Plugin export routing, broker and worker pending |
| R2 ABI/Kernel/Broker | **In progress** | `KernelRegistry` external providers; complete-name plugin export routing; `CapabilityBroker` with vendor policy; static `check --plugin` signatures; multi-export C test; provider tests. Isolated worker and handle table still pending |
| R3 Tool Protocol | Not started | — |
| R4 Analysis/Trace v1 | Not started | — |
| R5 environment/isolation | Not started | — |
+57
View File
@@ -213,6 +213,51 @@ static int32_t solver_add(MqCallContext *ctx, MqBytes args_wire,
return emit(response, (size_t)written, result_wire);
}
#ifdef MQ_SOLVER_MULTI_EXPORT
/* Test-only second export: `solver.neg`, used to prove complete-name routing
* (ADR-0010). It is not part of the default demo manifest. */
static int32_t solver_neg(MqCallContext *ctx, MqBytes args_wire,
MqOwnedBytes *result_wire, MqOwnedBytes *error_wire) {
char *json;
long long a = 0;
char response[160];
int written;
(void)ctx;
if (result_wire == NULL || error_wire == NULL) {
return MQ_ERR_INVALID_ARGUMENT;
}
*result_wire = (MqOwnedBytes){NULL, 0};
*error_wire = (MqOwnedBytes){NULL, 0};
if (args_wire.data == NULL || args_wire.len == 0) {
return emit_error("bad_arguments", "request wire is empty", error_wire,
MQ_ERR_INVALID_ARGUMENT);
}
json = (char *)malloc(args_wire.len + 1);
if (json == NULL) {
return emit_error("out_of_memory", "plugin could not copy request",
error_wire, MQ_ERR_OUT_OF_MEMORY);
}
memcpy(json, args_wire.data, args_wire.len);
json[args_wire.len] = '\0';
if (read_int_argument(json, "a", &a) != 0) {
free(json);
return emit_error("bad_arguments", "solver.neg requires Int `a`",
error_wire, MQ_ERR_INVALID_ARGUMENT);
}
free(json);
written = snprintf(
response, sizeof(response),
"{\"wire_version\":1,\"kind\":\"response\",\"value\":"
"{\"type\":\"int\",\"decimal\":\"%lld\"}}",
-a);
if (written < 0 || (size_t)written >= sizeof(response)) {
return MQ_ERR_INTERNAL;
}
return emit(response, (size_t)written, result_wire);
}
#endif
/* Required ABI v1 entry point. */
int32_t mq_plugin_entry_v1(const MqHostApi *host, MqPluginApi *plugin) {
MqBytes export_name;
@@ -252,5 +297,17 @@ int32_t mq_plugin_entry_v1(const MqHostApi *host, MqPluginApi *plugin) {
if (code != MQ_OK) {
return code;
}
#ifdef MQ_SOLVER_MULTI_EXPORT
export_name.data = (const uint8_t *)"solver.neg";
export_name.len = sizeof("solver.neg") - 1;
signature_wire.data = (const uint8_t *)"{\"signature\":\"($a: Int) -> Int\"}";
signature_wire.len = sizeof("{\"signature\":\"($a: Int) -> Int\"}") - 1;
code = host->register_function(host->host_data, export_name, signature_wire,
solver_neg);
if (code != MQ_OK) {
return code;
}
#endif
return MQ_OK;
}
+17 -15
View File
@@ -329,21 +329,24 @@ Document syntax (`examples/plugin-demo/plugin-call.mq.md`):
Semantics:
* the call namespace is derived from the **first** manifest export prefix
(`solver.add` → namespace `solver`); a manifest whose exports use several
prefixes registers only the first namespace, so exports under other prefixes
are not reachable in this build;
* every manifest export is registered by its **complete dotted name**
(`solver.add`, `graph.search`); there is no first-prefix/namespace-only
registration. A manifest is loaded atomically: a duplicate export from
another plugin rejects the whole load rather than overwriting (ADR-0010);
* `check --plugin <manifest>` reads manifests and validates export signatures
statically without loading a shared library. `run/call --plugin` performs the
same static validation before execution; a bad arity/parameter name is
`call.arity`, not a plugin failure;
* calls accept **named arguments only**; positional arguments are a runtime
type error ("plugin calls require named arguments");
* each call becomes `HostOp::PluginInvoke` with a typed wire request; the
plugin's typed response becomes a Marqdo value (`Unit` when absent);
* each call becomes `HostOp::PluginInvoke` with the complete export name and a
typed wire request; the plugin's typed response becomes a Marqdo value
(`Unit` when absent);
* the capability grant is re-checked on every call, not only at load;
* plugin namespace calls are **not statically validated**: `check` passes a
document that calls a namespace no plugin provides; at runtime the call fails
with `symbol.unknown` ("no plugin namespace ... is loaded") unless
`--plugin` loaded it;
* plugin host-capability requests are denied because the CLI installs no
capability handler (`LoadOptions::default()`);
* plugin host-capability requests go through `CapabilityBroker`: core
capabilities are checked against effective grants; vendor capabilities need a
trusted policy entry for the exact name and otherwise fail with
`capability.unavailable` (ADR-0011);
* `--mode strict` refuses to run before any plugin is loaded; `--mode pure`
cannot grant `--allow-plugin`, so loading fails with `permission.denied`.
@@ -410,10 +413,9 @@ when no C compiler is available.
| Isolated plugin worker transport (length-prefixed IPC) | Not implemented; `PlatformCapabilities::worker_processes = false`. |
| Wasm Component + WIT | Not implemented. |
| Hot unload/reload | Not supported by ABI v1 (no shutdown callback). |
| Plugin capability bridge from the CLI | Not implemented; CLI supplies no handler, so all plugin host-capability requests are denied. |
| Plugin installation by package manager | Not implemented; `marqdo.yaml` `plugins:` is declarative only. |
| Static validation of plugin namespaces/exports/signatures against loaded plugins | Not implemented; errors are runtime-only. |
| Multiple namespaces per plugin | Not implemented; single namespace from the first export prefix. |
| Vendor capability handlers | The broker and vendor-name validation exist; no concrete vendor handler is shipped in this build. |
| Static validation without an explicit manifest | `check` needs `--plugin <path>`; descriptors are not discovered from the network. |
| Positional plugin arguments | Not supported; named only. |
| Thread-safe / concurrent invocation | Not supported (single-threaded v1 contract). |
| Old `marqdo_abi.h` v2 compatibility | Not implemented and not claimed; a separate adapter would be required. |
+9 -2
View File
@@ -117,9 +117,12 @@ before reading. Full symlink/race hardening is an open P4 item.
* `fs.write` → `check_write` then `ProjectFs::write`;
* math ops → `capabilities.math` (in `crates/marqdo-host/src/kernels.rs`);
* foreign ops → `capabilities.check_foreign` (requires `foreign && process`);
* plugin invoke → the namespace must be loaded, then
* plugin invoke → the **complete export name** must be registered, then
`capabilities.check_plugin(package)` on **every call**; loading also checks
the same grant once;
* plugin host-capability requests → `CapabilityBroker` checks the package and
effective grants; unknown/vendor capabilities without a trusted policy entry
become `capability.unavailable`/`permission.denied`;
* print → output budget only.
Static analysis may warn, but it never replaces these runtime checks. There is
@@ -214,7 +217,11 @@ Strict mode refuses to run at all, so foreign execution is only reachable in
call arbitrary syscalls, bypass the capability model entirely and crash or
corrupt the host process. **A C ABI is not a sandbox.** `--trust-native-plugin`
must be treated as equivalent to running the plugin's code as the host user.
* Plugin call sites are written as `<namespace>.<export>(...)` in a function
* Every export is registered by its complete dotted name; a plugin may export
several prefixes, and a conflicting name rejects the whole load atomically.
`check --plugin <manifest>` (or `run/call --plugin`) validates export
signatures statically without loading a shared library.
* Plugin call sites are written as `<export>(...)` in a function
body (for example `solver.add(a=20, b=22)`). The namespace is derived from
the **first** manifest export prefix. Calls are made through
`HostOp::PluginInvoke` with a typed `wire_version` 1 request; the plugin's