fix(gateway): persist mitmproxy CA on the host, not a named volume (#450)

The shared gateway self-generates a mitmproxy CA that every bottle installs
to trust its TLS interception. It was persisted on a Docker named volume,
which survives `docker rm` but is silently wiped by `docker volume prune` /
`docker system prune --volumes` during routine host maintenance. When that
happens the gateway mints a fresh CA on restart, and every already-running
bottle fails the TLS handshake even after it re-resolves and reconnects to
the moved gateway — a re-attachment blocker distinct from #443/#445.

Move CA persistence to a host bind-mount under the app-data root
(`bot_bottle_root()/gateway-ca`, via `host_gateway_ca_dir()`), mirroring how
the shared DB and control-plane token already live on the host. Docker never
prunes a path under the root, and it stays inspectable + rotatable from the
host. mitmproxy already adopts an existing CA and generates one only on first
run, so the bind-mount gives adopt-existing/generate-on-first-run for free.

Add an explicit rollover path: `rotate_gateway_ca()` clears the persisted CA
so the next start remints it, and `python -m bot_bottle.orchestrator.rotate_ca`
wires that together with dropping the running gateway container (whose
mitmproxy still holds the old CA in memory). Rotation stays an operator action
— it doesn't auto-re-provision running bottles, which re-attach to pick up the
new anchor.

Scope: the Docker infra/gateway path (the "infra container" in the report).
The macOS (`container`-only volume) and Firecracker (VM-attached ext4) backends
persist the CA differently and are unaffected.

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

tests/unit/test_orchestrator_gateway.py

@@ -2,7 +2,9 @@
 
 from __future__ import annotations
 
+import tempfile
 import unittest
+from pathlib import Path
 from unittest.mock import Mock, patch
 
 from bot_bottle.orchestrator.gateway import (
@@ -10,7 +12,10 @@ from bot_bottle.orchestrator.gateway import (
     GATEWAY_NAME,
     DockerGateway,
     GatewayError,
+    rotate_gateway_ca,
 )
+from bot_bottle.paths import GATEWAY_CA_DIRNAME, host_gateway_ca_dir
+from tests.unit import use_bottle_root
 
 
 _CA_PEM = "-----BEGIN CERTIFICATE-----\nMII...\n-----END CERTIFICATE-----\n"
@@ -27,6 +32,11 @@ _ORCH_URL = "http://orchestrator:9000"
 
 class TestDockerGateway(unittest.TestCase):
     def setUp(self) -> None:
+        # Redirect the app-data root so ensure_running's host-dir mkdirs (CA +
+        # DB) land in a throwaway dir, not the real ~/.bot-bottle.
+        self._tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self._tmp.cleanup)
+        self.addCleanup(use_bottle_root(Path(self._tmp.name)))
         # Resolver-only data plane (PRD 0070): running the gateway requires an
         # orchestrator URL, so the fixture supplies one.
         self.sc = DockerGateway("bot-bottle-gateway:latest", orchestrator_url=_ORCH_URL)
@@ -103,8 +113,17 @@ class TestDockerGateway(unittest.TestCase):
         self.assertIn("bot-bottle-gateway:latest", runs[0])
         # Runs on the shared gateway network so agents can reach it by IP.
         self.assertEqual(self.sc.network, runs[0][runs[0].index("--network") + 1])
-        # Persists its CA on a named volume so agents keep trusting it.
-        self.assertTrue(any("mitmproxy" in a for a in runs[0]))
+        # Persists its CA on a HOST bind-mount (not a docker named volume, which
+        # `docker volume prune` would wipe — issue #450) so agents keep trusting
+        # it across restarts. The mount source is the host gateway-CA dir.
+        ca_mounts = [
+            a for a in runs[0]
+            if a.endswith(":/home/mitmproxy/.mitmproxy")
+        ]
+        self.assertEqual(1, len(ca_mounts))
+        src = ca_mounts[0].rsplit(":", 1)[0]
+        self.assertTrue(src.endswith("/" + GATEWAY_CA_DIRNAME), src)
+        self.assertTrue(Path(src).is_absolute(), src)
         # Shares the ONE host DB: the supervise daemon queues into the same
         # file the orchestrator + operator (over HTTP) use.
         self.assertTrue(any(
@@ -234,5 +253,49 @@ class TestDockerGatewayBuild(unittest.TestCase):
                 self.sc.ensure_built()
 
 
+class TestRotateGatewayCa(unittest.TestCase):
+    """rotate_gateway_ca clears the persisted CA so the next start remints it."""
+
+    def setUp(self) -> None:
+        self._tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self._tmp.cleanup)
+        self.addCleanup(use_bottle_root(Path(self._tmp.name)))
+
+    def _seed_ca(self) -> Path:
+        ca_dir = host_gateway_ca_dir()
+        # A representative mitmproxy confdir: the CA identity + derived encodings,
+        # plus one non-CA file that rotation must leave untouched.
+        for name in (
+            "mitmproxy-ca.pem",
+            "mitmproxy-ca-cert.pem",
+            "mitmproxy-ca-cert.cer",
+            "mitmproxy-ca-cert.p12",
+        ):
+            (ca_dir / name).write_text("x")
+        (ca_dir / "combined-trust.pem").write_text("keep")
+        return ca_dir
+
+    def test_removes_ca_material_only(self) -> None:
+        ca_dir = self._seed_ca()
+        removed = rotate_gateway_ca(ca_dir)
+        self.assertEqual(4, len(removed))
+        self.assertTrue(all(p.name.startswith("mitmproxy-ca") for p in removed))
+        # The CA files are gone; the non-CA trust bundle survives.
+        self.assertEqual(
+            {"combined-trust.pem"}, {p.name for p in ca_dir.iterdir()}
+        )
+
+    def test_defaults_to_host_ca_dir(self) -> None:
+        self._seed_ca()
+        removed = rotate_gateway_ca()  # no arg → host_gateway_ca_dir()
+        self.assertTrue(removed)
+        self.assertEqual(
+            [], list(host_gateway_ca_dir().glob("mitmproxy-ca*"))
+        )
+
+    def test_idempotent_when_no_ca(self) -> None:
+        self.assertEqual([], rotate_gateway_ca(host_gateway_ca_dir()))
+
+
 if __name__ == "__main__":
     unittest.main()

tests/unit/test_orchestrator_lifecycle.py

@@ -16,6 +16,7 @@ from bot_bottle.orchestrator.lifecycle import (
     OrchestratorStartError,
     source_hash,
 )
+from bot_bottle.paths import GATEWAY_CA_DIRNAME
 from tests.unit import use_bottle_root
 
 _URLOPEN = "bot_bottle.orchestrator.lifecycle.urllib.request.urlopen"
@@ -115,6 +116,14 @@ class TestOrchestratorService(unittest.TestCase):
         # Gateway daemons + orchestrator explicitly opted in.
         daemons_flag = "BOT_BOTTLE_GATEWAY_DAEMONS=egress,git-http,supervise,orchestrator"
         self.assertIn("orchestrator", argv[argv.index(daemons_flag)])
+        # The mitmproxy CA persists on a HOST bind-mount under the app-data root
+        # (not a docker named volume `docker volume prune` would wipe — #450), so
+        # a restarted infra container keeps the CA every running bottle trusts.
+        ca_mounts = [a for a in argv if a.endswith(":/home/mitmproxy/.mitmproxy")]
+        self.assertEqual(1, len(ca_mounts))
+        src = ca_mounts[0].rsplit(":", 1)[0]
+        self.assertTrue(src.startswith(self._tmp.name), src)
+        self.assertTrue(src.endswith("/" + GATEWAY_CA_DIRNAME), src)
 
     def test_ensure_running_builds_all_images(self) -> None:
         calls: list[list[str]] = []

tests/unit/test_orchestrator_rotate_ca.py

@@ -0,0 +1,59 @@
+"""Unit: the `rotate_ca` one-shot CLI (issue #450). Docker mocked."""
+
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import Mock, patch
+
+from bot_bottle.orchestrator import rotate_ca
+from bot_bottle.orchestrator.gateway import GATEWAY_NAME
+from bot_bottle.orchestrator.lifecycle import INFRA_NAME
+from bot_bottle.paths import host_gateway_ca_dir
+from tests.unit import use_bottle_root
+
+_RUN = "bot_bottle.orchestrator.rotate_ca.run_docker"
+
+
+def _proc(returncode: int = 0, stdout: str = "", stderr: str = "") -> Mock:
+    return Mock(returncode=returncode, stdout=stdout, stderr=stderr)
+
+
+class TestRotateCaCli(unittest.TestCase):
+    def setUp(self) -> None:
+        self._tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self._tmp.cleanup)
+        self.addCleanup(use_bottle_root(Path(self._tmp.name)))
+
+    def test_clears_ca_and_drops_gateway_containers(self) -> None:
+        ca_dir = host_gateway_ca_dir()
+        (ca_dir / "mitmproxy-ca.pem").write_text("x")
+        (ca_dir / "mitmproxy-ca-cert.pem").write_text("x")
+
+        calls: list[list[str]] = []
+
+        def fake(argv: list[str], **_kw: object) -> Mock:
+            calls.append(argv)
+            # Report a removed container name so the CLI logs it.
+            return _proc(stdout=argv[-1])
+
+        with patch(_RUN, side_effect=fake):
+            self.assertEqual(0, rotate_ca.main([]))
+
+        # Persisted CA is gone → next start remints it.
+        self.assertEqual([], list(ca_dir.glob("mitmproxy-ca*")))
+        # Both the infra container and the standalone gateway are force-removed
+        # so no mitmproxy keeps serving the old CA from memory.
+        removed = {c[-1] for c in calls if c[:3] == ["docker", "rm", "--force"]}
+        self.assertEqual({INFRA_NAME, GATEWAY_NAME}, removed)
+
+    def test_succeeds_with_no_persisted_ca(self) -> None:
+        with patch(_RUN, return_value=_proc()) as m:
+            self.assertEqual(0, rotate_ca.main([]))
+        # Still tears down any running gateway even when there was no CA on disk.
+        self.assertTrue(m.called)
+
+
+if __name__ == "__main__":
+    unittest.main()