envdrift 4.2.1__py3-none-any.whl

envdrift/encryption/base.py

@@ -0,0 +1,217 @@
+"""Abstract base class for encryption backends."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+
+class EncryptionBackendError(Exception):
+    """Base exception for encryption backend operations."""
+
+    pass
+
+
+class EncryptionNotFoundError(EncryptionBackendError):
+    """Encryption tool binary not found."""
+
+    pass
+
+
+class EncryptionStatus(Enum):
+    """Encryption status of an environment variable value."""
+
+    ENCRYPTED = "encrypted"
+    PLAINTEXT = "plaintext"
+    EMPTY = "empty"
+
+
+@dataclass
+class EncryptionResult:
+    """Result of an encryption/decryption operation."""
+
+    success: bool
+    message: str
+    file_path: Path | None = None
+
+
+class EncryptionBackend(ABC):
+    """Abstract interface for encryption backends.
+
+    Implementations must provide:
+    - encrypt: Encrypt a file
+    - decrypt: Decrypt a file
+    - is_installed: Check if the encryption tool is available
+    - detect_encryption_status: Detect if a value is encrypted by this backend
+    - has_encrypted_header: Check if file content has encryption markers
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """
+        Human-readable name of the encryption backend.
+
+        Returns:
+            str: Backend name (e.g., "dotenvx", "sops").
+        """
+        ...
+
+    @property
+    @abstractmethod
+    def encrypted_value_prefix(self) -> str | None:
+        """
+        Prefix used to identify encrypted values in .env files.
+
+        Returns:
+            str | None: The prefix (e.g., "encrypted:" for dotenvx, "ENC[" for SOPS),
+                        or None if the backend doesn't use value prefixes.
+        """
+        ...
+
+    @abstractmethod
+    def is_installed(self) -> bool:
+        """
+        Determine whether the encryption tool binary is available.
+
+        Returns:
+            bool: True if the tool is installed and available, False otherwise.
+        """
+        ...
+
+    @abstractmethod
+    def get_version(self) -> str | None:
+        """
+        Get the installed version of the encryption tool.
+
+        Returns:
+            str | None: Version string if available, None if not installed.
+        """
+        ...
+
+    @abstractmethod
+    def encrypt(
+        self,
+        env_file: Path | str,
+        keys_file: Path | str | None = None,
+        **kwargs,
+    ) -> EncryptionResult:
+        """
+        Encrypt a .env file.
+
+        Parameters:
+            env_file (Path | str): Path to the .env file to encrypt.
+            keys_file (Path | str | None): Optional path to keys file.
+            **kwargs: Backend-specific options.
+
+        Returns:
+            EncryptionResult: Result containing success status and message.
+
+        Raises:
+            EncryptionBackendError: If encryption fails.
+            EncryptionNotFoundError: If the encryption tool is not installed.
+        """
+        ...
+
+    @abstractmethod
+    def decrypt(
+        self,
+        env_file: Path | str,
+        keys_file: Path | str | None = None,
+        **kwargs,
+    ) -> EncryptionResult:
+        """
+        Decrypt a .env file.
+
+        Parameters:
+            env_file (Path | str): Path to the .env file to decrypt.
+            keys_file (Path | str | None): Optional path to keys file.
+            **kwargs: Backend-specific options.
+
+        Returns:
+            EncryptionResult: Result containing success status and message.
+
+        Raises:
+            EncryptionBackendError: If decryption fails.
+            EncryptionNotFoundError: If the encryption tool is not installed.
+        """
+        ...
+
+    @abstractmethod
+    def detect_encryption_status(self, value: str) -> EncryptionStatus:
+        """
+        Detect the encryption status of a single value.
+
+        Parameters:
+            value (str): The unquoted value string to classify.
+
+        Returns:
+            EncryptionStatus: EMPTY if value is empty, ENCRYPTED if it matches
+                              this backend's encrypted pattern, PLAINTEXT otherwise.
+        """
+        ...
+
+    @abstractmethod
+    def has_encrypted_header(self, content: str) -> bool:
+        """
+        Determine whether file content contains this backend's encryption markers.
+
+        Parameters:
+            content (str): Raw file content to inspect.
+
+        Returns:
+            bool: True if encryption markers are present, False otherwise.
+        """
+        ...
+
+    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:
+            bool: 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:
+        """
+        Check if a value is encrypted by this backend.
+
+        Parameters:
+            value (str): The value to check.
+
+        Returns:
+            bool: True if the value is encrypted, False otherwise.
+        """
+        return self.detect_encryption_status(value) == EncryptionStatus.ENCRYPTED
+
+    @abstractmethod
+    def install_instructions(self) -> str:
+        """
+        Provide installation instructions for the encryption tool.
+
+        Returns:
+            str: Human-readable installation instructions.
+        """
+        ...
+
+    def ensure_installed(self) -> None:
+        """
+        Ensure the encryption tool is installed, raising if not.
+
+        Raises:
+            EncryptionNotFoundError: If the tool is not installed.
+        """
+        if not self.is_installed():
+            raise EncryptionNotFoundError(
+                f"{self.name} is not installed.\n{self.install_instructions()}"
+            )

envdrift/encryption/dotenvx.py

@@ -0,0 +1,236 @@
+"""Dotenvx encryption backend implementation."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import ClassVar
+
+from envdrift.encryption.base import (
+    EncryptionBackend,
+    EncryptionBackendError,
+    EncryptionNotFoundError,
+    EncryptionResult,
+    EncryptionStatus,
+)
+
+
+class DotenvxEncryptionBackend(EncryptionBackend):
+    """Encryption backend using dotenvx CLI.
+
+    dotenvx is a tool for encrypting .env files with a public/private key pair.
+    It stores encrypted values with the prefix "encrypted:" and adds file headers.
+    """
+
+    # Patterns that indicate encrypted values (dotenvx format)
+    ENCRYPTED_PATTERN: ClassVar[re.Pattern[str]] = re.compile(r"^encrypted:")
+
+    # Header patterns that indicate the file has been encrypted by dotenvx
+    ENCRYPTED_FILE_MARKERS: ClassVar[list[str]] = [
+        "#/---BEGIN DOTENV ENCRYPTED---/",
+        "DOTENV_PUBLIC_KEY",
+    ]
+
+    def __init__(self, auto_install: bool = False):
+        """
+        Initialize the dotenvx encryption backend.
+
+        Parameters:
+            auto_install (bool): If True, attempt to auto-install dotenvx if not found.
+        """
+        self._auto_install = auto_install
+        self._wrapper = None
+
+    @property
+    def name(self) -> str:
+        """Return backend name."""
+        return "dotenvx"
+
+    @property
+    def encrypted_value_prefix(self) -> str:
+        """Return the prefix used to identify encrypted values."""
+        return "encrypted:"
+
+    def _get_wrapper(self):
+        """Lazily initialize the DotenvxWrapper."""
+        if self._wrapper is None:
+            from envdrift.integrations.dotenvx import DotenvxWrapper
+
+            self._wrapper = DotenvxWrapper(auto_install=self._auto_install)
+        return self._wrapper
+
+    def is_installed(self) -> bool:
+        """Check if dotenvx is installed."""
+        from envdrift.integrations.dotenvx import DotenvxError, DotenvxNotFoundError
+
+        try:
+            return self._get_wrapper().is_installed()
+        except (DotenvxNotFoundError, DotenvxError, OSError, RuntimeError):
+            return False
+
+    def get_version(self) -> str | None:
+        """Get the installed dotenvx version."""
+        from envdrift.integrations.dotenvx import DotenvxError, DotenvxNotFoundError
+
+        try:
+            if not self.is_installed():
+                return None
+            return self._get_wrapper().get_version()
+        except (DotenvxNotFoundError, DotenvxError, OSError, RuntimeError):
+            return None
+
+    def encrypt(
+        self,
+        env_file: Path | str,
+        keys_file: Path | str | None = None,
+        **kwargs,
+    ) -> EncryptionResult:
+        """
+        Encrypt a .env file using dotenvx.
+
+        Parameters:
+            env_file (Path | str): Path to the .env file to encrypt.
+            keys_file (Path | str | None): Optional path to .env.keys file.
+            **kwargs: Additional options:
+                - env (dict): Environment variables to pass to subprocess.
+                - cwd (Path | str): Working directory for subprocess.
+
+        Returns:
+            EncryptionResult: Result of the encryption operation.
+        """
+        env_file = Path(env_file)
+
+        if not env_file.exists():
+            return EncryptionResult(
+                success=False,
+                message=f"File not found: {env_file}",
+                file_path=env_file,
+            )
+
+        if not self.is_installed():
+            raise EncryptionNotFoundError(
+                f"dotenvx is not installed.\n{self.install_instructions()}"
+            )
+
+        try:
+            from envdrift.integrations.dotenvx import DotenvxError
+
+            wrapper = self._get_wrapper()
+            wrapper.encrypt(
+                env_file=env_file,
+                env_keys_file=keys_file,
+                env=kwargs.get("env"),
+                cwd=kwargs.get("cwd"),
+            )
+            return EncryptionResult(
+                success=True,
+                message=f"Encrypted {env_file}",
+                file_path=env_file,
+            )
+        except DotenvxError as e:
+            raise EncryptionBackendError(f"dotenvx encryption failed: {e}") from e
+
+    def decrypt(
+        self,
+        env_file: Path | str,
+        keys_file: Path | str | None = None,
+        **kwargs,
+    ) -> EncryptionResult:
+        """
+        Decrypt a .env file using dotenvx.
+
+        Parameters:
+            env_file (Path | str): Path to the .env file to decrypt.
+            keys_file (Path | str | None): Optional path to .env.keys file.
+            **kwargs: Additional options:
+                - env (dict): Environment variables to pass to subprocess.
+                - cwd (Path | str): Working directory for subprocess.
+
+        Returns:
+            EncryptionResult: Result of the decryption operation.
+        """
+        env_file = Path(env_file)
+
+        if not env_file.exists():
+            return EncryptionResult(
+                success=False,
+                message=f"File not found: {env_file}",
+                file_path=env_file,
+            )
+
+        if not self.is_installed():
+            raise EncryptionNotFoundError(
+                f"dotenvx is not installed.\n{self.install_instructions()}"
+            )
+
+        try:
+            from envdrift.integrations.dotenvx import DotenvxError
+
+            wrapper = self._get_wrapper()
+            wrapper.decrypt(
+                env_file=env_file,
+                env_keys_file=keys_file,
+                env=kwargs.get("env"),
+                cwd=kwargs.get("cwd"),
+            )
+            return EncryptionResult(
+                success=True,
+                message=f"Decrypted {env_file}",
+                file_path=env_file,
+            )
+        except DotenvxError as e:
+            raise EncryptionBackendError(f"dotenvx decryption failed: {e}") from e
+
+    def detect_encryption_status(self, value: str) -> EncryptionStatus:
+        """
+        Detect the encryption status of a value.
+
+        Parameters:
+            value (str): The unquoted value string to classify.
+
+        Returns:
+            EncryptionStatus: EMPTY if value is empty, ENCRYPTED if it starts
+                              with "encrypted:", PLAINTEXT otherwise.
+        """
+        if not value:
+            return EncryptionStatus.EMPTY
+
+        if self.ENCRYPTED_PATTERN.match(value):
+            return EncryptionStatus.ENCRYPTED
+
+        return EncryptionStatus.PLAINTEXT
+
+    def has_encrypted_header(self, content: str) -> bool:
+        """
+        Check if file content contains dotenvx encryption markers.
+
+        Parameters:
+            content (str): Raw file content to inspect.
+
+        Returns:
+            bool: True if dotenvx encryption markers are present.
+        """
+        for marker in self.ENCRYPTED_FILE_MARKERS:
+            if marker in content:
+                return True
+        return False
+
+    def install_instructions(self) -> str:
+        """Return installation instructions for dotenvx."""
+        from envdrift.integrations.dotenvx import DOTENVX_VERSION
+
+        return f"""
+dotenvx is not installed.
+
+Option 1 - Install to ~/.local/bin (recommended):
+  curl -sfS "https://dotenvx.sh?directory=$HOME/.local/bin" | sh -s -- --version={DOTENVX_VERSION}
+  (Make sure ~/.local/bin is in your PATH)
+
+Option 2 - Install to current directory:
+  curl -sfS "https://dotenvx.sh?directory=." | sh -s -- --version={DOTENVX_VERSION}
+
+Option 3 - System-wide install (requires sudo):
+  curl -sfS https://dotenvx.sh | sudo sh -s -- --version={DOTENVX_VERSION}
+
+After installing, run your envdrift command again.
+"""