Files
marqdo-cli/docs/adr/0057-capability-handler-registration.md
T
cflmy 1f6fd644a0 feat(ext): single callable binding, provider v2 CLI, capability handlers, stdlib aliases
Implements RFC-EXT-0001 PR-00..PR-07 first pass:
- CallSiteKey/CallBindingTable + one frontend binding pass; runtime dispatch by identity
- prepare composition root shared by check/run/inspect/Analysis; exact plugin reconciliation
- provider.json v2 --provider/--allow-provider worker CLI with fail-closed verification
- capability handler registry with real fs.read and audit
- verified stdlib public aliases replace print_override/AST scan
- docs: specs, ADR-0054/0055/0057/0058, README, CI/release gates, evidence

PR-04 extension selection/lock v4 and final frozen-binary evidence remain.
2026-11-22 00:17:36 +08:00

230 lines
10 KiB
Markdown

# ADR-0057: Trusted capability-handler registration
Status: **Accepted**
Date: 2026-11-21
Implements: RFC-EXT-0001 §7 (PR-05)
Extends: ADR-0011 (capability broker)
Scope: `crates/marqdo-host/src/capability.rs` (host-internal registry)
## Context
ADR-0011 introduced `CapabilityBroker` with two separate ideas but only one
implementation path:
* `decide()` answered "is this capability granted?" from `Capabilities` and a
trusted vendor-policy allow-list; and
* `execute()` special-cased the single real core implementation (`fs.read`)
inline, returning `capability.unavailable` for everything else.
That shape is why adding a capability looked like a one-line allow-list edit,
and it made "declared in policy" and "can actually execute" the same object.
RFC-EXT-0001 §7.1/§7.2 requires the chain:
```text
manifest requests capability
-> operator/CLI grants it
-> broker asks: is a trusted handler installed?
-> handler re-checks owner/grant/scope/budget
-> handler executes
-> audit { identity, effect, decision, duration, trace_id }
```
A name in an allow-list must never be enough to execute, and a capability with
no executor must never look like an empty success.
## Decision
### 1. Two independent registries
`CapabilityBroker` keeps:
* `vendor_policy: BTreeSet<String>` — names the trusted host *policy* accepts
(from `allow_vendor`); and
* `handlers: BTreeMap<String, HandlerEntry>` — names that have an explicitly
registered trusted executor.
`HandlerEntry` additionally carries an optional exact trusted package binding
(`None` = authorized by the capability grant alone).
The two sets cannot substitute for each other:
* vendor capability without a policy entry -> `permission.denied`
(declaration is not a grant; CAP-01);
* vendor policy entry without a handler -> `capability.unavailable` (CAP-02);
* core capability granted by `Capabilities` but without a handler ->
`capability.unavailable` (CAP-12).
### 2. Handler interface
```rust
pub struct CapabilityRequest<'a> {
pub package_instance: &'a str, // trusted identity from the host, not wire data
pub capability: &'a str,
pub payload: &'a [u8],
pub trace_id: &'a str,
}
pub trait CapabilityHandler: Send {
fn name(&self) -> &str;
fn execute(
&mut self,
request: &CapabilityRequest<'_>,
capabilities: &Capabilities,
budget: &mut Budget,
) -> Result<Vec<u8>, PluginError>;
}
```
The registry key is `handler.name()`, so the handler's declared capability can
never disagree with the name it is registered under (the RFC's "declared
protocol mismatch" rejection cannot occur by construction).
Registration is host-only; there is no wire path from a plugin manifest to this
API. `register_handler` installs a handler usable by any package holding a
grant; `register_package_handler(package, handler)` binds it to one exact
trusted package identity and denies every other claimed package (CAP-03, the
"trust the package the host loaded, not a self-reported name" rule of §7.4).
### 3. Registration validation
`register_handler` / `register_package_handler` reject:
| condition | stable code |
|---|---|
| empty name, surrounding whitespace, or not a core/vendor name | `capability.handler_invalid` |
| name under a reserved host prefix (`marqdo.`, `host.`) | `capability.handler_reserved` |
| name already registered (including the built-in `fs.read`) | `capability.handler_conflict` |
A rejected handler is never installed. The component that constructs the
broker is the trust boundary: only trusted host/embedder code can register, so
"untrusted source" is rejected by the absence of an API rather than a flag.
### 4. Fixed execution chain and audit
`execute()` is one function with one order:
1. `decide()` — `Capabilities`, vendor policy, request payload shape;
2. handler installed? — otherwise audit `unavailable`, return
`capability.unavailable`;
3. package-bound handler owns the claimed package? — otherwise audit `denied`,
return `permission.denied`;
4. handler executes under the broker `Budget` and the broker reply limit;
5. audit one entry with `package`, `capability`, `decision`
(`granted`/`denied`/`unavailable`), reason and `duration_micros`.
`authorize()` remains the grant decision only (`granted`/`denied`); it never
executes and therefore cannot demonstrate an executor. This keeps the
authorization and execution questions separate and auditable.
The reply is bounded by `reply_limit` (default
`MAX_CAPABILITY_REPLY_BYTES`) and oversize replies are `resource.exhausted`
(CAP-06). Handlers also receive `&mut Budget`, so an embedder can wire the
per-run budget and handlers can charge fuel/output (tested). Response payloads
are never written to the audit log, so file contents and request secrets stay
out of it (CAP-09).
### 5. `fs.read` becomes the first standard handler
The former inline `fs.read` match arm moved into `FsReadHandler`, installed by
`CapabilityBroker::with_fs(fs)`. It:
* resolves the path with `ProjectFs::resolve` (absolute paths, `..`, empty
paths rejected) **before** I/O;
* re-checks `Capabilities::check_read` against the normalized
project-relative path at the execution point, so the grant is enforced on the
same path the filesystem uses;
* reads through `ProjectFs` (regular file, UTF-8, project root, 8 MiB limit).
`with_fs` still installs exactly one handler; `capability_broker.rs` and
`host.rs` call sites are unchanged. Every other core capability and every
vendor capability without a registered handler keeps returning
`capability.unavailable`; nothing returns an empty `Ok` as a stand-in for
"implemented".
## RFC deviations (explicit)
1. **`EffectiveGrant` -> `Capabilities`; `ResourceBudget` -> `Budget`.** The
RFC (§7.2) says these are design-interface names and the implementation must
reuse the existing grant and limit structures instead of building a second
permission system; that is exactly what happened.
2. **`CapabilityError` -> `PluginError`.** The capability bridge across the
plugin/worker ABI already uses `marqdo_plugin_abi::PluginError`; reusing it
avoids a second error taxonomy. Codes remain the stable contract.
3. **`trace_id` is plumbed through `CapabilityRequest` and settable with
`with_trace_id`, but the host wiring is a follow-up.** `host.rs` does not set
it yet, so audit entries from the current CLI plugin path have an empty
trace id. Wiring it requires the run/session id from `ExecutionContext`,
which is outside this PR's write scope.
4. **`resource.exhausted` preserves the broker code but not the runtime
category.** `PluginError` kind `Capability` maps to
`RuntimeError` category `PermissionDenied` in `host.rs::map_plugin_error`.
The stable code is `resource.exhausted` (what CAP-06 asserts at the broker
boundary); teaching the host mapping about a resource-limit plugin code is a
follow-up because `host.rs` is outside this PR's scope.
5. **`CapabilityBroker` is no longer `Clone`** because it owns `Box<dyn
CapabilityHandler>`. No in-tree caller cloned it; a future embedder that
needs a clone should share the broker behind the same lock instead, which is
also what the one-call-at-a-time ABI requires.
## Alternatives
1. Keep the closed match arm and add capabilities to it. Rejected: every
vendor operation would need a core release and the broker would still have
no separation between "granted" and "executable".
2. Treat a vendor policy entry as proof of an executor. Rejected: that is the
exact "declaration becomes privilege" failure the RFC forbids; CAP-02 locks
it out.
3. Register handlers by `(name, package)` strings only and trust the caller's
package argument. Rejected: a wire-supplied package name must not authorize
anything; package-bound registration pins the identity the host selected at
load time.
4. Give every core capability an empty handler so `execute()` always returns
`Ok`. Rejected: it converts "not implemented" into a silent success, the
failure mode RFC §7.1 calls out.
## Compatibility
* Existing `Capabilities`, `with_fs`, `with_audit`, `allow_vendor`,
`authorize`, `execute` and `capability_audit()` call sites are unchanged;
`host.rs` needed no edit.
* One observable change: a vendor capability without a trusted policy entry is
now `permission.denied` instead of `capability.unavailable`. This matches
ADR-0011 ("a missing grant is `permission.denied`") and RFC CAP-01.
* `CapabilityAudit` gained `duration_micros`; all fields remain public and the
existing tests that read `package`/`capability`/`decision` compile unchanged.
* `CapabilityBroker` lost `Clone` (see deviation 5).
* No ABI, wire, manifest or CLI change.
## Security
* Registration is a trusted-host operation with no manifest/wire entry point;
a plugin cannot install, replace or enumerate handlers.
* Package-bound handlers reject cross-package impersonation even when policy
and grant match.
* `fs.read` keeps `ProjectFs` root confinement, glob scope and size limits; the
grant is re-checked on the normalized path at the execution point.
* Audit records decisions and durations but never payload contents.
* This remains a cooperative in-process API contract, not an OS sandbox: a
native plugin can still issue direct syscalls. The registry narrows what the
host will *do on request*; it does not confine plugin memory or syscalls.
## Testing
`crates/marqdo-host/tests/capability_handlers.rs` covers CAP-01..CAP-12:
policy-vs-handler separation, package binding, registration rejection, real
`fs.read` scope enforcement, reply budget and handler budget charging, forged
and replayed handles, audit hygiene, resource-stream regression smoke, project
mode not being OS-strict, and "no handler is never a silent success".
Unit tests in `capability.rs` keep the `CORE_CAPABILITIES` list in sync with
`decide()` and assert that the built-in `fs.read` handler is installed by
`with_fs`.
## Migration & rollout
`with_fs` installs the migrated `fs.read` handler automatically, so existing
plugin loads keep working. Future core capabilities migrate by adding a handler
and registering it in the trusted composition root; until then they remain
`capability.unavailable`. Vendor operations that need a non-streaming API
should first use the existing `resource.open/read/write/close` stream path
(RFC-EXT-0001 §7.3) instead of registering a new host handler.