kstlib 0.0.1a0__py3-none-any.whl → 1.0.0__py3-none-any.whl

kstlib/secrets/models.py

@@ -0,0 +1,62 @@
+"""Data models used by the secrets resolver."""
+
+from __future__ import annotations
+
+import typing
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, MutableMapping
+else:  # pragma: no cover - runtime aliases for typing constructs
+    Mapping = typing.Mapping
+    MutableMapping = typing.MutableMapping
+
+
+class SecretSource(str, Enum):
+    """Enumerates the possible origins for a resolved secret."""
+
+    KWARGS = "kwargs"
+    ENVIRONMENT = "environment"
+    KEYRING = "keyring"
+    SOPS = "sops"
+    KMS = "kms"
+    DEFAULT = "default"
+
+
+@dataclass(slots=True)
+class SecretRequest:
+    """Describes a secret lookup request.
+
+    Attributes:
+        name: Identifier of the secret (e.g. "smtp.password").
+        scope: Optional scope that providers can exploit for namespacing.
+        required: Whether the resolver must raise if the secret is missing.
+        default: Optional fallback value when the secret is not required.
+        metadata: Arbitrary provider hints (e.g. keyring namespace).
+    """
+
+    name: str
+    scope: str | None = None
+    required: bool = True
+    default: Any | None = None
+    metadata: MutableMapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class SecretRecord:
+    """Represents the value returned by the resolver.
+
+    Attributes:
+        value: The secret itself.
+        source: The origin of the secret.
+        metadata: Provider specific metadata (e.g. timestamp, path, ttl).
+    """
+
+    value: Any
+    source: SecretSource
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+
+__all__ = ["SecretRecord", "SecretRequest", "SecretSource"]

kstlib/secrets/providers/__init__.py

@@ -0,0 +1,79 @@
+"""Provider registry utilities for the secrets subsystem."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from kstlib.secrets.providers.base import ProviderFactory, SecretProvider
+from kstlib.utils.lazy import lazy_factory
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+_REGISTRY: dict[str, ProviderFactory] = {}
+
+
+def register_provider(name: str, factory: ProviderFactory) -> None:
+    """Register a provider factory under the given name."""
+    _REGISTRY[name] = factory
+
+
+def get_provider(name: str, **kwargs: Any) -> SecretProvider:
+    """Instantiate a provider by name."""
+    try:
+        factory = _REGISTRY[name]
+    except KeyError as exc:  # pragma: no cover - defensive branch
+        raise ValueError(f"Unknown secret provider '{name}'") from exc
+    return factory(**kwargs)
+
+
+def configure_provider(provider: SecretProvider, settings: Mapping[str, Any] | None) -> SecretProvider:
+    """Apply provider-specific configuration and return the provider."""
+    provider.configure(settings)
+    return provider
+
+
+__all__ = [
+    "ProviderFactory",
+    "SecretProvider",
+    "configure_provider",
+    "get_provider",
+    "register_provider",
+]
+
+
+# --- Lazy-loaded provider factories ---
+# Providers are only imported when their factory is called, not at module load.
+# Body is replaced by the decorator; type: ignore[empty-body] silences mypy.
+
+
+@lazy_factory("kstlib.secrets.providers.kwargs", "KwargsProvider")
+def _kwargs_factory(**_kwargs: Any) -> SecretProvider:  # type: ignore[empty-body]
+    ...  # pragma: no cover - body replaced by decorator
+
+
+@lazy_factory("kstlib.secrets.providers.environment", "EnvironmentProvider")
+def _environment_factory(**_kwargs: Any) -> SecretProvider:  # type: ignore[empty-body]
+    ...  # pragma: no cover - body replaced by decorator
+
+
+@lazy_factory("kstlib.secrets.providers.keyring", "KeyringProvider")
+def _keyring_factory(**_kwargs: Any) -> SecretProvider:  # type: ignore[empty-body]
+    ...  # pragma: no cover - body replaced by decorator
+
+
+@lazy_factory("kstlib.secrets.providers.sops", "SOPSProvider")
+def _sops_factory(**_kwargs: Any) -> SecretProvider:  # type: ignore[empty-body]
+    ...  # pragma: no cover - body replaced by decorator
+
+
+@lazy_factory("kstlib.secrets.providers.kms", "KMSProvider")
+def _kms_factory(**_kwargs: Any) -> SecretProvider:  # type: ignore[empty-body]
+    ...  # pragma: no cover - body replaced by decorator
+
+
+register_provider("kwargs", _kwargs_factory)
+register_provider("environment", _environment_factory)
+register_provider("keyring", _keyring_factory)
+register_provider("sops", _sops_factory)
+register_provider("kms", _kms_factory)

kstlib/secrets/providers/base.py

@@ -0,0 +1,58 @@
+"""Provider base classes and registry helpers."""
+
+from __future__ import annotations
+
+# pylint: disable=unnecessary-ellipsis,too-few-public-methods
+import asyncio
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any, Protocol
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from kstlib.secrets.models import SecretRecord, SecretRequest
+
+
+class SecretProvider(ABC):
+    """Abstract provider responsible for retrieving secrets from a backend."""
+
+    name: str = "provider"
+
+    @abstractmethod
+    def resolve(self, request: SecretRequest) -> SecretRecord | None:
+        """Retrieve the secret synchronously.
+
+        Args:
+            request: Details about the requested secret.
+
+        Returns:
+            A ``SecretRecord`` if the provider can handle the request, otherwise
+            ``None``.
+        """
+
+    async def resolve_async(self, request: SecretRequest) -> SecretRecord | None:
+        """Async-friendly hook.
+
+        Providers may override this method when native async support is
+        available. The default implementation delegates to ``resolve`` using
+        ``asyncio.to_thread`` to avoid blocking the event loop.
+        """
+        return await asyncio.to_thread(self.resolve, request)
+
+    def configure(self, settings: Mapping[str, Any] | None = None) -> None:
+        """Apply provider specific configuration settings.
+
+        Subclasses can override to handle provider-level configuration. The
+        default implementation ignores the settings.
+        """
+        if not settings:
+            return
+        _ = settings
+
+
+class ProviderFactory(Protocol):
+    """Protocol describing callables that build providers."""
+
+    def __call__(self, **kwargs: Any) -> SecretProvider:  # pragma: no cover - protocol definition
+        """Return a configured provider instance."""
+        ...

kstlib/secrets/providers/environment.py

@@ -0,0 +1,66 @@
+"""Environment variable provider."""
+
+from __future__ import annotations
+
+import os
+import typing
+from typing import TYPE_CHECKING, Any
+
+from kstlib.secrets.models import SecretRecord, SecretRequest, SecretSource
+from kstlib.secrets.providers.base import SecretProvider
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+else:  # pragma: no cover - runtime alias for typing constructs
+    Mapping = typing.Mapping
+
+
+class EnvironmentProvider(SecretProvider):
+    """Resolve secrets from process environment variables."""
+
+    name = "environment"
+
+    def __init__(self, *, prefix: str = "KSTLIB_", delimiter: str = "__") -> None:
+        """Configure the provider prefix and delimiter."""
+        self._prefix = prefix
+        self._delimiter = delimiter
+
+    def configure(self, settings: Mapping[str, Any] | None = None) -> None:
+        """Apply settings overrides coming from configuration files.
+
+        Args:
+            settings: Optional mapping that may provide ``prefix`` or
+                ``delimiter`` keys overriding the defaults.
+        """
+        if not settings:
+            return
+        self._prefix = settings.get("prefix", self._prefix)
+        self._delimiter = settings.get("delimiter", self._delimiter)
+
+    def resolve(self, request: SecretRequest) -> SecretRecord | None:
+        """Resolve a secret using the environment cascade.
+
+        Args:
+            request: Secret descriptor describing scope and key.
+
+        Returns:
+            A ``SecretRecord`` populated from the environment when present,
+            otherwise ``None``.
+        """
+        env_key = self._build_env_key(request)
+        value = os.getenv(env_key)
+        if value is None:
+            return None
+        return SecretRecord(value=value, source=SecretSource.ENVIRONMENT, metadata={"env_key": env_key})
+
+    def _build_env_key(self, request: SecretRequest) -> str:
+        """Construct the canonical environment variable name for a request."""
+        parts: list[str] = [self._prefix.rstrip(self._delimiter)]
+        if request.scope:
+            parts.append(request.scope)
+        parts.append(request.name)
+        env_key = self._delimiter.join(part.upper().replace(".", self._delimiter) for part in parts if part)
+        return env_key
+
+
+__all__ = ["EnvironmentProvider"]

kstlib/secrets/providers/keyring.py

@@ -0,0 +1,107 @@
+"""Keyring-backed provider."""
+
+from __future__ import annotations
+
+import typing
+from typing import TYPE_CHECKING, Any
+
+from kstlib.secrets.models import SecretRecord, SecretRequest, SecretSource
+from kstlib.secrets.providers.base import SecretProvider
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+else:  # pragma: no cover - runtime alias for typing constructs
+    Mapping = typing.Mapping
+
+# pylint: disable=invalid-name
+keyring_backend: Any | None
+try:  # pragma: no cover - optional dependency
+    import keyring as keyring_module  # type: ignore[import-not-found]
+except ModuleNotFoundError:  # pragma: no cover - fallback when keyring absent
+    keyring_backend = None
+else:
+    keyring_backend = keyring_module
+
+
+class KeyringProvider(SecretProvider):
+    """Retrieve secrets from the system keyring."""
+
+    name = "keyring"
+
+    def __init__(self, *, service: str = "kstlib") -> None:
+        """Instantiate the provider with an optional service namespace."""
+        self._service = service
+
+    def configure(self, settings: Mapping[str, Any] | None = None) -> None:
+        """Load configuration overrides into the provider.
+
+        Args:
+            settings: Optional mapping with a ``service`` key overriding the
+                default keyring service name.
+        """
+        if not settings:
+            return
+        self._service = settings.get("service", self._service)
+
+    def resolve(self, request: SecretRequest) -> SecretRecord | None:
+        """Retrieve a secret from the backing keyring.
+
+        Args:
+            request: Secret lookup description provided by the resolver.
+
+        Returns:
+            A populated ``SecretRecord`` when the secret exists, otherwise
+            ``None`` to signal a miss.
+        """
+        if keyring_backend is None:
+            return None
+        username = self._username_for(request)
+        value = keyring_backend.get_password(self._service, username)
+        if value is None:
+            return None
+        metadata = {"service": self._service, "username": username}
+        return SecretRecord(value=value, source=SecretSource.KEYRING, metadata=metadata)
+
+    def store(self, request: SecretRequest, value: str) -> None:
+        """Persist a secret to the keyring backend.
+
+        Args:
+            request: Secret descriptor used to derive a keyring username.
+            value: Plaintext secret that should be stored.
+
+        Raises:
+            RuntimeError: If the optional ``keyring`` dependency is missing.
+        """
+        if keyring_backend is None:
+            raise RuntimeError("keyring package is not available")
+        username = self._username_for(request)
+        keyring_backend.set_password(self._service, username, value)
+
+    def delete(self, request: SecretRequest) -> None:
+        """Remove a secret from the keyring backend.
+
+        Args:
+            request: Secret descriptor used to derive a keyring username.
+
+        Raises:
+            RuntimeError: If the optional ``keyring`` dependency is missing.
+        """
+        if keyring_backend is None:
+            raise RuntimeError("keyring package is not available")
+        username = self._username_for(request)
+        keyring_backend.delete_password(self._service, username)
+
+    def _username_for(self, request: SecretRequest) -> str:
+        """Compute a stable username for the keyring entry.
+
+        Args:
+            request: Secret descriptor providing scope and name details.
+
+        Returns:
+            The composed username used for keyring operations.
+        """
+        scope = request.scope or "default"
+        return f"{scope}:{request.name}"
+
+
+__all__ = ["KeyringProvider"]

kstlib/secrets/providers/kms.py

@@ -0,0 +1,223 @@
+"""AWS KMS-backed secret provider.
+
+This provider uses AWS KMS to encrypt/decrypt secret values directly.
+It supports both real AWS KMS and LocalStack for local development.
+
+Note: For SOPS-managed files with KMS encryption, use SOPSProvider instead.
+This provider is for direct KMS encrypt/decrypt operations.
+"""
+
+# pylint: disable=too-many-arguments
+# Justification: __init__ takes standard AWS config params (key_id, region,
+# endpoint, access_key, secret_key) - this is the canonical AWS client pattern.
+# Wrapping in a dataclass would add indirection without benefit.
+
+# pylint: disable=broad-exception-caught
+# Justification: False positive - ClientError is a fallback to Exception only when
+# boto3 is not installed (line 34). At runtime with boto3, we catch the real
+# botocore.exceptions.ClientError, not the generic Exception.
+
+from __future__ import annotations
+
+import base64
+from typing import TYPE_CHECKING, Any
+
+from kstlib.logging import get_logger
+from kstlib.secrets.exceptions import SecretDecryptionError
+from kstlib.secrets.models import SecretRecord, SecretRequest, SecretSource
+from kstlib.secrets.providers.base import SecretProvider
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+logger = get_logger(__name__)
+
+# boto3 is optional - only needed when KMS provider is used
+try:
+    import boto3  # type: ignore[import-not-found]
+    from botocore.exceptions import ClientError  # type: ignore[import-not-found]
+
+    _HAS_BOTO3 = True
+except ImportError:  # pragma: no cover
+    _HAS_BOTO3 = False
+    boto3 = None  # type: ignore[assignment]
+    ClientError = Exception  # type: ignore[misc,assignment]
+
+
+class KMSProvider(SecretProvider):
+    """Load and decrypt secrets using AWS KMS.
+
+    This provider can:
+    - Decrypt base64-encoded ciphertext stored in environment variables or config
+    - Store encrypted values using KMS encrypt operation
+
+    Unlike SOPSProvider which decrypts entire files, KMSProvider works with
+    individual secret values that have been encrypted with KMS.
+
+    Example:
+        >>> from kstlib.secrets.providers.kms import KMSProvider
+        >>> provider = KMSProvider(
+        ...     key_id="alias/my-key",
+        ...     endpoint_url="http://localhost:4566",  # LocalStack
+        ... )
+        >>> # provider.resolve(SecretRequest(name="db.password", metadata={"ciphertext": "..."}))
+    """
+
+    name = "kms"
+
+    def __init__(
+        self,
+        *,
+        key_id: str | None = None,
+        region_name: str = "us-east-1",
+        endpoint_url: str | None = None,
+        aws_access_key_id: str | None = None,
+        aws_secret_access_key: str | None = None,
+    ) -> None:
+        """Configure the KMS provider.
+
+        Args:
+            key_id: Default KMS key ID or alias (e.g., "alias/kstlib-test").
+            region_name: AWS region (default: us-east-1).
+            endpoint_url: Custom endpoint for LocalStack (e.g., "http://localhost:4566").
+            aws_access_key_id: AWS access key (optional, uses default credential chain).
+            aws_secret_access_key: AWS secret key (optional, uses default credential chain).
+        """
+        self._key_id = key_id
+        self._region_name = region_name
+        self._endpoint_url = endpoint_url
+        self._aws_access_key_id = aws_access_key_id
+        self._aws_secret_access_key = aws_secret_access_key
+        self._client: Any = None
+
+    def configure(self, settings: Mapping[str, Any] | None = None) -> None:
+        """Apply configuration from settings mapping."""
+        if not settings:
+            return
+        if "key_id" in settings:
+            self._key_id = settings["key_id"]
+        if "region_name" in settings:
+            self._region_name = settings["region_name"]
+        if "endpoint_url" in settings:
+            self._endpoint_url = settings["endpoint_url"]
+        if "aws_access_key_id" in settings:
+            self._aws_access_key_id = settings["aws_access_key_id"]
+        if "aws_secret_access_key" in settings:
+            self._aws_secret_access_key = settings["aws_secret_access_key"]
+        # Reset client to pick up new config
+        self._client = None
+
+    def _get_client(self) -> Any:
+        """Lazily initialize and return the KMS client."""
+        if self._client is not None:
+            return self._client
+
+        if not _HAS_BOTO3:
+            raise SecretDecryptionError("boto3 is required for KMS provider. Install with: pip install boto3")
+
+        client_kwargs: dict[str, Any] = {
+            "service_name": "kms",
+            "region_name": self._region_name,
+        }
+        if self._endpoint_url:
+            client_kwargs["endpoint_url"] = self._endpoint_url
+        if self._aws_access_key_id:
+            client_kwargs["aws_access_key_id"] = self._aws_access_key_id
+        if self._aws_secret_access_key:
+            client_kwargs["aws_secret_access_key"] = self._aws_secret_access_key
+
+        self._client = boto3.client(**client_kwargs)  # type: ignore[union-attr]
+        return self._client
+
+    def resolve(self, request: SecretRequest) -> SecretRecord | None:
+        """Resolve a secret by decrypting KMS ciphertext.
+
+        The ciphertext can be provided in request metadata as:
+        - "ciphertext": base64-encoded encrypted data
+        - "ciphertext_blob": raw bytes (less common)
+
+        If no ciphertext is provided, returns None (allowing fallback to other providers).
+        """
+        metadata = request.metadata or {}
+        ciphertext_b64 = metadata.get("ciphertext")
+        ciphertext_blob = metadata.get("ciphertext_blob")
+
+        if ciphertext_b64 is None and ciphertext_blob is None:
+            return None
+
+        try:
+            if ciphertext_b64:
+                ciphertext_blob = base64.b64decode(ciphertext_b64)
+
+            client = self._get_client()
+            response = client.decrypt(CiphertextBlob=ciphertext_blob)
+            plaintext = response["Plaintext"]
+
+            # Decode if bytes
+            if isinstance(plaintext, bytes):
+                plaintext = plaintext.decode("utf-8")
+
+            return SecretRecord(
+                value=plaintext,
+                source=SecretSource.KMS,
+                metadata={
+                    "key_id": response.get("KeyId", self._key_id),
+                    "region": self._region_name,
+                    "endpoint": self._endpoint_url,
+                },
+            )
+        except ClientError as exc:
+            error_code = exc.response.get("Error", {}).get("Code", "Unknown")  # type: ignore[union-attr]
+            logger.debug("KMS decryption failed for %s: %s", request.name, error_code)
+            raise SecretDecryptionError(f"Failed to decrypt secret '{request.name}': {error_code}") from exc
+
+    def encrypt(self, plaintext: str | bytes, *, key_id: str | None = None) -> str:
+        """Encrypt a plaintext value and return base64-encoded ciphertext.
+
+        Args:
+            plaintext: The value to encrypt (string or bytes).
+            key_id: KMS key ID or alias. If not provided, uses the default key_id.
+
+        Returns:
+            Base64-encoded ciphertext that can be decrypted later.
+
+        Raises:
+            SecretDecryptionError: If encryption fails or no key_id is configured.
+        """
+        effective_key_id = key_id or self._key_id
+        if not effective_key_id:
+            raise SecretDecryptionError("No KMS key_id configured for encryption")
+
+        if isinstance(plaintext, str):
+            plaintext = plaintext.encode("utf-8")
+
+        try:
+            client = self._get_client()
+            response = client.encrypt(KeyId=effective_key_id, Plaintext=plaintext)
+            ciphertext_blob = response["CiphertextBlob"]
+            return base64.b64encode(ciphertext_blob).decode("ascii")
+        except ClientError as exc:
+            error_code = exc.response.get("Error", {}).get("Code", "Unknown")  # type: ignore[union-attr]
+            raise SecretDecryptionError(f"Failed to encrypt: {error_code}") from exc
+
+    def is_available(self) -> bool:
+        """Check if KMS is reachable and the configured key exists.
+
+        Returns:
+            True if KMS is accessible and the key can be used.
+        """
+        if not _HAS_BOTO3:
+            return False
+
+        if not self._key_id:
+            return False
+
+        try:
+            client = self._get_client()
+            client.describe_key(KeyId=self._key_id)
+        except ClientError:
+            return False
+        return True
+
+
+__all__ = ["KMSProvider"]