ripv-py 1.0.0__py3-none-any.whl

pv/__init__.py

@@ -0,0 +1,48 @@
+"""PersonalVault Python SDK - secure API key retrieval for backend applications.
+
+Usage (sync):
+    import pv
+    pv.init()
+    openai_key = pv("OPENAI_API_KEY")
+
+Usage (async):
+    from pv import pv_async
+    openai_key = await pv_async("OPENAI_API_KEY")
+"""
+
+import types
+import sys
+
+from pv.client import (
+    pv,
+    pv_async,
+    init,
+    PVAuthError,
+    PVDeniedError,
+    PVKeyNotFoundError,
+    PVNotInitializedError,
+)
+
+__all__ = [
+    "pv",
+    "pv_async",
+    "init",
+    "PVAuthError",
+    "PVDeniedError",
+    "PVKeyNotFoundError",
+    "PVNotInitializedError",
+]
+
+__version__ = "1.0.0"
+
+
+class _CallableModule(types.ModuleType):
+    """Makes ``import pv; pv("KEY")`` work by forwarding calls to ``pv.pv``."""
+
+    def __call__(self, key_name: str) -> str:
+        return pv(key_name)
+
+
+# Replace this module's class so the module itself is callable.
+_self = sys.modules[__name__]
+_self.__class__ = _CallableModule

pv/client.py

@@ -0,0 +1,220 @@
+"""Core PersonalVault SDK client with sync and async key retrieval."""
+
+from __future__ import annotations
+
+import os
+import time
+from typing import Dict, List, Optional
+
+import httpx
+
+__all__ = [
+    "pv",
+    "pv_async",
+    "init",
+    "PVAuthError",
+    "PVDeniedError",
+    "PVKeyNotFoundError",
+    "PVNotInitializedError",
+]
+
+_SDK_VERSION = "1.0.0"
+_USER_AGENT = f"pv-python-sdk/{_SDK_VERSION}"
+
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+class PVAuthError(Exception):
+    """Raised when the PV_API_KEY is missing, invalid, or expired."""
+
+
+class PVDeniedError(Exception):
+    """Raised when the server rejects the request (403)."""
+
+
+class PVKeyNotFoundError(Exception):
+    """Raised when a requested key is not present in the vault cache."""
+
+
+class PVNotInitializedError(Exception):
+    """Raised when pv() is called before the SDK has been initialized."""
+
+
+# ---------------------------------------------------------------------------
+# Internal state
+# ---------------------------------------------------------------------------
+
+_key_cache: Dict[str, str] = {}
+_initialized: bool = False
+_cache_expiry: float = 0.0
+_cache_ttl: int = int(os.environ.get("PV_CACHE_TTL", "3600"))
+
+
+def _is_cache_valid() -> bool:
+    return _initialized and time.time() < _cache_expiry
+
+
+def _get_api_key() -> str:
+    key = os.environ.get("PV_API_KEY")
+    if not key:
+        raise PVAuthError(
+            "PersonalVault: PV_API_KEY not found in environment.\n"
+            "Generate one at https://pv.sprkt.xyz/dashboard -> Backend Keys"
+        )
+    return key
+
+
+def _get_api_url() -> str:
+    return os.environ.get("PV_API_URL", "https://pv.sprkt.xyz")
+
+
+def _build_headers(api_key: str) -> Dict[str, str]:
+    return {
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {api_key}",
+        "User-Agent": _USER_AGENT,
+    }
+
+
+def _handle_error_response(status_code: int, data: dict) -> None:
+    error_msg = data.get("error", "")
+    if status_code == 401:
+        raise PVAuthError(error_msg or "Invalid or expired backend key")
+    if status_code == 403:
+        raise PVDeniedError(error_msg or "Access denied")
+    raise Exception(error_msg or f"Request failed with status {status_code}")
+
+
+def _apply_fetched_keys(keys: Dict[str, str]) -> None:
+    global _key_cache, _initialized, _cache_expiry
+    _key_cache = keys
+    _initialized = True
+    _cache_expiry = time.time() + _cache_ttl
+
+
+# ---------------------------------------------------------------------------
+# Sync fetch (uses httpx.Client)
+# ---------------------------------------------------------------------------
+
+def _fetch_keys_sync(key_names: Optional[List[str]] = None) -> Dict[str, str]:
+    api_key = _get_api_key()
+    url = f"{_get_api_url()}/api/backend/keys"
+    body: dict = {}
+    if key_names:
+        body["keyNames"] = key_names
+
+    with httpx.Client() as client:
+        resp = client.post(url, json=body, headers=_build_headers(api_key))
+
+    if resp.status_code != 200:
+        try:
+            data = resp.json()
+        except Exception:
+            data = {}
+        _handle_error_response(resp.status_code, data)
+
+    return resp.json()["keys"]
+
+
+# ---------------------------------------------------------------------------
+# Async fetch (uses httpx.AsyncClient)
+# ---------------------------------------------------------------------------
+
+async def _fetch_keys_async(key_names: Optional[List[str]] = None) -> Dict[str, str]:
+    api_key = _get_api_key()
+    url = f"{_get_api_url()}/api/backend/keys"
+    body: dict = {}
+    if key_names:
+        body["keyNames"] = key_names
+
+    async with httpx.AsyncClient() as client:
+        resp = await client.post(url, json=body, headers=_build_headers(api_key))
+
+    if resp.status_code != 200:
+        try:
+            data = resp.json()
+        except Exception:
+            data = {}
+        _handle_error_response(resp.status_code, data)
+
+    return resp.json()["keys"]
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def init() -> None:
+    """Synchronously initialize the SDK by fetching keys from PersonalVault.
+
+    Use this in synchronous frameworks (Django, Flask) that don't have an
+    event loop. Blocks until the fetch completes.
+
+    Raises:
+        PVAuthError: If PV_API_KEY is missing or invalid.
+        PVDeniedError: If the server rejects the request.
+    """
+    if _is_cache_valid():
+        return
+    keys = _fetch_keys_sync()
+    _apply_fetched_keys(keys)
+
+
+def pv(key_name: str) -> str:
+    """Synchronously retrieve a key from the in-memory cache.
+
+    The SDK must be initialized first via ``init()`` or ``pv_async()``.
+
+    Args:
+        key_name: The name of the key to retrieve.
+
+    Returns:
+        The key value as a string.
+
+    Raises:
+        PVNotInitializedError: If the SDK has not been initialized or the
+            cache has expired.
+        PVKeyNotFoundError: If the key is not in the cache.
+    """
+    if not _is_cache_valid():
+        raise PVNotInitializedError(
+            "PersonalVault: not initialized. "
+            "Use pv_async() for the first call or call init()."
+        )
+    value = _key_cache.get(key_name)
+    if value is None:
+        raise PVKeyNotFoundError(
+            f"Key '{key_name}' not found in vault or not allowed for this backend key"
+        )
+    return value
+
+
+async def pv_async(key_name: str) -> str:
+    """Asynchronously retrieve a key, initializing the SDK if needed.
+
+    On the first call (or after cache expiry), this fetches keys from the
+    PersonalVault server. Subsequent calls return from the in-memory cache.
+
+    Args:
+        key_name: The name of the key to retrieve.
+
+    Returns:
+        The key value as a string.
+
+    Raises:
+        PVAuthError: If PV_API_KEY is missing or invalid.
+        PVDeniedError: If the server rejects the request.
+        PVKeyNotFoundError: If the key is not in the fetched results.
+    """
+    if not _is_cache_valid():
+        keys = await _fetch_keys_async()
+        _apply_fetched_keys(keys)
+
+    value = _key_cache.get(key_name)
+    if value is None:
+        raise PVKeyNotFoundError(
+            f"Key '{key_name}' not found in vault or not allowed for this backend key"
+        )
+    return value

ripv_py-1.0.0.dist-info/METADATA

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: ripv-py
+Version: 1.0.0
+Summary: Python SDK for PersonalVault - secure API key retrieval
+License-Expression: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: respx>=0.20; extra == "dev"
+
+# PersonalVault Python SDK
+
+Secure API key retrieval for Python backend applications.
+
+## Installation
+
+```bash
+pip install personalvault
+```
+
+## Quick Start
+
+### Environment Variables
+
+```bash
+export PV_API_KEY="pvault_bk_..."       # Required - your backend key
+export PV_API_URL="https://pv.example.com"  # Optional - defaults to http://localhost:8923
+export PV_CACHE_TTL="3600"              # Optional - cache TTL in seconds (default: 3600)
+```
+
+### Synchronous (Django, Flask)
+
+```python
+from personalvault import init, pv
+
+# Initialize once at startup
+init()
+
+# Retrieve keys instantly from cache
+openai_key = pv("OPENAI_API_KEY")
+db_password = pv("DB_PASS")
+```
+
+### Asynchronous (FastAPI, AIOHTTP)
+
+```python
+from personalvault import pv_async
+
+# Auto-initializes on first call, then serves from cache
+openai_key = await pv_async("OPENAI_API_KEY")
+db_password = await pv_async("DB_PASS")
+```
+
+## API Reference
+
+### `init() -> None`
+Synchronously fetch and cache all allowed keys. Blocks until complete.
+
+### `pv(key_name: str) -> str`
+Synchronous cache lookup. Raises `PVNotInitializedError` if `init()` hasn't been called or cache has expired.
+
+### `pv_async(key_name: str) -> str`
+Async key retrieval. Automatically initializes/refreshes the cache when needed.
+
+## Exceptions
+
+| Exception | When |
+|---|---|
+| `PVAuthError` | `PV_API_KEY` missing, invalid, or expired |
+| `PVDeniedError` | Server rejected request (IP allowlist, etc.) |
+| `PVKeyNotFoundError` | Key not in vault or not allowed for this backend key |
+| `PVNotInitializedError` | `pv()` called before `init()` or cache expired |
+
+## Framework Examples
+
+### FastAPI
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from personalvault import pv_async, pv
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await pv_async("DB_URL")  # warm the cache
+    yield
+
+app = FastAPI(lifespan=lifespan)
+
+@app.get("/")
+async def root():
+    return {"db": pv("DB_URL")}
+```
+
+### Flask
+
+```python
+from flask import Flask
+from personalvault import init, pv
+
+app = Flask(__name__)
+init()  # fetch keys at import time
+
+@app.route("/")
+def index():
+    return {"db": pv("DB_URL")}
+```
+
+### Django (settings.py)
+
+```python
+from personalvault import init, pv
+
+init()
+
+DATABASES = {
+    "default": {
+        "ENGINE": "django.db.backends.postgresql",
+        "PASSWORD": pv("DB_PASS"),
+    }
+}
+```

ripv_py-1.0.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+pv/__init__.py,sha256=XvuXioP7vIF7FOXBqj4OloPhKfgri_IMTUuprwzkcD4,976
+pv/client.py,sha256=vbmrJdvyxAq5mFTfL9M7EdQtrYb2tz0ot1EQ9OCaxOY,6676
+ripv_py-1.0.0.dist-info/METADATA,sha256=NELmvI0azMZIFObytSEGZK41hmO71y3fvWotUb8siL4,2909
+ripv_py-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+ripv_py-1.0.0.dist-info/top_level.txt,sha256=EfDDilaSYq7eE6JeB7uEi0pH_wB4I-t4tmKu5rqnjf4,3
+ripv_py-1.0.0.dist-info/RECORD,,

ripv_py-1.0.0.dist-info/WHEEL

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

ripv_py-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pv