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

3.0 KiB

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:

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.