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
This commit is contained in:
cflmy committed 2026-11-20 13:08:56 +08:00
1 parent 47a2e1883f
commit 0f01a69048
11 files changed
+720 -64

No files matched your search

+10 -8
View File
@@ -203,13 +203,15 @@ Foreign provider integrity and environment metadata:
* The environment fields are metadata only. uv/npm environment materialization,
environment-directory hashing and lock-v3 integration are **not**
implemented.
* H3-A is **partially implemented**: the native plugin broker now executes a
granted `fs.read` through `ProjectFs` and returns real bytes, with audit;
unsupported capabilities return `capability.unavailable` rather than empty
success. H3-A remains open for the worker capability bridge, live session
identity in the ABI callback and broader service operations. H3-B (OS
isolation) remains open; Worker capability requests are still denied and
`strict` is refused on every platform. No G-C claim is made.
* H3-A is **implemented for `fs.read`**: both native and worker plugins can
request a granted `fs.read` through the broker; it executes via `ProjectFs`,
returns real bytes, and records an audit decision. Unsupported capabilities
return `capability.unavailable` rather than empty success. Worker
request/reply frames are request-scoped and carry no trusted identity
(ADR-0018).
* H3-A remains open for live ABI session identity, resource budgets per
capability call, and broader executing services. H3-B (OS isolation) remains
open; `strict` is refused on every platform and no G-C claim is made.
### M0.6 implementation progress
@@ -223,7 +225,7 @@ Foreign provider integrity and environment metadata:
| S3-A/H2-C Tool protocol | **Done** | SemVer negotiation at install+dispatch, whole-bundle manifest/digest verification, atomic install/remove, reserved record file (see §S3-A/H2-C) |
| S4-A/B-13 B-14 quality gates | **Partial** | real schema instance validation + negative mutations in CI; Windows/macOS runtime tests for core/Analysis/Trace and strict refusal. Tool/C-ABI/worker runtime evidence remains Unix-only (see §S4-A) |
| S5-A/B-12 foreign integrity | **Done for metadata/integrity** | provider digest verified at registration and before spawn; environment descriptor fields; full uv/npm materialization and H3-A/B remain open (see §S5-A/B-12) |
| S5-B/H3-A broker execution | **Partial** | native `fs.read` executes through `ProjectFs` with audit; unsupported capabilities fail unavailable. Worker bridge/session identity/H3-B OS isolation remain open and are not claimed |
| S5-B/H3-A broker execution | **Done for fs.read (native+worker)** | registered plugin capability requests execute `fs.read` through `ProjectFs` with audit; unsupported capabilities fail unavailable. Session identity breadth and H3-B OS isolation remain open and are not claimed (ADR-0018) |
| R0 baseline + ADRs | **Done** | this section; `docs/adr/0008`–`0012`; full workspace gate |
| R1 package-aware identity + callable registry | **Done for statics; superseded by S1 lock v3** | `ModuleId { instance, relative_path }`; `PackageResolver` path sources; lock v3 transitive graph (ADR-0016) replaces the flat v2 lock; `CallableRegistry` for builtins/marqdo/declared ABI exports; external manifest wiring is R2 |
| R2 ABI/Kernel/Broker | **Done (worker = crash isolation)** | `KernelRegistry` external providers; complete-name export routing; `CapabilityBroker`; static `check --plugin`; multi-export C test; isolated worker with timeout/crash tests; host handle table. Native/worker are not an OS sandbox |
+1 -1
View File
@@ -1,6 +1,6 @@
# ADR-0011: Capability broker and vendor-namespaced requests
Status: **Accepted**
Status: **Accepted** (extended by ADR-0018 for worker capability frames)
Date: 2026-11-20
## Context
+90
View File
@@ -0,0 +1,90 @@
# 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`.
* 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.