envdrift 4.2.1__py3-none-any.whl

envdrift/core/schema.py

@@ -0,0 +1,253 @@
+"""Schema loader for Pydantic Settings classes."""
+
+from __future__ import annotations
+
+import importlib
+import os
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from pydantic_settings import BaseSettings
+
+# Environment variable to signal schema extraction mode
+ENVDRIFT_SCHEMA_EXTRACTION = "ENVDRIFT_SCHEMA_EXTRACTION"
+
+
+@dataclass
+class FieldMetadata:
+    """Metadata about a settings field."""
+
+    name: str
+    required: bool
+    sensitive: bool
+    default: Any
+    description: str | None
+    field_type: type
+    annotation: str
+
+    @property
+    def is_optional(self) -> bool:
+        """
+        Indicates that the field can be omitted because it has a default value.
+
+        Returns:
+            `true` if the field can be omitted because it has a default value, `false` otherwise.
+        """
+        return not self.required
+
+
+@dataclass
+class SchemaMetadata:
+    """Complete schema metadata."""
+
+    class_name: str
+    module_path: str
+    fields: dict[str, FieldMetadata] = field(default_factory=dict)
+    extra_policy: str = "ignore"  # "forbid", "ignore", "allow"
+
+    @property
+    def required_fields(self) -> list[str]:
+        """
+        List the names of fields marked as required in the schema.
+
+        Returns:
+            list[str]: Field names for which FieldMetadata.required is True.
+        """
+        return [name for name, f in self.fields.items() if f.required]
+
+    @property
+    def optional_fields(self) -> list[str]:
+        """
+        List optional field names from the schema.
+
+        Returns:
+            list[str]: Field names whose corresponding FieldMetadata.required is False.
+        """
+        return [name for name, f in self.fields.items() if not f.required]
+
+    @property
+    def sensitive_fields(self) -> list[str]:
+        """
+        List names of fields that are marked as sensitive.
+
+        Returns:
+            list[str]: Field names for which the corresponding FieldMetadata.sensitive is True.
+        """
+        return [name for name, f in self.fields.items() if f.sensitive]
+
+
+class SchemaLoadError(Exception):
+    """Error loading schema."""
+
+    pass
+
+
+class SchemaLoader:
+    """Load and introspect Pydantic Settings classes."""
+
+    def load(self, dotted_path: str, service_dir: Path | str | None = None) -> type[BaseSettings]:
+        """
+        Load a Pydantic BaseSettings subclass specified by a dotted path.
+
+        Parameters:
+            dotted_path (str): Dotted import path with class name separated by `:`, e.g. "module.path:SettingsClass".
+            service_dir (Path | str | None): Optional directory to temporarily add to sys.path to assist imports.
+
+        Returns:
+            type[BaseSettings]: The resolved Pydantic Settings class.
+
+        Raises:
+            SchemaLoadError: If the path format is invalid, the module cannot be imported, the class is missing,
+                             or the resolved object is not a subclass of `BaseSettings`.
+        """
+        # Add service directory to path if provided
+        if service_dir:
+            service_dir = Path(service_dir).resolve()
+            if str(service_dir) not in sys.path:
+                sys.path.insert(0, str(service_dir))
+
+        # Parse the dotted path
+        if ":" not in dotted_path:
+            raise SchemaLoadError(
+                f"Invalid schema path '{dotted_path}'. Expected format: 'module.path:ClassName'"
+            )
+
+        module_path, class_name = dotted_path.rsplit(":", 1)
+
+        # Set environment variable to signal schema extraction mode
+        # This allows user code to skip Settings instantiation during import
+        os.environ[ENVDRIFT_SCHEMA_EXTRACTION] = "1"
+        try:
+            module = importlib.import_module(module_path)
+        except ImportError as e:
+            raise SchemaLoadError(f"Cannot import module '{module_path}': {e}") from e
+        finally:
+            # Clean up the environment variable
+            os.environ.pop(ENVDRIFT_SCHEMA_EXTRACTION, None)
+
+        try:
+            settings_cls = getattr(module, class_name)
+        except AttributeError as e:
+            raise SchemaLoadError(
+                f"Class '{class_name}' not found in module '{module_path}'"
+            ) from e
+
+        # Verify it's a BaseSettings subclass
+        if not isinstance(settings_cls, type) or not issubclass(settings_cls, BaseSettings):
+            raise SchemaLoadError(f"'{class_name}' is not a Pydantic BaseSettings subclass")
+
+        return settings_cls
+
+    def extract_metadata(self, settings_cls: type[BaseSettings]) -> SchemaMetadata:
+        """
+        Builds a SchemaMetadata instance describing the given Pydantic BaseSettings class, including each field's metadata and the model's extra policy.
+
+        Inspects the class's model_config.extra (defaulting to "ignore") and model_fields to populate FieldMetadata entries; for required fields the stored default is None, sensitivity is read from a field's json_schema_extra["sensitive"] if present, and type annotations fall back to "Any" when not available.
+
+        Parameters:
+            settings_cls (type[BaseSettings]): The Pydantic BaseSettings subclass to inspect.
+
+        Returns:
+            SchemaMetadata: Metadata for the settings class, including field map and extra policy.
+        """
+        schema = SchemaMetadata(
+            class_name=settings_cls.__name__,
+            module_path=settings_cls.__module__,
+        )
+
+        # Determine extra policy from model_config
+        model_config = getattr(settings_cls, "model_config", {})
+        if isinstance(model_config, dict):
+            extra = model_config.get("extra", "ignore")
+        else:
+            # SettingsConfigDict object
+            extra = getattr(model_config, "extra", "ignore")
+
+        schema.extra_policy = extra if extra else "ignore"
+
+        # Extract field metadata
+        for field_name, field_info in settings_cls.model_fields.items():
+            # Check if field is required
+            is_required = field_info.is_required()
+
+            # Check if marked as sensitive
+            extra_schema = field_info.json_schema_extra
+            is_sensitive = False
+            if isinstance(extra_schema, dict):
+                is_sensitive = extra_schema.get("sensitive", False)
+
+            # Get default value
+            default_value = None if is_required else field_info.default
+
+            # Get description
+            description = field_info.description
+
+            # Get type annotation as string
+            annotation = field_info.annotation
+            if annotation is not None:
+                if hasattr(annotation, "__name__"):
+                    type_str = annotation.__name__
+                else:
+                    type_str = str(annotation)
+            else:
+                type_str = "Any"
+
+            schema.fields[field_name] = FieldMetadata(
+                name=field_name,
+                required=is_required,
+                sensitive=is_sensitive,
+                default=default_value,
+                description=description,
+                field_type=annotation if annotation else type(None),
+                annotation=type_str,
+            )
+
+        return schema
+
+    def get_schema_metadata_func(
+        self, module_path: str, service_dir: Path | str | None = None
+    ) -> dict[str, Any] | None:
+        """
+        Invoke a module-level get_schema_metadata() function if present and return its result.
+
+        Parameters:
+            module_path (str): Dotted module path to import (e.g., "config.settings").
+            service_dir (Path | str | None): Optional directory to add to sys.path to aid importing the module.
+
+        Returns:
+            dict[str, Any] | None: The dictionary returned by get_schema_metadata() if callable and executed successfully,
+            or `None` if the module cannot be imported or the function is absent.
+        """
+        if service_dir:
+            service_dir = Path(service_dir).resolve()
+            if str(service_dir) not in sys.path:
+                sys.path.insert(0, str(service_dir))
+
+        try:
+            module = importlib.import_module(module_path)
+        except ImportError:
+            return None
+
+        func = getattr(module, "get_schema_metadata", None)
+        if callable(func):
+            return func()
+
+        return None
+
+    def load_and_extract(
+        self, dotted_path: str, service_dir: Path | str | None = None
+    ) -> SchemaMetadata:
+        """
+        Convenience method that loads a Pydantic BaseSettings class from a dotted path and returns its SchemaMetadata.
+
+        Parameters:
+            dotted_path (str): Dotted import path with class name, e.g. "config.settings:ProductionSettings".
+            service_dir (Path | str | None): Optional directory to add to sys.path to assist imports.
+
+        Returns:
+            SchemaMetadata: Metadata describing the loaded settings class and its fields.
+        """
+        settings_cls = self.load(dotted_path, service_dir)
+        return self.extract_metadata(settings_cls)

envdrift/core/validator.py

@@ -0,0 +1,312 @@
+"""Validation logic for .env files against Pydantic schemas."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from envdrift.core.parser import EncryptionStatus, EnvFile
+from envdrift.core.schema import SchemaMetadata
+
+
+@dataclass
+class ValidationResult:
+    """Result of schema validation."""
+
+    valid: bool
+    missing_required: set[str] = field(default_factory=set)
+    missing_optional: set[str] = field(default_factory=set)
+    extra_vars: set[str] = field(default_factory=set)
+    unencrypted_secrets: set[str] = field(default_factory=set)
+    type_errors: dict[str, str] = field(default_factory=dict)
+    warnings: list[str] = field(default_factory=list)
+
+    @property
+    def has_errors(self) -> bool:
+        """
+        Return whether the validation contains any errors (exclude warnings).
+
+        Checks for missing required variables, type errors, or extra variables
+        present when the schema forbids extras. Unencrypted secrets are warnings,
+        not errors - use `envdrift encrypt --check` for strict enforcement.
+
+        Returns:
+            True if any errors are present, False otherwise.
+        """
+        return bool(self.missing_required) or bool(self.type_errors) or bool(self.extra_vars)
+
+    @property
+    def error_count(self) -> int:
+        """
+        Compute the total number of validation error entries.
+
+        Returns:
+            int: Sum of missing required variables, type errors, and extra variables.
+        """
+        return len(self.missing_required) + len(self.type_errors) + len(self.extra_vars)
+
+    @property
+    def warning_count(self) -> int:
+        """
+        Compute the total number of warning entries.
+
+        Combines explicit warnings, missing optional variables, and unencrypted secrets.
+
+        Returns:
+            The total count of warnings as an integer.
+        """
+        return len(self.warnings) + len(self.missing_optional) + len(self.unencrypted_secrets)
+
+
+class Validator:
+    """Validate .env files against Pydantic schemas."""
+
+    # Patterns that suggest a value is a secret
+    SECRET_PATTERNS = [
+        re.compile(r"^sk[-_]", re.IGNORECASE),  # API keys (Stripe, OpenAI)
+        re.compile(r"^pk[-_]", re.IGNORECASE),  # Public/private keys
+        re.compile(r"password", re.IGNORECASE),  # Passwords
+        re.compile(r"secret", re.IGNORECASE),  # Secrets
+        re.compile(r"^ghp_"),  # GitHub personal tokens
+        re.compile(r"^gho_"),  # GitHub OAuth tokens
+        re.compile(r"^ghu_"),  # GitHub user tokens
+        re.compile(r"^xox[baprs]-"),  # Slack tokens
+        re.compile(r"^AKIA[0-9A-Z]{16}$"),  # AWS access keys
+        re.compile(r"^postgres://.*:.*@"),  # DB URLs with credentials
+        re.compile(r"^postgresql://.*:.*@"),
+        re.compile(r"^mysql://.*:.*@"),
+        re.compile(r"^redis://.*:.*@"),
+        re.compile(r"^mongodb://.*:.*@"),
+        re.compile(r"^mongodb\+srv://.*:.*@"),
+        re.compile(r"eyJ[A-Za-z0-9_-]+\.eyJ"),  # JWT tokens
+    ]
+
+    # Variable names that suggest sensitive content
+    SENSITIVE_VAR_PATTERNS = [
+        re.compile(r".*_KEY$", re.IGNORECASE),
+        re.compile(r".*_SECRET$", re.IGNORECASE),
+        re.compile(r".*_TOKEN$", re.IGNORECASE),
+        re.compile(r".*_PASSWORD$", re.IGNORECASE),
+        re.compile(r".*_PASS$", re.IGNORECASE),
+        re.compile(r".*_CREDENTIAL.*", re.IGNORECASE),
+        re.compile(r".*_API_KEY$", re.IGNORECASE),
+        re.compile(r"^JWT_.*", re.IGNORECASE),
+        re.compile(r"^AUTH_.*", re.IGNORECASE),
+        re.compile(r".*_DSN$", re.IGNORECASE),  # Sentry DSN
+    ]
+
+    def validate(
+        self,
+        env_file: EnvFile,
+        schema: SchemaMetadata,
+        check_encryption: bool = True,
+        check_extra: bool = True,
+    ) -> ValidationResult:
+        """Validate env file against schema.
+
+        Checks:
+        1. All required vars exist
+        2. No unexpected vars (if schema has extra="forbid")
+        3. Sensitive vars are encrypted
+        4. Values match expected types (basic check)
+
+        Args:
+            env_file: Parsed env file
+            schema: Schema metadata
+            check_encryption: Whether to check if sensitive vars are encrypted
+            check_extra: Whether to check for extra variables
+
+        Returns:
+            ValidationResult with all issues found
+        """
+        result = ValidationResult(valid=True)
+
+        env_var_names = set(env_file.variables.keys())
+        schema_field_names = set(schema.fields.keys())
+
+        # Check for missing required variables
+        for field_name, field_meta in schema.fields.items():
+            if field_meta.required and field_name not in env_var_names:
+                result.missing_required.add(field_name)
+
+        # Check for missing optional variables (as warning)
+        for field_name, field_meta in schema.fields.items():
+            if not field_meta.required and field_name not in env_var_names:
+                result.missing_optional.add(field_name)
+
+        # Check for extra variables
+        if check_extra:
+            extra = env_var_names - schema_field_names
+            if extra:
+                if schema.extra_policy == "forbid":
+                    result.extra_vars = extra
+                else:
+                    # Just a warning when extra is "ignore" or "allow"
+                    for var_name in extra:
+                        result.warnings.append(f"Extra variable '{var_name}' not in schema")
+
+        # Check encryption status for sensitive variables
+        if check_encryption:
+            for field_name, field_meta in schema.fields.items():
+                if field_name not in env_file.variables:
+                    continue
+
+                env_var = env_file.variables[field_name]
+
+                # Check schema-defined sensitive fields
+                if field_meta.sensitive:
+                    if env_var.encryption_status == EncryptionStatus.PLAINTEXT:
+                        result.unencrypted_secrets.add(field_name)
+
+            # Also check for suspicious plaintext values
+            for var_name, env_var in env_file.variables.items():
+                if env_var.encryption_status == EncryptionStatus.PLAINTEXT:
+                    if self.is_value_suspicious(env_var.value):
+                        if var_name not in schema.sensitive_fields:
+                            result.warnings.append(
+                                f"'{var_name}' looks like a secret but "
+                                "is not marked sensitive in schema"
+                            )
+                    if self.is_name_suspicious(var_name):
+                        if var_name not in schema.sensitive_fields:
+                            result.warnings.append(
+                                f"'{var_name}' has a name suggesting sensitive data "
+                                "but is not marked sensitive in schema"
+                            )
+
+        # Basic type validation
+        for field_name, field_meta in schema.fields.items():
+            if field_name not in env_file.variables:
+                continue
+
+            env_var = env_file.variables[field_name]
+            type_error = self._check_type(env_var.value, field_meta.field_type)
+            if type_error:
+                result.type_errors[field_name] = type_error
+
+        # Determine overall validity
+        # Note: unencrypted_secrets are warnings, not errors
+        # Use `envdrift encrypt --check` for strict encryption enforcement
+        result.valid = not (result.missing_required or result.type_errors or result.extra_vars)
+
+        return result
+
+    def is_value_suspicious(self, value: str) -> bool:
+        """
+        Determine whether a plaintext value matches any known secret-like pattern.
+
+        Returns:
+            `true` if the value matches any secret-like pattern, `false` otherwise.
+        """
+        for pattern in self.SECRET_PATTERNS:
+            if pattern.search(value):
+                return True
+        return False
+
+    def is_name_suspicious(self, name: str) -> bool:
+        """
+        Determine whether an environment variable name indicates it contains sensitive data.
+
+        Parameters:
+            name (str): Environment variable name to evaluate.
+
+        Returns:
+            bool: `True` if the variable name matches a sensitive pattern, `False` otherwise.
+        """
+        for pattern in self.SENSITIVE_VAR_PATTERNS:
+            if pattern.match(name):
+                return True
+        return False
+
+    def _check_type(self, value: str, expected_type: type) -> str | None:
+        """
+        Validate a plaintext .env value against an expected Python type.
+
+        Parameters:
+            value (str): The raw value read from a .env file.
+            expected_type (type): The Python type expected for the value (e.g., int, float, bool, list).
+
+        Notes:
+            If `expected_type` is None or `value` is an empty string, no type check is performed and the function returns None.
+
+        Returns:
+            str | None: An error message describing the type mismatch, or `None` if the value is acceptable or no check was performed.
+        """
+        if expected_type is None or value == "":
+            return None
+
+        # Skip type check for encrypted values (supports both dotenvx and SOPS)
+        # dotenvx format: encrypted:...
+        # SOPS format: ENC[AES256_GCM,...
+        if value.startswith("encrypted:") or value.startswith("ENC["):
+            return None
+
+        type_name = getattr(expected_type, "__name__", str(expected_type))
+
+        # Handle int
+        if type_name == "int":
+            try:
+                int(value)
+            except ValueError:
+                return f"Expected integer, got '{value}'"
+
+        # Handle float
+        elif type_name == "float":
+            try:
+                float(value)
+            except ValueError:
+                return f"Expected float, got '{value}'"
+
+        # Handle bool
+        elif type_name == "bool":
+            if value.lower() not in ("true", "false", "1", "0", "yes", "no"):
+                return f"Expected boolean, got '{value}'"
+
+        # Handle list (basic check for list-like structure)
+        elif type_name == "list":
+            # Lists in .env are typically comma-separated or JSON
+            # We'll accept anything here, just check it's not obviously wrong
+            pass
+
+        return None
+
+    def generate_fix_template(self, result: ValidationResult, schema: SchemaMetadata) -> str:
+        """
+        Generate a .env snippet that provides assignments for any missing schema variables.
+
+        Parameters:
+            result (ValidationResult): Validation outcome containing `missing_required` and `missing_optional` sets.
+            schema (SchemaMetadata): Schema metadata used to include field descriptions, defaults, and sensitivity flags.
+
+        Returns:
+            template (str): A newline-separated .env template. Required sensitive fields use the placeholder
+            `encrypted:YOUR_VALUE_HERE`; optional fields include commented defaults when available.
+        """
+        lines = []
+
+        if result.missing_required:
+            lines.append("# Missing required variables:")
+            for var_name in sorted(result.missing_required):
+                field_meta = schema.fields.get(var_name)
+                if field_meta and field_meta.description:
+                    lines.append(f"# {field_meta.description}")
+                if field_meta and field_meta.sensitive:
+                    lines.append(f'{var_name}="encrypted:YOUR_VALUE_HERE"')
+                else:
+                    lines.append(f"{var_name}=")
+                lines.append("")
+
+        if result.missing_optional:
+            lines.append("# Missing optional variables (have defaults):")
+            for var_name in sorted(result.missing_optional):
+                field_meta = schema.fields.get(var_name)
+                if field_meta and field_meta.description:
+                    lines.append(f"# {field_meta.description}")
+                default = field_meta.default if field_meta else None
+                if default is not None:
+                    lines.append(f"# {var_name}={default}")
+                else:
+                    lines.append(f"# {var_name}=")
+                lines.append("")
+
+        return "\n".join(lines)

envdrift/encryption/__init__.py

@@ -0,0 +1,117 @@
+"""Encryption backend interfaces for multiple encryption tools."""
+
+from __future__ import annotations
+
+from enum import Enum
+from pathlib import Path
+
+from envdrift.encryption.base import (
+    EncryptionBackend,
+    EncryptionBackendError,
+    EncryptionNotFoundError,
+)
+
+
+class EncryptionProvider(Enum):
+    """Supported encryption providers."""
+
+    DOTENVX = "dotenvx"
+    SOPS = "sops"
+
+
+def get_encryption_backend(provider: EncryptionProvider | str, **config) -> EncryptionBackend:
+    """
+    Create and return a provider-specific EncryptionBackend.
+
+    Parameters:
+        provider (EncryptionProvider | str): Encryption provider enum or name ("dotenvx", "sops").
+        **config: Provider-specific configuration:
+            - For "dotenvx": `auto_install` (bool) - optional, defaults to False.
+            - For "sops": `config_file` (str) - optional path to .sops.yaml.
+                        `age_key` (str) - optional age private key (SOPS_AGE_KEY).
+                        `age_key_file` (str) - optional age key file path (SOPS_AGE_KEY_FILE).
+                        `auto_install` (bool) - optional, defaults to False.
+
+    Returns:
+        EncryptionBackend: A configured backend instance for the requested provider.
+
+    Raises:
+        ValueError: If the provider is unsupported.
+    """
+    if isinstance(provider, str):
+        provider = EncryptionProvider(provider)
+
+    if provider == EncryptionProvider.DOTENVX:
+        from envdrift.encryption.dotenvx import DotenvxEncryptionBackend
+
+        return DotenvxEncryptionBackend(
+            auto_install=config.get("auto_install", False),
+        )
+
+    elif provider == EncryptionProvider.SOPS:
+        from envdrift.encryption.sops import SOPSEncryptionBackend
+
+        return SOPSEncryptionBackend(
+            config_file=config.get("config_file"),
+            age_key=config.get("age_key"),
+            age_key_file=config.get("age_key_file"),
+            auto_install=config.get("auto_install", False),
+        )
+
+    raise ValueError(f"Unsupported encryption provider: {provider}")
+
+
+def detect_encryption_provider(file_path) -> EncryptionProvider | None:
+    """
+    Auto-detect which encryption provider was used to encrypt a file.
+
+    Parameters:
+        file_path: Path to the encrypted file.
+
+    Returns:
+        EncryptionProvider if detected, None if file is not encrypted or unknown format.
+    """
+    path = Path(file_path)
+    if not path.exists():
+        return None
+
+    content = path.read_text(encoding="utf-8")
+
+    # Check for dotenvx markers first (most common)
+    dotenvx_markers = ["#/---BEGIN DOTENV ENCRYPTED---/", "DOTENV_PUBLIC_KEY"]
+    for marker in dotenvx_markers:
+        if marker in content:
+            return EncryptionProvider.DOTENVX
+
+    # Check for SOPS markers
+    # SOPS encrypted files have "sops" key in YAML/JSON or ENC[] markers in dotenv
+    sops_markers = [
+        "sops:",  # YAML format
+        '"sops":',  # JSON format
+        "ENC[AES256_GCM,",  # SOPS encrypted value marker
+    ]
+    for marker in sops_markers:
+        if marker in content:
+            return EncryptionProvider.SOPS
+
+    # Check for .sops.yaml in same directory or parent
+    sops_config_locations = [
+        path.parent / ".sops.yaml",
+        path.parent.parent / ".sops.yaml",
+    ]
+    for sops_config in sops_config_locations:
+        if sops_config.exists():
+            # .sops.yaml alone does not prove encryption; avoid false positives for plaintext files.
+            return None
+
+    return None
+
+
+__all__ = [
+    "EncryptionBackend",
+    "EncryptionBackendError",
+    "EncryptionNotFoundError",
+    "EncryptionProvider",
+    "detect_encryption_provider",
+    "get_encryption_backend",
+]