yaml-secrets 0.1.0__py3-none-any.whl

yaml_secrets/__init__.py

@@ -0,0 +1,43 @@
+"""yaml_secrets — drop-in YAML with secret substitution from HashiCorp Vault or OpenBao."""
+
+from yaml_secrets.loader import (
+    SafeLoader,
+    Loader,
+    FullLoader,
+    UnsafeLoader,
+    CSafeLoader,
+    CLoader,
+    CFullLoader,
+    dump,
+    dump_all,
+    safe_dump,
+    safe_dump_all,
+    load,
+    safe_load,
+    load_all,
+    safe_load_all,
+)
+from yaml_secrets.vault import SecretClient, SecretError, SecretSettings
+
+__all__ = [
+    "SecretClient",
+    "SecretError",
+    "SecretSettings",
+    "CFullLoader",
+    "CLoader",
+    "CSafeLoader",
+    "FullLoader",
+    "Loader",
+    "SafeLoader",
+    "UnsafeLoader",
+    "dump",
+    "dump_all",
+    "load",
+    "load_all",
+    "safe_dump",
+    "safe_dump_all",
+    "safe_load",
+    "safe_load_all",
+]
+
+__version__ = "0.1.0"

yaml_secrets/loader.py

@@ -0,0 +1,203 @@
+"""Drop-in PyYAML-compatible loaders with secret substitution.
+
+Usage is identical to PyYAML::
+
+    import yaml_secrets as yaml
+    cfg = yaml.safe_load(open("config.yaml"))
+
+Templates use Jinja2 syntax::
+
+    api_key: "{{ vault('secret/app/db', 'api_key') }}"
+    # or the shorter tag form:
+    api_key: !vault secret/app/db#api_key
+    # or the filter form:
+    api_key: "{{ 'secret/app/db#api_key' | vault }}"
+
+Any Jinja2 expression works — ``{{ env.HOME }}``, ``{{ region }}`` — as long as
+it is a complete value. Jinja does not split string values, so keep the
+template as the whole YAML value.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Any, BinaryIO, IO, TextIO
+
+import yaml as _pyyaml
+from jinja2 import Environment, BaseLoader, StrictUndefined, Undefined
+
+from yaml_secrets.vault import SecretClient, SecretError, SecretSettings
+
+__all__ = [
+    "SafeLoader",
+    "Loader",
+    "FullLoader",
+    "UnsafeLoader",
+    "CSafeLoader",
+    "CLoader",
+    "CFullLoader",
+    "dump",
+    "dump_all",
+    "safe_dump",
+    "safe_dump_all",
+    "load",
+    "safe_load",
+    "load_all",
+    "safe_load_all",
+]
+
+# Jinja delimiters kept as class attributes so users can rebind them.
+BLOCK_START = "{{"
+BLOCK_END = "}}"
+STATEMENT_START = "{%"
+STATEMENT_END = "%}"
+COMMENT_START = "{#"
+COMMENT_END = "#}"
+
+_VAULT_TAG_RE = re.compile(
+    r"^(?P<indent>[ \t]*)(?P<key>[^\s:]+)\s*:\s*!vault\s+(?P<ref>\S+)$",
+    re.MULTILINE,
+)
+
+
+def _build_env(client: SecretClient, strict: bool = True) -> Environment:
+    env = Environment(
+        loader=BaseLoader(),
+        undefined=StrictUndefined if strict else Undefined,
+        autoescape=False,
+        keep_trailing_newline=True,
+        trim_blocks=True,
+        lstrip_blocks=True,
+    )
+
+    def vault(path: str, key: str | None = None, default: Any = ...) -> Any:
+        if key is None:
+            return client.read_secret(path)
+        return client.get(path, key, default=default)
+
+    def vault_get(path: str) -> dict[str, Any]:
+        return client.read_secret(path)
+
+    def vault_filter(path_and_key: str, default: Any = ...) -> Any:
+        if "#" not in path_and_key:
+            raise SecretError(f"vault filter needs 'path#key', got: {path_and_key!r}")
+        path, key = path_and_key.split("#", 1)
+        return client.get(path.strip(), key.strip(), default=default)
+
+    env.globals["vault"] = vault
+    env.globals["vault_get"] = vault_get
+    env.filters["vault"] = vault_filter
+    return env
+
+
+def _expand_vault_tags(text: str) -> str:
+    """Rewrite ``key: !vault path#field`` to Jinja before rendering."""
+
+    def repl(match: re.Match[str]) -> str:
+        indent = match.group("indent")
+        key = match.group("key")
+        ref = match.group("ref").strip().strip("'\"")
+        if "#" not in ref:
+            raise SecretError(f"!vault needs 'path#key', got: {ref!r}")
+        path, field = ref.split("#", 1)
+        expr = "{{ vault('%s', '%s') }}" % (path.strip(), field.strip())
+        return f"{indent}{key}: {expr}"
+
+    return _VAULT_TAG_RE.sub(repl, text)
+
+
+class _SecretMixin:
+    """Mixin that renders Jinja2 + expands !vault tags before handing off to
+    the underlying PyYAML loader."""
+
+    strict: bool = True
+
+    def __init__(self, stream: IO[str] | TextIO | BinaryIO | str | os.PathLike[str]) -> None:
+        if isinstance(stream, (str, os.PathLike)):
+            raw = Path(stream).read_text(encoding="utf-8")
+        else:
+            raw = stream.read()  # type: ignore[union-attr]
+
+        client = SecretClient()
+        env = _build_env(client, strict=self.strict)
+        rendered = env.from_string(_expand_vault_tags(raw)).render(env=os.environ)
+
+        import io
+
+        super().__init__(io.StringIO(rendered))
+
+
+class SafeLoader(_SecretMixin, _pyyaml.SafeLoader):
+    """Drop-in replacement for ``yaml.SafeLoader`` with Vault substitution."""
+
+    strict = True
+
+
+class Loader(_SecretMixin, _pyyaml.Loader):
+    strict = True
+
+
+class FullLoader(_SecretMixin, _pyyaml.FullLoader):
+    strict = True
+
+
+class UnsafeLoader(_SecretMixin, _pyyaml.UnsafeLoader):
+    strict = True
+
+
+# C-Loader variants map to the pure-Python loaders (functionally identical).
+CSafeLoader = SafeLoader
+CLoader = Loader
+CFullLoader = FullLoader
+
+
+def _load_with(
+    LoaderCls: type,
+    stream: IO[str] | TextIO | BinaryIO | str | os.PathLike[str],
+    Loader: type | None = None,
+) -> Any:
+    obj = LoaderCls(stream)
+    return obj.get_single_data()
+
+
+def _load_all_with(
+    LoaderCls: type,
+    stream: IO[str] | TextIO | BinaryIO | str | os.PathLike[str],
+    Loader: type | None = None,
+):
+    obj = LoaderCls(stream)
+    return obj.get_data()
+
+
+def safe_load(stream):
+    return _load_with(SafeLoader, stream)
+
+
+def load(stream, Loader=None):
+    return _load_with(Loader or Loader, stream)
+
+
+def safe_load_all(stream):
+    return _load_all_with(SafeLoader, stream)
+
+
+def load_all(stream, Loader=None):
+    return _load_all_with(Loader, stream)
+
+
+def safe_dump(data, stream=None, **kwargs):
+    return _pyyaml.safe_dump(data, stream, **kwargs)
+
+
+def safe_dump_all(data, stream=None, **kwargs):
+    return _pyyaml.safe_dump_all(data, stream, **kwargs)
+
+
+def dump(data, stream=None, **kwargs):
+    return _pyyaml.dump(data, stream, **kwargs)
+
+
+def dump_all(data, stream=None, **kwargs):
+    return _pyyaml.dump_all(data, stream, **kwargs)

yaml_secrets/vault.py

@@ -0,0 +1,214 @@
+"""Secret backend for Vault and OpenBao.
+
+Works with zero configuration: it auto-discovers a running Vault or OpenBao from
+environment variables. If none is reachable, lookups return defaults or raise
+clear errors — no server is ever required just to import the library.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+
+class SecretError(RuntimeError):
+    """Raised when a secret lookup fails."""
+
+
+def _env(name: str, default: str = "") -> str:
+    return os.environ.get(name, default)
+
+
+@dataclass
+class SecretSettings:
+    """Connection settings.
+
+    OpenBao is detected automatically when ``BOPENBAO_ADDR`` or ``OPENBAO_ADDR``
+    is set; otherwise standard ``VAULT_ADDR`` / ``VAULT_TOKEN`` variables are
+    used. Both servers share the KV API, so no code paths differ between them.
+    """
+
+    addr: str = field(
+        default_factory=lambda: _env("OPENBAO_ADDR", _env("VAULT_ADDR", _env("BAO_ADDR")))
+    )
+    token: str = field(
+        default_factory=lambda: _env("OPENBAO_TOKEN", _env("VAULT_TOKEN", _env("BAO_TOKEN")))
+    )
+    namespace: str = field(
+        default_factory=lambda: _env("OPENBAO_NAMESPACE", _env("VAULT_NAMESPACE"))
+    )
+    role_id: str = field(
+        default_factory=lambda: _env("OPENBAO_ROLE_ID", _env("VAULT_ROLE_ID"))
+    )
+    secret_id: str = field(
+        default_factory=lambda: _env("OPENBAO_SECRET_ID", _env("VAULT_SECRET_ID"))
+    )
+    kv_mount: str = field(
+        default_factory=lambda: _env("OPENBAO_KV_MOUNT", _env("VAULT_KV_MOUNT", "secret"))
+    )
+    kv_version: int = field(
+        default_factory=lambda: int(
+            _env("OPENBAO_KV_VERSION", _env("VAULT_KV_VERSION", "2")) or 2
+        )
+    )
+    cache_ttl_seconds: float = field(
+        default_factory=lambda: float(_env("BAO_CACHE_TTL", "60") or 60)
+    )
+    # Local fallback map for offline dev/tests. JSON or YAML, path -> {key: value}.
+    mock_secrets_path: str = field(
+        default_factory=lambda: _env("BAO_MOCK_SECRETS", _env("AICONF_MOCK_SECRETS"))
+    )
+
+    @property
+    def backend(self) -> str:
+        return "openbao" if _env("OPENBAO_ADDR", _env("BOPENBAO_ADDR")) else "vault"
+
+
+class SecretClient:
+    """Read KV secrets from Vault or OpenBao with local caching.
+
+    Usage is identical for both servers::
+
+        client = SecretClient()
+        value = client.get("secret/app/db", "password")
+        whole = client.read_secret("secret/app/db")
+    """
+
+    def __init__(self, settings: SecretSettings | None = None) -> None:
+        self.settings = settings or SecretSettings()
+        self._client: Any | None = None
+        self._cache: dict[str, tuple[float, dict[str, Any]]] = {}
+        self._mock: dict[str, dict[str, Any]] | None = None
+
+        if self.settings.mock_secrets_path:
+            self._mock = self._load_mock(self.settings.mock_secrets_path)
+
+    @staticmethod
+    def _load_mock(path: str) -> dict[str, dict[str, Any]]:
+        import json
+        from pathlib import Path
+
+        import yaml
+
+        file_path = Path(path)
+        if not file_path.exists():
+            return {}
+        text = file_path.read_text(encoding="utf-8")
+        if not text.strip():
+            return {}
+        data = yaml.safe_load(text) if path.endswith((".yaml", ".yml")) else json.loads(text)
+        if data is None:
+            return {}
+        if not isinstance(data, dict):
+            raise SecretError(f"Mock secrets file must be a mapping: {path}")
+        return {str(k): dict(v) for k, v in data.items()}
+
+    def _ensure_client(self) -> Any:
+        if self._mock is not None:
+            return None
+        if self._client is not None:
+            return self._client
+
+        if not self.settings.addr:
+            raise SecretError(
+                "No Vault/OpenBao server configured. Set VAULT_ADDR (or OPENBAO_ADDR) "
+                "and VAULT_TOKEN (or OPENBAO_TOKEN), or use BAO_MOCK_SECRETS for local mocks."
+            )
+
+        import hvac
+
+        client = hvac.Client(url=self.settings.addr, namespace=self.settings.namespace or None)
+
+        if self.settings.token:
+            client.token = self.settings.token
+        elif self.settings.role_id and self.settings.secret_id:
+            client.auth.approle.login(
+                role_id=self.settings.role_id,
+                secret_id=self.settings.secret_id,
+            )
+        else:
+            raise SecretError("No auth configured. Set VAULT_TOKEN or VAULT_ROLE_ID + VAULT_SECRET_ID.")
+
+        if not client.is_authenticated():
+            raise SecretError("Authentication failed.")
+
+        self._client = client
+        return client
+
+    @staticmethod
+    def _normalize_path(path: str, mount: str, kv_version: int) -> tuple[str, str]:
+        """Return (mount, secret_path) for a Vault path."""
+        path = path.strip().strip("/")
+        mount = mount.strip("/")
+        if path.startswith(f"{mount}/"):
+            rest = path[len(mount) + 1 :]
+            if kv_version == 2 and rest.startswith("data/"):
+                rest = rest[5:]
+            return mount, rest
+        return mount, path
+
+    def read_secret(self, path: str) -> dict[str, Any]:
+        """Read all key/value pairs at a KV path."""
+        now = time.monotonic()
+        cached = self._cache.get(path)
+        if cached and (now - cached[0]) < self.settings.cache_ttl_seconds:
+            return dict(cached[1])
+
+        if self._mock is not None:
+            data = self._mock.get(path) or self._mock.get(path.strip("/"))
+            if data is None:
+                mount, secret_path = self._normalize_path(
+                    path, self.settings.kv_mount, self.settings.kv_version
+                )
+                data = self._mock.get(secret_path) or self._mock.get(f"{mount}/{secret_path}")
+            if data is None:
+                raise SecretError(f"Secret not found: {path}")
+            self._cache[path] = (now, dict(data))
+            return dict(data)
+
+        client = self._ensure_client()
+        mount, secret_path = self._normalize_path(
+            path, self.settings.kv_mount, self.settings.kv_version
+        )
+
+        try:
+            if self.settings.kv_version == 2:
+                response = client.secrets.kv.v2.read_secret_version(
+                    path=secret_path, mount_point=mount
+                )
+                data = response["data"]["data"]
+            else:
+                response = client.secrets.kv.v1.read_secret(
+                    path=secret_path, mount_point=mount
+                )
+                data = response["data"]
+        except Exception as exc:  # noqa: BLE001
+            raise SecretError(f"Failed to read '{path}': {exc}") from exc
+
+        if not isinstance(data, dict):
+            raise SecretError(f"Unexpected secret payload at '{path}'")
+
+        self._cache[path] = (now, dict(data))
+        return dict(data)
+
+    def get(
+        self, path: str, key: str, default: Any = ..., *, required: bool = True
+    ) -> Any:
+        """Read one key from a secret path.
+
+        ``default=...`` (ellipsis) requires the key. Pass ``required=False`` to
+        return None when the key is missing.
+        """
+        data = self.read_secret(path)
+        if key not in data:
+            if default is not ...:
+                return default
+            if not required:
+                return None
+            raise SecretError(f"Key '{key}' not found at '{path}'")
+        return data[key]
+
+    def clear_cache(self) -> None:
+        self._cache.clear()

yaml_secrets-0.1.0.dist-info/METADATA

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: yaml-secrets
+Version: 0.1.0
+Summary: Drop-in PyYAML replacement with Vault/OpenBao secret substitution
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: jinja2>=3.0
+Requires-Dist: hvac>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# yaml_secrets
+
+Drop-in PyYAML replacement with secret substitution from HashiCorp Vault or OpenBao.
+
+## Install
+
+```bash
+cd configvault
+python3 -m venv .venv
+.venv/bin/pip install -e .
+```
+
+## Usage
+
+Replace `import yaml` with `import yaml_secrets as yaml` — nothing else changes.
+
+```python
+import yaml_secrets as yaml  # or: import vault_yaml as yaml / openbao_yaml as yaml
+
+with open("config.yaml") as f:
+    cfg = yaml.safe_load(f)
+```
+
+### Template syntax
+
+Three equivalent ways to reference a secret:
+
+```yaml
+# Jinja2 function (most common)
+api_key: "{{ vault('secret/app/db', 'api_key') }}"
+
+# YAML tag shortcut
+api_key: !vault secret/app/db#api_key
+
+# Jinja2 filter
+api_key: "{{ 'secret/app/db#api_key' | vault }}"
+```
+
+Any Jinja2 expression works:
+
+```yaml
+user: "{{ env.HOME }}/user"
+region: "{{ region }}"
+```
+
+## Configuration
+
+Set environment variables before importing yaml_secrets:
+
+```bash
+# HashiCorp Vault
+export VAULT_ADDR=https://vault.example.com:8200
+export VAULT_TOKEN=hvs.xxxxx
+
+# OpenBao (same API, different env prefix)
+export OPENBAO_ADDR=https://openbao.example.com:8200
+export OPENBAO_TOKEN=root-token-xxxxx
+
+# Local mock (no server required — for dev/tests)
+export BAO_MOCK_SECRETS=/path/to/mock-secrets.yaml
+```
+
+Mock file format:
+
+```yaml
+secret/app/db:
+  password: hunter2
+  host: db.internal
+secret/app/api:
+  api_key: sk-live-123
+```
+
+## Testing
+
+```bash
+.venv/bin/python -m pytest tests/ -v
+```

yaml_secrets-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+yaml_secrets/__init__.py,sha256=oZSF5DMd4eGXeffLymzEiyr_wydqNHTj5zQ8cUpI8pM,783
+yaml_secrets/loader.py,sha256=yFhvYSfdLTCf6yKEc3LHD6qpr34tqI4WOPiVlCNV_n8,5392
+yaml_secrets/vault.py,sha256=inCdSEC5Dqrg7g5mI-N-V52b_ROK3w4n4suKu0S4Y3E,7550
+yaml_secrets-0.1.0.dist-info/licenses/LICENSE,sha256=w1fPKhHdEihb-3_GM7U6VYf0EinqGvqB7yFXwI1u29M,1067
+yaml_secrets-0.1.0.dist-info/METADATA,sha256=xStfc8wDUTnAIdNZV2GF5KHU_DfkeU0VPmio9BkIAVM,1831
+yaml_secrets-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+yaml_secrets-0.1.0.dist-info/top_level.txt,sha256=YZnVRc9JUx0HG_6pQXcp51bMI_BjXizPWIpBUTKG_vE,13
+yaml_secrets-0.1.0.dist-info/RECORD,,

yaml_secrets-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

yaml_secrets-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tylerlhess
+
+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.

yaml_secrets-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+yaml_secrets