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:
1 parent
47a2e1883f
commit
0f01a69048
11 files changed
+720
-64
No files matched your search
+10
-8
@@ -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,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
|
||||
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user