redenv 0.2.0__tar.gz

redenv-0.2.0/.gitignore

@@ -0,0 +1,9 @@
+# Python
+example*.py
+
+# Build
+build
+dist
+.eggs
+__pycache__
+.pytest_cache

redenv-0.2.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.2.0] - 2026-01-22
+
+### Added
+
+- **Synchronous Client:** Added `RedenvSync` for blocking contexts (scripts, legacy apps).
+- **Write Support:** Implemented `client.set(key, value)` with full version history management.
+- **Smart Secrets Object:**
+  - `secrets.get(key, cast=int)`: Auto-convert types.
+  - `secrets.scope("PREFIX_")`: Create namespaced configuration subsets.
+  - `secrets.require("KEY")`: Fail-fast validation for missing keys.
+- **Time Travel:** Added `client.get_version(key, v)` to fetch historical secrets. Supports both absolute IDs and relative indexing (0=Latest, 1=Previous).
+- **Security Hardening:** `Secrets` object now masks values (`********`) in logs/print statements to prevent accidental leakage.
+- **Override Protection:** Added `env.override` option to prevent overwriting existing environment variables.
+
+## [0.1.0] - 2026-01-22
+
+### Added
+
+- **Initial Release:** First public beta release of the `redenv` Python SDK.
+- **Zero-Knowledge Security:** All cryptographic operations (AES-256-GCM, PBKDF2) are performed locally.
+- **Async Support:** Built on `asyncio` and `upstash-redis` for high-performance non-blocking operations.
+- **SWR Caching:** Implemented a robust `Stale-While-Revalidate` caching strategy using `cachetools.LRUCache`.
+- **Environment Injection:** Automatically populates `os.environ` with decrypted secrets on `load()`.

redenv-0.2.0/LICENSE

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

redenv-0.2.0/Makefile

@@ -0,0 +1,24 @@
+.PHONY: install test lint build clean example example-sync
+
+# Install the package in editable mode with dev dependencies
+install:
+	pip install -e ".[dev]"
+
+# Run tests
+test:
+	PYTHONPATH=src python -m pytest
+
+# Run linting and type checking
+lint:
+	python -m ruff check src tests
+	python -m pyright src
+
+# Build the package artifacts
+build:
+	rm -rf dist/ build/
+	python -m build
+
+# Clean up build artifacts and caches
+clean:
+	rm -rf dist/ build/ *.egg-info .pytest_cache .ruff_cache
+	find . -type d -name "__pycache__" -exec rm -rf {} +

redenv-0.2.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: redenv
+Version: 0.2.0
+Summary: A zero-knowledge, end-to-end encrypted secret management SDK for Python.
+Project-URL: Homepage, https://github.com/redenv-labs/redenv
+Project-URL: Documentation, https://github.com/redenv-labs/redenv/tree/main/packages/python-client
+Project-URL: Repository, https://github.com/redenv-labs/redenv
+Project-URL: Issues, https://github.com/redenv-labs/redenv/issues
+Author-email: PRAS <prassamin@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 PRAS
+        
+        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.
+License-File: LICENSE
+Keywords: dotenv,encryption,redis,sdk,secrets,security,upstash
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Requires-Dist: cachetools>=5.0.0
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: upstash-redis>=1.0.0
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pyright; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: python-dotenv; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Redenv Python SDK
+
+The official, zero-knowledge Python client for [Redenv](https://github.com/redenv-labs/redenv). Securely fetch, cache, and manage your environment variables at runtime.
+
+![PyPI - Version](https://img.shields.io/pypi/v/redenv)
+![PyPI - License](https://img.shields.io/pypi/l/redenv)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/redenv)
+
+## Features
+
+- **🔒 Zero-Knowledge:** End-to-End Encryption. Secrets are decrypted locally using your Project Encryption Key (PEK).
+- **⚡ High Performance:** In-memory `LRUCache` with `Stale-While-Revalidate` strategy for zero-latency reads.
+- **🔄 Universal:** Native **Async** (`asyncio`) and **Synchronous** clients included.
+- **🛠️ Developer Experience:**
+  - **Smart Casting:** `secrets.get("PORT", cast=int)`
+  - **Scoping:** `secrets.scope("STRIPE_")` for namespaced configs.
+  - **Validation:** `secrets.require("API_KEY")` fail-fast checks.
+  - **Time Travel:** Fetch historical versions of secrets.
+- **🛡️ Secure by Default:** Secrets are masked (`********`) in logs to prevent accidental leaks.
+
+## Installation
+
+```bash
+pip install redenv
+```
+
+## Quick Start
+
+### Async Client (FastAPI / Modern Apps)
+
+```python
+import asyncio
+import os
+from redenv import Redenv
+
+async def main():
+    client = Redenv({
+        "project": os.getenv("REDENV_PROJECT"),
+        "token_id": os.getenv("REDENV_TOKEN_ID"),
+        "token": os.getenv("REDENV_TOKEN_KEY"),
+        "upstash": {
+            "url": os.getenv("UPSTASH_REDIS_URL"),
+            "token": os.getenv("UPSTASH_REDIS_TOKEN")
+        }
+    })
+
+    # 1. Load Secrets (Populates os.environ by default)
+    secrets = await client.load()
+    
+    # 2. Access Secrets
+    print(f"Database URL: {secrets['DATABASE_URL']}")
+    
+    # 3. Smart Casting
+    port = secrets.get("PORT", cast=int)
+    debug = secrets.get("DEBUG", cast=bool)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Synchronous Client (Flask / Scripts / Legacy)
+
+Perfect for scripts or frameworks where `async/await` is not available at the top level.
+
+```python
+from redenv import RedenvSync
+
+client = RedenvSync({ ... }) # Same config as above
+
+# Blocks until secrets are fetched
+secrets = client.load()
+
+print(secrets["API_KEY"])
+```
+
+## Advanced Usage
+
+### 1. Scoping & Validation
+Organize large configurations and ensure critical keys exist.
+
+```python
+secrets = await client.load()
+
+# Fail if these keys are missing
+secrets.require("STRIPE_KEY", "STRIPE_WEBHOOK")
+
+# Create a subset of keys (e.g., keys starting with "STRIPE_")
+# The prefix is automatically stripped.
+stripe_config = secrets.scope("STRIPE_")
+
+print(stripe_config["KEY"])     # Maps to STRIPE_KEY
+print(stripe_config["WEBHOOK"]) # Maps to STRIPE_WEBHOOK
+```
+
+### 2. Time Travel (Version History)
+Redenv stores a history of every secret change. You can access older versions for rollbacks or auditing.
+
+```python
+# Get the absolute version 5
+v5 = await client.get_version("API_KEY", 5)
+
+# Get the previous version (1 version older than latest)
+# Mode="index": 0=Latest, 1=Previous, -1=Oldest
+prev = await client.get_version("API_KEY", 1, mode="index")
+
+# Get the oldest version ever created
+first = await client.get_version("API_KEY", -1)
+```
+
+### 3. Writing Secrets
+You can update secrets programmatically. This automatically encrypts the value, increments the version, and updates the history.
+
+```python
+await client.set("FEATURE_FLAG", "true")
+```
+
+### 4. Configuration Options
+
+| Option | Type | Description | Default |
+|:---|:---|:---|:---|
+| `project` | str | Your Project ID | Required |
+| `token_id` | str | Service Token Public ID | Required |
+| `token` | str | Service Token Secret Key | Required |
+| `upstash` | dict | `{ url: ..., token: ... }` | Required |
+| `environment` | str | Target environment (dev, prod) | `development` |
+| `log` | str | Log level (`none`, `low`, `high`) | `low` |
+| `cache` | dict | `{ ttl: 300, swr: 86400 }` (seconds) | 5min / 24h |
+| `env.override` | bool | Overwrite existing `os.environ` keys | `True` |
+
+```python
+client = Redenv({
+    # ...
+    "env": {
+        "override": False # Protects local env vars from being overwritten
+    }
+})
+```
+
+## Security
+
+- **Masking:** If you accidentally print the `secrets` object, values are hidden: `Secrets({'API_KEY': '********'})`.
+- **Zero-Knowledge:** The server (Upstash) never sees the plaintext. Decryption happens only in your application's memory.
+
+## License
+
+MIT

redenv-0.2.0/README.md

@@ -0,0 +1,146 @@
+# Redenv Python SDK
+
+The official, zero-knowledge Python client for [Redenv](https://github.com/redenv-labs/redenv). Securely fetch, cache, and manage your environment variables at runtime.
+
+![PyPI - Version](https://img.shields.io/pypi/v/redenv)
+![PyPI - License](https://img.shields.io/pypi/l/redenv)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/redenv)
+
+## Features
+
+- **🔒 Zero-Knowledge:** End-to-End Encryption. Secrets are decrypted locally using your Project Encryption Key (PEK).
+- **⚡ High Performance:** In-memory `LRUCache` with `Stale-While-Revalidate` strategy for zero-latency reads.
+- **🔄 Universal:** Native **Async** (`asyncio`) and **Synchronous** clients included.
+- **🛠️ Developer Experience:**
+  - **Smart Casting:** `secrets.get("PORT", cast=int)`
+  - **Scoping:** `secrets.scope("STRIPE_")` for namespaced configs.
+  - **Validation:** `secrets.require("API_KEY")` fail-fast checks.
+  - **Time Travel:** Fetch historical versions of secrets.
+- **🛡️ Secure by Default:** Secrets are masked (`********`) in logs to prevent accidental leaks.
+
+## Installation
+
+```bash
+pip install redenv
+```
+
+## Quick Start
+
+### Async Client (FastAPI / Modern Apps)
+
+```python
+import asyncio
+import os
+from redenv import Redenv
+
+async def main():
+    client = Redenv({
+        "project": os.getenv("REDENV_PROJECT"),
+        "token_id": os.getenv("REDENV_TOKEN_ID"),
+        "token": os.getenv("REDENV_TOKEN_KEY"),
+        "upstash": {
+            "url": os.getenv("UPSTASH_REDIS_URL"),
+            "token": os.getenv("UPSTASH_REDIS_TOKEN")
+        }
+    })
+
+    # 1. Load Secrets (Populates os.environ by default)
+    secrets = await client.load()
+    
+    # 2. Access Secrets
+    print(f"Database URL: {secrets['DATABASE_URL']}")
+    
+    # 3. Smart Casting
+    port = secrets.get("PORT", cast=int)
+    debug = secrets.get("DEBUG", cast=bool)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Synchronous Client (Flask / Scripts / Legacy)
+
+Perfect for scripts or frameworks where `async/await` is not available at the top level.
+
+```python
+from redenv import RedenvSync
+
+client = RedenvSync({ ... }) # Same config as above
+
+# Blocks until secrets are fetched
+secrets = client.load()
+
+print(secrets["API_KEY"])
+```
+
+## Advanced Usage
+
+### 1. Scoping & Validation
+Organize large configurations and ensure critical keys exist.
+
+```python
+secrets = await client.load()
+
+# Fail if these keys are missing
+secrets.require("STRIPE_KEY", "STRIPE_WEBHOOK")
+
+# Create a subset of keys (e.g., keys starting with "STRIPE_")
+# The prefix is automatically stripped.
+stripe_config = secrets.scope("STRIPE_")
+
+print(stripe_config["KEY"])     # Maps to STRIPE_KEY
+print(stripe_config["WEBHOOK"]) # Maps to STRIPE_WEBHOOK
+```
+
+### 2. Time Travel (Version History)
+Redenv stores a history of every secret change. You can access older versions for rollbacks or auditing.
+
+```python
+# Get the absolute version 5
+v5 = await client.get_version("API_KEY", 5)
+
+# Get the previous version (1 version older than latest)
+# Mode="index": 0=Latest, 1=Previous, -1=Oldest
+prev = await client.get_version("API_KEY", 1, mode="index")
+
+# Get the oldest version ever created
+first = await client.get_version("API_KEY", -1)
+```
+
+### 3. Writing Secrets
+You can update secrets programmatically. This automatically encrypts the value, increments the version, and updates the history.
+
+```python
+await client.set("FEATURE_FLAG", "true")
+```
+
+### 4. Configuration Options
+
+| Option | Type | Description | Default |
+|:---|:---|:---|:---|
+| `project` | str | Your Project ID | Required |
+| `token_id` | str | Service Token Public ID | Required |
+| `token` | str | Service Token Secret Key | Required |
+| `upstash` | dict | `{ url: ..., token: ... }` | Required |
+| `environment` | str | Target environment (dev, prod) | `development` |
+| `log` | str | Log level (`none`, `low`, `high`) | `low` |
+| `cache` | dict | `{ ttl: 300, swr: 86400 }` (seconds) | 5min / 24h |
+| `env.override` | bool | Overwrite existing `os.environ` keys | `True` |
+
+```python
+client = Redenv({
+    # ...
+    "env": {
+        "override": False # Protects local env vars from being overwritten
+    }
+})
+```
+
+## Security
+
+- **Masking:** If you accidentally print the `secrets` object, values are hidden: `Secrets({'API_KEY': '********'})`.
+- **Zero-Knowledge:** The server (Upstash) never sees the plaintext. Decryption happens only in your application's memory.
+
+## License
+
+MIT

redenv-0.2.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "redenv"
+version = "0.2.0"
+description = "A zero-knowledge, end-to-end encrypted secret management SDK for Python."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { file = "LICENSE" }
+authors = [
+  { name = "PRAS", email = "prassamin@gmail.com" },
+]
+keywords = ["secrets", "security", "dotenv", "upstash", "redis", "encryption", "sdk"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Security",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Operating System :: OS Independent",
+]
+dependencies = [
+    "upstash-redis>=1.0.0",
+    "cryptography>=41.0.0",
+    "cachetools>=5.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/redenv-labs/redenv"
+Documentation = "https://github.com/redenv-labs/redenv/tree/main/packages/python-client"
+Repository = "https://github.com/redenv-labs/redenv"
+Issues = "https://github.com/redenv-labs/redenv/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "python-dotenv",
+    "build",
+    "twine",
+    "ruff",
+    "pyright"
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/redenv"]

redenv-0.2.0/src/redenv/__init__.py

@@ -0,0 +1,7 @@
+from .client import Redenv
+from .errors import RedenvError
+from .secrets import Secrets
+from .sync import Redenv as RedenvSync
+
+__version__ = "0.2.0"
+__all__ = ["Redenv", "RedenvSync", "RedenvError", "Secrets"]

redenv-0.2.0/src/redenv/client.py

@@ -0,0 +1,137 @@
+import asyncio
+import time
+from typing import Dict, Any, Optional, Literal
+from upstash_redis.asyncio import Redis
+from cachetools import LRUCache
+from .types import RedenvOptions, CacheEntry
+from .secrets import Secrets
+from .utils import fetch_and_decrypt, populate_env, log, error, set_secret, get_secret_version
+from .errors import RedenvError
+
+class Redenv:
+    def __init__(self, options: Dict[str, Any]):
+        self.options = RedenvOptions.from_dict(options)
+        self.validate_options()
+        
+        self._cache = LRUCache(maxsize=1000)
+        
+        self.redis = Redis(
+            url=self.options.upstash.url,
+            token=self.options.upstash.token
+        )
+
+    def validate_options(self):
+        if not self.options.project:
+            raise RedenvError("Missing required configuration option: project", "MISSING_CONFIG")
+        if not self.options.token_id:
+            raise RedenvError("Missing required configuration option: token_id", "MISSING_CONFIG")
+        if not self.options.token:
+            raise RedenvError("Missing required configuration option: token", "MISSING_CONFIG")
+        if not self.options.upstash.url or not self.options.upstash.token:
+            raise RedenvError("Missing required configuration option: upstash", "MISSING_CONFIG")
+
+    def _get_cache_key(self) -> str:
+        return f"redenv:{self.options.project}:{self.options.environment}"
+
+    async def _get_secrets(self) -> Secrets:
+        key = self._get_cache_key()
+        entry = self._cache.get(key)
+        now = time.time()
+        
+        ttl_seconds = self.options.cache.ttl
+        swr_seconds = self.options.cache.swr
+        
+        # Function to fetch fresh value
+        async def fetch_fresh() -> Secrets:
+            try:
+                log("Fetching fresh secrets...", self.options.log)
+                secrets = await fetch_and_decrypt(self.redis, self.options)
+                
+                # Update cache with new entry
+                self._cache[key] = CacheEntry(secrets, time.time())
+                
+                # Side effect: populate environment
+                await populate_env(secrets, self.options)
+                
+                return secrets
+            except Exception as e:
+                error(f"Failed to fetch secrets: {e}", self.options.log)
+                raise e
+
+        if entry:
+            age = now - entry.created_at
+            
+            if age < ttl_seconds:
+                # Case 1: Fresh
+                log("Cache hit (Fresh).", self.options.log)
+                return entry.value
+            
+            elif age < (ttl_seconds + swr_seconds):
+                # Case 2: Stale (SWR)
+                log("Cache hit (Stale). Revalidating in background...", self.options.log)
+                # Return stale value immediately
+                # Spawn background refresh
+                asyncio.create_task(fetch_fresh())
+                return entry.value
+            else:
+                # Case 3: Expired
+                log("Cache expired. Fetching fresh...", self.options.log)
+                return await fetch_fresh()
+        else:
+            # Case 4: Miss
+            log("Cache miss. Fetching fresh...", self.options.log)
+            return await fetch_fresh()
+
+    async def init(self):
+        """
+        Initializes the environment with secrets.
+        Alias for load().
+        """
+        await self.load()
+
+    async def load(self) -> Secrets:
+        """
+        Fetches, caches, and injects secrets into the environment.
+        
+        Returns:
+            The Secrets object.
+        """
+        secrets = await self._get_secrets()
+        
+        # Ensure env is populated
+        await populate_env(secrets, self.options)
+        
+        return secrets
+
+    async def set(self, key: str, value: str):
+        """
+        Adds or updates a secret.
+        """
+        if not key or not value:
+            raise RedenvError("Key and value are required.", "INVALID_INPUT")
+            
+        try:
+            await set_secret(self.redis, self.options, key, value)
+            log(f'Successfully set secret for key "{key}".', self.options.log)
+            
+            # Invalidate cache
+            cache_key = self._get_cache_key()
+            if cache_key in self._cache:
+                del self._cache[cache_key]
+                
+        except Exception as e:
+            msg = str(e)
+            error(f"Failed to set secret: {msg}", self.options.log)
+            raise RedenvError(f"Failed to set secret: {msg}", "UNKNOWN_ERROR")
+
+    async def get_version(self, key: str, version: int, mode: Literal["id", "index"] = "id") -> Optional[str]:
+        """
+        Fetches a specific version of a secret with caching.
+        
+        Args:
+            key: The secret key.
+            version: The version ID or index.
+            mode: "id" (default) uses positive version numbers, negative for index from end.
+                  "index" treats version as a 0-based array index (0=latest).
+        """
+        return await get_secret_version(self.redis, self.options, self._cache, key, version, mode)