Files
marqdo-cli/docs/adr/0011-capability-broker.md
cflmy 0f01a69048 feat(plugin): bridge worker capability requests to the host broker (H3-A)
- 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
2026-11-20 13:08:56 +08:00

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.