Why this complements #30179

#30179 explicitly cut one corner in its Scope cuts (v1) section:

The CA is a 10-year self-signed cert. Rotation is manual for now.

This PR closes that gap: a first-class, audited rotation workflow so operators never have to hand-run openssl genrsa, and the recovery path is exercised in CI instead of being first attempted under pressure.

A companion host-hardening survey PR (hermes egress harden) is open separately against the same base.

What lands

hermes egress rotate-ca:

1. Archives the live ca.crt to ~/.hermes/proxy/ca-archive/ca-<YYYYMMDD-HHMMSS>.crt before touching the live cert. Archive dir keeps the 5 most recent; older ones are pruned.
2. Mints a fresh CA + key via ensure_ca_cert(force=True) — the same atomic 0o600-key write + os.replace path as first-boot generation.
3. If --no-restart isn't set and the daemon is alive: stop_proxy() then start_proxy(refresh_secrets_from_bitwarden=..., bitwarden_config=...) so the live proxy picks up the new signing key and keeps honouring the operator's existing credential-source choice.
4. Appends a structured entry to ~/.hermes/proxy/rotation-history.jsonl:

   {"ts": "2026-05-30T05:32:00Z", "old_fingerprint_sha256": "...", "new_fingerprint_sha256": "...", "reason": "annual rotation", "operator": "alice", "subject": "/CN=hermes iron-proxy CA", "valid_until": "2036-05-28T05:32:00Z"}

Flags:

hermes egress rotate-ca lists labeled hermes.sandbox=true containers and prompts by default when any are running — containers mount ca.crt at create time, so a sandbox started before the rotation keeps trusting the old CA until recreated.

New surfaces

Failure modes considered

Bugbot review fixes baked in

🟡 Medium severity — daemon restart silently degraded Bitwarden-mode proxies

The original implementation called start_proxy() bare in the rotation restart path. Since start_proxy defaults refresh_secrets_from_bitwarden=False and bitwarden_config=None, an operator on credential_source: bitwarden would have come back up with a proxy that's running but unable to inject credentials — the worst kind of silent degradation. Caught by Cursor Bugbot on the original cross-fork iteration.

Fix: rotate_ca() now accepts refresh_secrets_from_bitwarden and bitwarden_config kwargs and forwards them to start_proxy(). cmd_rotate_ca computes these from proxy_cfg identically to cmd_start (credential_source: bitwarden + secrets.bitwarden.enabled → propagate). Regression test added: test_rotate_passes_bitwarden_args_through_to_start_proxy.

🟢 Low severity — duplicated _ca_not_before / _ca_not_after

Bugbot flagged a ~25-line duplication between two openssl-shelling date helpers. Resolved by simple elision — _ca_not_before was only used by the companion doctor check that's deferred to a follow-up PR (it needs a DoctorCheck type from a separate stack). _ca_not_after stays as the single date helper in this PR.

Validation

$ pytest tests/test_iron_proxy*.py -q
109 passed, 1 skipped in 3.88s

The 1 skip is the existing E2E test gated behind HERMES_RUN_E2E=1 (unchanged).

8/8 in the new test file:

• rotate with no daemon: writes + archives, no stop_proxy / start_proxy called
• rotate with running daemon: stop_proxy then start_proxy, in order
• --dry-run: zero mtime changes (filesystem stat-before/after)
• --reason recorded with valid 64-hex fingerprints (old ≠ new)
• archive pruning: 7 archives in → only the 5 most recent retained
• --no-restart: daemon left alone (no stop/start calls)
• regression: bitwarden kwargs propagated through rotate_ca to start_proxy
• fingerprint redaction: failures in fingerprint reads never echo a full SHA-256 in error messages — first-8/last-8 only

Manual end-to-end smoke (isolated HERMES_HOME): --dry-run changed nothing; real rotate-ca --reason "annual rotation" archived the old cert, minted a 10-year CA, and wrote a parseable history line.

Coverage gaps

• No verify-trust subcommand (verifying live sandboxes still trust the new CA after restart). Deliberately deferred — documented as a known follow-up in the user guide.
• Interactive confirmation prompt path is exercised manually, not unit-tested (the underlying rotate_ca engine is fully tested, the prompt is a thin CLI wrapper).
• Companion ca-rotation doctor check that warns on rotation age depends on a DoctorCheck type that lives on a separate stacked branch (broader doctor / audit work). Lands once that work merges upstream.

Ambiguity flags

1. Bitwarden propagation surface — added two kwargs (refresh_secrets_from_bitwarden, bitwarden_config) to rotate_ca() rather than introducing a RotationOptions dataclass. Two args, mirrors start_proxy signature, keeps the call site readable. If you want a single options object, that's a refactor we can do here or later.
2. Archive retention = 5 — picked as a balance between "useful audit history" and "filesystem clutter." Controlled by _CA_ARCHIVE_KEEP constant.
3. Running sandbox prompt is interactive — uses input(), which means non-TTY callers (CI, scripts) have to pass --force. Documented in the help text. Open to flipping to "default proceed, --prompt to ask" if that fits the project conventions better.

Attribution

Opened by Bartok9 (Daniel Pike) at Daniel's request, in response to Teknium's invitation on X to @catalinmpit for a security review of #30179. Teknium's prompt was essentially "can we get a security review of how Hermes' egress proxy holds up in a real deployment?" — and this PR turns the manual openssl rotation step #30179 mentions into a first-class audited command.