envdrift 4.2.1__py3-none-any.whl

envdrift/vault/__init__.py

@@ -0,0 +1,107 @@
+"""Vault client interfaces for multiple backends."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from envdrift.vault.base import AuthenticationError, SecretValue, VaultClient, VaultError
+
+if TYPE_CHECKING:
+    pass
+
+
+class VaultProvider(Enum):
+    """Supported vault providers."""
+
+    AZURE = "azure"
+    AWS = "aws"
+    HASHICORP = "hashicorp"
+    GCP = "gcp"
+
+
+def get_vault_client(provider: VaultProvider | str, **config) -> VaultClient:
+    """
+    Create and return a provider-specific VaultClient configured from the provided keyword arguments.
+
+    Parameters:
+        provider (VaultProvider | str): Vault provider enum or provider name ("azure", "aws", "hashicorp", "gcp").
+        **config: Provider-specific configuration:
+            - For "azure": `vault_url` (str) — required.
+            - For "aws": `region` (str) — optional, defaults to "us-east-1".
+            - For "hashicorp": `url` (str) — required; `token` (str) — optional.
+            - For "gcp": `project_id` (str) — required.
+
+    Returns:
+        VaultClient: A configured client instance for the requested provider.
+
+    Raises:
+        ImportError: If the provider's optional dependencies are not installed.
+        ValueError: If the provider is unsupported or cannot be converted to a VaultProvider.
+    """
+    if isinstance(provider, str):
+        provider = VaultProvider(provider)
+
+    if provider == VaultProvider.AZURE:
+        try:
+            from envdrift.vault.azure import AzureKeyVaultClient
+        except ImportError as e:
+            raise ImportError(
+                "Azure vault support requires additional dependencies. "
+                "Install with: pip install envdrift[azure]"
+            ) from e
+        vault_url = config.get("vault_url")
+        if not vault_url:
+            raise ValueError("Azure vault requires 'vault_url' configuration")
+        return AzureKeyVaultClient(vault_url=vault_url)
+
+    elif provider == VaultProvider.AWS:
+        try:
+            from envdrift.vault.aws import AWSSecretsManagerClient
+        except ImportError as e:
+            raise ImportError(
+                "AWS vault support requires additional dependencies. "
+                "Install with: pip install envdrift[aws]"
+            ) from e
+        return AWSSecretsManagerClient(region=config.get("region", "us-east-1"))
+
+    elif provider == VaultProvider.HASHICORP:
+        try:
+            from envdrift.vault.hashicorp import HashiCorpVaultClient
+        except ImportError as e:
+            raise ImportError(
+                "HashiCorp Vault support requires additional dependencies. "
+                "Install with: pip install envdrift[hashicorp]"
+            ) from e
+        url = config.get("url")
+        if not url:
+            raise ValueError("HashiCorp Vault requires 'url' configuration")
+        return HashiCorpVaultClient(
+            url=url,
+            token=config.get("token"),
+        )
+
+    elif provider == VaultProvider.GCP:
+        try:
+            from envdrift.vault.gcp import GCPSecretManagerClient
+        except ImportError as e:
+            raise ImportError(
+                "GCP Secret Manager support requires additional dependencies. "
+                "Install with: pip install envdrift[gcp]"
+            ) from e
+        project_id = config.get("project_id")
+        if not project_id:
+            raise ValueError("GCP Secret Manager requires 'project_id' configuration")
+        return GCPSecretManagerClient(project_id=project_id)
+
+    raise ValueError(f"Unsupported vault provider: {provider}")
+
+
+__all__ = [
+    "AuthenticationError",
+    "SecretValue",
+    "VaultClient",
+    "VaultError",
+    "VaultProvider",
+    "get_vault_client",
+]

envdrift/vault/aws.py

@@ -0,0 +1,282 @@
+"""AWS Secrets Manager client implementation."""
+
+from __future__ import annotations
+
+import json
+
+from envdrift.vault.base import (
+    AuthenticationError,
+    SecretNotFoundError,
+    SecretValue,
+    VaultClient,
+    VaultError,
+)
+
+try:
+    import boto3
+    from botocore.exceptions import (
+        ClientError,
+        NoCredentialsError,
+        PartialCredentialsError,
+    )
+
+    AWS_AVAILABLE = True
+except ImportError:
+    AWS_AVAILABLE = False
+    boto3 = None
+    ClientError = Exception
+    NoCredentialsError = Exception
+    PartialCredentialsError = Exception
+
+
+class AWSSecretsManagerClient(VaultClient):
+    """AWS Secrets Manager implementation.
+
+    Uses boto3's default credential chain which supports:
+    - Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
+    - Shared credential file (~/.aws/credentials)
+    - AWS config file (~/.aws/config)
+    - IAM role credentials (EC2, ECS, Lambda)
+    """
+
+    def __init__(self, region: str = "us-east-1"):
+        """Initialize AWS Secrets Manager client.
+
+        Args:
+            region: AWS region name
+        """
+        if not AWS_AVAILABLE:
+            raise ImportError("boto3 not installed. Install with: pip install envdrift[aws]")
+
+        self.region = region
+        self._client = None
+
+    def authenticate(self) -> None:
+        """
+        Initialize the AWS Secrets Manager client for the configured region and verify access.
+
+        Raises:
+            AuthenticationError: if AWS credentials are missing or incomplete.
+            VaultError: if the Secrets Manager service returns an error.
+        """
+        try:
+            self._client = boto3.client(
+                "secretsmanager",
+                region_name=self.region,
+            )
+            # Test authentication using get_caller_identity via STS
+            # This is more reliable than list_secrets which requires extra permissions
+            sts = boto3.client("sts", region_name=self.region)
+            sts.get_caller_identity()
+        except (NoCredentialsError, PartialCredentialsError) as e:
+            raise AuthenticationError(f"AWS authentication failed: {e}") from e
+        except ClientError as e:
+            error_code = e.response.get("Error", {}).get("Code", "")
+            if error_code in ("AccessDenied", "InvalidClientTokenId"):
+                raise AuthenticationError(f"AWS authentication failed: {e}") from e
+            raise VaultError(f"AWS Secrets Manager error: {e}") from e
+
+    def is_authenticated(self) -> bool:
+        """
+        Return whether the AWS Secrets Manager client has been authenticated.
+
+        This method validates credentials by calling STS get_caller_identity(),
+        which ensures that expired or revoked credentials are detected.
+
+        Returns:
+            `true` if the client is authenticated and credentials are valid, `false` otherwise.
+        """
+        if self._client is None:
+            return False
+
+        # Validate credentials are still valid by calling STS
+        try:
+            sts = boto3.client("sts", region_name=self.region)
+            sts.get_caller_identity()
+            return True
+        except (NoCredentialsError, PartialCredentialsError, ClientError):
+            # Credentials are invalid/expired, reset client state
+            self._client = None
+            return False
+
+    def get_secret(self, name: str) -> SecretValue:
+        """
+        Retrieve a secret from AWS Secrets Manager.
+
+        Parameters:
+            name (str): Secret name or ARN.
+
+        Returns:
+            SecretValue: Contains the secret's name, value, version, and metadata (`arn`, `created_date`, `version_stages`).
+
+        Raises:
+            SecretNotFoundError: If the secret does not exist.
+            VaultError: For other AWS Secrets Manager errors.
+        """
+        self.ensure_authenticated()
+
+        try:
+            response = self._client.get_secret_value(SecretId=name)
+
+            # Secret can be string or binary
+            if "SecretString" in response:
+                value = response["SecretString"]
+            else:
+                # Binary secrets - try UTF-8, fall back to base64
+                try:
+                    value = response["SecretBinary"].decode("utf-8")
+                except UnicodeDecodeError:
+                    import base64
+
+                    value = base64.b64encode(response["SecretBinary"]).decode("ascii")
+
+            created = response.get("CreatedDate")
+            created_str = str(created) if created else None
+            return SecretValue(
+                name=response.get("Name", name),
+                value=value,
+                version=response.get("VersionId"),
+                metadata={
+                    "arn": response.get("ARN"),
+                    "created_date": created_str,
+                    "version_stages": response.get("VersionStages", []),
+                },
+            )
+        except ClientError as e:
+            error_code = e.response.get("Error", {}).get("Code", "")
+            if error_code == "ResourceNotFoundException":
+                raise SecretNotFoundError(f"Secret '{name}' not found") from e
+            raise VaultError(f"AWS Secrets Manager error: {e}") from e
+
+    def list_secrets(self, prefix: str = "") -> list[str]:
+        """
+        List secret names stored in AWS Secrets Manager.
+
+        Parameters:
+            prefix (str): Optional name prefix to filter results; only secrets whose names start with this prefix are returned.
+
+        Returns:
+            List of secret names.
+        """
+        self.ensure_authenticated()
+
+        try:
+            secrets = []
+            paginator = self._client.get_paginator("list_secrets")
+
+            # Note: AWS ListSecrets filter with Key="name" performs exact match,
+            # so we fetch all secrets and filter client-side for prefix matching
+            for page in paginator.paginate():
+                for secret in page.get("SecretList", []):
+                    name = secret.get("Name")
+                    if name:
+                        # Apply client-side prefix filtering
+                        if not prefix or name.startswith(prefix):
+                            secrets.append(name)
+
+            return sorted(secrets)
+        except ClientError as e:
+            raise VaultError(f"AWS Secrets Manager error: {e}") from e
+
+    def get_secret_json(self, name: str) -> dict:
+        """
+        Retrieve the secret identified by `name` and parse its value as a JSON object.
+
+        Returns:
+            dict: Parsed JSON from the secret value.
+
+        Raises:
+            VaultError: If the secret value is not valid JSON.
+        """
+        secret = self.get_secret(name)
+        try:
+            return json.loads(secret.value)
+        except json.JSONDecodeError as e:
+            raise VaultError(f"Secret '{name}' is not valid JSON: {e}") from e
+
+    def create_secret(self, name: str, value: str, description: str = "") -> SecretValue:
+        """
+        Create a new secret in AWS Secrets Manager.
+
+        Parameters:
+            name (str): The name to assign to the secret.
+            value (str): The secret value to store.
+            description (str): Optional human-readable description for the secret.
+
+        Returns:
+            SecretValue: The created secret's representation, including the stored value, version identifier, and metadata (ARN).
+
+        Raises:
+            VaultError: If AWS Secrets Manager returns an error while creating the secret.
+        """
+        self.ensure_authenticated()
+
+        try:
+            response = self._client.create_secret(
+                Name=name,
+                SecretString=value,
+                Description=description,
+            )
+            return SecretValue(
+                name=response.get("Name", name),
+                value=value,
+                version=response.get("VersionId"),
+                metadata={"arn": response.get("ARN")},
+            )
+        except ClientError as e:
+            raise VaultError(f"AWS Secrets Manager error: {e}") from e
+
+    def update_secret(self, name: str, value: str) -> SecretValue:
+        """
+        Update an existing secret in AWS Secrets Manager.
+
+        Returns:
+            SecretValue: Contains the updated secret's name, value, version, and ARN metadata.
+
+        Raises:
+            VaultError: If AWS Secrets Manager returns an error.
+        """
+        self.ensure_authenticated()
+
+        try:
+            response = self._client.put_secret_value(
+                SecretId=name,
+                SecretString=value,
+            )
+            return SecretValue(
+                name=response.get("Name", name),
+                value=value,
+                version=response.get("VersionId"),
+                metadata={"arn": response.get("ARN")},
+            )
+        except ClientError as e:
+            raise VaultError(f"AWS Secrets Manager error: {e}") from e
+
+    def set_secret(self, name: str, value: str) -> SecretValue:
+        """
+        Create or update a secret in AWS Secrets Manager.
+
+        Attempts to update the secret first; if it doesn't exist, creates it.
+
+        Parameters:
+            name (str): The name of the secret.
+            value (str): The secret value to store.
+
+        Returns:
+            SecretValue: The created or updated secret's representation.
+
+        Raises:
+            VaultError: If AWS Secrets Manager returns an error.
+        """
+        self.ensure_authenticated()
+
+        try:
+            # Try to update first (most common case)
+            return self.update_secret(name, value)
+        except VaultError as e:
+            # Extract original ClientError if available
+            if e.__cause__ and hasattr(e.__cause__, "response"):
+                error_code = e.__cause__.response.get("Error", {}).get("Code", "")
+                if error_code == "ResourceNotFoundException":
+                    return self.create_secret(name, value)
+            raise

envdrift/vault/azure.py

@@ -0,0 +1,170 @@
+"""Azure Key Vault client implementation."""
+
+from __future__ import annotations
+
+from envdrift.vault.base import (
+    AuthenticationError,
+    SecretNotFoundError,
+    SecretValue,
+    VaultClient,
+    VaultError,
+)
+
+try:
+    from azure.core.exceptions import (
+        ClientAuthenticationError,
+        HttpResponseError,
+        ResourceNotFoundError,
+    )
+    from azure.identity import DefaultAzureCredential
+    from azure.keyvault.secrets import SecretClient
+
+    AZURE_AVAILABLE = True
+except ImportError:
+    AZURE_AVAILABLE = False
+    DefaultAzureCredential = None
+    SecretClient = None
+    ResourceNotFoundError = Exception
+    ClientAuthenticationError = Exception
+    HttpResponseError = Exception
+
+
+class AzureKeyVaultClient(VaultClient):
+    """Azure Key Vault implementation.
+
+    Uses DefaultAzureCredential which supports:
+    - Environment variables (AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID)
+    - Managed Identity
+    - Azure CLI credentials
+    - VS Code credentials
+    - Interactive browser login
+    """
+
+    def __init__(self, vault_url: str):
+        """
+        Create an Azure Key Vault client bound to the provided vault URL.
+
+        Parameters:
+            vault_url (str): Vault URL (e.g., "https://my-vault.vault.azure.net/").
+
+        Raises:
+            ImportError: If the Azure SDK is not installed (install with `pip install envdrift[azure]`).
+        """
+        if not AZURE_AVAILABLE:
+            raise ImportError("Azure SDK not installed. Install with: pip install envdrift[azure]")
+
+        self.vault_url = vault_url
+        self._client: SecretClient | None = None
+        self._credential = None
+
+    def authenticate(self) -> None:
+        """
+        Authenticate to Azure Key Vault using DefaultAzureCredential and initialize the SecretClient.
+
+        On success sets self._credential to the created credential and self._client to a ready SecretClient.
+        Raises AuthenticationError if credential acquisition fails and VaultError for HTTP-related Key Vault errors.
+        """
+        try:
+            self._credential = DefaultAzureCredential()
+            self._client = SecretClient(
+                vault_url=self.vault_url,
+                credential=self._credential,
+            )
+            # Test authentication by actually consuming one item from the iterator
+            # The iterator is lazy and won't authenticate until iterated
+            secrets_iter = self._client.list_properties_of_secrets()
+            next(iter(secrets_iter), None)  # Consume one item to verify auth
+        except ClientAuthenticationError as e:
+            raise AuthenticationError(f"Azure authentication failed: {e}") from e
+        except HttpResponseError as e:
+            raise VaultError(f"Azure Key Vault error: {e}") from e
+
+    def is_authenticated(self) -> bool:
+        """
+        Return whether the client has an initialized SecretClient and is ready for operations.
+
+        Returns:
+            `true` if the internal client is initialized, `false` otherwise.
+        """
+        return self._client is not None
+
+    def get_secret(self, name: str) -> SecretValue:
+        """
+        Retrieve a secret from the configured Azure Key Vault.
+
+        Parameters:
+            name (str): The name of the secret to retrieve.
+
+        Returns:
+            SecretValue: Contains the secret's name, value, version, and metadata (keys: "enabled", "created_on", "updated_on", "content_type").
+
+        Raises:
+            SecretNotFoundError: If no secret with the given name exists in the vault.
+            VaultError: For other Azure Key Vault HTTP errors.
+        """
+        self.ensure_authenticated()
+
+        try:
+            secret = self._client.get_secret(name)
+            props = secret.properties
+            created = str(props.created_on) if props.created_on else None
+            updated = str(props.updated_on) if props.updated_on else None
+            return SecretValue(
+                name=name,
+                value=secret.value or "",
+                version=props.version,
+                metadata={
+                    "enabled": props.enabled,
+                    "created_on": created,
+                    "updated_on": updated,
+                    "content_type": props.content_type,
+                },
+            )
+        except ResourceNotFoundError as e:
+            raise SecretNotFoundError(f"Secret '{name}' not found in vault") from e
+        except HttpResponseError as e:
+            raise VaultError(f"Azure Key Vault error: {e}") from e
+
+    def list_secrets(self, prefix: str = "") -> list[str]:
+        """
+        List secret names in the vault, optionally filtered by a prefix.
+
+        Parameters:
+            prefix (str): Optional string; include only secret names that start with this prefix.
+
+        Returns:
+            list[str]: Sorted list of secret names that match the prefix.
+        """
+        self.ensure_authenticated()
+
+        try:
+            secrets = []
+            for secret_properties in self._client.list_properties_of_secrets():
+                name = secret_properties.name
+                if name and (not prefix or name.startswith(prefix)):
+                    secrets.append(name)
+            return sorted(secrets)
+        except HttpResponseError as e:
+            raise VaultError(f"Azure Key Vault error: {e}") from e
+
+    def set_secret(self, name: str, value: str) -> SecretValue:
+        """
+        Store or update a secret in Azure Key Vault.
+
+        Returns:
+            SecretValue containing the stored secret's name, value, version, and metadata (includes `enabled`).
+        """
+        self.ensure_authenticated()
+
+        try:
+            secret = self._client.set_secret(name, value)
+            return SecretValue(
+                name=name,
+                value=secret.value or "",
+                version=secret.properties.version,
+                metadata={
+                    "enabled": secret.properties.enabled,
+                },
+            )
+        except HttpResponseError as e:
+            raise VaultError(f"Azure Key Vault error: {e}") from e