- add request-scoped capability_request/capability_reply/capability_error frames to the worker transport (ADR-0018); no C ABI change - worker routes its capability handler through stdin/stdout, the host serves requests inside the existing invoke deadline and binds identity from the spawned worker, never from frame text - both native and worker plugins now execute a granted fs.read through ProjectFs with audit; unsupported capabilities return capability.unavailable - add a real C capability plugin and CLI test for granted read and denial - document the bridge and that strict OS isolation (H3-B) is still refused
5.1 KiB
ADR-0011: Capability broker and vendor-namespaced requests
Status: Accepted (extended by ADR-0018 for worker capability frames) Date: 2026-11-20
Context
M0.5 has a useful Capabilities struct but no way for an extension to request
a capability at runtime:
marqdo-plugin-abi::KNOWN_CAPABILITIESis a closed list and unknown names are rejected during manifest validation;Host::load_pluginpassesLoadOptions::default(), whose capability handler is empty, so every pluginrequest_capabilityis denied;- adding a new capability requires changing the core enum, the manifest list and the host dispatch together.
The M0.6 audit (E04/E09/E13) requires a broker: core capabilities stay finite and auditable, while vendor-namespaced requests are declarative and can execute only when a trusted host policy provides a handler and the user grants them.
Decision
1. Two capability classes
Core capabilities are implemented by the host and keep a fixed list:
console, math.compute, fs.read, fs.write, net.request, process,
clock, random, log, artifact.record. They map to concrete host
operations and existing CLI grants.
Vendor capabilities match ^[a-z][a-z0-9-]*\.[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)*$
and must contain a vendor namespace (for example vendor.device.read). A
manifest may declare them, but a declaration is only a request. They never map
to a core operation automatically and cannot spell a core capability with a
different prefix (fs.read cannot be recreated as vendor.fs.read).
2. Broker interface
pub struct CapabilityRequest<'a> {
pub plugin_instance: &'a str,
pub package: &'a str,
pub capability: &'a str,
pub call_context: &'a ExecutionContext,
pub reason: Option<&'a str>,
}
pub trait CapabilityBroker {
fn authorize(&mut self, request: &CapabilityRequest<'_>) -> Result<CapabilityGrant, RuntimeError>;
fn audit(&mut self, request: &CapabilityRequest<'_>, decision: &CapabilityDecision);
}
The CLI installs a broker populated from explicit user grants. The default
broker denies everything not in the effective Capabilities set. A vendor
capability is granted only if:
- a trusted host policy has registered a handler for that exact name;
- the user explicitly granted it for that package/instance; and
- the request carries a live
ExecutionContext(module, span, run id, generation).
A missing handler is capability.unavailable; a missing grant is
permission.denied. Both are distinct from runtime errors.
3. Budget, audit and scope
Every broker decision records the plugin instance, package, capability, run id and decision in the effect trace. Grants are scoped to one run and one plugin instance; they are not reusable across sessions, after unload, or by another package. Resource limits (fuel, stack, timeout, output) are applied by the host around the handler, not by the plugin.
4. ABI and manifest
The ABI callback signature is unchanged for v1. The loader passes a broker-backed
handler instead of None. Unknown vendor capability names are accepted by
manifest validation and reported as "requested, requires policy"; unknown core
names are rejected. No vendor capability can bypass HostOp dispatch: a
handler must ultimately call a host primitive and is subject to the same budget
and audit checks.
Alternatives
- Keep the closed
KNOWN_CAPABILITIESlist and add names as new core releases. Rejected: every vendor extension would require a core release. - Allow arbitrary strings and treat unknown names as granted. Rejected: privilege escalation by declaration.
- Let plugins implement their own sockets/processes. Rejected: bypasses the host and the audit trail.
- Use the existing
Capabilitiesstruct only. Rejected: it cannot express vendor handlers or per-instance/session scope.
Compatibility
Core capability names and CLI flags remain valid. Manifests that previously
failed with unknown_capability for a valid vendor name now validate but still
fail at execution unless a trusted handler and grant exist. ABI v1 layout is
unchanged; future broker fields require an ABI minor/major negotiation.
Security
The broker is the only path from an extension request to a host primitive. It checks the actual package instance, not a self-declared name. It records audit events and cannot mint capabilities from strings. Native in-process plugins are still trusted code; the broker limits what they can ask the host to do, not what they can do with their own memory.
Testing
- authorized plugin reads a project-limited file; unauthorized read/write/
process requests fail with
permission.denied; - a vendor capability without a handler fails with
capability.unavailable; - a grant cannot be reused by another plugin instance or after unload;
- a manifest cannot declare
fs.*under a vendor prefix to obtain core access; - audit entries contain the expected package/capability/decision.
Migration & rollout
R2 implements the broker and vendor-name validation. spec/security.md and
spec/plugin-abi.md are updated. Existing plugins that only declare core
capabilities keep the same denied-by-default behavior.