feat(m0.6-r2): host-owned plugin handle authority

- add PluginHandleTable with owner, run id and generation scoping
- reject forged, cross-owner, cross-run and post-unload handles
- reject any plugin_handle returned by plugin or foreign-kernel output,
  including nested values
- add ADR-0014 and update value-wire/security specs
This commit is contained in:
cflmy committed 2026-11-20 11:43:21 +08:00
1 parent d940013f35
commit 7797d78d86
8 files changed
+276 -9

No files matched your search

+162
View File
@@ -0,0 +1,162 @@
//! Host-issued plugin handle table (ADR-0014 / M0.6 audit E15).
//!
//! A `PluginHandle` decoded from wire JSON is only a structural claim. It is
//! never accepted as authority: the host mints handles with an owner package,
//! run id and generation, and validates exact matches before use. A plugin
//! returning a handle value to the host is rejected because plugin output must
//! not mint host authority.
use std::collections::BTreeMap;
use marqdo_value::{ErrorCategory, PluginHandle, RuntimeError};
#[derive(Debug, Clone, PartialEq, Eq)]
struct HandleEntry {
plugin: String,
export: String,
owner_package: String,
run_id: u64,
generation: u64,
}
/// Host-owned handle table.
#[derive(Debug, Clone, Default)]
pub struct PluginHandleTable {
next_id: u64,
generation: u64,
live: BTreeMap<u64, HandleEntry>,
}
impl PluginHandleTable {
/// Mint a handle for one export and owner package in one run.
pub fn mint(
&mut self,
plugin: impl Into<String>,
export: impl Into<String>,
owner_package: impl Into<String>,
run_id: u64,
) -> PluginHandle {
self.next_id += 1;
self.generation += 1;
let id = self.next_id;
self.live.insert(
id,
HandleEntry {
plugin: plugin.into(),
export: export.into(),
owner_package: owner_package.into(),
run_id,
generation: self.generation,
},
);
PluginHandle {
plugin: self.live[&id].plugin.clone(),
export: self.live[&id].export.clone(),
id,
}
}
/// Validate a handle against its claimed owner and current run.
pub fn validate(
&self,
handle: &PluginHandle,
owner_package: &str,
run_id: u64,
) -> Result<(), RuntimeError> {
let Some(entry) = self.live.get(&handle.id) else {
return Err(rejected("unknown or expired plugin handle"));
};
if entry.plugin != handle.plugin || entry.export != handle.export {
return Err(rejected("plugin handle identity does not match the table"));
}
if entry.owner_package != owner_package || entry.run_id != run_id {
return Err(rejected(
"plugin handle belongs to another package or run session",
));
}
if entry.generation == 0 {
return Err(rejected("plugin handle generation is no longer valid"));
}
Ok(())
}
/// Invalidate all handles from a run (unload/shutdown).
pub fn clear_run(&mut self, run_id: u64) {
self.live.retain(|_, entry| entry.run_id != run_id);
self.generation += 1;
}
/// Number of live handles (testing/diagnostics).
pub fn len(&self) -> usize {
self.live.len()
}
/// Whether the table is empty.
pub fn is_empty(&self) -> bool {
self.live.is_empty()
}
}
fn rejected(message: &str) -> RuntimeError {
RuntimeError::new(
ErrorCategory::PermissionDenied,
None,
format!("plugin_handle.untrusted: {message}"),
)
}
/// Recursively detect a plugin handle in a value returned by an untrusted
/// extension (plugin or foreign kernel).
pub fn contains_plugin_handle(value: &marqdo_value::Value) -> bool {
match value {
marqdo_value::Value::PluginHandle(_) => true,
marqdo_value::Value::List(items) => items.iter().any(contains_plugin_handle),
marqdo_value::Value::Map(map) => map.values().any(contains_plugin_handle),
marqdo_value::Value::Table(table) => table
.rows
.iter()
.flat_map(|row| row.iter())
.any(contains_plugin_handle),
_ => false,
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn forged_cross_owner_and_expired_handles_are_rejected() {
let mut table = PluginHandleTable::default();
let handle = table.mint("demo.solver", "solver.resource", "demo.solver", 7);
table
.validate(&handle, "demo.solver", 7)
.expect("owner handle");
assert!(table.validate(&handle, "other.solver", 7).is_err());
assert!(table.validate(&handle, "demo.solver", 8).is_err());
let mut forged = handle.clone();
forged.id = 999;
assert!(table.validate(&forged, "demo.solver", 7).is_err());
let mut wrong_export = handle.clone();
wrong_export.export = "solver.other".into();
assert!(table.validate(&wrong_export, "demo.solver", 7).is_err());
table.clear_run(7);
assert!(table.validate(&handle, "demo.solver", 7).is_err());
assert_eq!(table.len(), 0);
}
#[test]
fn handles_inside_untrusted_values_are_detected() {
let mut table = PluginHandleTable::default();
let handle = table.mint("demo", "demo.resource", "demo", 1);
let value = marqdo_value::Value::List(vec![marqdo_value::Value::Map(
[("h".to_string(), marqdo_value::Value::PluginHandle(handle))]
.into_iter()
.collect(),
)]);
assert!(contains_plugin_handle(&value));
assert!(!contains_plugin_handle(&marqdo_value::Value::Int(1.into())));
}
}
+13
View File
@@ -16,6 +16,7 @@ use crate::budget::Budget;
use crate::capability::{Capabilities, CapabilityAudit, CapabilityBroker};
use crate::context::ExecutionContext;
use crate::fs::ProjectFs;
use crate::handles::{contains_plugin_handle, PluginHandleTable};
use crate::trace::{EffectTrace, TraceEntry};
use marqdo_sandbox::{PlatformCapabilities, SandboxMode};
@@ -121,6 +122,8 @@ pub struct StdHost {
vendor_capabilities: BTreeSet<String>,
/// Shared audit log for plugin capability requests.
broker_audit: Arc<Mutex<Vec<CapabilityAudit>>>,
/// Host-issued opaque plugin handles.
pub handles: PluginHandleTable,
}
struct PluginSlot {
@@ -160,6 +163,7 @@ impl StdHost {
plugin_exports: BTreeMap::new(),
vendor_capabilities: BTreeSet::new(),
broker_audit: Arc::new(Mutex::new(Vec::new())),
handles: PluginHandleTable::default(),
}
}
@@ -399,6 +403,15 @@ impl StdHost {
.invoke(&request)
.map_err(map_plugin_error)?;
let value = response.typed_value().map_err(map_plugin_error)?;
if let Some(value) = &value {
if contains_plugin_handle(value) {
return Err(RuntimeError::new(
ErrorCategory::PluginFailure,
ctx.span,
"plugin_handle.untrusted: plugin output may not mint host handles",
));
}
}
Ok(value.unwrap_or(Value::Unit))
}
+10 -2
View File
@@ -194,13 +194,21 @@ pub(crate) fn foreign(
),
));
}
result.value.ok_or_else(|| {
let value = result.value.ok_or_else(|| {
RuntimeError::new(
ErrorCategory::ForeignFailure,
span,
"foreign call returned no typed value",
)
})
})?;
if crate::handles::contains_plugin_handle(&value) {
return Err(RuntimeError::new(
ErrorCategory::PermissionDenied,
span,
"plugin_handle.untrusted: foreign kernel output may not mint host handles",
));
}
Ok(value)
}
_ => Err(RuntimeError::new(
ErrorCategory::Internal,
+2
View File
@@ -8,6 +8,7 @@ pub mod budget;
pub mod capability;
pub mod context;
pub mod fs;
pub mod handles;
pub mod host;
pub mod kernels;
pub mod trace;
@@ -16,6 +17,7 @@ pub use budget::{Budget, DEFAULT_FUEL, DEFAULT_OUTPUT_BYTES, DEFAULT_STACK_LIMIT
pub use capability::Capabilities;
pub use context::ExecutionContext;
pub use fs::ProjectFs;
pub use handles::{contains_plugin_handle, PluginHandleTable};
pub use host::{arity, expect_text, Host, HostOp, StdHost};
pub use marqdo_sandbox::{PlatformCapabilities, SandboxMode, StrictIsolation};
pub use trace::{EffectTrace, TraceEntry};
+1 -1
View File
@@ -15,6 +15,6 @@ pub use error::{CallFrame, ErrorCategory, RuntimeError};
pub use marqdo_span::{LineCol, Span};
pub use value::{
bigint_to_exact_f64, float_to_bigint, format_float, CodeValue, FormulaValue, FunctionRef,
Table, Value,
PluginHandle, Table, Value,
};
pub use wire::{from_wire, to_wire, WireError, WIRE_VERSION};
@@ -0,0 +1,77 @@
# ADR-0014: Plugin handles are host-minted authority, never wire claims
Status: **Accepted**
Date: 2026-11-20
## Context
`marqdo_value::PluginHandle { plugin, export, id }` is decodable from the
public wire format. M0.5 documented it as non-unforgeable but had no host table
and no producer; a future stateful plugin API could accidentally treat a
decoded JSON handle as authority. The M0.6 audit E15 requires fixing the
authority model **before** stateful plugin resources are added.
## Decision
`marqdo-host::PluginHandleTable` owns every live handle:
```rust
struct HandleEntry {
plugin: String,
export: String,
owner_package: String,
run_id: u64,
generation: u64,
}
```
* Handles are minted only by the host (`mint`) and carry the owner package and
run id; `validate` requires an exact plugin/export/id match plus the caller's
package and current run.
* `clear_run` invalidates every handle from a run; generation increments on
mint/clear, so an old handle cannot be revived.
* A plugin or foreign kernel returning a `PluginHandle` in its typed output is
rejected (`plugin_handle.untrusted`), including handles nested in lists,
maps or tables. Untrusted output may not mint host authority.
* Wire JSON remains able to represent a handle for data/debugging, but decoding
is not authorization. The runtime must call `validate` with the trusted
context before any future resource operation.
No stateful plugin resource API is added in this milestone; the table and the
boundary rejection exist so that such an API cannot be built on a forgeable
value.
## Alternatives
1. Remove `PluginHandle` from the wire entirely. Rejected for now: it is part
of the frozen v1 value union; rejecting untrusted output at the host achieves
the required authority separation without a wire break.
2. Use the `id` alone as a capability token. Rejected: IDs are guessable and
cross-session replay would work.
3. Sign handles cryptographically. Rejected as unnecessary complexity when a
host-side table with run/owner scope is available.
## Compatibility
The wire encoding is unchanged. Existing values remain decodable; a handle
returned by a plugin/foreign kernel now fails at the host boundary instead of
being surfaced as an inert value. No legitimate M0.5 producer exists (none was
implemented), so this is not a behavioral regression.
## Security
The table is in host memory and never serialized. A forged, cross-package,
cross-run or post-unload handle fails. The host address and internal entry
fields are not exposed by `PluginHandle`.
## Testing
`crates/marqdo-host/src/handles.rs` tests forged IDs, wrong export, cross-owner,
cross-run and cleared-run rejection, plus nested-handle detection. The plugin
and foreign adapters reject untrusted handle output.
## Migration & rollout
R2 adds the table and boundary rejection. A future stateful API must define
resource lifetime, owner transfer rules and a host op that validates the table;
it must not accept handles straight from wire JSON.
+7 -4
View File
@@ -272,10 +272,13 @@ 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 isolation and a plugin capability bridge are unimplemented;
only trusted in-process native plugins are possible.
6. `plugin_handle` wire values are structurally reconstructable (see
`value-wire.md` §4.1); no unforgeable capability token.
5. Plugin worker isolation is unimplemented; only trusted in-process native
plugins are possible. The capability broker exists, but no vendor handler is
shipped.
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
(ADR-0014, `value-wire.md` §4.1).
7. Budgets do not cover all allocation paths (for example list/table growth
inside the interpreter is bounded only by fuel and memory).
8. `--json` run output includes the full program stdout string; that is the
+4 -2
View File
@@ -127,8 +127,10 @@ The following are **not** bounded by `WireLimits` in
`plugin_handle.plugin`/`export` are not checked against
`max_string_bytes`;
* a `plugin_handle` decoded from wire data is a structurally reconstructed
`Value::PluginHandle`; this build does not carry an unforgeable capability
token. Host code must therefore treat a plugin handle as opaque *intent* and
`Value::PluginHandle`; it is **not** an authorization token. The host owns a
`PluginHandleTable` with owner/run/generation scope (ADR-0014), and plugin or
foreign output containing any handle is rejected with
`plugin_handle.untrusted`. Host code must therefore treat a plugin handle as opaque *intent* and
re-authorize any operation, not as proof of prior authorization. The header
comment "cannot be forged from wire data" is aspirational for this point and
should be fixed or reworded in a future ADR.