ripv-py 1.0.0__tar.gz

ripv_py-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,112 @@
+# 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/pyproject.toml

@@ -0,0 +1,15 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ripv-py"
+version = "1.0.0"
+description = "Python SDK for PersonalVault - secure API key retrieval"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.8"
+dependencies = ["httpx>=0.24.0"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-asyncio>=0.21", "respx>=0.20"]

ripv_py-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ripv_py-1.0.0/src/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

ripv_py-1.0.0/src/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/src/ripv_py.egg-info/PKG-INFO

@@ -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/src/ripv_py.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+src/pv/__init__.py
+src/pv/client.py
+src/ripv_py.egg-info/PKG-INFO
+src/ripv_py.egg-info/SOURCES.txt
+src/ripv_py.egg-info/dependency_links.txt
+src/ripv_py.egg-info/requires.txt
+src/ripv_py.egg-info/top_level.txt
+tests/test_client.py

ripv_py-1.0.0/src/ripv_py.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ripv_py-1.0.0/src/ripv_py.egg-info/requires.txt

@@ -0,0 +1,6 @@
+httpx>=0.24.0
+
+[dev]
+pytest>=7.0
+pytest-asyncio>=0.21
+respx>=0.20

ripv_py-1.0.0/src/ripv_py.egg-info/top_level.txt

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

ripv_py-1.0.0/tests/test_client.py

@@ -0,0 +1,254 @@
+"""Tests for the PersonalVault Python SDK."""
+
+from __future__ import annotations
+
+import time
+from unittest.mock import patch
+
+import httpx
+import pytest
+import pytest_asyncio  # noqa: F401 (ensures plugin is loaded)
+import respx
+
+import pv
+from pv import (
+    pv_async,
+    init,
+    PVAuthError,
+    PVDeniedError,
+    PVKeyNotFoundError,
+    PVNotInitializedError,
+)
+from pv import client as _client
+
+API_URL = "http://localhost:8923"
+FAKE_KEY = "pvault_bk_testkey123"
+MOCK_KEYS = {"OPENAI_API_KEY": "sk-test123", "DB_PASS": "secret456"}
+
+
+@pytest.fixture(autouse=True)
+def _reset_state(monkeypatch):
+    """Reset SDK internal state before each test."""
+    _client._key_cache.clear()
+    _client._initialized = False
+    _client._cache_expiry = 0.0
+    _client._cache_ttl = 3600
+    monkeypatch.setenv("PV_API_URL", API_URL)
+    monkeypatch.delenv("PV_API_KEY", raising=False)
+    yield
+
+
+# ---------------------------------------------------------------------------
+# PV_API_KEY missing
+# ---------------------------------------------------------------------------
+
+class TestMissingApiKey:
+    def test_sync_init_raises(self):
+        with pytest.raises(PVAuthError, match="PV_API_KEY not found"):
+            init()
+
+    @pytest.mark.asyncio
+    async def test_async_raises(self):
+        with pytest.raises(PVAuthError, match="PV_API_KEY not found"):
+            await pv_async("ANY_KEY")
+
+
+# ---------------------------------------------------------------------------
+# Sync pv() before init
+# ---------------------------------------------------------------------------
+
+class TestNotInitialized:
+    def test_pv_raises(self):
+        with pytest.raises(PVNotInitializedError, match="not initialized"):
+            pv("SOME_KEY")
+
+
+# ---------------------------------------------------------------------------
+# Key not found
+# ---------------------------------------------------------------------------
+
+class TestKeyNotFound:
+    @respx.mock
+    def test_sync_key_not_found(self, monkeypatch):
+        monkeypatch.setenv("PV_API_KEY", FAKE_KEY)
+        respx.post(f"{API_URL}/api/backend/keys").mock(
+            return_value=httpx.Response(200, json={"keys": MOCK_KEYS})
+        )
+        init()
+        with pytest.raises(PVKeyNotFoundError, match="MISSING"):
+            pv("MISSING")
+
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_async_key_not_found(self, monkeypatch):
+        monkeypatch.setenv("PV_API_KEY", FAKE_KEY)
+        respx.post(f"{API_URL}/api/backend/keys").mock(
+            return_value=httpx.Response(200, json={"keys": MOCK_KEYS})
+        )
+        with pytest.raises(PVKeyNotFoundError, match="MISSING"):
+            await pv_async("MISSING")
+
+
+# ---------------------------------------------------------------------------
+# Successful retrieval
+# ---------------------------------------------------------------------------
+
+class TestSuccessfulRetrieval:
+    @respx.mock
+    def test_sync_flow(self, monkeypatch):
+        """import pv; pv.init(); pv("KEY") pattern."""
+        monkeypatch.setenv("PV_API_KEY", FAKE_KEY)
+        respx.post(f"{API_URL}/api/backend/keys").mock(
+            return_value=httpx.Response(200, json={"keys": MOCK_KEYS})
+        )
+        pv.init()
+        assert pv("OPENAI_API_KEY") == "sk-test123"
+        assert pv("DB_PASS") == "secret456"
+
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_async_flow(self, monkeypatch):
+        """from pv import pv_async; await pv_async("KEY") pattern."""
+        monkeypatch.setenv("PV_API_KEY", FAKE_KEY)
+        respx.post(f"{API_URL}/api/backend/keys").mock(
+            return_value=httpx.Response(200, json={"keys": MOCK_KEYS})
+        )
+        assert await pv_async("OPENAI_API_KEY") == "sk-test123"
+        assert await pv_async("DB_PASS") == "secret456"
+
+
+# ---------------------------------------------------------------------------
+# Cache expiry
+# ---------------------------------------------------------------------------
+
+class TestCacheExpiry:
+    @respx.mock
+    def test_expired_cache_raises_not_initialized(self, monkeypatch):
+        monkeypatch.setenv("PV_API_KEY", FAKE_KEY)
+        respx.post(f"{API_URL}/api/backend/keys").mock(
+            return_value=httpx.Response(200, json={"keys": MOCK_KEYS})
+        )
+        init()
+        assert pv("OPENAI_API_KEY") == "sk-test123"
+
+        # Force cache expiry
+        _client._cache_expiry = time.time() - 1
+        with pytest.raises(PVNotInitializedError):
+            pv("OPENAI_API_KEY")
+
+
+# ---------------------------------------------------------------------------
+# HTTP error handling
+# ---------------------------------------------------------------------------
+
+class TestHttpErrors:
+    @respx.mock
+    def test_401_raises_auth_error(self, monkeypatch):
+        monkeypatch.setenv("PV_API_KEY", FAKE_KEY)
+        respx.post(f"{API_URL}/api/backend/keys").mock(
+            return_value=httpx.Response(
+                401, json={"error": "Invalid or expired backend key"}
+            )
+        )
+        with pytest.raises(PVAuthError, match="Invalid or expired"):
+            init()
+
+    @respx.mock
+    def test_403_raises_denied_error(self, monkeypatch):
+        monkeypatch.setenv("PV_API_KEY", FAKE_KEY)
+        respx.post(f"{API_URL}/api/backend/keys").mock(
+            return_value=httpx.Response(
+                403, json={"error": "IP not in allowlist"}
+            )
+        )
+        with pytest.raises(PVDeniedError, match="IP not in allowlist"):
+            init()
+
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_401_async(self, monkeypatch):
+        monkeypatch.setenv("PV_API_KEY", FAKE_KEY)
+        respx.post(f"{API_URL}/api/backend/keys").mock(
+            return_value=httpx.Response(
+                401, json={"error": "Invalid or expired backend key"}
+            )
+        )
+        with pytest.raises(PVAuthError):
+            await pv_async("ANY")
+
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_403_async(self, monkeypatch):
+        monkeypatch.setenv("PV_API_KEY", FAKE_KEY)
+        respx.post(f"{API_URL}/api/backend/keys").mock(
+            return_value=httpx.Response(403, json={"error": "Access denied"})
+        )
+        with pytest.raises(PVDeniedError):
+            await pv_async("ANY")
+
+
+# ---------------------------------------------------------------------------
+# User-Agent header
+# ---------------------------------------------------------------------------
+
+class TestUserAgent:
+    @respx.mock
+    def test_sends_user_agent(self, monkeypatch):
+        monkeypatch.setenv("PV_API_KEY", FAKE_KEY)
+        route = respx.post(f"{API_URL}/api/backend/keys").mock(
+            return_value=httpx.Response(200, json={"keys": MOCK_KEYS})
+        )
+        init()
+        request = route.calls[0].request
+        assert request.headers["user-agent"] == "pv-python-sdk/1.0.0"
+
+
+# ---------------------------------------------------------------------------
+# Cache TTL env var
+# ---------------------------------------------------------------------------
+
+class TestCacheTTLConfig:
+    @respx.mock
+    def test_custom_ttl(self, monkeypatch):
+        monkeypatch.setenv("PV_API_KEY", FAKE_KEY)
+        _client._cache_ttl = 60  # 1 minute
+        respx.post(f"{API_URL}/api/backend/keys").mock(
+            return_value=httpx.Response(200, json={"keys": MOCK_KEYS})
+        )
+        init()
+        # Verify expiry is roughly 60s from now, not 3600s
+        assert _client._cache_expiry < time.time() + 120
+
+
+# ---------------------------------------------------------------------------
+# Init is idempotent when cache is valid
+# ---------------------------------------------------------------------------
+
+class TestIdempotentInit:
+    @respx.mock
+    def test_init_only_fetches_once(self, monkeypatch):
+        monkeypatch.setenv("PV_API_KEY", FAKE_KEY)
+        route = respx.post(f"{API_URL}/api/backend/keys").mock(
+            return_value=httpx.Response(200, json={"keys": MOCK_KEYS})
+        )
+        init()
+        init()
+        assert route.call_count == 1
+
+
+# ---------------------------------------------------------------------------
+# Module is callable (import pv; pv("KEY"))
+# ---------------------------------------------------------------------------
+
+class TestCallableModule:
+    @respx.mock
+    def test_module_callable(self, monkeypatch):
+        """Verify `import pv; pv.init(); pv('KEY')` works."""
+        monkeypatch.setenv("PV_API_KEY", FAKE_KEY)
+        respx.post(f"{API_URL}/api/backend/keys").mock(
+            return_value=httpx.Response(200, json={"keys": MOCK_KEYS})
+        )
+        pv.init()
+        # pv is the module, calling it should work
+        assert pv("OPENAI_API_KEY") == "sk-test123"
+        assert pv("DB_PASS") == "secret456"