bot-bottle/docs/prds/prd-new-control-plane-auth-provisioning.md

PRD prd-new: Uniform control-plane auth provisioning

• Status: Draft
• Author: claude
• Created: 2026-07-26
• Issue: #476

Summary

Hoist control-plane auth provisioning out of the per-backend launchers into a single shared contract, parameterized per trust domain. A backend obtains its signing key and the data plane's token through one seam (trust_domain.ControlPlaneProvisioning) instead of re-deriving, by hand, how to generate the signing key, scope it to the orchestrator, mint the gateway JWT, and keep the host key canonical. This removes the integration-bug class that took PR #471 three review rounds to land, and gives issue #468's host controller a clean seam to instantiate its own domain (own key, own roles) without weakening the control plane's.

Problem

Each launcher (docker gateway, docker infra, macos infra, firecracker infra) implemented the control-plane auth invariants independently. Every blocking finding in PR #471 was the same class of integration bug — not a flaw in the auth primitive (orchestrator_auth.mint/verify), but in how each backend wired it:

• Round 1 (High): the data plane got the full-power control-plane token, so a compromised egress/git-gate could approve its own supervise proposals. Fixed with role-scoped JWTs (gateway vs cli).
• Round 2 (High): the Firecracker infra VM never provisioned the signing key or a gateway JWT, so the control plane fell into open mode and handed every unauthenticated caller the cli role.
• Round 3 (High): the Firecracker fix then clobbered the host-canonical orchestrator-token with its guest key, 401'ing every already-running Docker/macOS orchestrator.

Miss one step per bespoke launcher and it's either a security hole or a cross-backend coexistence regression — and the tests didn't catch it because each backend's provisioning was hand-rolled.

Goals / Success Criteria

• One shared seam every backend satisfies for control-plane auth provisioning; no launcher re-derives the four invariants.
• The signing key is host-canonical — a guest is handed it, never generates or overwrites it.
• Only the orchestrator process receives the raw key; the data plane receives a pre-minted, role-scoped gateway token it cannot rewrite into cli.
• The host CLI's cli token is minted from the same canonical key, so it stays valid across simultaneously-running backends.
• Open mode is unreachable for any backend whose data plane shares a host/VM with the control plane (fail-closed by default).
• Provisioning is parameterized per trust domain, so #468 adds a separate host-controller domain (own key, own verifier, own role set) rather than a host role on the control plane's frozenset.
• Adding a backend or a data-plane daemon means implementing the contract, not rediscovering the invariants.

Non-goals

• Not a rewrite of the auth primitive. orchestrator_auth's HMAC mint/verify is unchanged except for an optional roles= argument (default preserved) so a domain can scope its own role set.
• Not the #468 host-controller domain itself — this only provides the seam it will instantiate.
• Not a change to network topology, the plane split (#469), or the server's documented open-mode fallback for tests/isolated control planes.
• The complementary #469 hardening (distinct non-root UIDs for co-located daemons) stays separate.

Design

Trust domain — the unit of provisioning

A trust domain (trust_domain.TrustDomain) is one credential boundary: a host-canonical signing key file, the role set that key may sign, and the env vars the raw key and a pre-minted token ride in. mint/verify are scoped to the domain's roles, so a token minted in one domain neither carries nor verifies a role from another.

The orchestrator control plane is one domain, CONTROL_PLANE (key orchestrator-token, roles {gateway, cli}). The security reason provisioning is per-domain and not per-key: adding a host role to CONTROL_PLANE.roles would let anything holding the control-plane key (the orchestrator itself) mint host-controller tokens, collapsing the boundary #468 needs — the host controller owns the orchestrator's lifecycle, so it must not be forgeable by the orchestrator. Two keys, two verifiers, two role sets.

paths.host_signing_key(filename) generalizes the old host_orchestrator_token() (now a thin specialization) so each domain names its own host-canonical key file.

The provisioning contract

ControlPlaneProvisioning composes a domain with a declared Topology and answers the four invariants once:

• orchestrator_key() → the raw key the control-plane process receives. Fail-closed: raises ProvisioningError for a co-located topology when the key is empty (which would run the server OPEN).
• gateway_token() → the pre-minted gateway token the data plane receives, minted from the canonical key, never the key itself.

The Orchestrator ABC (orchestrator/lifecycle.py) holds one ControlPlaneProvisioning and exposes control_plane_key() and mint_gateway_token() over it. Each backend's orchestrator obtains its key through control_plane_key() and applies it via its own transport (docker/macOS: env var key_env; firecracker: SSH push to the guest) — the transport differs, the derivation no longer does.

Topology — the backend declares what it is

Topology captures the provisioning-relevant dimensions the issue names (combined-guest vs standalone, data plane co-located vs isolated). The default, COLOCATED, makes the signing key mandatory (fail-closed). Every current backend is co-located (docker/macOS: two containers on one host; firecracker: two VMs on one host, agents L3-isolated), so none needs to redeclare it — the safe posture is the default, and a genuinely isolated control plane opts out explicitly.

Data flow

host key file (per-domain, 0600, host-canonical)
        │  paths.host_signing_key(domain.key_filename)
        ▼
TrustDomain ── mint(role) ─────────────► gateway token ─► data-plane process (token_env / SSH)
        │  signing_key()                 (gateway role, unrewritable)
        ▼
ControlPlaneProvisioning.orchestrator_key()  ─► control-plane process (key_env / SSH)
        │  (fail-closed for co-located topology)
        ▼
OrchestratorClient ── CONTROL_PLANE.mint(cli) ─► host CLI's own operator token

Open questions

None blocking. #468 will add its host-controller domain as a second TrustDomain + ControlPlaneProvisioning-shaped consumer; whether the provisioning class is renamed to a domain-neutral DomainProvisioning at that point is a cosmetic call to make when #468 lands.