redenv 0.2.0__py3-none-any.whl

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/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)

redenv/crypto.py

@@ -0,0 +1,71 @@
+import os
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
+from .errors import RedenvError
+
+# --- Configuration ---
+IV_LENGTH = 12
+KEY_LENGTH = 32 # 256 bits = 32 bytes
+PBKDF2_ITERATIONS = 310000
+SALT_LENGTH = 16
+
+def buffer_to_hex(buffer: bytes) -> str:
+    return buffer.hex()
+
+def hex_to_buffer(hex_str: str) -> bytes:
+    return bytes.fromhex(hex_str)
+
+def random_bytes(length: int = 32) -> bytes:
+    return os.urandom(length)
+
+def generate_salt() -> bytes:
+    return random_bytes(SALT_LENGTH)
+
+def derive_key(password: str, salt: bytes) -> bytes:
+    """
+    Derives an encryption key from a password and salt using PBKDF2.
+    """
+    kdf = PBKDF2HMAC(
+        algorithm=hashes.SHA256(),
+        length=KEY_LENGTH,
+        salt=salt,
+        iterations=PBKDF2_ITERATIONS,
+    )
+    return kdf.derive(password.encode('utf-8'))
+
+def encrypt(data: str, key: bytes) -> str:
+    """
+    Encrypts data using AES-256-GCM.
+    Returns a string containing the iv and the ciphertext, separated by a dot.
+    """
+    iv = os.urandom(IV_LENGTH)
+    aesgcm = AESGCM(key)
+    ciphertext = aesgcm.encrypt(iv, data.encode('utf-8'), None)
+    
+    return f"{buffer_to_hex(iv)}.{buffer_to_hex(ciphertext)}"
+
+def decrypt(encrypted_string: str, key: bytes) -> str:
+    """
+    Decrypts data that was encrypted with the `encrypt` function.
+    """
+    if not encrypted_string:
+        raise RedenvError("Encrypted string cannot be empty.", "UNKNOWN_ERROR")
+
+    parts = encrypted_string.split(".")
+    if len(parts) != 2 or not parts[0] or not parts[1]:
+        raise RedenvError("Invalid encrypted string format.", "UNKNOWN_ERROR")
+
+    try:
+        iv = hex_to_buffer(parts[0])
+        ciphertext = hex_to_buffer(parts[1])
+        
+        aesgcm = AESGCM(key)
+        decrypted_data = aesgcm.decrypt(iv, ciphertext, None)
+        
+        return decrypted_data.decode('utf-8')
+    except Exception:
+        raise RedenvError(
+            "Decryption failed. This likely means an incorrect password was used or the data is corrupted.",
+            "DECRYPTION_FAILED"
+        )

redenv/errors.py

@@ -0,0 +1,6 @@
+class RedenvError(Exception):
+    """Base exception for Redenv."""
+    def __init__(self, message: str, code: str = "UNKNOWN_ERROR"):
+        self.message = message
+        self.code = code
+        super().__init__(f"[{code}] {message}")

redenv/secrets.py

@@ -0,0 +1,95 @@
+import json
+from typing import Any, Callable, Optional, Type, TypeVar, Union
+from .errors import RedenvError
+
+T = TypeVar("T")
+
+class Secrets(dict):
+    """
+    A specialized dictionary for managing decrypted secrets with 
+    type-casting, scoping, and validation capabilities.
+    """
+
+    def get(self, key: str, default: Any = None, cast: Optional[Union[Type[T], Callable[[Any], T]]] = None) -> Union[T, Any]:
+        """
+        Retrieves a secret and optionally casts it to a specific type.
+        """
+        value = super().get(key)
+        
+        if value is None:
+            return default
+            
+        if cast is None:
+            return value
+            
+        try:
+            # Special handling for boolean strings
+            if cast is bool:
+                if isinstance(value, bool):
+                    return value
+                if isinstance(value, str):
+                    return value.lower() in ("true", "1", "yes", "on", "t")
+                return bool(value)
+                
+            # Special handling for JSON types (dict/list)
+            if (cast is dict or cast is list) and isinstance(value, str):
+                try:
+                    return json.loads(value)
+                except json.JSONDecodeError:
+                    return default
+            
+            # General casting (int, float, or custom callable)
+            return cast(value) # type: ignore
+            
+        except (ValueError, TypeError):
+            return default
+
+    def __getitem__(self, key: str) -> Any:
+        """
+        Ensures standard dict access still works but raises a 
+        helpful error if the key is missing.
+        """
+        try:
+            return super().__getitem__(key)
+        except KeyError:
+            raise KeyError(f"Secret '{key}' not found in Redenv.")
+
+    def scope(self, prefix: str) -> "Secrets":
+        """
+        Returns a new Secrets object containing only the keys that start with
+        the given prefix. The prefix is stripped from the keys in the new object.
+        """
+        subset = Secrets()
+        for key, value in self.items():
+            if key.startswith(prefix):
+                new_key = key[len(prefix):]
+                if new_key:
+                    subset[new_key] = value
+        return subset
+
+    def require(self, *keys: str) -> "Secrets":
+        """
+        Validates that all provided keys exist.
+        Raises RedenvError if any key is missing.
+        Returns self for chaining.
+        """
+        missing = [k for k in keys if k not in self]
+        if missing:
+            raise RedenvError(
+                f"Missing required secrets: {', '.join(missing)}",
+                "SECRET_NOT_FOUND"
+            )
+        return self
+
+    def __repr__(self) -> str:
+        """
+        Masks secret values to prevent accidental leakage in logs.
+        """
+        masked = {k: "********" for k in self.keys()}
+        return f"Secrets({masked})"
+
+    def __str__(self) -> str:
+        """
+        Returns the masked representation of the secrets.
+        """
+        return self.__repr__()

redenv/sync/__init__.py

@@ -0,0 +1,3 @@
+from .client import Redenv
+
+__all__ = ["Redenv"]

redenv/sync/client.py

@@ -0,0 +1,131 @@
+import time
+from typing import Dict, Any, Optional, Literal
+from upstash_redis import Redis
+from cachetools import LRUCache
+from ..types import RedenvOptions
+from ..secrets import Secrets
+from .utils import fetch_and_decrypt, populate_env, log, error, set_secret, get_secret_version
+from ..errors import RedenvError
+
+class CacheEntry:
+    def __init__(self, value: Any, created_at: float):
+        self.value = value
+        self.created_at = created_at
+
+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}"
+
+    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
+        
+        def fetch_fresh() -> Secrets:
+            try:
+                log("Fetching fresh secrets...", self.options.log)
+                secrets = fetch_and_decrypt(self.redis, self.options)
+                self._cache[key] = CacheEntry(secrets, time.time())
+                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:
+                log("Cache hit (Fresh).", self.options.log)
+                return entry.value
+            
+            elif age < (ttl_seconds + swr_seconds):
+                # In Sync mode, we can't easily background refresh without threads.
+                # Option 1: Block and refresh (Safe)
+                # Option 2: Return stale (Fast, but never updates)
+                # We choose Option 1 for correctness in Sync scripts.
+                log("Cache stale. Refreshing (Blocking)...", self.options.log)
+                return fetch_fresh()
+            else:
+                log("Cache expired. Fetching fresh...", self.options.log)
+                return fetch_fresh()
+        else:
+            log("Cache miss. Fetching fresh...", self.options.log)
+            return fetch_fresh()
+
+    def init(self):
+        """
+        Initializes the environment with secrets.
+        Alias for load().
+        """
+        self.load()
+
+    def load(self) -> Secrets:
+        """
+        Fetches, caches, and injects secrets into the environment.
+        
+        Args:
+            override: If True (default), overwrites existing environment variables.
+        """
+        secrets = self._get_secrets()
+        
+        # Ensure env is populated
+        populate_env(secrets, self.options)
+        
+        return secrets
+
+    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:
+            set_secret(self.redis, self.options, key, value)
+            log(f'Successfully set secret for key "{key}".', self.options.log)
+            
+            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")
+
+    def get_version(self, key: str, version: int, mode: Literal["id", "index"] = "id") -> Optional[str]:
+        """
+        Fetches a specific version of a secret.
+        
+        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 get_secret_version(self.redis, self.options, self._cache, key, version, mode)

redenv/sync/utils.py

@@ -0,0 +1,199 @@
+import json
+import os
+import time
+from typing import Dict, Optional, Any, Union, Literal
+from upstash_redis import Redis as SyncRedis
+from ..crypto import derive_key, decrypt, hex_to_buffer, encrypt
+from ..types import RedenvOptions, CacheEntry
+from ..errors import RedenvError
+from ..secrets import Secrets
+from ..utils import log, error
+from cachetools import LRUCache
+
+def get_pek(redis: SyncRedis, options: RedenvOptions, metadata: Optional[Dict[str, Any]] = None) -> bytes:
+    """
+    Fetches and decrypts the Project Encryption Key (PEK).
+    """
+    if not metadata:
+        meta_key = f"meta@{options.project}"
+        metadata = redis.hgetall(meta_key)
+    
+    if not metadata:
+        raise RedenvError(f'Project "{options.project}" not found.', "PROJECT_NOT_FOUND")
+
+    service_tokens = metadata.get("serviceTokens")
+    if isinstance(service_tokens, str):
+        service_tokens = json.loads(service_tokens)
+    
+    token_info = service_tokens.get(options.token_id) if service_tokens else None
+
+    if not token_info:
+        ephemeral_field = f"ephemeral:{options.token_id}"
+        raw_ephemeral = metadata.get(ephemeral_field)
+        if raw_ephemeral:
+            token_info = json.loads(raw_ephemeral) if isinstance(raw_ephemeral, str) else raw_ephemeral
+
+    if not token_info:
+        raise RedenvError("Invalid Redenv Token ID.", "INVALID_TOKEN_ID")
+
+    salt = hex_to_buffer(token_info["salt"])
+    token_key = derive_key(options.token, salt)
+    
+    decrypted_pek_hex = decrypt(token_info["encryptedPEK"], token_key)
+    
+    return hex_to_buffer(decrypted_pek_hex)
+
+def fetch_and_decrypt(redis: SyncRedis, options: RedenvOptions) -> Secrets:
+    """
+    Fetches all secrets for a given environment and decrypts them.
+    """
+    log("Expired Cache: Fetching secrets from source...", options.log, "high")
+    
+    try:
+        pek = get_pek(redis, options)
+    except Exception as e:
+        error(f"Failed to get PEK: {e}", options.log)
+        raise e
+
+    env_key = f"{options.environment}:{options.project}"
+    versioned_secrets = redis.hgetall(env_key)
+
+    secrets = Secrets()
+    if not versioned_secrets:
+        log("No secrets found for this environment.", options.log)
+        return secrets
+    
+    for key, history_str in versioned_secrets.items():
+        if key.startswith("__"):
+            continue
+
+        try:
+            history = json.loads(history_str) if isinstance(history_str, str) else history_str
+            if not isinstance(history, list) or len(history) == 0:
+                continue
+            
+            encrypted_value = history[0]["value"]
+            decrypted_value = decrypt(encrypted_value, pek)
+            secrets[key] = decrypted_value
+        except Exception:
+            error(f'Failed to decrypt secret "{key}".', options.log)
+            continue
+
+    log(f"Successfully loaded {len(secrets)} secrets.", options.log)
+    return secrets
+
+def populate_env(secrets: Union[Dict[str, str], Secrets], options: RedenvOptions):
+    """
+    Injects secrets into the current runtime's environment.
+    """
+    log("Populating environment with secrets...", options.log)
+    injected_count = 0
+    
+    for key, value in secrets.items():
+        if not options.env.override and key in os.environ:
+            continue
+            
+        os.environ[key] = value
+        injected_count += 1
+        
+    log(f"Injection complete. {injected_count} variables were set.", options.log)
+
+def set_secret(redis: SyncRedis, options: RedenvOptions, key: str, value: str):
+    """
+    Sets a secret in Redis with versioning and history.
+    """
+    env_key = f"{options.environment}:{options.project}"
+    meta_key = f"meta@{options.project}"
+    
+    # Sequential fetch (Simpler for sync, parallel requires threads)
+    metadata = redis.hgetall(meta_key)
+    current_history_str = redis.hget(env_key, key)
+    
+    if not metadata:
+        raise RedenvError(f'Project "{options.project}" not found.', "PROJECT_NOT_FOUND")
+        
+    pek = get_pek(redis, options, metadata)
+    
+    history_limit = int(metadata.get("historyLimit", 10))
+    
+    history = []
+    if current_history_str:
+        history = json.loads(current_history_str) if isinstance(current_history_str, str) else current_history_str
+        
+    if not isinstance(history, list):
+        history = []
+        
+    last_version = history[0]["version"] if len(history) > 0 else 0
+    
+    encrypted_value = encrypt(value, pek)
+    
+    from datetime import datetime, timezone
+    
+    new_version = {
+        "version": last_version + 1,
+        "value": encrypted_value,
+        "user": options.token_id,
+        "createdAt": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+    }
+    
+    history.insert(0, new_version)
+    
+    if history_limit > 0:
+        history = history[:history_limit]
+        
+    return redis.hset(env_key, key, json.dumps(history))
+
+def get_secret_version(redis: SyncRedis, options: RedenvOptions, cache: LRUCache, key: str, version: int, mode: Literal["id", "index"] = "id") -> Optional[str]:
+    """
+    Fetches a specific version of a secret with optimized caching and smart indexing.
+    """
+    hist_cache_key = f"history:{options.project}:{options.environment}:{key}"
+    entry = cache.get(hist_cache_key)
+    
+    history_list = []
+    
+    if entry:
+        log(f"History cache hit for {key}.", options.log)
+        history_list = entry.value
+    else:
+        log(f"History cache miss for {key}. Fetching full history...", options.log)
+        env_key = f"{options.environment}:{options.project}"
+        history_str = redis.hget(env_key, key)
+        
+        if history_str:
+            try:
+                raw_list = json.loads(history_str) if isinstance(history_str, str) else history_str
+                if isinstance(raw_list, list):
+                    history_list = raw_list
+                    cache[hist_cache_key] = CacheEntry(history_list, time.time())
+            except Exception as e:
+                error(f"Failed to parse history: {e}", options.log)
+
+    if not history_list:
+        return None
+
+    target_record = None
+
+    if mode == "index":
+        try:
+            target_record = history_list[version]
+        except IndexError:
+            return None
+    else:
+        if version < 0:
+            try:
+                target_record = history_list[version]
+            except IndexError:
+                return None
+        else:
+            target_record = next((item for item in history_list if item.get("version") == version), None)
+
+    if not target_record:
+        return None
+
+    try:
+        pek = get_pek(redis, options)
+        return decrypt(target_record["value"], pek)
+    except Exception as e:
+        error(f"Failed to decrypt version {version} ({mode}): {e}", options.log)
+        return None

redenv/types.py

@@ -0,0 +1,64 @@
+from dataclasses import dataclass, field
+from typing import Literal, Dict, Any
+
+LogPreference = Literal["none", "low", "high"]
+
+@dataclass
+class UpstashConfig:
+    url: str
+    token: str
+
+@dataclass
+class CacheConfig:
+    ttl: int = 300
+    swr: int = 86400
+
+@dataclass
+class EnvConfig:
+    override: bool = True
+
+class CacheEntry:
+    def __init__(self, value: Any, created_at: float):
+        self.value = value
+        self.created_at = created_at
+
+@dataclass
+class RedenvOptions:
+    project: str
+    token_id: str
+    token: str
+    upstash: UpstashConfig
+    environment: str = "development"
+    cache: CacheConfig = field(default_factory=CacheConfig)
+    env: EnvConfig = field(default_factory=EnvConfig)
+    log: LogPreference = "low"
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'RedenvOptions':
+        upstash_data = data.get("upstash", {})
+        upstash = UpstashConfig(
+            url=upstash_data.get("url", ""),
+            token=upstash_data.get("token", "")
+        )
+        
+        cache_data = data.get("cache", {})
+        cache = CacheConfig(
+            ttl=cache_data.get("ttl", 300),
+            swr=cache_data.get("swr", 86400)
+        )
+
+        env_data = data.get("env", {})
+        env = EnvConfig(
+            override=env_data.get("override", True)
+        )
+
+        return cls(
+            project=data.get("project", ""),
+            token_id=data.get("token_id", data.get("tokenId", "")),
+            token=data.get("token", ""),
+            upstash=upstash,
+            environment=data.get("environment", "development"),
+            cache=cache,
+            env=env,
+            log=data.get("log", "low")
+        )

redenv/utils.py

@@ -0,0 +1,251 @@
+from .crypto import derive_key, decrypt, hex_to_buffer, encrypt
+from .types import RedenvOptions, LogPreference, CacheEntry
+from .errors import RedenvError
+from upstash_redis import AsyncRedis
+from .secrets import Secrets
+import asyncio
+import json
+import os
+import time
+from typing import Literal, Optional, Dict, Any, Union
+from cachetools import LRUCache
+
+import logging
+
+logger = logging.getLogger("redenv")
+
+if not logger.handlers:
+    logger.addHandler(logging.NullHandler())
+
+def log(message: str, preference: LogPreference = "low", priority: str = "low"):
+    """
+    Logs messages using the standard python logging module.
+    """
+    if preference == "none":
+        return
+
+    # If preference is "low", we only log high priority messages as INFO
+    # If preference is "high", we log everything (low priority as DEBUG, high as INFO)
+    
+    if priority == "high":
+        logger.info(message)
+    elif preference == "high":
+        logger.debug(message)
+
+def error(message: str, preference: LogPreference = "low"):
+    """
+    Logs errors using the standard python logging module.
+    """
+    if preference != "none":
+        logger.error(message)
+
+async def get_pek(redis: AsyncRedis, options: RedenvOptions, metadata: Optional[Dict[str, Any]] = None) -> bytes:
+    """
+    Fetches and decrypts the Project Encryption Key (PEK).
+    If metadata is provided, it skips the Redis fetch.
+    """
+    if not metadata:
+        meta_key = f"meta@{options.project}"
+        metadata = await redis.hgetall(meta_key)
+        
+    if not metadata:
+        raise RedenvError(f'Project "{options.project}" not found.', "PROJECT_NOT_FOUND")
+
+    service_tokens = metadata.get("serviceTokens")
+    if isinstance(service_tokens, str):
+        service_tokens = json.loads(service_tokens)
+    
+    token_info = service_tokens.get(options.token_id) if service_tokens else None
+
+    # If not found in standard service tokens, check for ephemeral token field
+    if not token_info:
+        ephemeral_field = f"ephemeral:{options.token_id}"
+        raw_ephemeral = metadata.get(ephemeral_field)
+        if raw_ephemeral:
+            token_info = json.loads(raw_ephemeral) if isinstance(raw_ephemeral, str) else raw_ephemeral
+
+    if not token_info:
+        raise RedenvError("Invalid Redenv Token ID.", "INVALID_TOKEN_ID")
+
+    salt = hex_to_buffer(token_info["salt"])
+    # Note: derive_key in python takes string password and bytes salt
+    token_key = derive_key(options.token, salt)
+    
+    decrypted_pek_hex = decrypt(token_info["encryptedPEK"], token_key)
+    
+    return hex_to_buffer(decrypted_pek_hex)
+
+async def fetch_and_decrypt(redis: AsyncRedis, options: RedenvOptions) -> Secrets:
+    """
+    Fetches all secrets for a given environment and decrypts them.
+    """
+    log("Expired Cache: Fetching secrets from source...", options.log, "high")
+    
+    try:
+        pek = await get_pek(redis, options)
+    except Exception as e:
+        error(f"Failed to get PEK: {e}", options.log)
+        raise e
+
+    env_key = f"{options.environment}:{options.project}"
+    versioned_secrets = await redis.hgetall(env_key)
+
+    secrets = Secrets()
+    if not versioned_secrets:
+        log("No secrets found for this environment.", options.log)
+        return secrets
+
+    # versioned_secrets is Dict[str, str] where values are JSON strings of arrays
+    
+    for key, history_str in versioned_secrets.items():
+        if key.startswith("__"):
+            continue
+
+        try:
+            history = json.loads(history_str) if isinstance(history_str, str) else history_str
+            if not isinstance(history, list) or len(history) == 0:
+                continue
+            
+            # history[0] is the latest
+            encrypted_value = history[0]["value"]
+            decrypted_value = decrypt(encrypted_value, pek)
+            secrets[key] = decrypted_value
+        except Exception:
+            error(f'Failed to decrypt secret "{key}".', options.log)
+            continue
+
+    log(f"Successfully loaded {len(secrets)} secrets.", options.log)
+    return secrets
+
+async def populate_env(secrets: Union[Dict[str, str], Secrets], options: RedenvOptions):
+    """
+    Injects secrets into the current runtime's environment.
+    """
+    log("Populating environment with secrets...", options.log)
+    injected_count = 0
+    
+    for key, value in secrets.items():
+        if not options.env.override and key in os.environ:
+            continue
+            
+        os.environ[key] = value
+        injected_count += 1
+        
+    log(f"Injection complete. {injected_count} variables were set.", options.log)
+
+async def set_secret(redis: AsyncRedis, options: RedenvOptions, key: str, value: str):
+    """
+    Sets a secret in Redis with versioning and history.
+    """
+    env_key = f"{options.environment}:{options.project}"
+    meta_key = f"meta@{options.project}"
+    
+    # Fetch metadata (for PEK & historyLimit) and current history in parallel
+    metadata, current_history = await asyncio.gather(
+        redis.hgetall(meta_key), 
+        redis.hget(env_key, key)
+    )
+    
+    if not metadata:
+        raise RedenvError(f'Project "{options.project}" not found.', "PROJECT_NOT_FOUND")
+        
+    # Reuse metadata to get PEK without extra fetch
+    pek = await get_pek(redis, options, metadata)
+    
+    history_limit = int(metadata.get("historyLimit", 10))
+    
+    # Fetch current history for the key
+    history = []
+    if current_history:
+        history = json.loads(current_history) if isinstance(current_history, str) else current_history
+        
+    if not isinstance(history, list):
+        history = []
+        
+    last_version = history[0]["version"] if len(history) > 0 else 0
+    
+    # Encrypt new value
+    encrypted_value = encrypt(value, pek)
+    
+    from datetime import datetime, timezone
+    
+    new_version = {
+        "version": last_version + 1,
+        "value": encrypted_value,
+        "user": options.token_id, # Using token_id as the user/auditor
+        "createdAt": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+    }
+    
+    # Prepend new version
+    history.insert(0, new_version)
+    
+    # Trim history
+    if history_limit > 0:
+        history = history[:history_limit]
+        
+    # Write back
+    return await redis.hset(env_key, key, json.dumps(history))
+
+async def get_secret_version(redis: AsyncRedis, options: RedenvOptions, cache: LRUCache, key: str, version: int, mode: Literal["id", "index"] = "id") -> Optional[str]:
+    """
+    Fetches a specific version of a secret with optimized caching and smart indexing.
+    
+    Args:
+        mode: "id" (default) - positive numbers for version ID, negative for index from end.
+              "index" - treats version as array index (0=latest, 1=prev, -1=oldest).
+    """
+    hist_cache_key = f"history:{options.project}:{options.environment}:{key}"
+    entry = cache.get(hist_cache_key)
+    
+    history_list = []
+    
+    if entry:
+        log(f"History cache hit for {key}.", options.log)
+        history_list = entry.value
+    else:
+        log(f"History cache miss for {key}. Fetching full history...", options.log)
+        env_key = f"{options.environment}:{options.project}"
+        history_str = await redis.hget(env_key, key)
+        
+        if history_str:
+            try:
+                raw_list = json.loads(history_str) if isinstance(history_str, str) else history_str
+                if isinstance(raw_list, list):
+                    history_list = raw_list
+                    cache[hist_cache_key] = CacheEntry(history_list, time.time())
+            except Exception as e:
+                error(f"Failed to parse history: {e}", options.log)
+
+    if not history_list:
+        return None
+
+    target_record = None
+
+    if mode == "index":
+        try:
+            # history_list is sorted newest-first
+            target_record = history_list[version]
+        except IndexError:
+            return None
+    else:
+        # Default "id" mode
+        if version < 0:
+            # Smart fallback: use as index for negative numbers
+            try:
+                target_record = history_list[version]
+            except IndexError:
+                return None
+        else:
+            # Standard search by ID
+            target_record = next((item for item in history_list if item.get("version") == version), None)
+
+    if not target_record:
+        return None
+
+    try:
+        pek = await get_pek(redis, options)
+        return decrypt(target_record["value"], pek)
+    except Exception as e:
+        error(f"Failed to decrypt version {version} ({mode}): {e}", options.log)
+        return None
+

redenv-0.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,15 @@
+redenv/__init__.py,sha256=FA93IXHIpI5yfm3NeytvuHnE0lcIwmymW7fer9jtV6U,211
+redenv/client.py,sha256=zKy7YHt8su4u7mxAtFRIyYEBU-4x4SYqV1V91oRyb1s,5126
+redenv/crypto.py,sha256=KtN7yv9qVPNdNQcWIQfiUakdLULulfs2oT39-oJq6wc,2196
+redenv/errors.py,sha256=AMCC_ESUnqBfFHhJ_sGrvOzuR9MV-jwvpjQ-6KWQnuA,238
+redenv/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+redenv/secrets.py,sha256=jVdjkJPMG4nqppzJ00eBTjyZ0V6FTWmvQ-aBQAnD6eM,3105
+redenv/types.py,sha256=DlTZPTMzwQlqMEQTi2RzYsI4Qu8PZJem8HpjwmcXYyQ,1680
+redenv/utils.py,sha256=ZJm6RIVjZqwe4_kogb8H3W3wY3y90QqSm18-ZuB5oPk,8632
+redenv/sync/__init__.py,sha256=tP9hJvl09rcEWs6ZJWz-Jo7WI2wHGTdsLeMbs8DONgY,49
+redenv/sync/client.py,sha256=d0H1m-k4XZYm9MKR1IIUBIpLd_C3rCb1o5gRshpEsxg,4950
+redenv/sync/utils.py,sha256=9D2ei-4_OSWwbfzA3I_DqeMdLGX2DkUjo-NhCs0b3bU,6819
+redenv-0.2.0.dist-info/METADATA,sha256=WlPSRF1Z8soaDALdr1ycozid47Mo2PdFeGglCpWOuqM,7247
+redenv-0.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+redenv-0.2.0.dist-info/licenses/LICENSE,sha256=HFevb6E77SZAFe4_NUry6n_xpbs8FMzN8M8Tpvb753M,1061
+redenv-0.2.0.dist-info/RECORD,,

redenv-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

redenv-0.2.0.dist-info/licenses/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.