mdb-engine 0.1.6__py3-none-any.whl → 0.2.0__py3-none-any.whl

mdb_engine/core/app_secrets.py

@@ -0,0 +1,290 @@
+"""
+App Secrets Manager
+
+Manages encrypted app secrets stored in MongoDB using envelope encryption.
+
+This module is part of MDB_ENGINE - MongoDB Engine.
+
+The AppSecretsManager stores encrypted app secrets in the `_mdb_engine_app_secrets`
+collection, which is only accessible via raw MongoDB client (not scoped wrapper).
+"""
+
+import base64
+import logging
+import secrets
+from datetime import datetime
+from typing import Optional
+
+from motor.motor_asyncio import AsyncIOMotorDatabase
+from pymongo.errors import OperationFailure, PyMongoError
+
+from .encryption import EnvelopeEncryptionService
+
+logger = logging.getLogger(__name__)
+
+# Collection name for storing encrypted app secrets
+SECRETS_COLLECTION_NAME = "_mdb_engine_app_secrets"
+
+
+class AppSecretsManager:
+    """
+    Manages encrypted app secrets using envelope encryption.
+
+    Secrets are stored encrypted in MongoDB and can only be verified,
+    not retrieved in plaintext (except during rotation).
+    """
+
+    def __init__(
+        self,
+        mongo_db: AsyncIOMotorDatabase,
+        encryption_service: EnvelopeEncryptionService,
+    ):
+        """
+        Initialize the app secrets manager.
+
+        Args:
+            mongo_db: MongoDB database instance (raw, not scoped)
+            encryption_service: Envelope encryption service instance
+        """
+        self._mongo_db = mongo_db
+        self._encryption_service = encryption_service
+        self._secrets_collection = mongo_db[SECRETS_COLLECTION_NAME]
+
+    async def store_app_secret(self, app_slug: str, secret: str) -> None:
+        """
+        Store an encrypted app secret.
+
+        Args:
+            app_slug: App slug identifier
+            secret: Plaintext secret to encrypt and store
+
+        Raises:
+            OperationFailure: If MongoDB operation fails
+
+        The secret is encrypted using envelope encryption and stored with
+        metadata (created_at, updated_at, rotation_count).
+        """
+        try:
+            # Encrypt secret
+            encrypted_secret, encrypted_dek = self._encryption_service.encrypt_secret(secret)
+
+            # Encode as base64 for storage
+            encrypted_secret_b64 = base64.b64encode(encrypted_secret).decode()
+            encrypted_dek_b64 = base64.b64encode(encrypted_dek).decode()
+
+            # Prepare document
+            now = datetime.utcnow()
+            document = {
+                "_id": app_slug,
+                "encrypted_secret": encrypted_secret_b64,
+                "encrypted_dek": encrypted_dek_b64,
+                "algorithm": "AES-256-GCM",
+                "updated_at": now,
+            }
+
+            # Check if secret already exists
+            existing = await self._secrets_collection.find_one({"_id": app_slug})
+            if existing:
+                # Update existing secret
+                document["created_at"] = existing.get("created_at", now)
+                document["rotation_count"] = existing.get("rotation_count", 0) + 1
+                await self._secrets_collection.replace_one({"_id": app_slug}, document)
+                logger.info(
+                    f"Updated encrypted secret for app '{app_slug}' "
+                    f"(rotation #{document['rotation_count']})"
+                )
+            else:
+                # Insert new secret
+                document["created_at"] = now
+                document["rotation_count"] = 0
+                await self._secrets_collection.insert_one(document)
+                logger.info(f"Stored encrypted secret for app '{app_slug}'")
+
+        except PyMongoError as e:
+            logger.error(f"Database error storing secret for app '{app_slug}': {e}", exc_info=True)
+            raise OperationFailure(f"Failed to store app secret: {e}") from e
+        except (ValueError, TypeError) as e:
+            logger.error(
+                f"Encryption error storing secret for app '{app_slug}': {e}", exc_info=True
+            )
+            raise
+
+    def verify_app_secret_sync(self, app_slug: str, provided_secret: str) -> bool:
+        """
+        Synchronous version of verify_app_secret for use in sync contexts.
+
+        Note: This uses asyncio.run() which creates a new event loop.
+        Use verify_app_secret() in async contexts for better performance.
+
+        Args:
+            app_slug: App slug identifier
+            provided_secret: Secret to verify
+
+        Returns:
+            True if secret matches, False otherwise
+        """
+        import asyncio
+
+        try:
+            # Try to get running loop
+            asyncio.get_running_loop()
+            # If we're in an async context, we can't use asyncio.run()
+            # Return False and log warning
+            logger.warning(
+                f"Cannot verify app secret synchronously in async context "
+                f"for '{app_slug}'. Use verify_app_secret() instead."
+            )
+            return False
+        except RuntimeError:
+            # No running loop - safe to use asyncio.run()
+            return asyncio.run(self.verify_app_secret(app_slug, provided_secret))
+
+    async def verify_app_secret(self, app_slug: str, provided_secret: str) -> bool:
+        """
+        Verify an app secret against stored encrypted value.
+
+        Args:
+            app_slug: App slug identifier
+            provided_secret: Secret to verify
+
+        Returns:
+            True if secret matches, False otherwise
+
+        Uses constant-time comparison to prevent timing attacks.
+        """
+        # Get encrypted secret from database
+        doc = await self._secrets_collection.find_one({"_id": app_slug})
+        if not doc:
+            # Log detailed info for debugging
+            logger.warning(f"Secret verification failed: app '{app_slug}' not found")
+            # Return False without revealing app existence
+            return False
+
+        # Decode base64
+        try:
+            encrypted_secret = base64.b64decode(doc["encrypted_secret"])
+            encrypted_dek = base64.b64decode(doc["encrypted_dek"])
+        except (ValueError, KeyError, TypeError) as e:
+            # Log detailed error for debugging
+            logger.warning(f"Secret verification error for app '{app_slug}': {e}", exc_info=True)
+            # Return False without revealing specific error
+            return False
+
+        # Decrypt stored secret
+        try:
+            stored_secret = self._encryption_service.decrypt_secret(encrypted_secret, encrypted_dek)
+        except ValueError:
+            # Log detailed error for debugging
+            logger.warning(f"Secret decryption failed for app '{app_slug}'", exc_info=True)
+            # Return False without revealing decryption failure
+            return False
+
+        # Use secrets.compare_digest for constant-time comparison
+        # Note: compare_digest handles length differences internally, preventing timing attacks
+        result = secrets.compare_digest(provided_secret.encode(), stored_secret.encode())
+        if result:
+            logger.debug(f"Secret verification succeeded for app '{app_slug}'")
+        else:
+            logger.warning(f"Secret verification failed for app '{app_slug}'")
+        return result
+
+    async def get_app_secret(self, app_slug: str) -> Optional[str]:
+        """
+        Get decrypted app secret (for rotation purposes only).
+
+        Args:
+            app_slug: App slug identifier
+
+        Returns:
+            Decrypted secret if found, None otherwise
+
+        Warning:
+            This method returns plaintext secrets. Use only for rotation.
+            Regular verification should use verify_app_secret().
+        """
+        doc = await self._secrets_collection.find_one({"_id": app_slug})
+        if not doc:
+            return None
+
+        # Decode base64
+        try:
+            encrypted_secret = base64.b64decode(doc["encrypted_secret"])
+            encrypted_dek = base64.b64decode(doc["encrypted_dek"])
+        except (ValueError, KeyError, TypeError) as e:
+            logger.warning(f"Failed to decode secret for app '{app_slug}': {e}")
+            return None
+
+        # Decrypt secret
+        try:
+            secret = self._encryption_service.decrypt_secret(encrypted_secret, encrypted_dek)
+            return secret
+        except ValueError as e:
+            logger.warning(f"Failed to decrypt secret for app '{app_slug}': {e}")
+            return None
+
+    async def rotate_app_secret(self, app_slug: str) -> str:
+        """
+        Rotate an app secret (generate new secret, re-encrypt and store).
+
+        Args:
+            app_slug: App slug identifier
+
+        Returns:
+            New plaintext secret (caller must store securely)
+
+        Raises:
+            ValueError: If app secret not found
+
+        The new secret is encrypted and stored, replacing the old one.
+        """
+        # Generate new secret
+        new_secret = secrets.token_urlsafe(32)
+
+        # Store new encrypted secret
+        await self.store_app_secret(app_slug, new_secret)
+
+        logger.info(f"Rotated secret for app '{app_slug}'")
+        return new_secret
+
+    def app_secret_exists_sync(self, app_slug: str) -> bool:
+        """
+        Synchronous version of app_secret_exists for use in sync contexts.
+
+        Args:
+            app_slug: App slug identifier
+
+        Returns:
+            True if secret exists, False otherwise
+
+        Note: If called from an async context, this will return False and log a warning.
+        Use app_secret_exists() in async contexts.
+        """
+        import asyncio
+
+        try:
+            # Try to get running loop
+            asyncio.get_running_loop()
+            # We're in an async context - can't safely check without blocking
+            # Return False (assume no secret) to allow backward compatibility
+            # The secret will be verified at query time through async methods
+            logger.debug(
+                f"Cannot check app secret existence synchronously in async context "
+                f"for '{app_slug}'. Assuming no secret exists (backward compatibility)."
+            )
+            return False
+        except RuntimeError:
+            # No running loop - safe to use asyncio.run()
+            return asyncio.run(self.app_secret_exists(app_slug))
+
+    async def app_secret_exists(self, app_slug: str) -> bool:
+        """
+        Check if an app secret exists.
+
+        Args:
+            app_slug: App slug identifier
+
+        Returns:
+            True if secret exists, False otherwise
+        """
+        doc = await self._secrets_collection.find_one({"_id": app_slug}, projection={"_id": 1})
+        return doc is not None

mdb_engine/core/connection.py

@@ -14,9 +14,12 @@ from typing import Optional
 from motor.motor_asyncio import AsyncIOMotorClient, AsyncIOMotorDatabase
 from pymongo.errors import ConnectionFailure, ServerSelectionTimeoutError
 
-from ..constants import (DEFAULT_MAX_IDLE_TIME_MS, DEFAULT_MAX_POOL_SIZE,
-                         DEFAULT_MIN_POOL_SIZE,
-                         DEFAULT_SERVER_SELECTION_TIMEOUT_MS)
+from ..constants import (
+    DEFAULT_MAX_IDLE_TIME_MS,
+    DEFAULT_MAX_POOL_SIZE,
+    DEFAULT_MIN_POOL_SIZE,
+    DEFAULT_SERVER_SELECTION_TIMEOUT_MS,
+)
 from ..exceptions import InitializationError
 from ..observability import get_logger as get_contextual_logger
 from ..observability import record_operation
@@ -73,9 +76,7 @@ class ConnectionManager:
         start_time = time.time()
 
         if self._initialized:
-            logger.warning(
-                "ConnectionManager already initialized. Skipping re-initialization."
-            )
+            logger.warning("ConnectionManager already initialized. Skipping re-initialization.")
             return
 
         contextual_logger.info(
@@ -232,11 +233,19 @@ class ConnectionManager:
             raise RuntimeError(
                 "ConnectionManager not initialized. Call initialize() first.",
             )
-        assert (
-            self._mongo_db is not None
-        ), "MongoDB database should not be None after initialization"
+        # Allow None for testing scenarios where mongo_db is patched
         return self._mongo_db
 
+    @mongo_db.deleter
+    def mongo_db(self) -> None:
+        """Allow deletion of mongo_db property for testing purposes."""
+        self._mongo_db = None
+
+    @mongo_db.setter
+    def mongo_db(self, value: Optional[AsyncIOMotorDatabase]) -> None:
+        """Allow setting mongo_db property for testing purposes."""
+        self._mongo_db = value
+
     @property
     def initialized(self) -> bool:
         """Check if connection is initialized."""

mdb_engine/core/encryption.py

@@ -0,0 +1,223 @@
+"""
+Envelope Encryption Service
+
+Provides envelope encryption for app secrets using a master key and
+per-secret data encryption keys (DEKs).
+
+This module is part of MDB_ENGINE - MongoDB Engine.
+
+Envelope Encryption Model:
+- Master Key (MK): Encrypts DEKs, stored in environment variable
+- Data Encryption Key (DEK): Encrypts app secrets, encrypted with MK
+- App Secret: Plaintext secret, encrypted with DEK
+
+This provides defense-in-depth: even if DEKs are compromised, they
+cannot be decrypted without the master key.
+"""
+
+import base64
+import logging
+import os
+import secrets
+from typing import Tuple
+
+import cryptography.exceptions
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+logger = logging.getLogger(__name__)
+
+# Master key environment variable name
+MASTER_KEY_ENV_VAR = "MDB_ENGINE_MASTER_KEY"
+
+# AES-GCM configuration
+AES_KEY_SIZE = 32  # 256 bits
+AES_NONCE_SIZE = 12  # 96 bits for GCM
+
+
+class EnvelopeEncryptionService:
+    """
+    Service for envelope encryption of app secrets.
+
+    Uses AES-256-GCM for encryption with envelope encryption pattern:
+    1. Generate random DEK for each secret
+    2. Encrypt secret with DEK
+    3. Encrypt DEK with master key
+    4. Store both encrypted values
+
+    This allows master key rotation without re-encrypting all secrets.
+    """
+
+    def __init__(self, master_key: bytes | None = None):
+        """
+        Initialize the encryption service.
+
+        Args:
+            master_key: Master key bytes. If None, loads from environment.
+
+        Raises:
+            ValueError: If master key is not provided and not in environment.
+        """
+        self._master_key = master_key or self._load_master_key()
+        if not self._master_key:
+            raise ValueError(
+                f"Master key not found. Set {MASTER_KEY_ENV_VAR} environment variable "
+                "or provide master_key parameter."
+            )
+
+    def _load_master_key(self) -> bytes | None:
+        """
+        Load master key from environment variable.
+
+        Returns:
+            Master key bytes if found, None otherwise.
+
+        Raises:
+            ValueError: If master key format is invalid.
+        """
+        master_key_str = os.getenv(MASTER_KEY_ENV_VAR)
+        if not master_key_str:
+            return None
+
+        try:
+            # Decode base64-encoded master key
+            master_key_bytes = base64.b64decode(master_key_str.encode())
+            if len(master_key_bytes) != AES_KEY_SIZE:
+                raise ValueError(
+                    f"Master key must be {AES_KEY_SIZE} bytes (256 bits) when decoded. "
+                    f"Got {len(master_key_bytes)} bytes."
+                )
+            return master_key_bytes
+        except (ValueError, TypeError, UnicodeDecodeError) as e:
+            raise ValueError(
+                f"Invalid master key format in {MASTER_KEY_ENV_VAR}. "
+                f"Expected base64-encoded {AES_KEY_SIZE}-byte key. Error: {e}"
+            ) from e
+
+    @staticmethod
+    def generate_master_key() -> str:
+        """
+        Generate a new master key.
+
+        Returns:
+            Base64-encoded master key string (suitable for environment variable).
+
+        Example:
+            >>> key = EnvelopeEncryptionService.generate_master_key()
+            >>> # Store in .env: MDB_ENGINE_MASTER_KEY={key}
+        """
+        key_bytes = secrets.token_bytes(AES_KEY_SIZE)
+        return base64.b64encode(key_bytes).decode()
+
+    @staticmethod
+    def generate_dek() -> bytes:
+        """
+        Generate a random Data Encryption Key (DEK).
+
+        Returns:
+            Random 32-byte DEK.
+
+        Note:
+            Each secret gets its own DEK for better security isolation.
+        """
+        return secrets.token_bytes(AES_KEY_SIZE)
+
+    def encrypt_secret(self, secret: str, master_key: bytes | None = None) -> Tuple[bytes, bytes]:
+        """
+        Encrypt a secret using envelope encryption.
+
+        Args:
+            secret: Plaintext secret to encrypt.
+            master_key: Master key to use. If None, uses instance master key.
+
+        Returns:
+            Tuple of (encrypted_secret, encrypted_dek) as bytes.
+
+        Process:
+            1. Generate random DEK
+            2. Encrypt secret with DEK using AES-GCM
+            3. Encrypt DEK with master key using AES-GCM
+            4. Return both encrypted values
+
+        Example:
+            >>> service = EnvelopeEncryptionService()
+            >>> encrypted_secret, encrypted_dek = service.encrypt_secret("my_secret")
+        """
+        master_key = master_key or self._master_key
+
+        # Generate random DEK
+        dek = self.generate_dek()
+
+        # Encrypt secret with DEK
+        aesgcm_secret = AESGCM(dek)
+        nonce_secret = secrets.token_bytes(AES_NONCE_SIZE)
+        encrypted_secret = aesgcm_secret.encrypt(nonce_secret, secret.encode(), None)
+
+        # Prepend nonce to encrypted secret
+        encrypted_secret_with_nonce = nonce_secret + encrypted_secret
+
+        # Encrypt DEK with master key
+        aesgcm_dek = AESGCM(master_key)
+        nonce_dek = secrets.token_bytes(AES_NONCE_SIZE)
+        encrypted_dek = aesgcm_dek.encrypt(nonce_dek, dek, None)
+
+        # Prepend nonce to encrypted DEK
+        encrypted_dek_with_nonce = nonce_dek + encrypted_dek
+
+        return encrypted_secret_with_nonce, encrypted_dek_with_nonce
+
+    def decrypt_secret(
+        self,
+        encrypted_secret: bytes,
+        encrypted_dek: bytes,
+        master_key: bytes | None = None,
+    ) -> str:
+        """
+        Decrypt a secret using envelope decryption.
+
+        Args:
+            encrypted_secret: Encrypted secret (with nonce prepended).
+            encrypted_dek: Encrypted DEK (with nonce prepended).
+            master_key: Master key to use. If None, uses instance master key.
+
+        Returns:
+            Decrypted plaintext secret.
+
+        Raises:
+            ValueError: If decryption fails (invalid key, corrupted data, etc.).
+
+        Process:
+            1. Decrypt DEK with master key
+            2. Decrypt secret with DEK
+            3. Return plaintext secret
+
+        Example:
+            >>> service = EnvelopeEncryptionService()
+            >>> secret = service.decrypt_secret(encrypted_secret, encrypted_dek)
+        """
+        master_key = master_key or self._master_key
+
+        try:
+            # Extract nonce and encrypted data for DEK
+            if len(encrypted_dek) < AES_NONCE_SIZE:
+                raise ValueError("Encrypted DEK too short (missing nonce)")
+            nonce_dek = encrypted_dek[:AES_NONCE_SIZE]
+            encrypted_dek_data = encrypted_dek[AES_NONCE_SIZE:]
+
+            # Decrypt DEK with master key
+            aesgcm_dek = AESGCM(master_key)
+            dek = aesgcm_dek.decrypt(nonce_dek, encrypted_dek_data, None)
+
+            # Extract nonce and encrypted data for secret
+            if len(encrypted_secret) < AES_NONCE_SIZE:
+                raise ValueError("Encrypted secret too short (missing nonce)")
+            nonce_secret = encrypted_secret[:AES_NONCE_SIZE]
+            encrypted_secret_data = encrypted_secret[AES_NONCE_SIZE:]
+
+            # Decrypt secret with DEK
+            aesgcm_secret = AESGCM(dek)
+            secret_bytes = aesgcm_secret.decrypt(nonce_secret, encrypted_secret_data, None)
+
+            return secret_bytes.decode()
+        except (ValueError, TypeError, UnicodeDecodeError, cryptography.exceptions.InvalidTag) as e:
+            logger.warning(f"Decryption failed: {e}")
+            raise ValueError(f"Failed to decrypt secret: {e}") from e