- 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
78 lines
3.0 KiB
Markdown
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.
|