From 7797d78d8647427b5410e820dfbdf0ae07614480 Mon Sep 17 00:00:00 2001 From: cflmy Date: Fri, 20 Nov 2026 11:43:21 +0800 Subject: [PATCH] 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 --- crates/marqdo-host/src/handles.rs | 162 ++++++++++++++++++ crates/marqdo-host/src/host.rs | 13 ++ crates/marqdo-host/src/kernels.rs | 12 +- crates/marqdo-host/src/lib.rs | 2 + crates/marqdo-value/src/lib.rs | 2 +- docs/adr/0014-host-plugin-handle-authority.md | 77 +++++++++ spec/security.md | 11 +- spec/value-wire.md | 6 +- 8 files changed, 276 insertions(+), 9 deletions(-) create mode 100644 crates/marqdo-host/src/handles.rs create mode 100644 docs/adr/0014-host-plugin-handle-authority.md diff --git a/crates/marqdo-host/src/handles.rs b/crates/marqdo-host/src/handles.rs new file mode 100644 index 0000000..00ab365 --- /dev/null +++ b/crates/marqdo-host/src/handles.rs @@ -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, +} + +impl PluginHandleTable { + /// Mint a handle for one export and owner package in one run. + pub fn mint( + &mut self, + plugin: impl Into, + export: impl Into, + owner_package: impl Into, + 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()))); + } +} diff --git a/crates/marqdo-host/src/host.rs b/crates/marqdo-host/src/host.rs index dfce7a7..d7ff1f6 100644 --- a/crates/marqdo-host/src/host.rs +++ b/crates/marqdo-host/src/host.rs @@ -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, /// Shared audit log for plugin capability requests. broker_audit: Arc>>, + /// 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)) } diff --git a/crates/marqdo-host/src/kernels.rs b/crates/marqdo-host/src/kernels.rs index a6de137..5496548 100644 --- a/crates/marqdo-host/src/kernels.rs +++ b/crates/marqdo-host/src/kernels.rs @@ -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, diff --git a/crates/marqdo-host/src/lib.rs b/crates/marqdo-host/src/lib.rs index 1df0d7b..f50b8dc 100644 --- a/crates/marqdo-host/src/lib.rs +++ b/crates/marqdo-host/src/lib.rs @@ -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}; diff --git a/crates/marqdo-value/src/lib.rs b/crates/marqdo-value/src/lib.rs index 10c70ff..308eddb 100644 --- a/crates/marqdo-value/src/lib.rs +++ b/crates/marqdo-value/src/lib.rs @@ -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}; diff --git a/docs/adr/0014-host-plugin-handle-authority.md b/docs/adr/0014-host-plugin-handle-authority.md new file mode 100644 index 0000000..972fb4b --- /dev/null +++ b/docs/adr/0014-host-plugin-handle-authority.md @@ -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. diff --git a/spec/security.md b/spec/security.md index 624c7e2..226a10d 100644 --- a/spec/security.md +++ b/spec/security.md @@ -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 diff --git a/spec/value-wire.md b/spec/value-wire.md index 990d165..11d0394 100644 --- a/spec/value-wire.md +++ b/spec/value-wire.md @@ -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.