feat(control-plane): role-scoped signed tokens so the gateway can't drive operator routes

Review follow-up on #469: the data plane held the same control-plane secret
that authorizes every route, so a compromised egress/git-gate could queue a
supervise proposal AND approve it (or rewrite policy, read injected tokens) —
the (source_ip, identity_token) checks attribute the *bottle*, not the caller.

Replace the single shared bearer secret with role-scoped, HMAC-signed tokens
(compact HS256 JWTs, stdlib-only — no new dependency):

  * new `control_auth` mints/verifies `{role}` tokens; roles are `gateway`
    (data plane) and `cli` (host operator/launcher).
  * the orchestrator holds only the signing *key* and verifies; `dispatch`
    gates each route by role — `gateway` reaches /resolve + /supervise/
    {propose,poll}, everything else is `cli`-only (401 unauthenticated,
    403 wrong role).
  * the gateway is handed a pre-minted `gateway` token it cannot rewrite into
    `cli`; the host CLI mints its own `cli` token from the host key.
  * `gateway_init` scopes the signing key to the orchestrator process and the
    gateway token to the data-plane daemons, so even in the combined infra
    container a compromised data-plane daemon never sees the key.

Launchers (docker gateway + infra, macOS infra) inject the minted token(s);
Firecracker stays open behind its nft boundary. Open mode (no key) still grants
full `cli` access — the fail-visible fallback for tests.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

bot_bottle/backend/macos_container/infra.py

@@ -48,7 +48,9 @@ from ...orchestrator.lifecycle import (
     OrchestratorStartError,
     source_hash,
 )
+from ...control_auth import ROLE_GATEWAY, mint
 from ...paths import (
+    CONTROL_AUTH_JWT_ENV,
     CONTROL_PLANE_TOKEN_ENV,
     HOST_DB_FILENAME,
     host_control_plane_token,
@@ -237,18 +239,26 @@ class MacosInfraService:
             # Baked onto the container so `_source_current` can detect a real
             # control-plane code change and recreate.
             "--env", f"BOT_BOTTLE_SOURCE_HASH={current_hash}",
-            # The control-plane secret, for BOTH the control plane (to require
-            # it) and the gateway's PolicyResolver (to present it) — they share
-            # this one container. Bare `--env NAME` inherits the value from the
-            # run process below, so the secret never lands on argv or in
-            # `container inspect`'s command line. The agent runs in a SEPARATE
-            # container that is never given this var, which is the whole point.
+            # The control-plane signing key (control plane: verifies tokens) and
+            # the pre-minted `gateway` JWT (the gateway's PolicyResolver: presents
+            # it) — they share this one container, and gateway_init scopes each to
+            # its process so a compromised data-plane daemon never sees the key
+            # (issue #469 review). Bare `--env NAME` inherits the value from the
+            # run process below, so neither lands on argv or in `container
+            # inspect`'s command line. The agent runs in a SEPARATE container that
+            # is never given these vars, which is the whole point.
             "--env", CONTROL_PLANE_TOKEN_ENV,
+            "--env", CONTROL_AUTH_JWT_ENV,
             "--entrypoint", "sh",
             self.image,
             "-c", _init_script(self.port),
         ]
-        run_env = {**os.environ, CONTROL_PLANE_TOKEN_ENV: host_control_plane_token()}
+        _signing_key = host_control_plane_token()
+        run_env = {
+            **os.environ,
+            CONTROL_PLANE_TOKEN_ENV: _signing_key,
+            CONTROL_AUTH_JWT_ENV: mint(ROLE_GATEWAY, _signing_key),
+        }
         result = container_mod.run_container_argv(argv, env=run_env)
         if result.returncode != 0:
             raise OrchestratorStartError(

bot_bottle/control_auth.py

@@ -0,0 +1,100 @@
+"""Role-scoped control-plane credentials (issue #469 review follow-up).
+
+The control plane no longer trusts a single shared bearer secret for every
+route. Instead the orchestrator holds a *signing key* and issues short,
+HMAC-signed tokens (compact HS256 JWTs) that embed a **role** naming the kind
+of caller:
+
+  * ``gateway`` — the data plane (egress / git-gate / supervise). Restricted to
+    the agent-facing routes it actually needs (``/resolve``,
+    ``/supervise/propose``, ``/supervise/poll``).
+  * ``cli`` — the host operator / launcher. Full access to the mutating and
+    operator routes (launch/teardown, policy, ``/supervise/respond``, …).
+
+Only the orchestrator (and the host CLI, which shares the host trust domain)
+holds the signing key; the gateway is handed a pre-minted ``gateway`` token it
+cannot rewrite into a ``cli`` token. So a compromised data-plane process can no
+longer approve its own supervise proposals or drive operator routes — it can
+only present the ``gateway`` role it was issued (control_plane rejects it on
+operator routes with 403).
+
+Stdlib-only (HMAC-SHA256 over a JSON payload); no JWT dependency — the project
+carries no runtime pip deps. Tokens are **signed, not encrypted** (the role is
+not a secret) and **long-lived** (parity with the static token they replace;
+the security win is the unforgeable role claim, not rotation).
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+import hmac
+import json
+
+ROLE_GATEWAY = "gateway"
+ROLE_CLI = "cli"
+ROLES: frozenset[str] = frozenset({ROLE_GATEWAY, ROLE_CLI})
+
+_ALG = "HS256"
+
+
+def _b64url_encode(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
+
+
+def _b64url_decode(text: str) -> bytes:
+    padded = text + "=" * (-len(text) % 4)
+    return base64.urlsafe_b64decode(padded.encode("ascii"))
+
+
+def _sign(secret: str, signing_input: str) -> str:
+    mac = hmac.new(secret.encode("utf-8"), signing_input.encode("ascii"), hashlib.sha256)
+    return _b64url_encode(mac.digest())
+
+
+# The fixed, canonical JOSE header — the same for every token we mint.
+_HEADER_SEGMENT = _b64url_encode(
+    json.dumps({"alg": _ALG, "typ": "JWT"}, separators=(",", ":")).encode("utf-8")
+)
+
+
+def mint(role: str, secret: str) -> str:
+    """A compact HS256 token asserting `role`, signed with `secret`.
+
+    Raises ValueError for an unknown role (mint only what the control plane will
+    accept) or an empty signing key (an unsigned credential is never valid)."""
+    if role not in ROLES:
+        raise ValueError(f"unknown control-plane role {role!r}")
+    if not secret:
+        raise ValueError("cannot mint a control-plane token without a signing key")
+    payload = _b64url_encode(json.dumps({"role": role}, separators=(",", ":")).encode("utf-8"))
+    signing_input = f"{_HEADER_SEGMENT}.{payload}"
+    return f"{signing_input}.{_sign(secret, signing_input)}"
+
+
+def verify(token: str, secret: str) -> str | None:
+    """The role a valid `token` carries, or None if it is malformed, wrongly
+    signed, or names an unknown role. Constant-time signature check; rejects any
+    header whose alg isn't HS256 (no alg-confusion / `none`)."""
+    if not token or not secret:
+        return None
+    parts = token.split(".")
+    if len(parts) != 3:
+        return None
+    header_b64, payload_b64, sig = parts
+    expected = _sign(secret, f"{header_b64}.{payload_b64}")
+    if not hmac.compare_digest(sig, expected):
+        return None
+    try:
+        header = json.loads(_b64url_decode(header_b64))
+        payload = json.loads(_b64url_decode(payload_b64))
+    except (ValueError, binascii.Error):
+        return None
+    if not isinstance(header, dict) or header.get("alg") != _ALG:
+        return None
+    role = payload.get("role") if isinstance(payload, dict) else None
+    return role if isinstance(role, str) and role in ROLES else None
+
+
+__all__ = ["ROLE_GATEWAY", "ROLE_CLI", "ROLES", "mint", "verify"]

bot_bottle/gateway_init.py

@@ -54,6 +54,15 @@ class _DaemonSpec:
 _EGRESS_ONLY_ENV_PREFIXES: tuple[str, ...] = ("EGRESS_TOKEN_",)
 _READY_GATED_DAEMONS: tuple[str, ...] = ("git-gate", "git-http")
 
+# The control-plane signing key is the orchestrator's alone — verifying tokens.
+# The data-plane daemons instead hold the pre-minted `gateway` JWT they present.
+# Scoping each to its process (even in the combined infra container) keeps a
+# compromised data-plane daemon from reading the key and minting a `cli` token
+# (issue #469 review). Values match paths.CONTROL_PLANE_TOKEN_ENV /
+# CONTROL_AUTH_JWT_ENV; hardcoded here so this supervisor stays import-light.
+_SIGNING_KEY_ENV = "BOT_BOTTLE_CONTROL_PLANE_TOKEN"
+_GATEWAY_JWT_ENV = "BOT_BOTTLE_CONTROL_AUTH_JWT"
+
 # Daemons that must be requested explicitly via BOT_BOTTLE_GATEWAY_DAEMONS
 # and are NOT started in the default (env-var-unset) case. The orchestrator
 # only runs in the combined infra container, never in a standalone gateway.
@@ -61,16 +70,24 @@ _OPT_IN_DAEMONS: frozenset[str] = frozenset({"orchestrator"})
 
 
 def _env_for_daemon(name: str, base_env: dict[str, str]) -> dict[str, str]:
-    """Egress sees the full bundle env. Everyone else gets a copy
-    with `EGRESS_TOKEN_*` (and any other future egress-only
-    credential slots) stripped. Returns a fresh dict — callers
-    can mutate without affecting `base_env`."""
-    if name == "egress":
-        return dict(base_env)
-    return {
-        k: v for k, v in base_env.items()
-        if not any(k.startswith(p) for p in _EGRESS_ONLY_ENV_PREFIXES)
-    }
+    """Per-daemon env, scoped to what each process legitimately needs.
+    Returns a fresh dict — callers can mutate without affecting `base_env`.
+
+      * `EGRESS_TOKEN_*` upstream-auth slots go to egress only.
+      * the control-plane signing key goes to the orchestrator only.
+      * the pre-minted `gateway` JWT goes to the data-plane daemons only (the
+        orchestrator verifies tokens, it never presents one)."""
+    env = dict(base_env)
+    if name != "egress":
+        env = {
+            k: v for k, v in env.items()
+            if not any(k.startswith(p) for p in _EGRESS_ONLY_ENV_PREFIXES)
+        }
+    if name == "orchestrator":
+        env.pop(_GATEWAY_JWT_ENV, None)
+    else:
+        env.pop(_SIGNING_KEY_ENV, None)
+    return env
 
 
 # The orchestrator is listed first so it starts before the gateway daemons,

bot_bottle/orchestrator/client.py

@@ -18,6 +18,7 @@ import urllib.request
 from collections.abc import Iterable
 from dataclasses import dataclass
 
+from ..control_auth import ROLE_CLI, mint
 from ..paths import host_control_plane_token
 from .control_plane import CONTROL_AUTH_HEADER
 
@@ -25,12 +26,14 @@ DEFAULT_TIMEOUT_SECONDS = 5.0
 
 
 def _host_auth_token() -> str:
-    """The per-host control-plane secret, or "" if it can't be read. "" means
-    'send no auth header' — correct against an open (unconfigured) control
-    plane, and harmlessly rejected by a secured one."""
+    """A freshly minted `cli`-role token, signed with the host control-plane
+    key, or "" if the key can't be read. The host CLI shares the orchestrator's
+    trust domain, so it holds the signing key and mints its own operator token;
+    "" means 'send no auth header' — correct against an open (unconfigured)
+    control plane, and harmlessly rejected by a secured one."""
     try:
-        return host_control_plane_token()
-    except OSError:
+        return mint(ROLE_CLI, host_control_plane_token())
+    except (OSError, ValueError):
         return ""
 
 

bot_bottle/orchestrator/control_plane.py

@@ -53,7 +53,6 @@ returned only once, to the caller that launches the bottle.
 
 from __future__ import annotations
 
-import hmac
 import http.server
 import json
 import os
@@ -62,6 +61,7 @@ import sys
 import typing
 from urllib.parse import urlsplit
 
+from ..control_auth import ROLE_CLI, ROLES, verify
 from ..paths import CONTROL_PLANE_TOKEN_ENV
 from ..supervise_types import TOOLS
 from .service import Orchestrator
@@ -69,14 +69,32 @@ from .service import Orchestrator
 # JSON body payload type (parsed request / rendered response).
 Json = dict[str, object]
 
-# The request header carrying the per-host control-plane secret. Every route
-# except `GET /health` requires it (see `dispatch`). The trusted callers hold
-# the secret (the gateway's PolicyResolver, the host CLI's OrchestratorClient);
-# an agent that can merely *reach* the port cannot present it, so it can't
-# enumerate bottles, rewrite policy, read injected upstream tokens, or approve
-# its own supervise proposals.
+# The request header carrying the caller's role-scoped control-plane token (a
+# signed JWT naming the caller's role — see control_auth). The role gates which
+# routes the caller may reach: the data plane holds a `gateway` token good only
+# for the agent-facing lookups; the host CLI holds a `cli` token for the
+# operator/mutating routes. An agent that can merely *reach* the port holds no
+# token at all, and a compromised gateway holds only `gateway` — neither can
+# drive the operator routes (approve proposals, rewrite policy, read tokens).
 CONTROL_AUTH_HEADER = "x-bot-bottle-control-auth"
 
+# The routes the data plane (role `gateway`) is allowed to reach — exactly the
+# per-request lookups PolicyResolver makes. Every other authenticated route is
+# operator-only. `cli` is a superset role: it may reach any route.
+_GATEWAY_ROUTES: frozenset[tuple[str, str]] = frozenset({
+    ("POST", "/resolve"),
+    ("POST", "/supervise/propose"),
+    ("POST", "/supervise/poll"),
+})
+
+
+def _allowed_roles(method: str, route: str) -> frozenset[str]:
+    """The roles permitted on `(method, route)`: `gateway` or `cli` on the
+    data-plane routes, `cli`-only everywhere else."""
+    if (method, route) in _GATEWAY_ROUTES:
+        return ROLES
+    return frozenset({ROLE_CLI})
+
 
 def _parse_json_object(body: bytes) -> Json:
     """Parse a JSON object body. Raises ValueError for non-objects / bad JSON."""
@@ -89,28 +107,33 @@ def _parse_json_object(body: bytes) -> Json:
 
 
 def dispatch(  # pylint: disable=too-many-return-statements,too-many-branches
-    orch: Orchestrator, method: str, path: str, body: bytes, *, authorized: bool = True,
+    orch: Orchestrator, method: str, path: str, body: bytes, *, role: str | None = ROLE_CLI,
 ) -> tuple[int, Json]:
     """Route one control-plane request to a (status, payload) pair. Pure —
     no I/O beyond the orchestrator — so it is fully testable without a socket.
 
-    `authorized` is whether the request presented the control-plane secret (or
-    no secret is configured — see `ControlPlaneServer`). Every route except
-    `GET /health` requires it: the source-IP + identity-token checks inside
-    `/resolve` and `/attribute` authenticate the *bottle* a request is about,
-    not the *caller*, so without this gate any agent that can reach the port
-    could rewrite another bottle's policy, read the injected upstream tokens,
-    or approve its own supervise proposals. Defaults True so unit tests of the
-    routing logic don't have to thread it through."""
+    `role` is the caller's verified control-plane role (`gateway` or `cli`), or
+    None for an unauthenticated request; an open-mode server (no signing key
+    configured — see `ControlPlaneServer`) passes `cli`. Every route except
+    `GET /health` requires a role: a missing role is 401, and a role that
+    doesn't cover the route is 403 — so a `gateway` data-plane token can reach
+    `/resolve` + `/supervise/{propose,poll}` but not the operator routes
+    (rewrite policy, read injected tokens, approve its own supervise proposals).
+    The source-IP + identity-token checks inside `/resolve` and `/attribute`
+    authenticate the *bottle* a request is about, not the *caller*, so this role
+    gate is what protects the caller-privileged routes. Defaults `cli` so unit
+    tests of the routing logic don't have to thread it through."""
     route = urlsplit(path).path.rstrip("/") or "/"
 
     if method == "GET" and route == "/health":
         return 200, {"status": "ok"}
 
-    if not authorized:
-        # Everything below is a trusted-caller operation. Deny before touching
-        # the registry / broker / supervise store.
+    # Role gate — every route below is a trusted-caller operation. Deny before
+    # touching the registry / broker / supervise store.
+    if role is None:
         return 401, {"error": "control-plane authentication required"}
+    if role not in _allowed_roles(method, route):
+        return 403, {"error": "insufficient role for this route"}
 
     if method == "GET" and route == "/gateway":
         return 200, orch.gateway_status()
@@ -343,10 +366,10 @@ class Handler(http.server.BaseHTTPRequestHandler):
         assert isinstance(server, ControlPlaneServer)
         length = int(self.headers.get("Content-Length") or 0)
         body = self.rfile.read(length) if length > 0 else b""
-        authorized = server.is_authorized(self.headers.get(CONTROL_AUTH_HEADER, ""))
+        role = server.role_for(self.headers.get(CONTROL_AUTH_HEADER, ""))
         try:
             status, payload = dispatch(
-                server.orchestrator, method, self.path, body, authorized=authorized)
+                server.orchestrator, method, self.path, body, role=role)
         except Exception as e:  # noqa: BLE001 — the control plane must stay up
             sys.stderr.write(f"orchestrator: {method} {self.path} failed: {e!r}\n")
             sys.stderr.flush()
@@ -374,22 +397,24 @@ class Handler(http.server.BaseHTTPRequestHandler):
 class ControlPlaneServer(socketserver.ThreadingMixIn, http.server.HTTPServer):
     """Threading HTTP server that carries the orchestrator for its handlers.
 
-    Holds the per-host control-plane secret (from `$BOT_BOTTLE_CONTROL_PLANE_TOKEN`,
-    injected by the launcher into this container only). When a secret is set,
-    every route but `/health` requires it; when it is unset the server runs
-    **open** and says so loudly at startup — a fail-visible fallback for tests
-    and any backend that hasn't wired the secret yet (e.g. Firecracker, whose
-    nft boundary already blocks agents from the control-plane port)."""
+    Holds the per-host control-plane *signing key* (from
+    `$BOT_BOTTLE_CONTROL_PLANE_TOKEN`, injected by the launcher into the
+    orchestrator process only) and verifies each request's role-scoped token
+    against it. When a key is set, every route but `/health` requires a valid
+    token whose role covers the route; when it is unset the server runs **open**
+    (full `cli` access) and says so loudly at startup — a fail-visible fallback
+    for tests and any backend that hasn't wired the key yet (e.g. Firecracker,
+    whose nft boundary already blocks agents from the control-plane port)."""
 
     daemon_threads = True
     allow_reuse_address = True
 
     def __init__(self, address: tuple[str, int], orchestrator: Orchestrator) -> None:
         self.orchestrator = orchestrator
-        self._auth_token = os.environ.get(CONTROL_PLANE_TOKEN_ENV, "").strip()
-        if not self._auth_token:
+        self._signing_key = os.environ.get(CONTROL_PLANE_TOKEN_ENV, "").strip()
+        if not self._signing_key:
             sys.stderr.write(
-                "orchestrator: WARNING — no control-plane secret "
+                "orchestrator: WARNING — no control-plane signing key "
                 f"(${CONTROL_PLANE_TOKEN_ENV}); running WITHOUT caller "
                 "authentication. Any client that can reach this port can drive "
                 "it. Backends that put the control plane on an agent-reachable "
@@ -398,13 +423,15 @@ class ControlPlaneServer(socketserver.ThreadingMixIn, http.server.HTTPServer):
             sys.stderr.flush()
         super().__init__(address, Handler)
 
-    def is_authorized(self, presented: str) -> bool:
-        """True iff the request may proceed past `/health`: either no secret is
-        configured (open mode) or the presented header matches it. Constant-time
-        compare so a wrong token leaks nothing timing-wise."""
-        if not self._auth_token:
-            return True
-        return hmac.compare_digest(presented, self._auth_token)
+    def role_for(self, presented: str) -> str | None:
+        """The role the request is authorized as, or None if unauthenticated.
+        Open mode (no signing key) grants full `cli` access — the fail-visible
+        fallback. Otherwise verify the presented signed token; a missing/invalid
+        token yields None (→ 401), a valid one yields its `gateway`/`cli`
+        role (→ per-route 401/403 in `dispatch`)."""
+        if not self._signing_key:
+            return ROLE_CLI
+        return verify(presented, self._signing_key)
 
 
 def make_server(

bot_bottle/orchestrator/gateway.py

@@ -22,9 +22,10 @@ import os
 import time
 from pathlib import Path
 
+from ..control_auth import ROLE_GATEWAY, mint
 from ..docker_cmd import run_docker
 from ..paths import (
-    CONTROL_PLANE_TOKEN_ENV,
+    CONTROL_AUTH_JWT_ENV,
     host_control_plane_token,
     host_gateway_ca_dir,
 )
@@ -252,11 +253,14 @@ class DockerGateway(Gateway):
         # policy against the control plane per request (guaranteed non-empty by
         # the check above).
         argv += ["--env", f"BOT_BOTTLE_ORCHESTRATOR_URL={self._orchestrator_url}"]
-        # ...and present the control-plane secret on those /resolve calls (the
-        # control plane requires it). Bare `--env NAME` keeps the value off argv
-        # / `docker inspect`; only the gateway (not the agent) is given it.
-        argv += ["--env", CONTROL_PLANE_TOKEN_ENV]
-        run_env[CONTROL_PLANE_TOKEN_ENV] = host_control_plane_token()
+        # ...presenting a role-scoped `gateway` token (a signed JWT minted from
+        # the host signing key) on those calls. The gateway never receives the
+        # signing key — only this pre-minted token, which it cannot rewrite into
+        # a `cli` token, so a compromised data-plane process can't drive the
+        # operator routes (issue #469 review). Bare `--env NAME` keeps the value
+        # off argv / `docker inspect`; only the gateway (not the agent) is given it.
+        argv += ["--env", CONTROL_AUTH_JWT_ENV]
+        run_env[CONTROL_AUTH_JWT_ENV] = mint(ROLE_GATEWAY, host_control_plane_token())
         argv.append(self.image_ref)
         proc = run_docker(argv, env=run_env)
         if proc.returncode != 0:

bot_bottle/orchestrator/lifecycle.py

@@ -22,8 +22,10 @@ import urllib.request
 from pathlib import Path
 
 from .. import log
+from ..control_auth import ROLE_GATEWAY, mint
 from ..docker_cmd import run_docker
 from ..paths import (
+    CONTROL_AUTH_JWT_ENV,
     CONTROL_PLANE_TOKEN_ENV,
     bot_bottle_root,
     host_control_plane_token,
@@ -186,6 +188,7 @@ class OrchestratorService:
         so a later `ensure_running` can detect a real code change."""
         self._ensure_network()
         run_docker(["docker", "rm", "--force", self._infra_name])
+        _signing_key = host_control_plane_token()
         proc = run_docker([
             "docker", "run", "--detach",
             "--name", self._infra_name,
@@ -209,16 +212,23 @@ class OrchestratorService:
             # Orchestrator registry DB on the host (sole writer: control plane).
             "--volume", f"{self._host_root}:{_ROOT_IN_CONTAINER}",
             "--env", f"BOT_BOTTLE_ROOT={_ROOT_IN_CONTAINER}",
-            # Control-plane secret: required by the orchestrator (to enforce)
-            # and by the gateway daemons (to present on /resolve calls).
+            # Control-plane signing key (orchestrator: verifies tokens) + the
+            # pre-minted `gateway` JWT (data-plane daemons: present it). gateway_init
+            # scopes each to its process, so a compromised data-plane daemon never
+            # sees the key and can't mint a `cli` token (issue #469 review).
             "--env", CONTROL_PLANE_TOKEN_ENV,
+            "--env", CONTROL_AUTH_JWT_ENV,
             # Gateway daemons reach the orchestrator over loopback at its
             # fixed internal port (DEFAULT_PORT), independent of self.port.
             "--env", f"BOT_BOTTLE_ORCHESTRATOR_URL=http://127.0.0.1:{DEFAULT_PORT}",
             # Opt the orchestrator into gateway_init's supervise tree.
             "--env", f"BOT_BOTTLE_GATEWAY_DAEMONS={_INFRA_DAEMONS}",
             self.image,
-        ], env={**os.environ, CONTROL_PLANE_TOKEN_ENV: host_control_plane_token()})
+        ], env={
+            **os.environ,
+            CONTROL_PLANE_TOKEN_ENV: _signing_key,
+            CONTROL_AUTH_JWT_ENV: mint(ROLE_GATEWAY, _signing_key),
+        })
         if proc.returncode != 0:
             raise OrchestratorStartError(
                 f"infra container failed to start: {proc.stderr.strip()}"

bot_bottle/paths.py

@@ -37,7 +37,16 @@ HOST_DB_FILENAME = "bot-bottle.db"
 # trusted callers (control plane, gateway, host CLI) and never handed to an
 # agent, so an agent that can reach the control-plane port still can't drive it.
 CONTROL_PLANE_TOKEN_FILENAME = "control-plane-token"
+# The env var carrying the control-plane *signing key* — held only by the
+# orchestrator (to verify tokens) and the host CLI (to mint its own), never by
+# the data plane. Same value as the host token file; the name is unchanged for
+# backward compatibility with existing launchers.
 CONTROL_PLANE_TOKEN_ENV = "BOT_BOTTLE_CONTROL_PLANE_TOKEN"
+# The env var carrying the data plane's pre-minted `gateway`-role token (a
+# signed JWT the launcher mints from the signing key). The gateway presents this
+# on /resolve + /supervise/{propose,poll}; it never holds the signing key, so it
+# cannot forge a higher-privilege `cli` token (issue #469 review).
+CONTROL_AUTH_JWT_ENV = "BOT_BOTTLE_CONTROL_AUTH_JWT"
 
 # The host directory holding the gateway's persistent mitmproxy CA. Bind-mounted
 # into the infra/gateway container at mitmproxy's confdir so the self-generated
@@ -124,6 +133,7 @@ __all__ = [
     "HOST_DB_FILENAME",
     "CONTROL_PLANE_TOKEN_FILENAME",
     "CONTROL_PLANE_TOKEN_ENV",
+    "CONTROL_AUTH_JWT_ENV",
     "GATEWAY_CA_DIRNAME",
     "bot_bottle_root",
     "host_db_path",

bot_bottle/policy_resolver.py

@@ -34,21 +34,22 @@ import urllib.request
 
 DEFAULT_TIMEOUT_SECONDS = 2.0
 
-# The control-plane secret this gateway presents on every /resolve call, read
-# from the env the launcher injects into the gateway container. The control
-# plane requires it (orchestrator/control_plane.py). Constant + env-var name are
-# duplicated here rather than imported because this module is COPYed flat into
-# the gateway image, free of bot-bottle imports — same rationale as
-# IDENTITY_HEADER in egress_addon / git_http_backend.
+# The role-scoped `gateway` token this data plane presents on every control-plane
+# call, read from the env the launcher injects into the gateway (a pre-minted
+# signed JWT — the gateway never holds the signing key, so it can't forge a
+# higher-privilege `cli` token). Constant + env-var name are duplicated here
+# rather than imported because this module is COPYed flat into the gateway image,
+# free of bot-bottle imports — same rationale as IDENTITY_HEADER in egress_addon
+# / git_http_backend.
 CONTROL_AUTH_HEADER = "x-bot-bottle-control-auth"
-CONTROL_PLANE_TOKEN_ENV = "BOT_BOTTLE_CONTROL_PLANE_TOKEN"
+CONTROL_AUTH_JWT_ENV = "BOT_BOTTLE_CONTROL_AUTH_JWT"
 
 
 def _control_auth_headers() -> dict[str, str]:
-    """The auth header to send, or {} when no secret is configured (an open
+    """The auth header to send, or {} when no token is configured (an open
     control plane, e.g. Firecracker behind its nft boundary — sending nothing
     is correct there and harmlessly ignored)."""
-    token = os.environ.get(CONTROL_PLANE_TOKEN_ENV, "").strip()
+    token = os.environ.get(CONTROL_AUTH_JWT_ENV, "").strip()
     return {CONTROL_AUTH_HEADER: token} if token else {}