- 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
123 lines
5.1 KiB
Markdown
123 lines
5.1 KiB
Markdown
# 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_CAPABILITIES` is a closed list and unknown names are
|
|
rejected during manifest validation;
|
|
* `Host::load_plugin` passes `LoadOptions::default()`, whose capability handler
|
|
is empty, so every plugin `request_capability` is 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
|
|
|
|
```rust
|
|
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:
|
|
|
|
1. a trusted host policy has registered a handler for that exact name;
|
|
2. the user explicitly granted it for that package/instance; and
|
|
3. 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
|
|
|
|
1. Keep the closed `KNOWN_CAPABILITIES` list and add names as new core
|
|
releases. Rejected: every vendor extension would require a core release.
|
|
2. Allow arbitrary strings and treat unknown names as granted. Rejected:
|
|
privilege escalation by declaration.
|
|
3. Let plugins implement their own sockets/processes. Rejected: bypasses the
|
|
host and the audit trail.
|
|
4. Use the existing `Capabilities` struct 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.
|