ranbval-sdk 1.4.0__py3-none-any.whl

ranbval_sdk/__init__.py

@@ -0,0 +1,115 @@
+"""Ranbval SDK — keep API secrets out of plaintext config.
+
+Encrypted vault tokens live in your ``.ranbval`` file; the SDK decrypts them only at the
+moment of use and never lets the plaintext reach a ``print``, log, or ``repr``.
+
+Public API, grouped by concern (each name re-exported from its home subpackage):
+
+- **Config** (:mod:`ranbval_sdk.config`) — ``load_ranbval``, ``get_project_key``,
+  ``find_ranbval_file``, ``find_ranbval_directory``, ``resolve_ranbval_mode``.
+- **Access** (:mod:`ranbval_sdk.config.access`) — ``Vault``, ``env``, ``inject``,
+  ``secrets``, ``iter_secrets``, ``public``, ``public_config``, ``is_public``,
+  ``Secret``, ``SecretConfig``, ``SecretProvider``.
+- **Crypto** (:mod:`ranbval_sdk.crypto`) — ``safe_decrypt``, ``decrypt_key``,
+  ``SecretString``, ``get_audit_log``, ``clear_audit_log``, ``audit_scope``.
+- **Telemetry** (:mod:`ranbval_sdk.telemetry`) — ``emit_telemetry``, ``aemit_telemetry``,
+  ``track``, ``tracked``.
+- **Integrations** (:mod:`ranbval_sdk.integrations`) — ``secure_client``, ``build_secure_client``.
+- **Secure proxy** (:mod:`ranbval_sdk.integrations.proxy`) — ``proxy_request``, ``aproxy_request``.
+- **Exceptions** (:mod:`ranbval_sdk.exceptions`) — ``RanbvalError`` and its subclasses.
+
+Basic use::
+
+    from ranbval_sdk import load_ranbval, decrypt_key
+    load_ranbval()
+    client = openai.OpenAI(api_key=decrypt_key("OPENAI_API_KEY").use())
+"""
+
+from ranbval_sdk.config import (
+    Secret,
+    SecretConfig,
+    SecretProvider,
+    Vault,
+    env,
+    find_ranbval_directory,
+    find_ranbval_file,
+    get_project_key,
+    inject,
+    is_public,
+    iter_secrets,
+    load_ranbval,
+    public,
+    public_config,
+    resolve_ranbval_mode,
+    secrets,
+)
+from ranbval_sdk.crypto import (
+    SecretString,
+    audit_scope,
+    clear_audit_log,
+    decrypt_key,
+    get_audit_log,
+    safe_decrypt,
+)
+from ranbval_sdk.exceptions import (
+    MissingKeyError,
+    ProxyError,
+    RanbvalConfigError,
+    RanbvalDecryptError,
+    RanbvalError,
+    RepoNotAllowedError,
+    RepoPolicyError,
+)
+from ranbval_sdk.integrations.factory import secure_client
+from ranbval_sdk.integrations.proxy import aproxy_request, proxy_request
+from ranbval_sdk.integrations.universal import build_secure_client
+from ranbval_sdk.telemetry import aemit_telemetry, emit_telemetry, track, tracked
+
+__version__ = "1.4.0"
+
+__all__ = [
+    # Config
+    "load_ranbval",
+    "get_project_key",
+    "find_ranbval_file",
+    "find_ranbval_directory",
+    "resolve_ranbval_mode",
+    # Access
+    "Vault",
+    "env",
+    "inject",
+    "secrets",
+    "iter_secrets",
+    "public",
+    "public_config",
+    "is_public",
+    "Secret",
+    "SecretConfig",
+    "SecretProvider",
+    # Crypto
+    "safe_decrypt",
+    "decrypt_key",
+    "SecretString",
+    "get_audit_log",
+    "clear_audit_log",
+    "audit_scope",
+    # Telemetry
+    "emit_telemetry",
+    "aemit_telemetry",
+    "track",
+    "tracked",
+    # Integrations
+    "secure_client",
+    "build_secure_client",
+    # Secure proxy
+    "proxy_request",
+    "aproxy_request",
+    # Exceptions
+    "RanbvalError",
+    "RanbvalDecryptError",
+    "RanbvalConfigError",
+    "MissingKeyError",
+    "RepoNotAllowedError",
+    "RepoPolicyError",
+    "ProxyError",
+]

ranbval_sdk/_internal/__init__.py

@@ -0,0 +1,5 @@
+"""Internal cross-cutting utilities (not part of the public API).
+
+- :mod:`~ranbval_sdk._internal.defaults` — shared constants and the telemetry-debug hook.
+- :mod:`~ranbval_sdk._internal.transport` — HTTPS via urllib with certifi's CA bundle.
+"""

ranbval_sdk/_internal/defaults.py

@@ -0,0 +1,11 @@
+"""Shared default constants for optional configuration.
+
+Override with environment variables when needed (e.g. self-hosted or local dev).
+"""
+
+# Password-manager origin only — no ``/api`` suffix (SDK appends ``/api/...`` paths).
+DEFAULT_RANBVAL_HOST = "https://api.ranbval.com"
+
+# The stderr debug warning moved to ``_internal.logging``; re-exported here so any
+# existing ``from ranbval_sdk._internal.defaults import warn_telemetry_send_failed`` keeps working.
+from ranbval_sdk._internal.logging import warn_telemetry_send_failed  # noqa: E402,F401

ranbval_sdk/_internal/logging.py

@@ -0,0 +1,17 @@
+"""Internal diagnostics — opt-in stderr warnings for otherwise-silent failures.
+
+The SDK never prints by default. Setting ``RANBVAL_TELEMETRY_DEBUG=1`` surfaces why a
+best-effort telemetry POST failed, so CI can debug it without changing code.
+"""
+
+import os
+import sys
+
+
+def warn_telemetry_send_failed(host: str, exc: BaseException) -> None:
+    """If ``RANBVAL_TELEMETRY_DEBUG=1``, print why POST /api/telemetry failed (default is silent)."""
+    v = (os.environ.get("RANBVAL_TELEMETRY_DEBUG") or "").strip().lower()
+    if v not in ("1", "true", "yes", "on"):
+        return
+    url = f"{host.rstrip('/')}/api/telemetry"
+    print(f"[Ranbval] Telemetry POST failed ({url}): {exc!r}", file=sys.stderr)

ranbval_sdk/_internal/transport.py

@@ -0,0 +1,17 @@
+"""HTTPS via urllib with certifi's CA bundle (fixes common macOS SSL verify failures)."""
+
+from __future__ import annotations
+
+import ssl
+import urllib.request
+from typing import Any
+
+
+def urlopen(req: urllib.request.Request, timeout: float | None = None) -> Any:
+    full = req.get_full_url()
+    if full.lower().startswith("https:"):
+        import certifi
+
+        ctx = ssl.create_default_context(cafile=certifi.where())
+        return urllib.request.urlopen(req, timeout=timeout, context=ctx)
+    return urllib.request.urlopen(req, timeout=timeout)

ranbval_sdk/config/__init__.py

@@ -0,0 +1,45 @@
+"""Configuration: loading ``.ranbval`` files and accessing the values in them.
+
+- :mod:`~ranbval_sdk.config.loader` — parse and merge layered ``.ranbval*`` files into the env.
+- :mod:`~ranbval_sdk.config.access` — imperative access (``Vault``, ``inject``, ``secrets``).
+- :mod:`~ranbval_sdk.config.declarative` — class-based access (``Secret``, ``SecretConfig``).
+"""
+
+from ranbval_sdk.config.access import (
+    SecretProvider,
+    Vault,
+    env,
+    inject,
+    is_public,
+    iter_secrets,
+    public,
+    public_config,
+    secrets,
+)
+from ranbval_sdk.config.declarative import Secret, SecretConfig
+from ranbval_sdk.config.loader import (
+    find_ranbval_directory,
+    find_ranbval_file,
+    get_project_key,
+    load_ranbval,
+    resolve_ranbval_mode,
+)
+
+__all__ = [
+    "load_ranbval",
+    "get_project_key",
+    "find_ranbval_file",
+    "find_ranbval_directory",
+    "resolve_ranbval_mode",
+    "Vault",
+    "env",
+    "inject",
+    "secrets",
+    "iter_secrets",
+    "public",
+    "public_config",
+    "is_public",
+    "Secret",
+    "SecretConfig",
+    "SecretProvider",
+]

ranbval_sdk/config/access.py

@@ -0,0 +1,367 @@
+"""High-level, ergonomic access to your ``.ranbval`` configuration surface.
+
+Thin, readable wrappers over :func:`~ranbval_sdk.config.loader.load_ranbval` and
+:func:`~ranbval_sdk.crypto.decrypt_key` so applications consume secrets with almost no
+boilerplate — a :class:`Vault` mapping, an ``@inject`` decorator, a ``secrets()`` context
+manager, and a :class:`Secret` descriptor. Decryption still happens only in
+``crypto.safe_decrypt``; these are pure convenience. Secrets stay sealed by default.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import functools
+import inspect
+import os
+import threading
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+from ranbval_sdk.config.loader import load_ranbval
+from ranbval_sdk.crypto.secret_string import SecretString
+from ranbval_sdk.exceptions import MissingKeyError, RanbvalConfigError
+
+_loaded_modes: set[str] = set()
+_load_lock = threading.Lock()
+
+#: Sentinel so ``public(name)`` can tell "no default given" apart from ``default=None``.
+_UNSET = object()
+
+
+def _is_token(value: str | None) -> bool:
+    """A value is a Ranbval vault token when it carries the ``ranbval.`` prefix."""
+    return bool(value) and value.startswith("ranbval.")
+
+
+def _ensure_env_loaded(mode: str | None = None) -> None:
+    """Load ``.ranbval*`` files for ``mode`` exactly once per process (thread-safe)."""
+    marker = mode or "__default__"
+    if marker in _loaded_modes:
+        return
+    with _load_lock:
+        if marker not in _loaded_modes:
+            load_ranbval(mode=mode)
+            _loaded_modes.add(marker)
+
+
+def _resolve(env_var: str, *, reveal: bool) -> Any:
+    """Decrypt a vault token or pass a plain value through; optionally reveal plaintext."""
+    raw = os.environ.get(env_var)
+    if raw is None:
+        raise MissingKeyError(
+            f"{env_var!r} is not set — did you create it in your .ranbval file?"
+        )
+    if not _is_token(raw):
+        return raw  # ordinary, safe-to-commit config value
+    from ranbval_sdk.crypto import decrypt_key
+
+    secret = decrypt_key(env_var)
+    return secret.use() if reveal else secret
+
+
+@runtime_checkable
+class SecretProvider(Protocol):
+    """Anything that can hand back a plaintext secret by name."""
+
+    def reveal(self, name: str) -> str: ...
+
+
+@dataclass(frozen=True, slots=True)
+class _Options:
+    mode: str | None = None
+    override: bool = False
+    autoload: bool = True
+
+
+class Vault:
+    """A lazy, dunder-rich view over your configuration surface.
+
+    Loads ``.ranbval*`` on first access, then serves values by attribute or item —
+    plain config as ``str``, secrets as :class:`SecretString` (decrypted once, cached)::
+
+        vault = Vault()
+        vault.OPENAI_API_KEY            # -> SecretString
+        vault["DATABASE_URL"]            # -> str (plain value)
+        vault.reveal("OPENAI_API_KEY")  # -> plaintext str, one line
+        "STRIPE_KEY" in vault            # membership test
+    """
+
+    __slots__ = ("_cache", "_loaded", "_opts", "_lock")
+
+    def __init__(
+        self, *, mode: str | None = None, override: bool = False, autoload: bool = True
+    ):
+        self._cache: dict[str, Any] = {}
+        self._loaded = False
+        self._lock = threading.Lock()
+        self._opts = _Options(mode=mode, override=override, autoload=autoload)
+
+    def _ensure_loaded(self) -> None:
+        if self._opts.autoload and not self._loaded:
+            with self._lock:
+                if not self._loaded:
+                    load_ranbval(mode=self._opts.mode, override=self._opts.override)
+                    self._loaded = True
+
+    def _get(self, name: str) -> Any:
+        self._ensure_loaded()
+        if name not in self._cache:
+            self._cache[name] = _resolve(name, reveal=False)
+        return self._cache[name]
+
+    # -- mapping protocol ---------------------------------------------------
+    def __getattr__(self, name: str) -> Any:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        try:
+            return self._get(name)
+        except KeyError as exc:
+            raise AttributeError(str(exc)) from exc
+
+    def __getitem__(self, name: str) -> Any:
+        return self._get(name)
+
+    def __contains__(self, name: str) -> bool:
+        self._ensure_loaded()
+        return name in os.environ
+
+    def __iter__(self) -> Iterator[str]:
+        self._ensure_loaded()
+        return iter(os.environ)
+
+    # -- public (unencrypted) access ---------------------------------------
+    def public(self, name: str, default: Any = _UNSET) -> str:
+        """Return a **plaintext** config value the public way — same policy as :func:`public`.
+
+        A key declared ``[secrets]`` (or any ``ranbval.*`` token) is refused, so a secret can
+        never be read through this public path::
+
+            env.public("DATABASE_URL")     # -> plain str
+            env.public("OPENAI_API_KEY")   # -> RanbvalConfigError (it's a secret)
+        """
+        self._ensure_loaded()
+        return _lookup_public(name, default)
+
+    def public_config(self) -> dict[str, str]:
+        """Every ``[public]``-declared key as ``{name: plaintext}`` (secrets never included)."""
+        self._ensure_loaded()
+        return _lookup_public_config()
+
+    # -- ergonomic helpers --------------------------------------------------
+    def reveal(self, name: str) -> str:
+        """Return the plaintext value in a single call (decrypts if needed)."""
+        value = self._get(name)
+        return value.use() if isinstance(value, SecretString) else value
+
+    async def areveal(self, name: str) -> str:
+        """Async, non-blocking :meth:`reveal` — decrypt + policy fetch run off-loop.
+
+        The vault-token decrypt makes a network call for repo policy; on an event
+        loop use this so FastAPI / asyncio callers don't block::
+
+            key = await vault.areveal("OPENAI_API_KEY")
+        """
+        import asyncio
+
+        return await asyncio.to_thread(self.reveal, name)
+
+    def get(self, name: str, default: Any = None) -> Any:
+        try:
+            return self._get(name)
+        except KeyError:
+            return default
+
+    def wipe(self) -> None:
+        """Zero every cached secret from memory."""
+        for value in self._cache.values():
+            if isinstance(value, SecretString):
+                value.wipe()
+        self._cache.clear()
+
+    def __repr__(self) -> str:  # never prints values — names only
+        return f"<Vault loaded={self._loaded} cached={list(self._cache)}>"
+
+
+#: Ready-to-use module singleton, e.g. ``ranbval_sdk.env.reveal("OPENAI_API_KEY")``.
+env = Vault()
+
+
+def inject(
+    *names: str, reveal: bool = False, mode: str | None = None, **aliases: str
+) -> Callable:
+    """Decorator that injects decrypted secrets into a function as keyword arguments.
+
+    ::
+
+        @inject("OPENAI_API_KEY")             # -> kwarg `openai_api_key` (SecretString)
+        def main(openai_api_key):
+            client = OpenAI(api_key=openai_api_key.use())   # reveal only at the call site
+
+    **Security-first default:** injects a sealed :class:`SecretString` — it refuses to be
+    printed or logged, and wipes itself from memory. Plaintext is never handed out by
+    default; call ``.use()`` at the exact point you pass it to an API. ``reveal=True`` is
+    an explicit opt-in that injects a guarded ``_ProtectedStr`` (still refuses to print) —
+    use it only when a library needs a plain ``str`` and you accept the trade-off.
+
+    Works on sync **and** async functions. Any argument the caller passes explicitly is
+    left untouched.
+    """
+    mapping: dict[str, str] = {name.lower(): name for name in names}
+    mapping.update(aliases)
+
+    def _fill(kwargs: dict[str, Any]) -> None:
+        _ensure_env_loaded(mode)
+        for param, env_var in mapping.items():
+            if param not in kwargs:
+                kwargs[param] = _resolve(env_var, reveal=reveal)
+
+    def decorator(fn: Callable) -> Callable:
+        if inspect.iscoroutinefunction(fn):
+
+            @functools.wraps(fn)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                _fill(kwargs)
+                return await fn(*args, **kwargs)
+
+            return async_wrapper
+
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            _fill(kwargs)
+            return fn(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+@contextlib.contextmanager
+def secrets(*, mode: str | None = None, override: bool = False) -> Iterator[Vault]:
+    """Context manager: load config, yield a :class:`Vault`, wipe secrets on exit.
+
+    ::
+
+        with secrets() as vault:
+            client = OpenAI(api_key=vault.reveal("OPENAI_API_KEY"))
+        # every decrypted secret is zeroed here
+    """
+    vault = Vault(mode=mode, override=override, autoload=True)
+    vault._ensure_loaded()
+    try:
+        yield vault
+    finally:
+        vault.wipe()
+
+
+def iter_secrets(*, mode: str | None = None) -> Iterator[tuple[str, SecretString]]:
+    """Yield ``(name, SecretString)`` for every vault token in the environment.
+
+    ::
+
+        for name, secret in iter_secrets():
+            print(name)          # names only — values stay sealed
+    """
+    _ensure_env_loaded(mode)
+    from ranbval_sdk.crypto import decrypt_key
+
+    for name, raw in os.environ.items():
+        if _is_token(raw):
+            yield name, decrypt_key(name)
+
+
+# -- public (unencrypted) configuration --------------------------------------
+def _lookup_public(name: str, default: Any) -> str:
+    """The single place that enforces the public-access policy (env assumed loaded).
+
+    A key declared ``[secrets]`` — or any ``ranbval.*`` token value — is **never** returned
+    here; both raise. This is what guarantees a secret can never leak through a public path,
+    no matter which surface (function or ``Vault`` method) the caller used.
+    """
+    from ranbval_sdk.config import manifest
+
+    if manifest.is_secret(name):
+        raise RanbvalConfigError(
+            f"{name!r} is declared under [secrets]; use decrypt_key({name!r}) instead. "
+            "public() only returns plaintext configuration.",
+            code="not_a_public_key",
+        )
+
+    raw = os.environ.get(name)
+    if raw is None:
+        if default is not _UNSET:
+            return default
+        raise MissingKeyError(
+            f"{name!r} is not set — did you create it in your .ranbval file?"
+        )
+    if _is_token(raw):
+        raise RanbvalConfigError(
+            f"{name!r} holds an encrypted vault token, not a plaintext value. "
+            f"Use decrypt_key({name!r}) to decrypt it.",
+            code="not_a_public_key",
+        )
+    return raw
+
+
+def _lookup_public_config() -> dict[str, str]:
+    """Collect all ``[public]``-declared plaintext values (env assumed loaded)."""
+    from ranbval_sdk.config import manifest
+
+    out: dict[str, str] = {}
+    for name in manifest.public_names():
+        raw = os.environ.get(name)
+        if raw is not None and not _is_token(raw):
+            out[name] = raw
+    return out
+
+
+def public(name: str, default: Any = _UNSET, *, mode: str | None = None) -> str:
+    """Return a **plaintext** config value — never decrypts, never a :class:`SecretString`.
+
+    For values you intentionally keep unencrypted (``DATABASE_URL``, ``CORS_ORIGINS``,
+    ``PORT``, …). Declare them under a ``[public]`` section in ``.ranbval`` to make the
+    intent explicit::
+
+        # .ranbval
+        [public]
+        DATABASE_URL=postgresql://localhost/mydb
+        CORS_ORIGINS=https://a.com,https://b.com
+
+        # app.py
+        from ranbval_sdk import public
+        db = public("DATABASE_URL")          # -> plain str
+
+    Safety rails:
+
+    - If the key was declared under ``[secrets]``, this raises — use ``decrypt_key`` for it.
+    - If the value looks like an encrypted ``ranbval.*`` token, this raises rather than
+      handing back ciphertext (you almost certainly meant :func:`~ranbval_sdk.decrypt_key`).
+
+    ``default`` is returned when the key is absent (otherwise :class:`MissingKeyError`).
+    """
+    _ensure_env_loaded(mode)
+    return _lookup_public(name, default)
+
+
+def public_config(*, mode: str | None = None) -> dict[str, str]:
+    """Return every key declared under ``[public]`` as a ``{name: plaintext}`` dict.
+
+    ::
+
+        cfg = public_config()
+        app.add_middleware(CORSMiddleware, allow_origins=cfg["CORS_ORIGINS"].split(","))
+    """
+    _ensure_env_loaded(mode)
+    return _lookup_public_config()
+
+
+def is_public(name: str) -> bool:
+    """True when *name* was declared under a ``[public]`` section in ``.ranbval``."""
+    from ranbval_sdk.config import manifest
+
+    return manifest.is_public(name)
+
+
+# The declarative, class-based API (``Secret`` / ``SecretConfig``) lives in
+# ``ranbval_sdk.config.declarative`` — a distinct access style from the imperative
+# ``Vault`` / ``inject`` / ``secrets`` above. Both are re-exported from ``config``.

ranbval_sdk/config/declarative.py

@@ -0,0 +1,72 @@
+"""Declarative secret configuration — the class-based access style.
+
+Complements the imperative API in :mod:`ranbval_sdk.config.access` (``Vault`` / ``inject`` /
+``secrets``): here you *declare* a config class whose fields are :class:`Secret` descriptors,
+decrypted lazily and cached per subclass. Both styles resolve through the same
+``config.access._resolve`` so behavior and sealing defaults stay identical.
+
+::
+
+    class Config(SecretConfig):
+        openai = Secret("OPENAI_API_KEY")
+        stripe = Secret("STRIPE_KEY", reveal=True)   # plaintext str
+
+    Config.openai   # -> SecretString (cached on the class)
+    Config.stripe   # -> plaintext str
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ranbval_sdk.config.access import _ensure_env_loaded, _resolve
+from ranbval_sdk.crypto.secret_string import SecretString
+
+
+class Secret:
+    """Descriptor for declaring a secret on a config class — decrypted lazily, cached.
+
+    ::
+
+        class Config(SecretConfig):
+            openai = Secret("OPENAI_API_KEY")
+            stripe = Secret("STRIPE_KEY", reveal=True)   # plaintext str
+
+        Config.openai        # -> SecretString (cached on the class)
+        Config.stripe        # -> plaintext str
+    """
+
+    __slots__ = ("env_var", "reveal", "attr")
+
+    def __init__(self, env_var: str, *, reveal: bool = False):
+        self.env_var = env_var
+        self.reveal = reveal
+        self.attr = env_var
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        self.attr = name
+
+    def __get__(self, obj: Any, owner: type | None = None) -> Any:
+        holder = owner if owner is not None else type(obj)
+        _ensure_env_loaded()
+        store = holder._secret_cache
+        if self.env_var not in store:
+            store[self.env_var] = _resolve(self.env_var, reveal=False)
+        value = store[self.env_var]
+        if self.reveal and isinstance(value, SecretString):
+            return value.use()
+        return value
+
+
+class SecretConfig:
+    """Base for declarative secret config classes; each subclass gets its own cache."""
+
+    _secret_cache: dict[str, Any] = {}
+    _secret_fields: tuple[str, ...] = ()
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        cls._secret_cache = {}
+        cls._secret_fields = tuple(
+            name for name, value in vars(cls).items() if isinstance(value, Secret)
+        )