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

10 KiB

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:

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

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.