stapel-vault 0.1.0__tar.gz

stapel_vault-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stapel contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stapel_vault-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: stapel-vault
+Version: 0.1.0
+Summary: Production secret storage for the Stapel framework — OpenBao/HashiCorp Vault behind the stapel-core secret-provider seam
+License: MIT
+Project-URL: Homepage, https://github.com/usestapel/stapel-vault
+Project-URL: Repository, https://github.com/usestapel/stapel-vault
+Project-URL: Documentation, https://github.com/usestapel/stapel-vault#readme
+Project-URL: Changelog, https://github.com/usestapel/stapel-vault/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/usestapel/stapel-vault/issues
+Keywords: django,stapel,vault,openbao,secrets,kv
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: stapel-core<0.11,>=0.10
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: Django>=5.1; extra == "dev"
+Provides-Extra: all
+Dynamic: license-file
+
+# stapel-vault
+
+Production secret storage for the [Stapel framework](https://github.com/usestapel).
+A facade over secret backends behind the `stapel_core.secrets` provider seam —
+the first backend is **OpenBao / HashiCorp Vault** (KV v2; their HTTP APIs are
+compatible, so one client speaks to both).
+
+Local dev and the `minimal` preset keep reading secrets from the environment
+(stapel-core's default provider). In production, where **env for secrets is
+unacceptable**, point the seam at `stapel-vault` and the framework reads
+`SECRET_KEY`, `JWT_SECRET_KEY`, database passwords and LLM pool keys from Vault
+instead — with no change to the code that consumes them.
+
+## Install
+
+```bash
+pip install stapel-vault      # requires stapel-core with the SecretProvider seam
+```
+
+## Wire it up
+
+The provider is selected at settings-bootstrap time (production settings
+resolve `SECRET_KEY` before `django.setup()`), via environment — which is also
+where Vault's own connection/auth config belongs:
+
+```bash
+# control plane only — never a workload container (see MODULE.md, S1)
+export STAPEL_SECRETS_PROVIDER=stapel_vault.VaultSecretProvider
+export VAULT_ADDR=https://vault.internal:8200
+export VAULT_K8S_ROLE=stapel-web       # Kubernetes auth (phase 2)
+```
+
+Then any `stapel_core.secrets.get_secret("DJANGO_SECRET_KEY")` — including the
+`SECRET_KEY` / `JWT_SECRET_KEY` reads in `stapel_core.django.settings` — comes
+from Vault. A missing secret is a hard, loud boot failure (`fail_closed`), not
+a silent `None`.
+
+## Secret layout (default convention)
+
+A service's secrets are keys of one KV v2 secret (the "bundle") at
+`secret/data/<prefix>/<app>` (defaults `secret/data/stapel/app`):
+
+```bash
+bao kv put secret/stapel/app \
+    DJANGO_SECRET_KEY=... JWT_SECRET_KEY=... POSTGRES_PASSWORD=...
+```
+
+`DJANGO_SECRET_KEY` then resolves to `GET v1/secret/data/stapel/app` →
+`.data.data["DJANGO_SECRET_KEY"]`. Override per name with `VAULT_SECRET_MAP`
+(JSON). See [MODULE.md](MODULE.md) for the full config reference, auth methods,
+rotation, and the deploy-mode map.
+
+## Auth methods
+
+| Method | When | Config |
+|---|---|---|
+| `token` | local/dev | `VAULT_TOKEN` |
+| `kubernetes` | prod on k8s (phase 2) | `VAULT_K8S_ROLE` (+ projected SA JWT) |
+| `approle` | prod, non-k8s | `VAULT_ROLE_ID` + `VAULT_SECRET_ID` |
+
+Auto-detected from what is present, or forced with `VAULT_AUTH_METHOD`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

stapel_vault-0.1.0/README.md

@@ -0,0 +1,65 @@
+# stapel-vault
+
+Production secret storage for the [Stapel framework](https://github.com/usestapel).
+A facade over secret backends behind the `stapel_core.secrets` provider seam —
+the first backend is **OpenBao / HashiCorp Vault** (KV v2; their HTTP APIs are
+compatible, so one client speaks to both).
+
+Local dev and the `minimal` preset keep reading secrets from the environment
+(stapel-core's default provider). In production, where **env for secrets is
+unacceptable**, point the seam at `stapel-vault` and the framework reads
+`SECRET_KEY`, `JWT_SECRET_KEY`, database passwords and LLM pool keys from Vault
+instead — with no change to the code that consumes them.
+
+## Install
+
+```bash
+pip install stapel-vault      # requires stapel-core with the SecretProvider seam
+```
+
+## Wire it up
+
+The provider is selected at settings-bootstrap time (production settings
+resolve `SECRET_KEY` before `django.setup()`), via environment — which is also
+where Vault's own connection/auth config belongs:
+
+```bash
+# control plane only — never a workload container (see MODULE.md, S1)
+export STAPEL_SECRETS_PROVIDER=stapel_vault.VaultSecretProvider
+export VAULT_ADDR=https://vault.internal:8200
+export VAULT_K8S_ROLE=stapel-web       # Kubernetes auth (phase 2)
+```
+
+Then any `stapel_core.secrets.get_secret("DJANGO_SECRET_KEY")` — including the
+`SECRET_KEY` / `JWT_SECRET_KEY` reads in `stapel_core.django.settings` — comes
+from Vault. A missing secret is a hard, loud boot failure (`fail_closed`), not
+a silent `None`.
+
+## Secret layout (default convention)
+
+A service's secrets are keys of one KV v2 secret (the "bundle") at
+`secret/data/<prefix>/<app>` (defaults `secret/data/stapel/app`):
+
+```bash
+bao kv put secret/stapel/app \
+    DJANGO_SECRET_KEY=... JWT_SECRET_KEY=... POSTGRES_PASSWORD=...
+```
+
+`DJANGO_SECRET_KEY` then resolves to `GET v1/secret/data/stapel/app` →
+`.data.data["DJANGO_SECRET_KEY"]`. Override per name with `VAULT_SECRET_MAP`
+(JSON). See [MODULE.md](MODULE.md) for the full config reference, auth methods,
+rotation, and the deploy-mode map.
+
+## Auth methods
+
+| Method | When | Config |
+|---|---|---|
+| `token` | local/dev | `VAULT_TOKEN` |
+| `kubernetes` | prod on k8s (phase 2) | `VAULT_K8S_ROLE` (+ projected SA JWT) |
+| `approle` | prod, non-k8s | `VAULT_ROLE_ID` + `VAULT_SECRET_ID` |
+
+Auto-detected from what is present, or forced with `VAULT_AUTH_METHOD`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

stapel_vault-0.1.0/__init__.py

@@ -0,0 +1,61 @@
+"""stapel-vault — production secret storage for the Stapel framework.
+
+A facade over secret backends behind the ``stapel_core.secrets`` provider seam.
+The first backend is **OpenBao / HashiCorp Vault** (KV v2 — their HTTP APIs are
+compatible, so one client speaks to both). Point the core seam at it and the
+framework reads ``SECRET_KEY`` / ``JWT_SECRET_KEY`` / DB passwords / LLM pool
+keys from Vault instead of the environment — the decision that "env for prod
+secrets is unacceptable" (arch-stapel-vault).
+
+    # deployment environment (control plane only — S1: never a workload container)
+    export STAPEL_SECRETS_PROVIDER=stapel_vault.VaultSecretProvider
+    export VAULT_ADDR=https://vault.internal:8200
+    export VAULT_K8S_ROLE=stapel-web
+
+See MODULE.md for the deploy-mode map (local=env / prod=vault+k8s auth) and
+the S1 constraint that workload containers never see Vault.
+
+Public API is lazily exported (PEP 562) so importing this package never runs
+the provider's relative imports until an attribute is actually used.
+"""
+
+try:  # single source of truth: pyproject version via package metadata
+    from importlib.metadata import version as _pkg_version
+
+    __version__ = _pkg_version("stapel-vault")
+except Exception:  # editable/vendored checkout without dist-info
+    __version__ = "0.1.0"
+
+__all__ = [
+    "SecretProvider",
+    "VaultAuthError",
+    "VaultConfigError",
+    "VaultError",
+    "VaultSecretProvider",
+    "VaultTransportError",
+    "__version__",
+]
+
+# name -> submodule that defines it. Deferred until first attribute access.
+_LAZY_EXPORTS = {
+    "SecretProvider": ".provider",
+    "VaultSecretProvider": ".provider",
+    "VaultAuthError": ".exceptions",
+    "VaultConfigError": ".exceptions",
+    "VaultError": ".exceptions",
+    "VaultTransportError": ".exceptions",
+}
+
+
+def __getattr__(name):
+    if name in _LAZY_EXPORTS:
+        from importlib import import_module
+
+        value = getattr(import_module(_LAZY_EXPORTS[name], __name__), name)
+        globals()[name] = value  # cache for subsequent lookups
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(globals()) | set(__all__))

stapel_vault-0.1.0/auth.py

@@ -0,0 +1,117 @@
+"""Vault auth methods: token (dev), kubernetes (service-account JWT), approle.
+
+Every method produces a short-lived *client token*; :class:`Authenticator`
+caches it until shortly before its lease expires and re-authenticates on
+demand (the token/lease TTL is honored — the same re-read-by-TTL idea the
+core seam applies to secret values). ``invalidate()`` drops the cached token
+so a 403 (token expired/revoked mid-flight) triggers exactly one re-auth.
+
+Kubernetes auth (deploy-topology phase 2): the pod's projected service-account
+JWT at ``VAULT_K8S_JWT_PATH`` is exchanged at
+``auth/<mount>/login`` for a Vault token bound to a Vault role. approle
+(``role_id`` + ``secret_id``) is the non-k8s server option; token auth is for
+local/dev.
+"""
+from __future__ import annotations
+
+import threading
+import time
+
+from .client import VaultHTTPClient
+from .config import VaultConfig
+from .exceptions import VaultAuthError, VaultConfigError
+
+# Re-authenticate once the token has less than this fraction of its lease left.
+_RENEW_AT = 0.9
+# Floor lease used when Vault reports a non-renewable/zero lease (token auth).
+_MIN_LEASE = 60.0
+
+
+class Authenticator:
+    """Produces (and refreshes) a valid Vault client token for the configured method."""
+
+    def __init__(self, config: VaultConfig, client: VaultHTTPClient) -> None:
+        self.config = config
+        self.client = client
+        self._lock = threading.Lock()
+        self._token: str | None = None
+        self._expires_at: float = 0.0
+
+    def token(self) -> str:
+        """A currently-valid client token (login/renew as needed)."""
+        now = time.monotonic()
+        tok = self._token
+        if tok is not None and self._expires_at > now:
+            return tok
+        with self._lock:
+            if self._token is not None and self._expires_at > time.monotonic():
+                return self._token
+            tok, lease = self._authenticate()
+            self._token = tok
+            self._expires_at = time.monotonic() + max(_MIN_LEASE, lease) * _RENEW_AT
+            return tok
+
+    def invalidate(self) -> None:
+        """Forget the cached token so the next :meth:`token` re-authenticates."""
+        with self._lock:
+            self._token = None
+            self._expires_at = 0.0
+
+    # -- per-method login ---------------------------------------------------
+
+    def _authenticate(self) -> tuple[str, float]:
+        method = self.config.auth_method
+        if method == "token":
+            if not self.config.token:
+                raise VaultConfigError(
+                    "auth method 'token' requires VAULT_TOKEN (or STAPEL_VAULT['TOKEN'])"
+                )
+            # A directly-supplied token has no lease we manage; treat as static.
+            return self.config.token, float("inf")
+        if method == "kubernetes":
+            return self._login_kubernetes()
+        if method == "approle":
+            return self._login_approle()
+        raise VaultConfigError(f"unknown auth method {method!r}")  # pragma: no cover
+
+    def _login_kubernetes(self) -> tuple[str, float]:
+        if not self.config.k8s_role:
+            raise VaultConfigError(
+                "auth method 'kubernetes' requires VAULT_K8S_ROLE"
+            )
+        try:
+            with open(self.config.k8s_jwt_path, encoding="utf-8") as fh:
+                jwt = fh.read().strip()
+        except OSError as exc:
+            raise VaultConfigError(
+                f"cannot read Kubernetes service-account JWT at "
+                f"{self.config.k8s_jwt_path}: {exc}"
+            ) from exc
+        return self._login({"role": self.config.k8s_role, "jwt": jwt})
+
+    def _login_approle(self) -> tuple[str, float]:
+        if not (self.config.role_id and self.config.secret_id):
+            raise VaultConfigError(
+                "auth method 'approle' requires VAULT_ROLE_ID and VAULT_SECRET_ID"
+            )
+        return self._login(
+            {"role_id": self.config.role_id, "secret_id": self.config.secret_id}
+        )
+
+    def _login(self, payload: dict) -> tuple[str, float]:
+        path = f"v1/auth/{self.config.auth_mount}/login"
+        resp = self.client.request("POST", path, json_body=payload)
+        if resp.status != 200:
+            errors = resp.data.get("errors") or [f"HTTP {resp.status}"]
+            raise VaultAuthError(
+                f"{self.config.auth_method} login to {path} failed: {errors}"
+            )
+        auth = resp.data.get("auth") or {}
+        client_token = auth.get("client_token")
+        if not client_token:
+            raise VaultAuthError(f"{path} returned no client_token")
+        lease = float(auth.get("lease_duration") or 0) or _MIN_LEASE
+        return client_token, lease
+
+
+__all__ = ["Authenticator"]

stapel_vault-0.1.0/client.py

@@ -0,0 +1,92 @@
+"""Minimal Vault / OpenBao HTTP client (stdlib ``urllib`` — no heavy deps).
+
+Design decision (arch-stapel-vault Part 2): we do **not** depend on ``hvac``.
+It is a large dependency for what we need (a couple of JSON endpoints), it
+pulls its own ``requests`` stack, and this facade must be importable at
+settings-bootstrap time in a control-plane process where a slim dependency
+footprint matters. The OpenBao and HashiCorp Vault HTTP APIs are compatible,
+so one small ``urllib`` client speaks to both. ``requests`` is avoided too —
+``urllib`` is stdlib and always present, so the provider adds *zero* runtime
+dependencies of its own.
+"""
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+
+from .exceptions import VaultTransportError
+
+
+@dataclass
+class VaultResponse:
+    status: int
+    data: dict
+
+
+class VaultHTTPClient:
+    """Tiny JSON-over-HTTP client for the Vault/OpenBao API.
+
+    Only :meth:`request` touches the network — tests mock this one method.
+    """
+
+    def __init__(self, addr: str, namespace: str | None = None, timeout: float = 5.0) -> None:
+        self.addr = addr.rstrip("/")
+        self.namespace = namespace
+        self.timeout = timeout
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        token: str | None = None,
+        json_body: dict | None = None,
+    ) -> VaultResponse:
+        """Perform one request. Returns status + parsed JSON.
+
+        Raises :class:`VaultTransportError` for unreachable host, timeout, a
+        5xx, or an unparseable body. Application-level statuses (200, 403,
+        404, …) are returned for the caller to interpret.
+        """
+        url = f"{self.addr}/{path.lstrip('/')}"
+        body = json.dumps(json_body).encode() if json_body is not None else None
+        headers = {"Accept": "application/json"}
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+        if token:
+            headers["X-Vault-Token"] = token
+        if self.namespace:
+            headers["X-Vault-Namespace"] = self.namespace
+
+        req = urllib.request.Request(url, data=body, method=method, headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:  # noqa: S310
+                return VaultResponse(resp.status, _parse(resp.read()))
+        except urllib.error.HTTPError as exc:
+            payload = _parse(exc.read() or b"")
+            if exc.code >= 500:
+                raise VaultTransportError(
+                    f"Vault returned {exc.code} for {method} {path}: "
+                    f"{payload.get('errors') or exc.reason}",
+                    status=exc.code,
+                ) from exc
+            return VaultResponse(exc.code, payload)
+        except (urllib.error.URLError, TimeoutError, OSError) as exc:
+            raise VaultTransportError(
+                f"cannot reach Vault at {self.addr} ({type(exc).__name__}: {exc})"
+            ) from exc
+
+
+def _parse(raw: bytes) -> dict:
+    if not raw:
+        return {}
+    try:
+        value = json.loads(raw)
+    except ValueError as exc:
+        raise VaultTransportError(f"Vault response was not JSON: {exc}") from exc
+    return value if isinstance(value, dict) else {"data": value}
+
+
+__all__ = ["VaultHTTPClient", "VaultResponse"]

stapel_vault-0.1.0/config.py

@@ -0,0 +1,146 @@
+"""Bootstrap-tolerant configuration for the Vault facade.
+
+Vault connection config (address, auth, mount) legitimately lives in the
+**environment / Kubernetes**, not in Django settings — because a production
+settings module resolves ``SECRET_KEY`` through Vault *before* ``django.setup()``
+runs. So every key is resolved env-first, with an optional ``STAPEL_VAULT``
+Django-settings override that only applies once Django is configured.
+
+Resolution order per key: ``STAPEL_VAULT[<key>]`` (when Django is configured)
+→ environment variable (the ``VAULT_*`` name) → default.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from .exceptions import VaultConfigError
+
+# Django-settings namespace for optional overrides (post-setup only).
+SETTINGS_NAMESPACE = "STAPEL_VAULT"
+
+# Default location of the Kubernetes service-account JWT (projected token).
+DEFAULT_K8S_JWT_PATH = "/var/run/secrets/kubernetes.io/serviceaccount/token"  # noqa: S105
+
+
+def _setting(key: str) -> str | None:
+    """Value from ``STAPEL_VAULT[key]`` if Django is configured, else None."""
+    try:
+        from django.conf import settings
+
+        ns = getattr(settings, SETTINGS_NAMESPACE, None) or {}
+        val = ns.get(key)
+        return None if val is None else str(val)
+    except Exception:
+        # Django not configured (bootstrap) — env is the source of truth.
+        return None
+
+
+def _resolve(key: str, env: str, default: str | None = None) -> str | None:
+    val = _setting(key)
+    if val is not None:
+        return val
+    val = os.environ.get(env)
+    if val is not None and val != "":
+        return val
+    return default
+
+
+@dataclass(frozen=True)
+class VaultConfig:
+    """Resolved connection + mapping configuration for :class:`VaultSecretProvider`."""
+
+    addr: str
+    namespace: str | None
+    kv_mount: str
+    path_prefix: str
+    app: str
+    kv_version: int | None
+    timeout: float
+    bundle_cache_ttl: float
+    # auth
+    auth_method: str  # "token" | "kubernetes" | "approle"
+    token: str | None
+    auth_mount: str
+    k8s_role: str | None
+    k8s_jwt_path: str
+    role_id: str | None
+    secret_id: str | None
+    # optional explicit per-name mapping: {"NAME": "path#key", ...}
+    secret_map: dict[str, str]
+
+
+def _auto_auth_method() -> str:
+    """Pick an auth method from what is present in the environment/settings."""
+    if _resolve("TOKEN", "VAULT_TOKEN"):
+        return "token"
+    if _resolve("ROLE_ID", "VAULT_ROLE_ID"):
+        return "approle"
+    if _resolve("K8S_ROLE", "VAULT_K8S_ROLE") or os.path.exists(
+        _resolve("K8S_JWT_PATH", "VAULT_K8S_JWT_PATH", DEFAULT_K8S_JWT_PATH) or ""
+    ):
+        return "kubernetes"
+    return "token"
+
+
+def _default_auth_mount(method: str) -> str:
+    return {"kubernetes": "kubernetes", "approle": "approle", "token": "token"}[method]
+
+
+def load_config(**overrides) -> VaultConfig:
+    """Resolve a :class:`VaultConfig`. Explicit *overrides* win over everything.
+
+    Raises :class:`VaultConfigError` for an unknown auth method (missing
+    required credentials are surfaced lazily at auth time so a misconfigured
+    non-token method still constructs — the boot error then names Vault).
+    """
+    import json
+
+    def ov(name, resolver):
+        return overrides[name] if name in overrides else resolver()
+
+    auth_method = ov("auth_method", lambda: _resolve("AUTH_METHOD", "VAULT_AUTH_METHOD") or _auto_auth_method())
+    if auth_method not in ("token", "kubernetes", "approle"):
+        raise VaultConfigError(
+            f"unknown VAULT auth method {auth_method!r} (expected token, "
+            "kubernetes or approle)"
+        )
+
+    raw_map = ov("secret_map", lambda: _resolve("SECRET_MAP", "VAULT_SECRET_MAP"))
+    if isinstance(raw_map, str):
+        try:
+            secret_map = dict(json.loads(raw_map))
+        except (ValueError, TypeError) as exc:
+            raise VaultConfigError(f"VAULT_SECRET_MAP is not valid JSON: {exc}") from exc
+    else:
+        secret_map = dict(raw_map or {})
+
+    def _int(name, env):
+        v = _resolve(name, env)
+        return int(v) if v not in (None, "") else None
+
+    def _float(name, env, default):
+        v = _resolve(name, env)
+        return float(v) if v not in (None, "") else default
+
+    return VaultConfig(
+        addr=ov("addr", lambda: _resolve("ADDR", "VAULT_ADDR", "http://127.0.0.1:8200")).rstrip("/"),
+        namespace=ov("namespace", lambda: _resolve("NAMESPACE", "VAULT_NAMESPACE")),
+        kv_mount=ov("kv_mount", lambda: _resolve("KV_MOUNT", "VAULT_KV_MOUNT", "secret")),
+        path_prefix=ov("path_prefix", lambda: _resolve("SECRET_PATH_PREFIX", "VAULT_SECRET_PATH_PREFIX", "stapel")),
+        app=ov("app", lambda: _resolve("SECRET_APP", "VAULT_SECRET_APP", "app")),
+        kv_version=ov("kv_version", lambda: _int("KV_VERSION", "VAULT_KV_VERSION")),
+        timeout=ov("timeout", lambda: _float("HTTP_TIMEOUT", "VAULT_HTTP_TIMEOUT", 5.0)),
+        bundle_cache_ttl=ov("bundle_cache_ttl", lambda: _float("BUNDLE_CACHE_TTL", "VAULT_BUNDLE_CACHE_TTL", 0.0)),
+        auth_method=auth_method,
+        token=ov("token", lambda: _resolve("TOKEN", "VAULT_TOKEN")),
+        auth_mount=ov("auth_mount", lambda: _resolve("AUTH_MOUNT", "VAULT_AUTH_MOUNT") or _default_auth_mount(auth_method)),
+        k8s_role=ov("k8s_role", lambda: _resolve("K8S_ROLE", "VAULT_K8S_ROLE")),
+        k8s_jwt_path=ov("k8s_jwt_path", lambda: _resolve("K8S_JWT_PATH", "VAULT_K8S_JWT_PATH", DEFAULT_K8S_JWT_PATH)),
+        role_id=ov("role_id", lambda: _resolve("ROLE_ID", "VAULT_ROLE_ID")),
+        secret_id=ov("secret_id", lambda: _resolve("SECRET_ID", "VAULT_SECRET_ID")),
+        secret_map=secret_map,
+    )
+
+
+__all__ = ["DEFAULT_K8S_JWT_PATH", "SETTINGS_NAMESPACE", "VaultConfig", "load_config"]

stapel_vault-0.1.0/conftest.py

@@ -0,0 +1,21 @@
+"""Pytest bootstrap.
+
+Config resolution is env-first and works with no Django at all; Django is
+configured here only so the ``STAPEL_VAULT`` settings-override path (and
+``override_settings``) can be exercised. No apps, no database.
+"""
+
+
+def pytest_configure(config):
+    from django.conf import settings
+
+    if not settings.configured:
+        settings.configure(
+            DEBUG=False,
+            INSTALLED_APPS=[],
+            DATABASES={},
+            USE_TZ=True,
+        )
+        import django
+
+        django.setup()

stapel_vault-0.1.0/exceptions.py

@@ -0,0 +1,39 @@
+"""Exceptions raised inside the Vault facade.
+
+These are *internal* failures (misconfiguration, auth failure, transport
+error). They are deliberately distinct from ``stapel_core.secrets``'s
+``SecretUnavailable`` — that one means "the secret simply isn't there and no
+default was given", which the core seam raises after a provider returns
+``None``. A ``VaultError`` here means "I could not even ask Vault properly",
+which propagates fail-closed through ``get_secret`` (a boot-stopping error, as
+intended for a production secret store).
+"""
+from __future__ import annotations
+
+
+class VaultError(Exception):
+    """Base class for all stapel-vault failures."""
+
+
+class VaultConfigError(VaultError):
+    """The provider is misconfigured (missing address, unknown auth method…)."""
+
+
+class VaultAuthError(VaultError):
+    """Authentication to Vault/OpenBao failed (bad token, role, secret-id…)."""
+
+
+class VaultTransportError(VaultError):
+    """A network/HTTP-level failure talking to Vault (timeout, 5xx, unreachable)."""
+
+    def __init__(self, message: str, *, status: int | None = None) -> None:
+        self.status = status
+        super().__init__(message)
+
+
+__all__ = [
+    "VaultAuthError",
+    "VaultConfigError",
+    "VaultError",
+    "VaultTransportError",
+]