envdrift 4.2.1__py3-none-any.whl

envdrift/core/diff.py

@@ -0,0 +1,233 @@
+"""Cross-environment diff engine."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+
+from envdrift.core.parser import EnvFile
+from envdrift.core.schema import SchemaMetadata
+
+
+class DiffType(Enum):
+    """Type of difference between environments."""
+
+    ADDED = "added"  # In env2 but not env1
+    REMOVED = "removed"  # In env1 but not env2
+    CHANGED = "changed"  # Different values
+    UNCHANGED = "unchanged"  # Same values
+
+
+@dataclass
+class VarDiff:
+    """Difference for a single variable."""
+
+    name: str
+    diff_type: DiffType
+    value1: str | None  # Value in env1 (masked if sensitive)
+    value2: str | None  # Value in env2 (masked if sensitive)
+    is_sensitive: bool
+    line_number1: int | None = None  # Line in env1
+    line_number2: int | None = None  # Line in env2
+
+
+@dataclass
+class DiffResult:
+    """Result of comparing two env files."""
+
+    env1_path: Path
+    env2_path: Path
+    differences: list[VarDiff] = field(default_factory=list)
+
+    @property
+    def added_count(self) -> int:
+        """
+        Number of variables that are present in env2 but not in env1.
+
+        Returns:
+            int: Count of variables classified as `ADDED`.
+        """
+        return sum(1 for d in self.differences if d.diff_type == DiffType.ADDED)
+
+    @property
+    def removed_count(self) -> int:
+        """
+        Number of variables that are present in the first environment but missing in the second.
+
+        Returns:
+            int: Count of diffs with type `DiffType.REMOVED`.
+        """
+        return sum(1 for d in self.differences if d.diff_type == DiffType.REMOVED)
+
+    @property
+    def changed_count(self) -> int:
+        """
+        Number of variables whose values differ between the two environments.
+
+        Returns:
+            int: Count of VarDiff entries whose `diff_type` is `DiffType.CHANGED`.
+        """
+        return sum(1 for d in self.differences if d.diff_type == DiffType.CHANGED)
+
+    @property
+    def unchanged_count(self) -> int:
+        """
+        Return the number of variables that are unchanged between the two environments.
+
+        Returns:
+            int: Count of VarDiff entries whose `diff_type` is `DiffType.UNCHANGED`.
+        """
+        return sum(1 for d in self.differences if d.diff_type == DiffType.UNCHANGED)
+
+    @property
+    def has_drift(self) -> bool:
+        """
+        Determine whether there is any drift between the two environments.
+
+        Returns:
+            True if at least one variable was added, removed, or changed, False otherwise.
+        """
+        return self.added_count + self.removed_count + self.changed_count > 0
+
+    def get_added(self) -> list[VarDiff]:
+        """
+        List VarDiff entries that are present only in the second environment.
+
+        Returns:
+            list[VarDiff]: VarDiff objects whose `diff_type` is `DiffType.ADDED`.
+        """
+        return [d for d in self.differences if d.diff_type == DiffType.ADDED]
+
+    def get_removed(self) -> list[VarDiff]:
+        """
+        Retrieve variables present in the first environment but absent in the second.
+
+        Returns:
+            list[VarDiff]: VarDiff objects whose `diff_type` is `DiffType.REMOVED`.
+        """
+        return [d for d in self.differences if d.diff_type == DiffType.REMOVED]
+
+    def get_changed(self) -> list[VarDiff]:
+        """
+        Return all variables whose values differ between the two environments.
+
+        Returns:
+            list[VarDiff]: List of VarDiff entries whose `diff_type` is `DiffType.CHANGED`.
+        """
+        return [d for d in self.differences if d.diff_type == DiffType.CHANGED]
+
+
+class DiffEngine:
+    """Compare two .env files."""
+
+    MASK_VALUE = "********"
+
+    def diff(
+        self,
+        env1: EnvFile,
+        env2: EnvFile,
+        schema: SchemaMetadata | None = None,
+        mask_values: bool = True,
+        include_unchanged: bool = False,
+    ) -> DiffResult:
+        """
+        Compute differences between two environment files and return a structured DiffResult.
+
+        Parameters:
+            env1 (EnvFile): First environment file (left-hand side of comparison).
+            env2 (EnvFile): Second environment file (right-hand side of comparison).
+            schema (SchemaMetadata | None): Optional schema used to identify sensitive fields.
+            mask_values (bool): If True, sensitive variable values are replaced with a mask in the result.
+            include_unchanged (bool): If True, variables with identical values in both files are included.
+
+        Returns:
+            DiffResult: Aggregated comparison result containing a list of VarDiff entries and summary counts.
+        """
+        result = DiffResult(env1_path=env1.path, env2_path=env2.path)
+
+        env1_vars = set(env1.variables.keys())
+        env2_vars = set(env2.variables.keys())
+
+        all_vars = env1_vars | env2_vars
+        sensitive_fields = set(schema.sensitive_fields) if schema else set()
+
+        for var_name in sorted(all_vars):
+            in_env1 = var_name in env1_vars
+            in_env2 = var_name in env2_vars
+            is_sensitive = var_name in sensitive_fields
+
+            var1 = env1.variables.get(var_name)
+            var2 = env2.variables.get(var_name)
+
+            # Get values (potentially masked)
+            value1 = var1.value if var1 else None
+            value2 = var2.value if var2 else None
+
+            if mask_values and is_sensitive:
+                display_value1 = self.MASK_VALUE if value1 else None
+                display_value2 = self.MASK_VALUE if value2 else None
+            else:
+                display_value1 = value1
+                display_value2 = value2
+
+            # Determine diff type
+            if not in_env1 and in_env2:
+                diff_type = DiffType.ADDED
+            elif in_env1 and not in_env2:
+                diff_type = DiffType.REMOVED
+            elif value1 != value2:
+                diff_type = DiffType.CHANGED
+            else:
+                diff_type = DiffType.UNCHANGED
+                if not include_unchanged:
+                    continue
+
+            var_diff = VarDiff(
+                name=var_name,
+                diff_type=diff_type,
+                value1=display_value1,
+                value2=display_value2,
+                is_sensitive=is_sensitive,
+                line_number1=var1.line_number if var1 else None,
+                line_number2=var2.line_number if var2 else None,
+            )
+
+            result.differences.append(var_diff)
+
+        return result
+
+    def to_dict(self, result: DiffResult) -> dict:
+        """
+        Convert a DiffResult into a JSON-serializable dictionary.
+
+        Args:
+            result: DiffResult instance to convert.
+
+        Returns:
+            dict: Mapping with keys:
+                - "env1": string path of the first env file
+                - "env2": string path of the second env file
+                - "summary": dict with counts ("added", "removed", "changed") and "has_drift" flag
+                - "differences": list of dicts for each variable containing "name", "type", "value_env1", "value_env2", and "sensitive"
+        """
+        return {
+            "env1": str(result.env1_path),
+            "env2": str(result.env2_path),
+            "summary": {
+                "added": result.added_count,
+                "removed": result.removed_count,
+                "changed": result.changed_count,
+                "has_drift": result.has_drift,
+            },
+            "differences": [
+                {
+                    "name": d.name,
+                    "type": d.diff_type.value,
+                    "value_env1": d.value1,
+                    "value_env2": d.value2,
+                    "sensitive": d.is_sensitive,
+                }
+                for d in result.differences
+            ],
+        }

envdrift/core/encryption.py

@@ -0,0 +1,400 @@
+"""Encryption detection for .env files.
+
+Supports multiple encryption backends:
+- dotenvx: Uses "encrypted:" prefix and dotenvx file headers
+- SOPS: Uses "ENC[AES256_GCM,..." format
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from envdrift.core.parser import EncryptionStatus, EnvFile
+from envdrift.core.schema import SchemaMetadata
+
+if TYPE_CHECKING:
+    pass
+
+
+@dataclass
+class EncryptionReport:
+    """Report on encryption status of an env file."""
+
+    path: Path
+    is_fully_encrypted: bool = False
+    encrypted_vars: set[str] = field(default_factory=set)
+    plaintext_vars: set[str] = field(default_factory=set)
+    empty_vars: set[str] = field(default_factory=set)
+    plaintext_secrets: set[str] = field(
+        default_factory=set
+    )  # Plaintext vars that look like secrets
+    warnings: list[str] = field(default_factory=list)
+    detected_backend: str | None = None  # Which encryption backend was detected
+
+    @property
+    def encryption_ratio(self) -> float:
+        """
+        Compute the fraction of non-empty variables that are encrypted.
+
+        Returns:
+            encryption_ratio (float): Fraction between 0.0 and 1.0 equal to encrypted_vars / (encrypted_vars + plaintext_vars). Returns 0.0 when there are no non-empty variables.
+        """
+        total = len(self.encrypted_vars) + len(self.plaintext_vars)
+        if total == 0:
+            return 0.0
+        return len(self.encrypted_vars) / total
+
+    @property
+    def total_vars(self) -> int:
+        """
+        Total number of variables considered by the report.
+
+        Returns:
+            int: Count of encrypted, plaintext, and empty variables.
+        """
+        return len(self.encrypted_vars) + len(self.plaintext_vars) + len(self.empty_vars)
+
+
+class EncryptionDetector:
+    """Detect encryption status of .env files.
+
+    Supports multiple encryption backends:
+    - dotenvx: Values prefixed with "encrypted:", file has dotenvx headers
+    - SOPS: Values in format "ENC[AES256_GCM,data:...,iv:...,tag:...,type:str]"
+    """
+
+    # Patterns that indicate encrypted values (dotenvx format)
+    DOTENVX_ENCRYPTED_PREFIXES = [
+        "encrypted:",
+    ]
+
+    # Patterns that indicate encrypted values (SOPS format)
+    SOPS_ENCRYPTED_PATTERN = re.compile(r"^ENC\[AES256_GCM,")
+
+    # All encrypted prefixes for backward compatibility
+    ENCRYPTED_PREFIXES = DOTENVX_ENCRYPTED_PREFIXES + ["ENC["]
+
+    # Header patterns that indicate the file has been encrypted by dotenvx
+    DOTENVX_FILE_MARKERS = [
+        "#/---BEGIN DOTENV ENCRYPTED---/",
+        "DOTENV_PUBLIC_KEY",
+    ]
+
+    # Header/content patterns that indicate the file has been encrypted by SOPS
+    SOPS_FILE_MARKERS = [
+        "sops:",  # YAML metadata
+        '"sops":',  # JSON metadata
+        "ENC[AES256_GCM,",  # Encrypted value marker
+    ]
+
+    # Combined file markers for backward compatibility
+    ENCRYPTED_FILE_MARKERS = DOTENVX_FILE_MARKERS + SOPS_FILE_MARKERS
+
+    # Patterns for suspicious plaintext secrets
+    SECRET_VALUE_PATTERNS = [
+        re.compile(r"^sk[-_]", re.IGNORECASE),  # Stripe, OpenAI keys
+        re.compile(r"^pk[-_]", re.IGNORECASE),  # Public keys
+        re.compile(r"^ghp_"),  # GitHub personal tokens
+        re.compile(r"^gho_"),  # GitHub OAuth tokens
+        re.compile(r"^xox[baprs]-"),  # Slack tokens
+        re.compile(r"^AKIA[0-9A-Z]{16}$"),  # AWS access keys
+        re.compile(r"^eyJ[A-Za-z0-9_-]+\.eyJ"),  # JWT tokens
+        re.compile(r"^postgres(ql)?://[^:]+:[^@]+@"),  # DB URLs with creds
+        re.compile(r"^mysql://[^:]+:[^@]+@"),
+        re.compile(r"^redis://[^:]+:[^@]+@"),
+        re.compile(r"^mongodb(\+srv)?://[^:]+:[^@]+@"),
+    ]
+
+    # Variable names that suggest sensitive content
+    SENSITIVE_NAME_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"^PRIVATE_.*", re.IGNORECASE),
+        re.compile(r".*_DSN$", re.IGNORECASE),
+    ]
+
+    def analyze(
+        self,
+        env_file: EnvFile,
+        schema: SchemaMetadata | None = None,
+    ) -> EncryptionReport:
+        """
+        Analyze an EnvFile to determine which variables are encrypted, plaintext, empty, and which plaintext values appear to be secrets.
+
+        Parameters:
+            env_file (EnvFile): Parsed env file to analyze.
+            schema (SchemaMetadata | None): Optional schema whose sensitive_fields will be treated as sensitive names.
+
+        Returns:
+            EncryptionReport: Report containing the file path, sets of encrypted/plaintext/empty variables, detected plaintext secrets, collected warnings, and the is_fully_encrypted flag.
+        """
+        report = EncryptionReport(path=env_file.path)
+
+        # Get sensitive fields from schema
+        schema_sensitive = set(schema.sensitive_fields) if schema else set()
+
+        for var_name, env_var in env_file.variables.items():
+            if env_var.encryption_status == EncryptionStatus.ENCRYPTED:
+                report.encrypted_vars.add(var_name)
+            elif env_var.encryption_status == EncryptionStatus.EMPTY:
+                report.empty_vars.add(var_name)
+            else:
+                report.plaintext_vars.add(var_name)
+
+                # Check if this plaintext value looks like a secret
+                is_suspicious = self.is_value_suspicious(env_var.value)
+                is_name_sensitive = self.is_name_sensitive(var_name)
+                is_schema_sensitive = var_name in schema_sensitive
+
+                if is_suspicious or is_name_sensitive or is_schema_sensitive:
+                    report.plaintext_secrets.add(var_name)
+
+                    if is_schema_sensitive:
+                        report.warnings.append(
+                            f"'{var_name}' is marked sensitive in schema but has plaintext value"
+                        )
+                    elif is_suspicious:
+                        report.warnings.append(f"'{var_name}' has a value that looks like a secret")
+                    elif is_name_sensitive:
+                        report.warnings.append(f"'{var_name}' has a name suggesting sensitive data")
+
+        # Determine if fully encrypted
+        non_empty_vars = report.encrypted_vars | report.plaintext_vars
+        if non_empty_vars:
+            report.is_fully_encrypted = len(report.plaintext_vars) == 0
+
+        detected_backends = {
+            env_var.encryption_backend
+            for env_var in env_file.variables.values()
+            if env_var.encryption_backend
+        }
+        if len(detected_backends) == 1:
+            report.detected_backend = next(iter(detected_backends))
+
+        return report
+
+    def should_block_commit(self, report: EncryptionReport) -> bool:
+        """
+        Decides whether a commit should be blocked due to plaintext secrets found in the report.
+
+        Parameters:
+            report (EncryptionReport): Analysis report to evaluate.
+
+        Returns:
+            `true` if the report contains any plaintext secrets, `false` otherwise.
+        """
+        return len(report.plaintext_secrets) > 0
+
+    def has_encrypted_header(self, content: str) -> bool:
+        """
+        Determine whether the given file content contains encryption markers.
+
+        Parameters:
+            content (str): Raw file content to inspect for encryption markers.
+
+        Returns:
+            `true` if any encrypted-file marker is present in content, `false` otherwise.
+        """
+        for marker in self.ENCRYPTED_FILE_MARKERS:
+            if marker in content:
+                return True
+        return False
+
+    def has_dotenvx_header(self, content: str) -> bool:
+        """
+        Determine whether the given file content contains a dotenvx encryption header.
+
+        Parameters:
+            content (str): Raw file content to inspect for encryption markers.
+
+        Returns:
+            `true` if any dotenvx marker is present in content, `false` otherwise.
+        """
+        for marker in self.DOTENVX_FILE_MARKERS:
+            if marker in content:
+                return True
+        return False
+
+    def has_sops_header(self, content: str) -> bool:
+        """
+        Determine whether the given file content contains SOPS encryption markers.
+
+        Parameters:
+            content (str): Raw file content to inspect for encryption markers.
+
+        Returns:
+            `true` if any SOPS marker is present in content, `false` otherwise.
+        """
+        for marker in self.SOPS_FILE_MARKERS:
+            if marker in content:
+                return True
+        return False
+
+    def detect_backend(self, content: str) -> str | None:
+        """
+        Detect which encryption backend was used for the content.
+
+        Parameters:
+            content (str): Raw file content to inspect.
+
+        Returns:
+            "dotenvx", "sops", or None if no encryption detected.
+        """
+        if self.has_dotenvx_header(content):
+            return "dotenvx"
+        if self.has_sops_header(content):
+            return "sops"
+        return None
+
+    def detect_backend_for_file(self, path: Path) -> str | None:
+        """
+        Detect which encryption backend was used for a file.
+
+        Parameters:
+            path (Path): Filesystem path to the file to inspect.
+
+        Returns:
+            "dotenvx", "sops", or None if no encryption detected.
+        """
+        if not path.exists():
+            return None
+
+        content = path.read_text(encoding="utf-8")
+        return self.detect_backend(content)
+
+    def is_file_encrypted(self, path: Path) -> bool:
+        """
+        Determine whether a file contains encryption markers.
+
+        Parameters:
+            path (Path): Filesystem path to the file to inspect.
+
+        Returns:
+            `true` if the file contains encryption markers, `false` otherwise.
+        """
+        if not path.exists():
+            return False
+
+        content = path.read_text(encoding="utf-8")
+        return self.has_encrypted_header(content)
+
+    def is_value_encrypted(self, value: str) -> bool:
+        """
+        Determine whether a value is encrypted by any supported backend.
+
+        Parameters:
+            value (str): The value to check.
+
+        Returns:
+            True if the value appears encrypted, False otherwise.
+        """
+        if not value:
+            return False
+
+        # Check dotenvx format
+        for prefix in self.DOTENVX_ENCRYPTED_PREFIXES:
+            if value.startswith(prefix):
+                return True
+
+        # Check SOPS format
+        return bool(self.SOPS_ENCRYPTED_PATTERN.match(value))
+
+    def detect_value_backend(self, value: str) -> str | None:
+        """
+        Detect which encryption backend was used for a specific value.
+
+        Parameters:
+            value (str): The value to check.
+
+        Returns:
+            "dotenvx", "sops", or None if not encrypted.
+        """
+        if not value:
+            return None
+
+        # Check dotenvx format
+        for prefix in self.DOTENVX_ENCRYPTED_PREFIXES:
+            if value.startswith(prefix):
+                return "dotenvx"
+
+        # Check SOPS format
+        if self.SOPS_ENCRYPTED_PATTERN.match(value):
+            return "sops"
+
+        return None
+
+    def is_value_suspicious(self, value: str) -> bool:
+        """
+        Determine whether a plaintext value matches any configured secret patterns.
+
+        Returns:
+            `true` if the value appears to be a secret, `false` otherwise.
+        """
+        for pattern in self.SECRET_VALUE_PATTERNS:
+            if pattern.search(value):
+                return True
+        return False
+
+    def is_name_sensitive(self, name: str) -> bool:
+        """
+        Determine whether an environment variable name indicates sensitive data.
+
+        Parameters:
+            name (str): The environment variable name to test.
+
+        Returns:
+            True if the name matches any configured sensitive-name pattern, False otherwise.
+        """
+        for pattern in self.SENSITIVE_NAME_PATTERNS:
+            if pattern.match(name):
+                return True
+        return False
+
+    def get_recommendations(
+        self,
+        report: EncryptionReport,
+        backend: str | None = None,
+    ) -> list[str]:
+        """
+        Builds human-readable remediation recommendations derived from an EncryptionReport.
+
+        Parameters:
+            report (EncryptionReport): Analysis result for a single .env file used to derive recommendations.
+            backend (str | None): Encryption backend to recommend ("dotenvx", "sops", or None for auto-detect).
+
+        Returns:
+            list[str]: Ordered list of recommendation strings; empty if no actions are suggested.
+        """
+        recommendations = []
+
+        # Use detected backend if not specified
+        if backend is None:
+            backend = report.detected_backend or "dotenvx"
+
+        if report.plaintext_secrets:
+            recommendations.append(
+                f"Encrypt the following variables before committing: "
+                f"{', '.join(sorted(report.plaintext_secrets))}"
+            )
+
+            if backend == "sops":
+                recommendations.append(f"Run: envdrift encrypt --backend sops {report.path}")
+            else:
+                recommendations.append(f"Run: envdrift encrypt {report.path}")
+
+        if not report.is_fully_encrypted and report.encrypted_vars:
+            recommendations.append(
+                "File is partially encrypted. Consider encrypting all sensitive values."
+            )
+
+        return recommendations