envdrift 4.2.1__py3-none-any.whl

envdrift/vault/base.py

@@ -0,0 +1,150 @@
+"""Abstract base class for vault clients."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+
+class VaultError(Exception):
+    """Base exception for vault operations."""
+
+    pass
+
+
+class AuthenticationError(VaultError):
+    """Authentication to vault failed."""
+
+    pass
+
+
+class SecretNotFoundError(VaultError):
+    """Secret not found in vault."""
+
+    pass
+
+
+@dataclass
+class SecretValue:
+    """Value retrieved from vault."""
+
+    name: str
+    value: str
+    version: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def __str__(self) -> str:
+        """
+        Produce a string representation of the SecretValue with the secret value masked.
+
+        Returns:
+            str: A string in the form "SecretValue(name=<name>, value=****)" where the actual secret value is redacted.
+        """
+        return f"SecretValue(name={self.name}, value=****)"
+
+
+class VaultClient(ABC):
+    """Abstract interface for vault backends.
+
+    Implementations must provide:
+    - get_secret: Retrieve a secret by name
+    - list_secrets: List available secret names
+    - is_authenticated: Check authentication status
+    - authenticate: Perform authentication
+    """
+
+    @abstractmethod
+    def get_secret(self, name: str) -> SecretValue:
+        """
+        Retrieve the secret identified by `name` from the vault.
+
+        Parameters:
+            name (str): Secret name or path within the vault.
+
+        Returns:
+            SecretValue: The secret object containing the secret's value and metadata.
+
+        Raises:
+            SecretNotFoundError: If the secret does not exist.
+            AuthenticationError: If the client is not authenticated.
+            VaultError: For other vault-related errors.
+        """
+        ...
+
+    @abstractmethod
+    def list_secrets(self, prefix: str = "") -> list[str]:
+        """
+        List secret names available in the vault, optionally filtered by a prefix.
+
+        Parameters:
+            prefix (str): Optional prefix to filter returned secret names.
+
+        Returns:
+            list[str]: Secret names that match the prefix (or all secret names if prefix is empty).
+
+        Raises:
+            AuthenticationError: If the client is not authenticated.
+            VaultError: For other vault-related errors.
+        """
+        ...
+
+    @abstractmethod
+    def is_authenticated(self) -> bool:
+        """
+        Determine whether the client is currently authenticated.
+
+        Returns:
+            True if the client is authenticated, False otherwise.
+        """
+        ...
+
+    @abstractmethod
+    def authenticate(self) -> None:
+        """
+        Authenticate the client with the vault.
+
+        Raises:
+            AuthenticationError: If authentication fails.
+        """
+        ...
+
+    @abstractmethod
+    def set_secret(self, name: str, value: str) -> SecretValue:
+        """
+        Create or update a secret in the vault.
+
+        Parameters:
+            name (str): Secret name or path within the vault.
+            value (str): The secret value to store.
+
+        Returns:
+            SecretValue: The stored secret object containing name, value, version, and metadata.
+
+        Raises:
+            AuthenticationError: If the client is not authenticated or lacks write permissions.
+            VaultError: For other vault-related errors.
+        """
+        ...
+
+    def get_secret_value(self, name: str) -> str:
+        """
+        Retrieve the value string of a secret identified by name.
+
+        Parameters:
+                name (str): The secret's name or path.
+
+        Returns:
+                The secret's value string.
+        """
+        return self.get_secret(name).value
+
+    def ensure_authenticated(self) -> None:
+        """
+        Authenticate the client if it is not already authenticated.
+
+        Raises:
+            AuthenticationError: If authentication fails.
+        """
+        if not self.is_authenticated():
+            self.authenticate()

envdrift/vault/gcp.py

@@ -0,0 +1,210 @@
+"""GCP Secret Manager client implementation."""
+
+from __future__ import annotations
+
+import contextlib
+
+from envdrift.vault.base import (
+    AuthenticationError,
+    SecretNotFoundError,
+    SecretValue,
+    VaultClient,
+    VaultError,
+)
+
+try:
+    from google.api_core import exceptions as google_exceptions
+    from google.auth.exceptions import DefaultCredentialsError
+    from google.cloud import secretmanager
+
+    GCP_AVAILABLE = True
+except ImportError:
+    GCP_AVAILABLE = False
+    secretmanager = None
+    google_exceptions = None
+    DefaultCredentialsError = Exception
+
+
+class GCPSecretManagerClient(VaultClient):
+    """GCP Secret Manager implementation.
+
+    Uses Application Default Credentials which support:
+    - GOOGLE_APPLICATION_CREDENTIALS env var
+    - gcloud auth application-default login
+    - Workload Identity / service account bindings
+    """
+
+    def __init__(self, project_id: str):
+        """
+        Create a GCP Secret Manager client bound to the provided project ID.
+
+        Parameters:
+            project_id (str): GCP project ID (e.g., "my-gcp-project").
+
+        Raises:
+            ImportError: If the GCP SDK is not installed (install with `pip install envdrift[gcp]`).
+        """
+        if not GCP_AVAILABLE:
+            raise ImportError(
+                "GCP Secret Manager support requires additional dependencies. "
+                "Install with: pip install envdrift[gcp]"
+            )
+
+        self.project_id = project_id
+        self._client: secretmanager.SecretManagerServiceClient | None = None
+
+    def _project_path(self) -> str:
+        return f"projects/{self.project_id}"
+
+    def _secret_id(self, name: str) -> str:
+        if name.startswith("projects/"):
+            parts = name.split("/")
+            if "secrets" in parts:
+                idx = parts.index("secrets")
+                if idx + 1 < len(parts):
+                    return parts[idx + 1]
+        return name
+
+    def _secret_path(self, name: str) -> str:
+        return f"{self._project_path()}/secrets/{self._secret_id(name)}"
+
+    def _version_path(self, name: str, version: str = "latest") -> str:
+        if name.startswith("projects/") and "/versions/" in name:
+            return name
+        if name.startswith("projects/") and "/secrets/" in name:
+            return f"{name}/versions/{version}"
+        return f"{self._secret_path(name)}/versions/{version}"
+
+    def authenticate(self) -> None:
+        """
+        Authenticate to GCP Secret Manager and initialize the client.
+
+        Raises AuthenticationError for credential issues and VaultError for API failures.
+        """
+        try:
+            self._client = secretmanager.SecretManagerServiceClient()
+            secrets_iter = self._client.list_secrets(
+                request={"parent": self._project_path(), "page_size": 1}
+            )
+            next(iter(secrets_iter), None)
+        except DefaultCredentialsError as e:
+            self._client = None
+            raise AuthenticationError(f"GCP authentication failed: {e}") from e
+        except (
+            google_exceptions.PermissionDenied,
+            google_exceptions.Unauthenticated,
+        ) as e:
+            self._client = None
+            raise AuthenticationError(f"GCP authentication failed: {e}") from e
+        except google_exceptions.GoogleAPICallError as e:
+            self._client = None
+            raise VaultError(f"GCP Secret Manager error: {e}") from e
+
+    def is_authenticated(self) -> bool:
+        return self._client is not None
+
+    def get_secret(self, name: str) -> SecretValue:
+        """
+        Retrieve a secret from GCP Secret Manager.
+
+        Parameters:
+            name (str): Secret name or full resource path.
+
+        Returns:
+            SecretValue: Contains the secret's name, value, version, and metadata.
+        """
+        self.ensure_authenticated()
+
+        try:
+            version_path = self._version_path(name)
+            response = self._client.access_secret_version(request={"name": version_path})
+            payload = response.payload.data if response.payload else b""
+            try:
+                value = payload.decode("utf-8")
+            except UnicodeDecodeError:
+                import base64
+
+                value = base64.b64encode(payload).decode("ascii")
+            version = response.name.split("/")[-1] if response.name else None
+            return SecretValue(
+                name=self._secret_id(name),
+                value=value,
+                version=version,
+                metadata={"name": response.name},
+            )
+        except google_exceptions.NotFound as e:
+            raise SecretNotFoundError(f"Secret '{name}' not found") from e
+        except (
+            google_exceptions.PermissionDenied,
+            google_exceptions.Unauthenticated,
+        ) as e:
+            raise AuthenticationError(f"Access denied to secret '{name}': {e}") from e
+        except google_exceptions.GoogleAPICallError as e:
+            raise VaultError(f"GCP Secret Manager error: {e}") from e
+
+    def list_secrets(self, prefix: str = "") -> list[str]:
+        """
+        List secret names in the project, optionally filtered by a prefix.
+
+        Parameters:
+            prefix (str): Optional prefix to filter secret names.
+        """
+        self.ensure_authenticated()
+
+        try:
+            secrets = []
+            for secret in self._client.list_secrets(request={"parent": self._project_path()}):
+                secret_id = secret.name.split("/")[-1] if secret.name else ""
+                if secret_id and (not prefix or secret_id.startswith(prefix)):
+                    secrets.append(secret_id)
+            return sorted(secrets)
+        except (
+            google_exceptions.PermissionDenied,
+            google_exceptions.Unauthenticated,
+        ) as e:
+            raise AuthenticationError(f"Access denied to list secrets: {e}") from e
+        except google_exceptions.GoogleAPICallError as e:
+            raise VaultError(f"GCP Secret Manager error: {e}") from e
+
+    def set_secret(self, name: str, value: str) -> SecretValue:
+        """
+        Create or update a secret in GCP Secret Manager.
+
+        Returns:
+            SecretValue containing the stored secret's name, value, version, and metadata.
+        """
+        self.ensure_authenticated()
+
+        secret_id = self._secret_id(name)
+        secret_path = self._secret_path(name)
+
+        try:
+            with contextlib.suppress(google_exceptions.AlreadyExists):
+                self._client.create_secret(
+                    request={
+                        "parent": self._project_path(),
+                        "secret_id": secret_id,
+                        "secret": {"replication": {"automatic": {}}},
+                    }
+                )
+
+            version = self._client.add_secret_version(
+                request={
+                    "parent": secret_path,
+                    "payload": {"data": value.encode("utf-8")},
+                }
+            )
+            version_id = version.name.split("/")[-1] if version.name else None
+            return SecretValue(
+                name=secret_id,
+                value=value,
+                version=version_id,
+                metadata={"name": version.name},
+            )
+        except (
+            google_exceptions.PermissionDenied,
+            google_exceptions.Unauthenticated,
+        ) as e:
+            raise AuthenticationError(f"Access denied to write secret '{name}': {e}") from e
+        except google_exceptions.GoogleAPICallError as e:
+            raise VaultError(f"GCP Secret Manager error: {e}") from e

envdrift/vault/hashicorp.py

@@ -0,0 +1,238 @@
+"""HashiCorp Vault client implementation."""
+
+from __future__ import annotations
+
+import os
+
+from envdrift.vault.base import (
+    AuthenticationError,
+    SecretNotFoundError,
+    SecretValue,
+    VaultClient,
+    VaultError,
+)
+
+try:
+    import hvac
+    from hvac.exceptions import Forbidden, InvalidPath, Unauthorized
+
+    HVAC_AVAILABLE = True
+except ImportError:
+    HVAC_AVAILABLE = False
+    hvac = None
+    InvalidPath = Exception
+    Forbidden = Exception
+    Unauthorized = Exception
+
+
+class HashiCorpVaultClient(VaultClient):
+    """HashiCorp Vault implementation.
+
+    Supports KV v2 secrets engine (the default in modern Vault).
+
+    Authentication methods supported:
+    - Token (via token parameter or VAULT_TOKEN env var)
+    """
+
+    def __init__(
+        self,
+        url: str,
+        token: str | None = None,
+        mount_point: str = "secret",
+    ):
+        """
+        Create a HashiCorp Vault client configured to use the KV v2 secrets engine.
+
+        Parameters:
+            url (str): Vault server URL (e.g., "https://vault.example.com:8200").
+            token (str | None): Authentication token; if omitted, the VAULT_TOKEN environment variable is used.
+            mount_point (str): KV secrets engine mount point (default "secret").
+        """
+        if not HVAC_AVAILABLE:
+            raise ImportError("hvac not installed. Install with: pip install envdrift[hashicorp]")
+
+        self.url = url
+        self.token = token or os.environ.get("VAULT_TOKEN")
+        self.mount_point = mount_point
+        self._client: hvac.Client | None = None
+
+    def authenticate(self) -> None:
+        """
+        Authenticate the client against HashiCorp Vault using the configured token.
+
+        This initializes and verifies the underlying hvac client and stores it on the instance
+        when authentication succeeds.
+
+        Raises:
+                AuthenticationError: If no token was provided, the token is invalid, expired, or Vault
+                        rejects authentication (including Unauthorized or Forbidden responses).
+                VaultError: For other connection or unexpected errors communicating with Vault.
+        """
+        if not self.token:
+            raise AuthenticationError(
+                "No Vault token provided. Set VAULT_TOKEN or pass token parameter."
+            )
+
+        try:
+            self._client = hvac.Client(url=self.url, token=self.token)
+
+            if not self._client.is_authenticated():
+                raise AuthenticationError("Vault token is invalid or expired")
+        except (Unauthorized, Forbidden) as e:
+            raise AuthenticationError(f"Vault authentication failed: {e}") from e
+        except Exception as e:
+            raise VaultError(f"Vault connection error: {e}") from e
+
+    def is_authenticated(self) -> bool:
+        """
+        Return whether the stored hvac client is currently authenticated.
+
+        Returns:
+            bool: `True` if an internal hvac client exists and reports it is authenticated, `False` otherwise.
+        """
+        if self._client is None:
+            return False
+        try:
+            return self._client.is_authenticated()
+        except Exception:
+            return False
+
+    def get_secret(self, name: str) -> SecretValue:
+        """
+        Retrieve a secret from Vault at the given path relative to the client's mount point.
+
+        If the stored secret data contains only a single key named "value", that value is returned; otherwise the entire secret data dict is JSON-encoded and returned as the value. The returned SecretValue includes the secret's version and metadata (created_time, deletion_time, destroyed, custom_metadata).
+
+        Parameters:
+            name: Secret path relative to the configured mount point.
+
+        Returns:
+            A SecretValue containing the secret's value, version, and metadata.
+
+        Raises:
+            SecretNotFoundError: If the secret path does not exist.
+            AuthenticationError: If access to the secret is denied or the client is unauthenticated.
+            VaultError: For other Vault-related errors.
+        """
+        self.ensure_authenticated()
+
+        try:
+            response = self._client.secrets.kv.v2.read_secret_version(
+                path=name,
+                mount_point=self.mount_point,
+            )
+
+            data = response.get("data", {})
+            secret_data = data.get("data", {})
+            metadata = data.get("metadata", {})
+
+            # If there's a single "value" key, return that
+            # Otherwise return the JSON string of all data
+            if "value" in secret_data and len(secret_data) == 1:
+                value = secret_data["value"]
+            else:
+                import json
+
+                value = json.dumps(secret_data)
+
+            return SecretValue(
+                name=name,
+                value=value,
+                version=str(metadata.get("version", "")),
+                metadata={
+                    "created_time": metadata.get("created_time"),
+                    "deletion_time": metadata.get("deletion_time"),
+                    "destroyed": metadata.get("destroyed", False),
+                    "custom_metadata": metadata.get("custom_metadata", {}),
+                },
+            )
+        except InvalidPath as e:
+            raise SecretNotFoundError(f"Secret '{name}' not found in Vault") from e
+        except (Unauthorized, Forbidden) as e:
+            raise AuthenticationError(f"Access denied to secret '{name}': {e}") from e
+        except Exception as e:
+            raise VaultError(f"Vault error: {e}") from e
+
+    def list_secrets(self, prefix: str = "") -> list[str]:
+        """List secret paths in HashiCorp Vault.
+
+        Args:
+            prefix: Path prefix to list under
+
+        Returns:
+            List of secret paths
+        """
+        self.ensure_authenticated()
+
+        try:
+            response = self._client.secrets.kv.v2.list_secrets(
+                path=prefix,
+                mount_point=self.mount_point,
+            )
+
+            keys = response.get("data", {}).get("keys", [])
+            return sorted(keys)
+        except InvalidPath:
+            # Path doesn't exist, return empty list
+            return []
+        except (Unauthorized, Forbidden) as e:
+            raise AuthenticationError(f"Access denied to list secrets: {e}") from e
+        except Exception as e:
+            raise VaultError(f"Vault error: {e}") from e
+
+    def create_or_update_secret(self, name: str, data: dict) -> SecretValue:
+        """
+        Create or update a secret at the given Vault path.
+
+        Parameters:
+            name (str): Secret path in the KV v2 engine.
+            data (dict): Dictionary of key-value pairs to store for the secret.
+
+        Returns:
+            SecretValue: The stored secret representation containing the secret `name`, a string `value` (JSON-encoded when multiple keys), the secret `version`, and metadata including `created_time`.
+
+        Raises:
+            AuthenticationError: If the client is not authorized to write the secret.
+            VaultError: For other Vault-related errors.
+        """
+        self.ensure_authenticated()
+
+        try:
+            response = self._client.secrets.kv.v2.create_or_update_secret(
+                path=name,
+                secret=data,
+                mount_point=self.mount_point,
+            )
+
+            metadata = response.get("data", {})
+
+            # Use same value extraction logic as get_secret for consistency
+            import json
+
+            value = data["value"] if ("value" in data and len(data) == 1) else json.dumps(data)
+
+            return SecretValue(
+                name=name,
+                value=value,
+                version=str(metadata.get("version", "")),
+                metadata={
+                    "created_time": metadata.get("created_time"),
+                },
+            )
+        except (Unauthorized, Forbidden) as e:
+            raise AuthenticationError(f"Access denied to write secret: {e}") from e
+        except Exception as e:
+            raise VaultError(f"Vault error: {e}") from e
+
+    def set_secret(self, name: str, value: str) -> SecretValue:
+        """
+        Set a string secret at the given path.
+
+        Parameters:
+            name (str): Secret path in Vault.
+            value (str): Secret string to store.
+
+        Returns:
+            SecretValue: The created or updated secret, including its stored value and metadata.
+        """
+        return self.create_or_update_secret(name, {"value": value})