The arca serve protocol

arca serve is the Vault port over newline-delimited JSON — the surface orchestrators (peregrin) embed. One JSON request per stdin line, one JSON response per stdout line, and the audit wire stays on stderr, unchanged — three separate fds, so a reply never rides the event stream and an event never answers a request. Protocol version: arca-serve/1 — send {"op":"manifest"} on the wire for the machine-readable self-description.

Serve is a thin front over the same arca-ops plumbing the CLI uses: [envs] routing, arca://<env>/… pins, and audit events are identical. run/env/deploy/init/ui/migrate/schema stay single-shot CLI verbs — serve covers what an embedder needs in-process.

Requests

{"id": 1, "op": "get", "ref": "arca://billing/stripe",
 "env": "prod", "actor": "agent:peregrin", "attestation": "…"}

field	notes
id	any JSON value — echoed verbatim (absent → null), ≤ 4 KiB serialized
op	get | put | rm | rotate | list | check | manifest | shutdown
ref	arca://ns/name ≤ 1 KiB — required by the four vault ops; an arca://<env>/… pin overrides env
env	per-request env override — else the loaded context (--env/ARCA_ENV)
value	plaintext ≤ 64 KiB — required by put/rotate. Values cross this wire deliberately: the parent owns the channel exactly like it owns arca get's stdout
actor	claimed actor id ≤ 256 B — advisory attribution recorded on audit events; validated, never verified
attestation	opaque identity claim ≤ 64 KiB — passed to the PDP verbatim, never interpreted by arca

Hard bounds on the wire: a request line may be at most 4 MiB — an oversized line answers bad_request and the reader resyncs to the next line, so a broken embedder can't exhaust memory. Blank or whitespace-only lines get no reply — legal keep-alive, unanswered. A non-UTF-8 line is a bad_request, not a crash.

Responses

{"id": 1, "ok": true, "result": {"ref": "arca://billing/stripe", "env": "prod",
 "value": "…", "version": 3, "created_at": "…", "rotated_at": "…"},
 "policy": {"allow": true, "reason": "…", "obligations": ["…"]}}

{"id": 2, "ok": false, "error": {"code": "denied", "message": "denied by policy: no prod reads"}}

policy appears on a response whenever a PDP was consulted for that op — the same verdict the audit event records.

error code	meaning
bad_request	malformed/oversized/non-UTF-8 line, missing ref/value, invalid ref/env/actor, field over cap — the loop keeps serving
unknown_op	op not in the table (a real CLI verb reports "not served — use the single-shot CLI")
denied	[guardrails] or PDP refusal
pdp_unreachable	the PDP couldn't answer (spawn, non-zero exit, timeout, flooded/oversized/unparseable verdict) and allow_on_error is false — fail-closed
not_found	the ref isn't stored in that env
op_error	vault/config/io failure

shutdown replies then exits cleanly; EOF on stdin exits too. manifest and shutdown are protocol meta-ops: they skip guardrails and the PDP consult by design — gating session lifecycle is the embedder's spawn decision, not a materialization.

The policy decision point — [serve.pdp]

Configured, serve consults the PDP before every op that can materialize — get/put/rm/rotate, and list/check too: list decrypts every record's metadata and check probes vaults, including scoped-token gets and outbound signed HTTP against cf vaults. Nothing crosses the vault boundary without a verdict. manifest/shutdown are meta-ops and don't consult. [guardrails] still apply on the serve path (the advisory layer, checked before the consult), and request validation runs before the consult too — a doomed request never spawns a PDP.

[serve.pdp]
exec = "peregrin policy decide"   # sh -c per decision
allow_on_error = false            # default: fail closed
timeout_ms = 5000                 # default: 5s per consult

A [serve.pdp] exec line is trust-root config: it authorizes shell execution. When arca serve loads it from an implicit ./arca.toml (the search path, not a pinned --config/$ARCA_CONFIG or ~/.config/arca/), it warns on stderr — the working directory decides what code runs.

The exec command runs once per decision — request JSON on stdin, verdict JSON on stdout, stderr discarded. The child inherits only the arca-shell env allowlist (same scrub arca run applies): ARCA_CF_TOKEN, CLOUDFLARE_API_TOKEN, and every other parent credential stay out of the decider.

{"actor": "agent:peregrin", "attestation": "…", "op": "get",
 "env": "prod", "ref": "billing/stripe"}

ref is the resolved path with the env pin stripped — and is absent on list/check consults, which carry no ref.

{"allow": true, "reason": "…", "obligations": ["redact", "session-bound"]}

allow is required; reason and obligations are free-form context the PDP wants on record (allow-with-conditions — arca records them; enforcing them is the requester's job). A deny is a denied response plus a denied audit event — no vault access.

A consult is hard-bounded so a misbehaving PDP can't take the broker with it: the child is killed at timeout_ms, the verdict is capped at 64 KiB (a flooding child blocks on its own pipe and dies on the deadline — it cannot sink memory), and the request write can't deadlock against a child that never reads stdin.

Spawn failure, non-zero exit, timeout, an oversized or unparseable verdict is unreachable → the op is denied (pdp_unreachable) unless allow_on_error = true, which runs the op anyway and records the degraded verdict (policy.reason says why). Fail-closed is the default because an unanswered policy engine must not silently mean "allowed".

Why exec and not a socket or HTTP: zero new dependencies, sync only, no daemon lifecycle. A PDP that wants a persistent endpoint can put socat/nc/curl in its own exec line — the wire stays the same. Note the per-op cost: every consult spawns a fresh sh -c, list decrypts each record, and check probes every vault — batch reads rather than looping list.

Actor claims are advisory

actor and attestation are claims, not proof — arca validates the actor string's shape and passes both through to audit and the PDP. Signed, short-lived attestation is the PDP's side (peregrin's design, a later decision); ADR-0003 only fixes the pass-through seam.