envdrift 4.2.1__py3-none-any.whl

envdrift/core/parser.py

@@ -0,0 +1,260 @@
+"""ENV file parser with multi-backend encryption detection.
+
+Supports:
+- dotenvx: Values starting with "encrypted:"
+- SOPS: Values starting with "ENC[AES256_GCM,"
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+
+
+class EncryptionStatus(Enum):
+    """Encryption status of an environment variable."""
+
+    ENCRYPTED = "encrypted"  # Encrypted value (dotenvx or SOPS)
+    PLAINTEXT = "plaintext"  # Unencrypted value
+    EMPTY = "empty"  # No value (KEY= or KEY="")
+
+
+@dataclass
+class EnvVar:
+    """Parsed environment variable."""
+
+    name: str
+    value: str
+    line_number: int
+    encryption_status: EncryptionStatus
+    raw_line: str
+    encryption_backend: str | None = None  # "dotenvx", "sops", or None
+
+    @property
+    def is_encrypted(self) -> bool:
+        """
+        Determine whether this environment variable's value is encrypted.
+
+        Returns:
+            True if the variable is encrypted, False otherwise.
+        """
+        return self.encryption_status == EncryptionStatus.ENCRYPTED
+
+    @property
+    def is_empty(self) -> bool:
+        """
+        Indicates whether the variable's value is empty.
+
+        Returns:
+            True if the variable's value is empty, False otherwise.
+        """
+        return self.encryption_status == EncryptionStatus.EMPTY
+
+
+@dataclass
+class EnvFile:
+    """Parsed .env file."""
+
+    path: Path
+    variables: dict[str, EnvVar] = field(default_factory=dict)
+    comments: list[str] = field(default_factory=list)
+
+    @property
+    def is_encrypted(self) -> bool:
+        """
+        Determine whether the file contains at least one encrypted environment variable.
+
+        Returns:
+            `true` if at least one variable in the file is encrypted, `false` otherwise.
+        """
+        return any(var.is_encrypted for var in self.variables.values())
+
+    @property
+    def is_fully_encrypted(self) -> bool:
+        """
+        Determine whether every non-empty environment variable in the file is encrypted.
+
+        Returns:
+            `true` if all non-empty variables have encryption status `ENCRYPTED`, `false` otherwise (also `false` when there are no non-empty variables).
+        """
+        non_empty_vars = [v for v in self.variables.values() if not v.is_empty]
+        if not non_empty_vars:
+            return False
+        return all(var.is_encrypted for var in non_empty_vars)
+
+    def get(self, name: str) -> EnvVar | None:
+        """
+        Retrieve the environment variable with the specified name from this EnvFile.
+
+        Parameters:
+            name (str): The variable name to look up.
+
+        Returns:
+            EnvVar | None: The matching EnvVar if found, `None` otherwise.
+        """
+        return self.variables.get(name)
+
+    def __contains__(self, name: str) -> bool:
+        """
+        Determine whether the EnvFile contains a variable with the given name.
+
+        Returns:
+            True if a variable with the given name exists in the file, False otherwise.
+        """
+        return name in self.variables
+
+    def __len__(self) -> int:
+        """
+        Number of environment variables contained in the EnvFile.
+
+        Returns:
+            int: The count of parsed variables.
+        """
+        return len(self.variables)
+
+
+class EnvParser:
+    """Parse .env files with multi-backend encryption awareness.
+
+    Handles:
+    - Standard KEY=value
+    - Quoted values: KEY="value" or KEY='value'
+    - dotenvx encrypted: KEY="encrypted:xxxx"
+    - SOPS encrypted: KEY="ENC[AES256_GCM,data:...,iv:...,tag:...,type:str]"
+    - Comments and blank lines (skipped)
+
+    Note:
+        Multiline values are not currently supported. Each line is parsed
+        independently. For multiline secrets (e.g., PEM keys), consider
+        base64 encoding or using a single-line escaped format.
+    """
+
+    # dotenvx encrypted value pattern
+    DOTENVX_ENCRYPTED_PATTERN = re.compile(r"^encrypted:")
+
+    # SOPS encrypted value pattern
+    SOPS_ENCRYPTED_PATTERN = re.compile(r"^ENC\[AES256_GCM,")
+
+    # Combined pattern for backward compatibility
+    ENCRYPTED_PATTERN = re.compile(r"^(encrypted:|ENC\[AES256_GCM,)")
+
+    # Pattern to match KEY=value lines
+    LINE_PATTERN = re.compile(r"^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$")
+
+    def parse(self, path: Path | str) -> EnvFile:
+        """
+        Parse a .env file and produce an EnvFile representing its parsed contents.
+
+        Parameters:
+            path (Path | str): Filesystem path to the .env file.
+
+        Returns:
+            EnvFile: Parsed file containing variables and comments.
+
+        Raises:
+            FileNotFoundError: If the file does not exist.
+        """
+        path = Path(path)
+
+        if not path.exists():
+            raise FileNotFoundError(f"ENV file not found: {path}")
+
+        content = path.read_text(encoding="utf-8")
+        env_file = self.parse_string(content)
+        env_file.path = path
+
+        return env_file
+
+    def parse_string(self, content: str) -> EnvFile:
+        """
+        Parse .env formatted text, extracting variables (with detected encryption status) and comments.
+
+        Parameters:
+            content (str): The complete text content of a .env file to parse.
+
+        Returns:
+            EnvFile: An EnvFile populated with parsed EnvVar entries keyed by variable name and a list of comment lines.
+        """
+        env_file = EnvFile(path=Path())
+        lines = content.splitlines()
+
+        for line_num, line in enumerate(lines, start=1):
+            original_line = line
+            line = line.strip()
+
+            # Skip empty lines
+            if not line:
+                continue
+
+            # Collect comments
+            if line.startswith("#"):
+                env_file.comments.append(line)
+                continue
+
+            # Parse KEY=value
+            match = self.LINE_PATTERN.match(line)
+            if not match:
+                continue
+
+            key = match.group(1)
+            value = match.group(2).strip()
+
+            # Remove surrounding quotes
+            value = self._unquote(value)
+
+            # Determine encryption status and backend
+            encryption_status, encryption_backend = self._detect_encryption_status(value)
+
+            env_var = EnvVar(
+                name=key,
+                value=value,
+                line_number=line_num,
+                encryption_status=encryption_status,
+                raw_line=original_line,
+                encryption_backend=encryption_backend,
+            )
+
+            env_file.variables[key] = env_var
+
+        return env_file
+
+    def _unquote(self, value: str) -> str:
+        """
+        Remove a single matching pair of surrounding single or double quotes from the value.
+
+        Returns:
+                the unquoted string if the value is enclosed in matching single quotes ('...') or double quotes ("..."); otherwise the original value
+        """
+        if len(value) >= 2:
+            if (value.startswith('"') and value.endswith('"')) or (
+                value.startswith("'") and value.endswith("'")
+            ):
+                return value[1:-1]
+        return value
+
+    def _detect_encryption_status(self, value: str) -> tuple[EncryptionStatus, str | None]:
+        """
+        Detects the encryption status and backend of an environment variable value.
+
+        Parameters:
+            value (str): The unquoted value string to classify.
+
+        Returns:
+            tuple[EncryptionStatus, str | None]: A tuple of (status, backend) where:
+                - status is EncryptionStatus.EMPTY, ENCRYPTED, or PLAINTEXT
+                - backend is "dotenvx", "sops", or None
+        """
+        if not value:
+            return EncryptionStatus.EMPTY, None
+
+        # Check for dotenvx encrypted format
+        if self.DOTENVX_ENCRYPTED_PATTERN.match(value):
+            return EncryptionStatus.ENCRYPTED, "dotenvx"
+
+        # Check for SOPS encrypted format
+        if self.SOPS_ENCRYPTED_PATTERN.match(value):
+            return EncryptionStatus.ENCRYPTED, "sops"
+
+        return EncryptionStatus.PLAINTEXT, None

envdrift/core/partial_encryption.py

@@ -0,0 +1,239 @@
+"""Partial encryption functionality for envdrift.
+
+This module implements a simple build pattern for partial encryption:
+- Source files: .env.{env}.clear + .env.{env}.secret
+- Generated file: .env.{env} (combined with warning header)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from envdrift.config import PartialEncryptionEnvironmentConfig
+from envdrift.integrations.dotenvx import DotenvxError, DotenvxWrapper
+
+WARNING_HEADER = """#/---------------------------------------------------/
+#/ WARNING: AUTO-GENERATED FILE                      /
+#/ DO NOT EDIT THIS FILE DIRECTLY                    /
+#/                                                    /
+#/ This file is generated by: envdrift push          /
+#/                                                    /
+#/ To make changes:                                  /
+#/   1. Edit: {clear_file:<36}/
+#/   2. Edit: {secret_file:<36}/
+#/   3. Run:  envdrift pull-partial (to decrypt)     /
+#/   4. Run:  envdrift push (to regenerate this)     /
+#/---------------------------------------------------/
+"""
+
+
+class PartialEncryptionError(Exception):
+    """Partial encryption operation failed."""
+
+    @classmethod
+    def encrypt_failed(cls, path: Path, cause: Exception) -> PartialEncryptionError:
+        """Create error for encryption failure."""
+        return cls(f"Failed to encrypt {path}: {cause}")
+
+    @classmethod
+    def decrypt_failed(cls, path: Path, cause: Exception) -> PartialEncryptionError:
+        """Create error for decryption failure."""
+        return cls(f"Failed to decrypt {path}: {cause}")
+
+    @classmethod
+    def file_not_found(cls, path: Path) -> PartialEncryptionError:
+        """Create error for missing file."""
+        return cls(f"Secret file not found: {path}")
+
+
+def is_file_encrypted(file_path: Path) -> bool:
+    """
+    Check if a file contains dotenvx encrypted content.
+
+    Args:
+        file_path: Path to check
+
+    Returns:
+        True if file contains encrypted: prefix or DOTENV_VAULT markers
+    """
+    if not file_path.exists():
+        return False
+
+    content = file_path.read_text()
+    return "encrypted:" in content or "DOTENV_VAULT" in content
+
+
+def combine_files(env_config: PartialEncryptionEnvironmentConfig) -> dict[str, int]:
+    """
+    Combine clear and encrypted secret files into a single combined file.
+
+    Process:
+        1. Read .env.{env}.clear (cleartext vars)
+        2. Read .env.{env}.secret (encrypted vars)
+        3. Combine with warning header → .env.{env}
+
+    Args:
+        env_config: Environment configuration
+
+    Returns:
+        Dict with counts: {"clear_lines": X, "secret_vars": Y}
+
+    Raises:
+        PartialEncryptionError: If operation fails
+    """
+    clear_file = Path(env_config.clear_file)
+    secret_file = Path(env_config.secret_file)
+    combined_file = Path(env_config.combined_file)
+
+    # Read files
+    clear_lines = []
+    if clear_file.exists():
+        clear_lines = clear_file.read_text().splitlines()
+
+    secret_lines = []
+    if secret_file.exists():
+        secret_lines = secret_file.read_text().splitlines()
+
+    # Build combined content with warning header
+    warning = WARNING_HEADER.format(
+        clear_file=env_config.clear_file,
+        secret_file=env_config.secret_file,
+    )
+
+    combined_lines = warning.splitlines()
+    combined_lines.append("")
+
+    # Add clear section
+    if clear_lines:
+        combined_lines.append(f"# From {env_config.clear_file}")
+        combined_lines.extend(clear_lines)
+        combined_lines.append("")
+
+    # Add encrypted secret section
+    if secret_lines:
+        # Skip dotenvx header comments from secret file to avoid clutter
+        secret_content = [line for line in secret_lines if not line.strip().startswith("#/---")]
+        combined_lines.append(f"# From {env_config.secret_file} (encrypted)")
+        combined_lines.extend(secret_content)
+
+    # Write combined file
+    combined_file.write_text("\n".join(combined_lines) + "\n")
+
+    # Count variables in secret file
+    secret_var_count = sum(
+        1 for line in secret_lines if "=" in line and not line.strip().startswith("#")
+    )
+
+    return {
+        "clear_lines": len(clear_lines),
+        "secret_vars": secret_var_count,
+    }
+
+
+def encrypt_secret_file(env_config: PartialEncryptionEnvironmentConfig) -> None:
+    """
+    Encrypt the secret file in-place using dotenvx.
+
+    Args:
+        env_config: Environment configuration
+
+    Raises:
+        PartialEncryptionError: If encryption fails
+    """
+    secret_file = Path(env_config.secret_file)
+
+    if not secret_file.exists():
+        return
+
+    # Check if already encrypted
+    if is_file_encrypted(secret_file):
+        return
+
+    # Encrypt using dotenvx
+    dotenvx = DotenvxWrapper()
+    try:
+        dotenvx.encrypt(secret_file)
+    except DotenvxError as e:
+        raise PartialEncryptionError.encrypt_failed(secret_file, e) from e
+
+
+def decrypt_secret_file(env_config: PartialEncryptionEnvironmentConfig) -> None:
+    """
+    Decrypt the secret file in-place using dotenvx.
+
+    Args:
+        env_config: Environment configuration
+
+    Raises:
+        PartialEncryptionError: If decryption fails
+    """
+    secret_file = Path(env_config.secret_file)
+
+    if not secret_file.exists():
+        raise PartialEncryptionError.file_not_found(secret_file)
+
+    # Check if already decrypted
+    if not is_file_encrypted(secret_file):
+        return  # Already decrypted
+
+    # Decrypt using dotenvx
+    dotenvx = DotenvxWrapper()
+    try:
+        dotenvx.decrypt(secret_file)
+    except DotenvxError as e:
+        raise PartialEncryptionError.decrypt_failed(secret_file, e) from e
+
+
+def push_partial_encryption(env_config: PartialEncryptionEnvironmentConfig) -> dict[str, int]:
+    """
+    Push operation: Encrypt secret file + combine with clear file.
+
+    Steps:
+    1. Encrypt .env.{env}.secret using dotenvx (in-place)
+    2. Combine .env.{env}.clear + encrypted .secret → .env.{env}
+
+    Args:
+        env_config: Environment configuration
+
+    Returns:
+        Dict with stats: {"clear_lines": X, "secret_vars": Y}
+
+    Raises:
+        PartialEncryptionError: If push operation fails
+    """
+    # Step 1: Encrypt secret file
+    encrypt_secret_file(env_config)
+
+    # Step 2: Combine files
+    stats = combine_files(env_config)
+
+    return stats
+
+
+def pull_partial_encryption(env_config: PartialEncryptionEnvironmentConfig) -> bool:
+    """
+    Pull operation: Decrypt secret file for editing.
+
+    Steps:
+    1. Decrypt .env.{env}.secret in-place
+
+    Args:
+        env_config: Environment configuration
+
+    Returns:
+        True if file was decrypted, False if already decrypted
+
+    Raises:
+        PartialEncryptionError: If pull operation fails
+    """
+    secret_file = Path(env_config.secret_file)
+
+    if not secret_file.exists():
+        raise PartialEncryptionError.file_not_found(secret_file)
+
+    was_encrypted = is_file_encrypted(secret_file)
+
+    # Decrypt secret file
+    decrypt_secret_file(env_config)
+
+    return was_encrypted