carlos / platform Public

caps: doc-engine capability for document-conversion sidecars (Gotenberg, OCR) open review pending

On branch sidecar-engine-capability

claude agent, operated by paul@keymail.dev operated by paul@keymail.dev session 01a0c4fe · pi · DOCS-T1

What

Adds doc_engine as the eighth capability token: the platform-side shape for running a document-conversion engine (Gotenberg, an OCR service) as a CARLOS route. A release declares doc_engine; an operator grants it per box with carlos route --grant doc-engine; the adopt pass materializes a systemd drop-in that raises the resource tier and fences the engine's egress away from every private network range — RFC1918, link-local, CGNAT, IPv6 ULA and the NAT64 prefix — while leaving loopback open for the engine's own Chromium/LibreOffice.

The fence is the point: a conversion engine fetches whatever URLs the documents handed to it name, so an unfenced engine on a fleet box is an SSRF proxy into the VPC. host_role and doc_engine are mutually exclusive and refused together at ship — host_role re-opens the cloud metadata address, and in systemd's BPF firewall an IPAddressAllow beats any IPAddressDeny.

README's capabilities section documents the operator-facing shape: eight names, the engine manifest example, the two box preconditions the grant assumes (loopback DNS resolver via systemd-resolved; a dedicated box, since loopback stays open), and why self-hosted engines remain the more secure offering.

Review history

Drafted from the sidecar design discussion (2026-09-17 session; plan and baseline decisions in the session notes).
Fable reviewed three rounds against the repo; final verdict "LAND. No remaining blocking items" (2026-09-18). All seven round-3 fixes verified applied: loopback comment, resolver precondition location, token name, the five fence gaps (fe80::/10, fec0::/10, fc00::/7, fd00::/8, 64:ff9b::/96), README section, both-grants test, softened "every backing" claim.
Copy review passed 2026-09-21: 8/8 strings approved with zero edits (README capabilities prose, --grant help line, ship refusal, both adopt advisories).

Verification

go build ./..., go vet ./..., gofmt -l . clean over the whole tree.
make test green (54 packages, -count=1), including the new golden-file fence tests, the both-grants refusal test, and the adopt-advisory tests.
Branch merged latest origin/main before the run.