Files
marqdo-cli/docs/adr/0018-worker-capability-bridge.md
T
cflmy f69c563afd fix(plugin): bound worker capability calls per invocation (H3-A)
- 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
2026-11-20 13:11:24 +08:00

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.