feat(secrets): pluggable secret backend with OpenBao read (Phase 4)

- secret_backends.py: SecretBackend protocol, FileSecretBackend (historical),
  OpenBaoBackend (KV-v2 read + file fallback), build_backend() env-selected
- _read_secret delegates to the active backend; default is file, so production
  is unchanged until CASTLE_SECRET_BACKEND=openbao
- OpenBao token bootstraps from the file backend; missing/unreachable falls back
- tests: file hit/miss, backend selection, unreachable + empty-token fallback

Read path verified live against castle-openbao. Write path, auto-unseal-on-boot,
and TLS hardening documented as remaining for full OpenBao production use.

core/src/castle_core/config.py

@@ -319,10 +319,15 @@ def resolve_env_vars(
 
 
 def _read_secret(name: str) -> str:
-    """Read a secret from ~/.castle/secrets/<name>. Returns placeholder if not found."""
-    secret_path = SECRETS_DIR / name
-    if secret_path.exists():
-        return secret_path.read_text().strip()
+    """Resolve a secret via the active backend (file by default; OpenBao opt-in).
+
+    Returns a ``<MISSING_SECRET:...>`` placeholder if unresolved (never raises).
+    """
+    from castle_core.secret_backends import build_backend
+
+    value = build_backend(SECRETS_DIR).read(name)
+    if value is not None:
+        return value
     return f"<MISSING_SECRET:{name}>"
 
 

core/src/castle_core/secret_backends.py

@@ -0,0 +1,90 @@
+"""Pluggable secret backends for ``${secret:NAME}`` resolution.
+
+Default is the **file** backend (``~/.castle/secrets/<name>``) — identical to the
+historical behavior, so nothing changes unless a backend is explicitly selected
+via ``CASTLE_SECRET_BACKEND``.
+
+The **openbao** backend reads from an OpenBao/Vault KV-v2 mount and falls back to
+the file backend, which is also how it bootstraps: the OpenBao *token* itself is a
+file secret (it can't live in the vault it unlocks).
+
+Selection (env, so it works in both the CLI and the systemd-run API):
+  CASTLE_SECRET_BACKEND        file | openbao        (default: file)
+  CASTLE_OPENBAO_ADDR          http://localhost:8200
+  CASTLE_OPENBAO_MOUNT         castle                (kv-v2 mount path)
+  CASTLE_OPENBAO_TOKEN_SECRET  OPENBAO_TOKEN         (file secret holding the token)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.request
+from pathlib import Path
+from typing import Protocol
+
+
+class SecretBackend(Protocol):
+    def read(self, name: str) -> str | None: ...
+
+
+class FileSecretBackend:
+    """Reads ``<secrets_dir>/<name>`` (the historical behavior)."""
+
+    def __init__(self, secrets_dir: Path) -> None:
+        self._dir = secrets_dir
+
+    def read(self, name: str) -> str | None:
+        path = self._dir / name
+        if path.exists():
+            return path.read_text().strip()
+        return None
+
+
+class OpenBaoBackend:
+    """Reads from an OpenBao/Vault KV-v2 mount; falls back to ``fallback``.
+
+    A missing key, an auth failure, or an unreachable server all fall through to
+    the fallback — so a partly-migrated vault and the bootstrap token both resolve.
+    """
+
+    def __init__(
+        self, addr: str, token: str, mount: str, fallback: SecretBackend
+    ) -> None:
+        self._addr = addr.rstrip("/")
+        self._token = token
+        self._mount = mount
+        self._fallback = fallback
+
+    def read(self, name: str) -> str | None:
+        value = self._read_bao(name)
+        if value is not None:
+            return value
+        return self._fallback.read(name)
+
+    def _read_bao(self, name: str) -> str | None:
+        if not self._token:
+            return None
+        url = f"{self._addr}/v1/{self._mount}/data/{name}"
+        req = urllib.request.Request(url, headers={"X-Vault-Token": self._token})
+        try:
+            with urllib.request.urlopen(req, timeout=5) as resp:  # noqa: S310
+                data = json.load(resp)
+            return data["data"]["data"].get("value")
+        except Exception:
+            return None
+
+
+def build_backend(secrets_dir: Path) -> SecretBackend:
+    """Construct the active secret backend from the environment."""
+    file_backend = FileSecretBackend(secrets_dir)
+    kind = os.environ.get("CASTLE_SECRET_BACKEND", "file").lower()
+    if kind == "openbao":
+        addr = os.environ.get("CASTLE_OPENBAO_ADDR", "http://localhost:8200")
+        mount = os.environ.get("CASTLE_OPENBAO_MOUNT", "castle")
+        token_secret = os.environ.get("CASTLE_OPENBAO_TOKEN_SECRET", "OPENBAO_TOKEN")
+        token = file_backend.read(token_secret) or os.environ.get(
+            "CASTLE_OPENBAO_TOKEN", ""
+        )
+        return OpenBaoBackend(addr, token, mount, fallback=file_backend)
+    return file_backend

core/tests/test_secret_backends.py

@@ -0,0 +1,54 @@
+"""Tests for the pluggable secret backends (file default, OpenBao opt-in)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from castle_core.secret_backends import (
+    FileSecretBackend,
+    OpenBaoBackend,
+    build_backend,
+)
+
+
+def test_file_backend_read_hit(tmp_path: Path) -> None:
+    (tmp_path / "MY_SECRET").write_text("value\n")
+    assert FileSecretBackend(tmp_path).read("MY_SECRET") == "value"
+
+
+def test_file_backend_read_miss(tmp_path: Path) -> None:
+    assert FileSecretBackend(tmp_path).read("ABSENT") is None
+
+
+def test_build_backend_defaults_to_file(tmp_path: Path, monkeypatch) -> None:
+    monkeypatch.delenv("CASTLE_SECRET_BACKEND", raising=False)
+    assert isinstance(build_backend(tmp_path), FileSecretBackend)
+
+
+def test_build_backend_openbao_selected(tmp_path: Path, monkeypatch) -> None:
+    monkeypatch.setenv("CASTLE_SECRET_BACKEND", "openbao")
+    assert isinstance(build_backend(tmp_path), OpenBaoBackend)
+
+
+def test_openbao_falls_back_to_file_when_unreachable(tmp_path: Path) -> None:
+    """An unreachable vault (or empty token) resolves via the file fallback."""
+    (tmp_path / "ONLY_IN_FILE").write_text("from-file")
+    backend = OpenBaoBackend(
+        addr="http://127.0.0.1:1",  # nothing listening
+        token="dummy",
+        mount="castle",
+        fallback=FileSecretBackend(tmp_path),
+    )
+    assert backend.read("ONLY_IN_FILE") == "from-file"
+    assert backend.read("NOT_ANYWHERE") is None
+
+
+def test_openbao_empty_token_uses_fallback(tmp_path: Path) -> None:
+    (tmp_path / "K").write_text("v")
+    backend = OpenBaoBackend(
+        addr="http://127.0.0.1:8200",
+        token="",  # no token → never hits the network
+        mount="castle",
+        fallback=FileSecretBackend(tmp_path),
+    )
+    assert backend.read("K") == "v"