- enforce at most 64 capability requests and 64 KiB per serialized request in both the worker handler and the host bridge - return structured capability.budget_exceeded / request_too_large errors and kill the worker on a host-side violation - add a real C loop fixture and CLI test proving a runaway plugin is stopped without producing file contents - update ADR-0018, plugin-abi and STATUS
96 lines
4.0 KiB
Markdown
96 lines
4.0 KiB
Markdown
# ADR-0018: Worker capability bridge frames
|
|
|
|
Status: **Accepted**
|
|
Date: 2026-11-20
|
|
Extends: ADR-0011 (capability broker) and `spec/plugin-abi.md` §9.1
|
|
|
|
## Context
|
|
|
|
The isolated worker transport initially supported only `ready`, `invoke`,
|
|
`shutdown` and `error` frames. The plugin loader's capability handler ran in
|
|
the host process for native plugins, but a worker was started with
|
|
`LoadOptions::default()`, so every worker capability request failed even when
|
|
the user had granted it. That made the broker's execution path unreachable for
|
|
the only transport designed to contain crashes.
|
|
|
|
The worker frame set is a versioned transport contract. Adding frames is an
|
|
explicit protocol extension, not an implementation detail.
|
|
|
|
## Decision
|
|
|
|
### 1. Runtime-only capability request/reply frames
|
|
|
|
While a worker is executing one `invoke`, it may send:
|
|
|
|
```json
|
|
{"kind":"capability_request","id":7,"capability":"fs.read",
|
|
"request":{"path":"data/allowed.txt"}}
|
|
```
|
|
|
|
The host replies with exactly one frame carrying the same `id`:
|
|
|
|
```json
|
|
{"kind":"capability_reply","id":7,"data":"file contents"}
|
|
```
|
|
|
|
or:
|
|
|
|
```json
|
|
{"kind":"capability_error","id":7,"code":"permission.denied",
|
|
"message":"read access ... was not granted"}
|
|
```
|
|
|
|
Rules:
|
|
|
|
* Requests carry **no trusted identity**. The host binds the package and
|
|
session from the worker it spawned; frame fields are untrusted data.
|
|
* `request` must be a JSON value; the host serializes it back to the request
|
|
bytes used by the broker. Non-JSON requests are rejected.
|
|
* Replies are text; `capability_reply.data` is returned to the plugin as raw
|
|
UTF-8 bytes. Non-UTF-8 replies become `capability_error`.
|
|
* A reply with an unknown/mismatched `id`, or a different kind, is a protocol
|
|
error. No other frames are accepted while waiting for a capability reply.
|
|
* Capability handling does not extend the invocation timeout: the host keeps a
|
|
single deadline for the whole `invoke`, including capability round-trips.
|
|
* Only the broker's executing capabilities are reachable. In this build that
|
|
means `fs.read`; everything else returns `capability.unavailable`.
|
|
* Budgets: at most 64 capability requests per invocation and 64 KiB per
|
|
serialized request. Exceeding either returns
|
|
`capability.budget_exceeded`/`capability.request_too_large`; the worker-side
|
|
handler and the host both enforce the limits, and a host violation kills the
|
|
worker.
|
|
* The frames do not change the C ABI or `MqHostApi`. They are an internal IPC
|
|
protocol between the host and its own worker binary.
|
|
|
|
### 2. Worker and host implementation
|
|
|
|
The worker routes its capability handler through the same stdin/stdout frame
|
|
channel. During plugin invocation the outer frame loop is not reading, so the
|
|
handler may synchronously send a request and wait for the reply. Reads/writes
|
|
are guarded by mutexes; clean EOF or a partial frame remains a protocol error.
|
|
|
|
The host's `WorkerPlugin` owns an optional capability handler (the broker with
|
|
the project filesystem). It serves capability frames inside the existing invoke
|
|
deadline, writes replies, and marks/kills the worker on any transport failure
|
|
so a stale stdin is never reused.
|
|
|
|
## Consequences
|
|
|
|
* The worker capability bridge is no longer a stub; granted `fs.read` works in
|
|
both native and worker transports.
|
|
* Request/reply identity is bound to the spawn, not to plugin-supplied text.
|
|
* Worker capability requests still run as the user process. This is cooperative
|
|
authorization, **not** an OS sandbox; H3-B strict isolation remains required
|
|
for any untrusted-code claim.
|
|
* The frame set change requires this ADR and an updated plugin-abi spec. Frame
|
|
kinds are additive for future ABI minors; unknown frames fail closed.
|
|
|
|
## Tests
|
|
|
|
* `worker_capability_bridge_reads_granted_file_and_denies_without_grant`
|
|
drives a real `.mq.md` program through a C worker plugin: granted
|
|
`fs.read` returns the file contents; without the grant the run fails with a
|
|
permission error and no contents.
|
|
* Host unit tests cover granted/denied `fs.read` and `capability.unavailable`
|
|
for unsupported capabilities.
|