Files
marqdo-cli/docs/adr/0014-host-plugin-handle-authority.md
cflmy 7797d78d86 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
2026-11-20 11:43:21 +08:00

78 lines
3.0 KiB
Markdown

# 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.