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:
1 parent
d940013f35
commit
7797d78d86
8 files changed
+276
-9
No files matched your search
@@ -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())));
|
||||
}
|
||||
}
|
||||
@@ -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))
|
||||
}
|
||||
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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};
|
||||
@@ -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
@@ -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
@@ -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.
|
||||
|
||||
Reference in new issue
Block a user