secrefs 0.2.0__py3-none-any.whl

secrefs/providers/aws.py

@@ -0,0 +1,156 @@
+"""
+AWS Secrets Manager provider. Two credential-sourcing modes:
+
+- **Ambient (default)**: boto3's default credential resolution chain -
+  environment variables, shared config/credentials files, ECS/EC2 instance
+  metadata, or an assumed IAM role - so no credentials ever need to live in
+  SecRefs configuration itself. One client is built lazily and reused for
+  the provider's lifetime.
+- **Control-plane-sourced** (`control_plane` option): a fresh,
+  request-scoped credential is minted per fetch via the control plane's
+  `/v1/credentials/mint`, so a distinct boto3 client is constructed per
+  path rather than reused - each one only ever carries the narrow scope
+  that one mint granted.
+
+boto3 is synchronous, so calls are offloaded to a thread via
+`asyncio.to_thread` to keep the async provider interface non-blocking.
+
+The ambient client is constructed lazily on first use - boto3.client()
+resolves (and validates) the region eagerly at construction time, raising
+NoRegionError immediately if none is configured anywhere, so building it in
+__init__ would mean simply having an AWSSecretsManagerProvider in your
+registry - even one you never reference via sec://aws/... - breaks the
+whole import in any region-less environment. Matches VaultProvider's own
+lazy-construction rationale.
+
+Fetched values are re-fetched on every expansion by default; see
+`cache_ttl_ms` and ../ttl_cache.py for why that default is what it is.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import Any, Optional, cast
+
+import boto3
+
+from ..control_plane_client import (
+    ControlPlaneClient,
+    ControlPlaneCredentialSource,
+    ControlPlaneRequestError,
+    MintedAWSCredentials,
+)
+from ..ttl_cache import TtlCache
+from .base import ProviderHealth, SecretFetchRequest, SecretProvider, extract_field
+
+
+class AWSSecretsManagerProvider(SecretProvider):
+    name = "aws"
+
+    def __init__(
+        self,
+        region: Optional[str] = None,
+        client: Optional[Any] = None,
+        control_plane: Optional[ControlPlaneCredentialSource] = None,
+        cache_ttl_ms: float = 0.0,
+    ) -> None:
+        """`client` injects a pre-configured boto3 client (primarily for
+        testing) and wins over `control_plane` if both are given, since a
+        test that supplies an explicit client wants full control regardless
+        of the mode. `cache_ttl_ms` is how long a fetched secret value may
+        be reused; it defaults to 0, meaning every expansion re-fetches, so
+        a rotated secret reaches a long-running consumer without a
+        redeploy."""
+        self._explicit_client = client
+        self._client_instance: Optional[Any] = None
+        self._region = region
+        self._control_plane = control_plane
+        self._control_plane_client: Optional[ControlPlaneClient] = None
+        if control_plane is not None:
+            self._control_plane_client = control_plane.client or ControlPlaneClient(
+                base_url=control_plane.base_url, token=control_plane.token
+            )
+        self._raw_cache: TtlCache[str] = TtlCache(ttl_ms=cache_ttl_ms)
+
+    def _region_name(self) -> Optional[str]:
+        return self._region or os.environ.get("AWS_REGION")
+
+    async def _client_for(self, path: str) -> Any:
+        """Resolves the boto3 client to use for one `path` - lazily built and
+        reused in ambient mode, freshly minted per call in control-plane
+        mode. An explicitly injected client always wins."""
+        if self._explicit_client is not None:
+            return self._explicit_client
+
+        if self._control_plane is not None and self._control_plane_client is not None:
+            minted = await self._control_plane_client.mint_credential(
+                self._control_plane.alias, path
+            )
+            credentials = minted.credentials
+            if not isinstance(credentials, MintedAWSCredentials):
+                raise ValueError(
+                    f'control plane returned a "{minted.provider}" credential for alias '
+                    f'"{self._control_plane.alias}", expected "aws"'
+                )
+            return boto3.client(
+                "secretsmanager",
+                region_name=self._region_name(),
+                aws_access_key_id=credentials.access_key_id,
+                aws_secret_access_key=credentials.secret_access_key,
+                aws_session_token=credentials.session_token,
+            )
+
+        if self._client_instance is None:
+            self._client_instance = boto3.client("secretsmanager", region_name=self._region_name())
+        return self._client_instance
+
+    async def _fetch_raw(self, path: str) -> str:
+        try:
+            client = await self._client_for(path)
+            response = await asyncio.to_thread(client.get_secret_value, SecretId=path)
+        except Exception as exc:  # noqa: BLE001 - re-raised with context below
+            raise ValueError(f'could not fetch secret "{path}": {exc}') from exc
+
+        if response.get("SecretString") is not None:
+            return cast(str, response["SecretString"])
+        if response.get("SecretBinary") is not None:
+            raw = response["SecretBinary"]
+            return raw.decode("utf-8") if isinstance(raw, (bytes, bytearray)) else str(raw)
+        raise ValueError(f'secret "{path}" has no SecretString or SecretBinary payload')
+
+    async def fetch_one(self, request: SecretFetchRequest) -> str:
+        # Keyed by path, not by path+field, so several `#field` references
+        # against the same secret still cost one call (and, in control-plane
+        # mode, one mint) when they're expanded together.
+        raw = await self._raw_cache.fetch(request.path, lambda: self._fetch_raw(request.path))
+        return extract_field(raw, request.field, provider=self.name, path=request.path)
+
+    async def health_check(self) -> ProviderHealth:
+        try:
+            if self._control_plane is not None and self._control_plane_client is not None:
+                # A control-plane-sourced provider has no single ambient
+                # credential to probe - health here means "the control plane
+                # is reachable and this token is accepted", checked with a
+                # deliberately-unresolvable synthetic path so this never
+                # mutates anything or depends on any specific secret
+                # existing. A 403 ("no grant authorizes...") still proves
+                # reachability + auth worked; only a network/5xx failure
+                # means unhealthy.
+                try:
+                    await self._control_plane_client.mint_credential(
+                        self._control_plane.alias, "__secrefs_health_check__"
+                    )
+                except ControlPlaneRequestError:
+                    return ProviderHealth(
+                        provider=self.name, ok=True, message="control plane reachable"
+                    )
+                return ProviderHealth(provider=self.name, ok=True)
+
+            # A cheap, low-privilege call that proves both network
+            # reachability and that ambient credentials are valid.
+            client = await self._client_for("__secrefs_health_check__")
+            await asyncio.to_thread(client.list_secrets, MaxResults=1)
+            return ProviderHealth(provider=self.name, ok=True)
+        except Exception as exc:  # noqa: BLE001
+            return ProviderHealth(provider=self.name, ok=False, message=str(exc))

secrefs/providers/base.py

@@ -0,0 +1,89 @@
+"""
+The provider contract every SecRefs backend implements. Providers never
+log, print, or persist the values they return - that discipline is
+enforced by the resolver/CLI layers above them.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, List, Optional
+
+_MISSING = object()
+
+
+@dataclass(frozen=True)
+class SecretFetchRequest:
+    path: str
+    field: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class ProviderHealth:
+    provider: str
+    ok: bool
+    message: Optional[str] = None  # human-readable diagnostic; never secret material
+
+
+class SecretFetchError(Exception):
+    def __init__(self, provider: str, path: str, cause: object) -> None:
+        self.provider = provider
+        self.path = path
+        super().__init__(f'[{provider}] failed to fetch secret at "{path}": {cause}')
+
+
+class SecretProvider(ABC):
+    name: str
+
+    @abstractmethod
+    async def fetch_one(self, request: SecretFetchRequest) -> str: ...
+
+    async def fetch_batch(self, requests: List[SecretFetchRequest]) -> List[str]:
+        """
+        Default implementation: concurrent individual fetches, surfacing the
+        first failure with full context. Providers may override this to use
+        a backend's native batch API.
+        """
+        results = await asyncio.gather(
+            *(self.fetch_one(r) for r in requests), return_exceptions=True
+        )
+        values: List[str] = []
+        for request, result in zip(requests, results):
+            if isinstance(result, BaseException):
+                raise SecretFetchError(self.name, request.path, result) from result
+            values.append(result)
+        return values
+
+    @abstractmethod
+    async def health_check(self) -> ProviderHealth: ...
+
+
+def extract_field(raw: str, field: Optional[str], *, provider: str, path: str) -> str:
+    """
+    Extracts a (possibly dot-nested) field from a JSON-encoded secret. If no
+    field is requested, `raw` is returned unchanged.
+    """
+    if not field:
+        return raw
+
+    try:
+        parsed: Any = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ValueError(
+            f'[{provider}] secret at "{path}" is not JSON, cannot extract field "{field}"'
+        ) from exc
+
+    current: Any = parsed
+    for part in field.split("."):
+        if not isinstance(current, dict):
+            raise ValueError(f'[{provider}] field "{field}" not found in secret at "{path}"')
+        current = current.get(part, _MISSING)
+        if current is _MISSING:
+            raise ValueError(f'[{provider}] field "{field}" not found in secret at "{path}"')
+
+    if isinstance(current, (dict, list)):
+        return json.dumps(current)
+    return str(current)

secrefs/providers/bitwarden.py

@@ -0,0 +1,257 @@
+"""
+Bitwarden **Secrets Manager** provider (not the password vault - see
+https://bitwarden.com/help/secrets-manager-overview/). Two structural
+differences from AWSSecretsManagerProvider/VaultProvider worth knowing
+before using this:
+
+1. **Secrets are end-to-end encrypted.** There is no plain authenticated
+   REST call to fetch a value - the official SDK derives a decryption key
+   from the access token during login and decrypts client-side. That's why
+   this provider depends on `bitwarden-sdk` (Bitwarden's own Python binding
+   over their Rust SDK) rather than a bare HTTP request.
+2. **Bitwarden addresses secrets by UUID, with no path hierarchy** the way
+   AWS/Vault secret names have. `path` may be that UUID directly, or - if
+   `organization_id` is configured (ambient mode) or supplied by the control
+   plane (control-plane mode) - a human-readable secret *name* (Bitwarden's
+   "key" field), resolved via one cached `secrets().list()` call. With
+   neither, only UUID paths work.
+
+`bitwarden-sdk` is an optional dependency (`pip install 'secrefs[bitwarden]'`)
+rather than a required one, unlike boto3 and hvac: it ships as prebuilt
+native wheels for a fixed set of platform tags with no source distribution
+to fall back on, so requiring it would break installing SecRefs at all on
+any platform Bitwarden doesn't publish a wheel for - including for the
+majority of users who never write a sec://bitwarden/... reference. It's
+therefore imported at first use rather than at module import, so having a
+BitwardenProvider in the default registry costs nothing until something
+actually resolves through it.
+
+The SDK is synchronous, so its calls are offloaded to a thread via
+`asyncio.to_thread`, the same way boto3 and hvac calls are.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import re
+from typing import Any, Dict, Optional
+
+from ..control_plane_client import (
+    ControlPlaneClient,
+    ControlPlaneCredentialSource,
+    MintedBitwardenCredentials,
+)
+from .base import ProviderHealth, SecretFetchRequest, SecretProvider, extract_field
+
+UUID_PATTERN = re.compile(
+    r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", re.IGNORECASE
+)
+
+
+def _unwrap(response: Any, context: str) -> Any:
+    """Pulls `data` out of the SDK's `{success, data, errorMessage}` response
+    envelope. The SDK itself already raises when `success` is false, so this
+    is the belt to that's braces - but the envelope types `data` as optional,
+    and an empty one would otherwise surface as an AttributeError rather than
+    as whatever the SDK put in `errorMessage`."""
+    data = getattr(response, "data", None)
+    if data is None:
+        message = getattr(response, "error_message", None) or "no data returned"
+        raise ValueError(f"{context}: {message}")
+    return data
+
+
+class BitwardenProvider(SecretProvider):
+    name = "bitwarden"
+
+    def __init__(
+        self,
+        access_token: Optional[str] = None,
+        organization_id: Optional[str] = None,
+        api_url: Optional[str] = None,
+        identity_url: Optional[str] = None,
+        state_file: Optional[str] = None,
+        control_plane: Optional[ControlPlaneCredentialSource] = None,
+        client: Optional[Any] = None,
+    ) -> None:
+        """`access_token` defaults to $BWS_ACCESS_TOKEN and `organization_id`
+        to $BWS_ORGANIZATION_ID; both are ignored when `control_plane` is
+        set, which supplies them per request instead. `api_url`/
+        `identity_url` (defaulting to $BWS_API_URL/$BWS_IDENTITY_URL) point
+        at a self-hosted instance.
+
+        `state_file` is an opt-in path to an encrypted session-state file the
+        SDK can reuse across calls to reduce auth rate-limiting (Bitwarden's
+        own docs describe this file's contents as fully encrypted, not
+        plaintext secret material). Omitted by default - this provider
+        authenticates in memory and writes nothing to disk unless a caller
+        opts in.
+
+        Setting `control_plane` sources the access token and organization id
+        from a running control plane (docs/control-plane-design.md §7/§10,
+        and §8 for why Bitwarden's distribution here isn't the same as AWS's
+        per-request minting). Every fetch still requests a distribution for
+        its specific `path`, so the control plane's RBAC Grant.path_pattern
+        is enforced per secret even though the underlying Bitwarden token
+        itself isn't scoped that narrowly - "SDK-side enforcement" as
+        documented on the control-plane side."""
+        self._explicit_client = client
+        self._client_instance: Optional[Any] = None
+        self._api_url = api_url or os.environ.get("BWS_API_URL")
+        self._identity_url = identity_url or os.environ.get("BWS_IDENTITY_URL")
+        self._state_file = state_file
+        self._control_plane = control_plane
+        self._control_plane_client: Optional[ControlPlaneClient] = None
+
+        self._ambient_access_token: Optional[str] = None
+        self._ambient_organization_id: Optional[str] = None
+        self._organization_id: Optional[str] = None
+
+        if control_plane is not None:
+            self._control_plane_client = control_plane.client or ControlPlaneClient(
+                base_url=control_plane.base_url, token=control_plane.token
+            )
+        else:
+            self._ambient_access_token = access_token or os.environ.get("BWS_ACCESS_TOKEN")
+            self._ambient_organization_id = organization_id or os.environ.get(
+                "BWS_ORGANIZATION_ID"
+            )
+            self._organization_id = self._ambient_organization_id
+
+        self._logged_in_token: Optional[str] = None
+        # Secret name -> id, populated by one list() call the first time a
+        # non-UUID path is requested. Dropped if organization_id ever changes
+        # (control-plane mode, defensively - static in practice).
+        self._name_to_id: Optional[Dict[str, str]] = None
+        # Serializes login and the name->id lookup so N concurrent
+        # expansions authenticate once and list once rather than N times.
+        self._login_lock = asyncio.Lock()
+        self._list_lock = asyncio.Lock()
+
+    def _get_client(self) -> Any:
+        if self._explicit_client is not None:
+            return self._explicit_client
+        if self._client_instance is not None:
+            return self._client_instance
+
+        try:
+            from bitwarden_sdk import BitwardenClient, ClientSettings
+        except ImportError as exc:
+            raise ValueError(
+                "the bitwarden-sdk package is required for sec://bitwarden/... references "
+                "(pip install 'secrefs[bitwarden]') - Bitwarden secrets are end-to-end "
+                "encrypted and can only be decrypted by their own SDK"
+            ) from exc
+
+        # Passing no settings at all when neither URL is overridden, rather
+        # than a settings object full of Nones, so the SDK's own defaults
+        # (bitwarden.com) stay the single source of that truth.
+        if self._api_url or self._identity_url:
+            self._client_instance = BitwardenClient(
+                ClientSettings(api_url=self._api_url, identity_url=self._identity_url)
+            )
+        else:
+            self._client_instance = BitwardenClient()
+        return self._client_instance
+
+    async def _login_with(self, access_token: str, organization_id: Optional[str]) -> None:
+        async with self._login_lock:
+            if organization_id != self._organization_id:
+                self._name_to_id = None  # stale map keyed to a now-superseded org
+                self._organization_id = organization_id
+            if self._logged_in_token == access_token:
+                return
+
+            client = self._get_client()
+            try:
+                await asyncio.to_thread(
+                    client.auth().login_access_token, access_token, self._state_file
+                )
+            except Exception as exc:  # noqa: BLE001 - re-raised with context below
+                raise ValueError(
+                    f"could not authenticate with the given access token: {exc}"
+                ) from exc
+            # Recorded only after a successful login, so a failure is retried
+            # rather than remembered as a session that exists.
+            self._logged_in_token = access_token
+
+    async def _ensure_logged_in_for(self, path: str) -> None:
+        """Ensures a session exists for `path`. Ambient mode logs in once
+        with the ambient token; control-plane mode requests a distribution
+        for this specific `path` every call - see the `control_plane`
+        constructor argument for why that RBAC check has to be per-path even
+        though the token it returns doesn't vary."""
+        if self._control_plane is None or self._control_plane_client is None:
+            if not self._ambient_access_token:
+                raise ValueError(
+                    "BWS_ACCESS_TOKEN is not set (required for sec://bitwarden/... references)"
+                )
+            await self._login_with(self._ambient_access_token, self._ambient_organization_id)
+            return
+
+        minted = await self._control_plane_client.mint_credential(self._control_plane.alias, path)
+        credentials = minted.credentials
+        if not isinstance(credentials, MintedBitwardenCredentials):
+            raise ValueError(
+                f'control plane returned a "{minted.provider}" credential for alias '
+                f'"{self._control_plane.alias}", expected "bitwarden"'
+            )
+        await self._login_with(credentials.access_token, credentials.organization_id)
+
+    async def _resolve_secret_id(self, path: str) -> str:
+        """Assumes _ensure_logged_in_for(path) has already run for this exact
+        `path` - callers always do that first, so self._organization_id is
+        already whatever this path's session resolved to."""
+        if UUID_PATTERN.match(path):
+            return path
+
+        if not self._organization_id:
+            raise ValueError(
+                f'"{path}" is not a secret UUID, and no organization_id is available to look up '
+                "a secret by name (set BWS_ORGANIZATION_ID, use the UUID directly, or - in "
+                "control-plane mode - the distributed credential didn't include one)"
+            )
+
+        async with self._list_lock:
+            if self._name_to_id is None:
+                organization_id = self._organization_id
+                response = await asyncio.to_thread(
+                    self._get_client().secrets().list, organization_id
+                )
+                listed = _unwrap(response, f'could not list secrets in "{organization_id}"')
+                self._name_to_id = {secret.key: str(secret.id) for secret in listed.data}
+            name_to_id = self._name_to_id
+
+        secret_id = name_to_id.get(path)
+        if secret_id is None:
+            raise ValueError(
+                f'no secret named "{path}" found in organization "{self._organization_id}"'
+            )
+        return secret_id
+
+    async def fetch_one(self, request: SecretFetchRequest) -> str:
+        try:
+            # One _ensure_logged_in_for per fetch - in control-plane mode
+            # this is the one distribution/RBAC-gate call for this path, and
+            # _resolve_secret_id below relies on it having already set
+            # self._organization_id.
+            await self._ensure_logged_in_for(request.path)
+            secret_id = await self._resolve_secret_id(request.path)
+            response = await asyncio.to_thread(self._get_client().secrets().get, secret_id)
+            secret = _unwrap(response, f'could not read secret "{request.path}"')
+            value: str = secret.value
+        except Exception as exc:  # noqa: BLE001 - re-raised with context below
+            raise ValueError(f'could not fetch secret "{request.path}": {exc}') from exc
+
+        # Deliberately outside the try: a missing #field is a reference
+        # problem, not a fetch failure, and extract_field's message already
+        # names the provider and path.
+        return extract_field(value, request.field, provider=self.name, path=request.path)
+
+    async def health_check(self) -> ProviderHealth:
+        try:
+            await self._ensure_logged_in_for("__secrefs_health_check__")
+            return ProviderHealth(provider=self.name, ok=True)
+        except Exception as exc:  # noqa: BLE001
+            return ProviderHealth(provider=self.name, ok=False, message=str(exc))

secrefs/providers/local.py

@@ -0,0 +1,79 @@
+"""
+Reads secrets from a gitignored, developer-local JSON file. Intended for
+local development only.
+
+Example `.secrefs.local.json`:
+    { "mock-db": { "password": "hunter2", "user": "postgres" } }
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional, Union
+
+from .base import ProviderHealth, SecretFetchRequest, SecretProvider, extract_field
+
+DEFAULT_FILENAME = ".secrefs.local.json"
+
+
+class LocalProvider(SecretProvider):
+    name = "local"
+
+    def __init__(
+        self,
+        file_path: Optional[Union[str, Path]] = None,
+        cache_file: bool = False,
+    ) -> None:
+        """`cache_file` keeps the parsed file in memory instead of re-reading
+        it per fetch. Off by default so an edit takes effect immediately -
+        caching it meant editing .secrefs.local.json mid-session silently did
+        nothing, which is the local-development shape of the same
+        stale-secret problem ../ttl_cache.py exists to solve."""
+        self._file_path = Path(
+            file_path or os.environ.get("SECREFS_LOCAL_FILE") or (Path.cwd() / DEFAULT_FILENAME)
+        )
+        self._cache_file = cache_file
+        self._cache: Optional[Dict[str, Any]] = None
+
+    def _load(self) -> Dict[str, Any]:
+        # The file is local and tiny, so re-reading it costs nothing worth
+        # trading an edit-takes-effect guarantee for.
+        if self._cache is not None and self._cache_file:
+            return self._cache
+
+        try:
+            raw = self._file_path.read_text(encoding="utf-8")
+        except OSError as exc:
+            raise ValueError(
+                f'[local] could not read local secrets file at "{self._file_path}": {exc}. '
+                "This file is gitignored by convention - see .secrefs.local.json in .gitignore."
+            ) from exc
+
+        try:
+            parsed = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f'[local] "{self._file_path}" is not valid JSON: {exc}') from exc
+
+        if not isinstance(parsed, dict):
+            raise ValueError(f'[local] "{self._file_path}" must contain a top-level JSON object')
+
+        self._cache = parsed
+        return self._cache
+
+    async def fetch_one(self, request: SecretFetchRequest) -> str:
+        data = self._load()
+        if request.path not in data:
+            raise ValueError(f'[local] no entry for path "{request.path}" in {self._file_path}')
+
+        entry = data[request.path]
+        raw = entry if isinstance(entry, str) else json.dumps(entry)
+        return extract_field(raw, request.field, provider=self.name, path=request.path)
+
+    async def health_check(self) -> ProviderHealth:
+        try:
+            self._load()
+            return ProviderHealth(provider=self.name, ok=True, message=str(self._file_path))
+        except Exception as exc:  # noqa: BLE001 - surfaced to the caller as a health message
+            return ProviderHealth(provider=self.name, ok=False, message=str(exc))

secrefs/providers/vault.py

@@ -0,0 +1,99 @@
+"""
+HashiCorp Vault provider supporting both KV v1 and KV v2 secrets engines.
+Auth is ambient via VAULT_ADDR/VAULT_TOKEN - point `path` at whatever the
+Vault HTTP API itself expects (KV v2 mounts include a literal `data/`
+segment, e.g. `secret/data/stripe`; KV v1 mounts do not).
+
+hvac is synchronous, so calls are offloaded to a thread via
+`asyncio.to_thread`. The client is constructed lazily on first use so that
+simply having a VaultProvider in your registry doesn't require Vault to be
+configured if you never reference sec://vault/... at all.
+
+Read secrets are re-read on every expansion by default; see `cache_ttl_ms`
+and ../ttl_cache.py for why that default is what it is.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from typing import Any, Dict, Optional, cast
+
+import hvac
+
+from ..ttl_cache import TtlCache
+from .base import ProviderHealth, SecretFetchRequest, SecretProvider, extract_field
+
+
+class VaultProvider(SecretProvider):
+    name = "vault"
+
+    def __init__(
+        self,
+        url: Optional[str] = None,
+        token: Optional[str] = None,
+        client: Optional[Any] = None,
+        cache_ttl_ms: float = 0.0,
+    ) -> None:
+        """`cache_ttl_ms` is how long a read secret may be reused; it
+        defaults to 0, meaning every expansion re-reads, so rotation reaches
+        a long-running consumer without a redeploy."""
+        self._explicit_client = client
+        self._url = url or os.environ.get("VAULT_ADDR")
+        self._token = token or os.environ.get("VAULT_TOKEN")
+        self._client_instance: Optional[Any] = None
+        self._data_cache: TtlCache[Dict[str, Any]] = TtlCache(ttl_ms=cache_ttl_ms)
+
+    def _get_client(self) -> Any:
+        if self._explicit_client is not None:
+            return self._explicit_client
+        if self._client_instance is not None:
+            return self._client_instance
+
+        if not self._url:
+            raise ValueError("VAULT_ADDR is not set (required for sec://vault/... references)")
+        if not self._token:
+            raise ValueError("VAULT_TOKEN is not set (required for sec://vault/... references)")
+
+        self._client_instance = hvac.Client(url=self._url, token=self._token)
+        return self._client_instance
+
+    async def _fetch_data(self, path: str) -> Dict[str, Any]:
+        # Outside the try: an unconfigured VAULT_ADDR/VAULT_TOKEN is a
+        # misconfiguration, not a failed read, and shouldn't be reported as
+        # one.
+        client = self._get_client()
+        try:
+            response = await asyncio.to_thread(client.read, path)
+        except Exception as exc:  # noqa: BLE001
+            raise ValueError(f'could not read Vault path "{path}": {exc}') from exc
+
+        if response is None or "data" not in response:
+            raise ValueError(f'no data returned for path "{path}"')
+
+        outer = response["data"]
+        # KV v2 responses nest the secret under data.data alongside
+        # data.metadata; KV v1 responses put the secret straight in data.
+        if isinstance(outer, dict) and "data" in outer and "metadata" in outer:
+            return cast(Dict[str, Any], outer["data"])
+        return cast(Dict[str, Any], outer)
+
+    async def fetch_one(self, request: SecretFetchRequest) -> str:
+        data = await self._data_cache.fetch(request.path, lambda: self._fetch_data(request.path))
+
+        if not request.field:
+            if len(data) == 1:
+                (only,) = data.values()
+                return only if isinstance(only, str) else json.dumps(only)
+            return json.dumps(data)
+
+        return extract_field(json.dumps(data), request.field, provider=self.name, path=request.path)
+
+    async def health_check(self) -> ProviderHealth:
+        try:
+            client = self._get_client()
+            await asyncio.to_thread(client.sys.read_health_status)
+            return ProviderHealth(provider=self.name, ok=True)
+        except Exception as exc:  # noqa: BLE001
+            return ProviderHealth(provider=self.name, ok=False, message=str(exc))