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

kstlib/secrets/providers/kwargs.py

@@ -0,0 +1,101 @@
+"""Kwargs-based provider for direct secret injection."""
+
+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
+
+
+class KwargsProvider(SecretProvider):
+    """Resolve secrets from explicitly provided keyword arguments.
+
+    This provider is useful for testing and temporary overrides. Secrets
+    passed via kwargs take precedence over all other providers.
+
+    Example:
+        >>> from kstlib.secrets.providers.kwargs import KwargsProvider
+        >>> provider = KwargsProvider({"api.key": "test-key"})
+        >>> from kstlib.secrets.models import SecretRequest
+        >>> record = provider.resolve(SecretRequest(name="api.key"))
+        >>> record.value
+        'test-key'
+    """
+
+    name = "kwargs"
+
+    def __init__(self, secrets: Mapping[str, Any] | None = None) -> None:
+        """Initialize with an optional mapping of secret names to values.
+
+        Args:
+            secrets: Mapping of dotted secret names to their values.
+        """
+        self._secrets: dict[str, Any] = dict(secrets) if secrets else {}
+
+    def configure(self, settings: Mapping[str, Any] | None = None) -> None:
+        """Apply settings overrides (merges additional secrets).
+
+        Args:
+            settings: Optional mapping that may provide additional secrets
+                under the ``secrets`` key.
+        """
+        if not settings:
+            return
+        additional = settings.get("secrets")
+        if isinstance(additional, Mapping):
+            self._secrets.update(additional)
+
+    def resolve(self, request: SecretRequest) -> SecretRecord | None:
+        """Resolve a secret from the provided kwargs.
+
+        Args:
+            request: Secret descriptor with the name to look up.
+
+        Returns:
+            A ``SecretRecord`` if the secret is found, otherwise ``None``.
+        """
+        value = self._secrets.get(request.name)
+        if value is None:
+            return None
+        return SecretRecord(
+            value=value,
+            source=SecretSource.KWARGS,
+            metadata={"provider": "kwargs"},
+        )
+
+    def set(self, name: str, value: Any) -> None:
+        """Add or update a secret at runtime.
+
+        Args:
+            name: The dotted secret name (e.g., "api.key").
+            value: The secret value.
+        """
+        self._secrets[name] = value
+
+    def remove(self, name: str) -> bool:
+        """Remove a secret by name.
+
+        Args:
+            name: The dotted secret name to remove.
+
+        Returns:
+            True if the secret was removed, False if it didn't exist.
+        """
+        if name in self._secrets:
+            del self._secrets[name]
+            return True
+        return False
+
+    def clear(self) -> None:
+        """Remove all secrets from this provider."""
+        self._secrets.clear()
+
+
+__all__ = ["KwargsProvider"]

kstlib/secrets/providers/sops.py

@@ -0,0 +1,209 @@
+"""SOPS-backed provider."""
+
+from __future__ import annotations
+
+# pylint: disable=duplicate-code
+import json
+import logging
+import re
+import shutil
+from collections import OrderedDict
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from subprocess import run as subprocess_run
+from typing import Any
+
+import yaml
+
+from kstlib.limits import HARD_MAX_SOPS_CACHE_ENTRIES, SopsLimits, get_sops_limits
+from kstlib.secrets.exceptions import SecretDecryptionError
+from kstlib.secrets.models import SecretRecord, SecretRequest, SecretSource
+from kstlib.secrets.providers.base import SecretProvider
+
+logger = logging.getLogger(__name__)
+
+
+class SOPSProvider(SecretProvider):
+    """Load secrets from SOPS encrypted documents."""
+
+    name = "sops"
+
+    def __init__(
+        self,
+        *,
+        path: str | Path | None = None,
+        binary: str = "sops",
+        document_format: str = "auto",
+        limits: SopsLimits | None = None,
+    ) -> None:
+        """Configure the provider with optional defaults."""
+        self._path = Path(path) if path else None
+        self._binary = binary
+        self._document_format = document_format
+        self._limits = limits or get_sops_limits()
+        self._max_cache_entries = self._limits.max_cache_entries
+        self._cache: OrderedDict[Path, tuple[float, Any]] = OrderedDict()
+
+    def configure(self, settings: Mapping[str, Any] | None = None) -> None:
+        """Apply overrides supplied by configuration files."""
+        if not settings:
+            return
+        target = settings.get("path")
+        if target:
+            self._path = Path(target)
+        binary = settings.get("binary")
+        if binary:
+            self._binary = binary
+        fmt = settings.get("format") or settings.get("document_format")
+        if fmt:
+            self._document_format = fmt
+        max_entries = settings.get("max_cache_entries")
+        if max_entries is not None:
+            # Enforce hard limit for deep defense
+            self._max_cache_entries = min(int(max_entries), HARD_MAX_SOPS_CACHE_ENTRIES)
+
+    def resolve(self, request: SecretRequest) -> SecretRecord | None:
+        """Resolve the requested secret from the encrypted document."""
+        path = self._resolve_path(request)
+        if path is None:
+            return None
+
+        document = self._load_document(path)
+        value = self._extract_value(document, request)
+        if value is None:
+            return None
+
+        metadata = {
+            "path": str(path),
+            "format": self._document_format,
+            "binary": self._binary,
+        }
+        return SecretRecord(value=value, source=SecretSource.SOPS, metadata=metadata)
+
+    def _resolve_path(self, request: SecretRequest) -> Path | None:
+        """Determine the effective SOPS path for a secret request."""
+        candidate = request.metadata.get("path") if request.metadata else None
+        if candidate:
+            return Path(candidate)
+        return self._path
+
+    def _load_document(self, path: Path) -> Any:
+        """Decrypt and parse the underlying SOPS document."""
+        try:
+            mtime = path.stat().st_mtime
+        except FileNotFoundError as exc:  # pragma: no cover - defensive branch
+            raise SecretDecryptionError(f"SOPS file not found: {path}") from exc
+
+        cached = self._cache.get(path)
+        if cached and cached[0] == mtime:
+            # Move to end for LRU tracking
+            self._cache.move_to_end(path)
+            return cached[1]
+
+        binary_path = shutil.which(self._binary)
+        if binary_path is None:
+            raise SecretDecryptionError(
+                "SOPS binary not found. Install from https://github.com/getsops/sops or set 'binary' option.",
+            )
+
+        command = [binary_path, "--decrypt", str(path)]
+        process = subprocess_run(
+            command,
+            capture_output=True,
+            text=True,
+            check=False,
+            shell=False,
+        )
+        if process.returncode != 0:
+            diagnostic = process.stderr.strip() or process.stdout.strip()
+            if diagnostic:
+                logger.debug(
+                    "SOPS decryption failed for %s: %s",
+                    path,
+                    self._redact_sensitive_output(diagnostic),
+                )
+            raise SecretDecryptionError(
+                f"Failed to decrypt secrets file '{path.name}'. Check SOPS configuration and file permissions."
+            )
+
+        document = self._parse_document(process.stdout)
+        self._cache[path] = (mtime, document)
+        self._cache.move_to_end(path)
+        # Evict oldest entries (LRU) if cache exceeds limit
+        while len(self._cache) > self._max_cache_entries:
+            self._cache.popitem(last=False)
+        return document
+
+    def _parse_document(self, payload: str) -> Any:
+        """Deserialize the decrypted payload according to the configured format."""
+        fmt = self._document_format.lower()
+        try:
+            if fmt == "json":
+                return json.loads(payload)
+            if fmt == "yaml":
+                return yaml.safe_load(payload)
+            if fmt == "text":
+                return payload
+            # auto-detect: try json then yaml, fallback to text
+            return json.loads(payload)
+        except json.JSONDecodeError:
+            try:
+                return yaml.safe_load(payload)
+            except yaml.YAMLError as exc:
+                raise SecretDecryptionError("Unable to parse decrypted document as JSON or YAML") from exc
+        except yaml.YAMLError as exc:
+            raise SecretDecryptionError("Unable to parse decrypted document as YAML") from exc
+
+    def _extract_value(self, document: Any, request: SecretRequest) -> Any | None:
+        """Extract the value identified by the request metadata or name."""
+        key_path = request.metadata.get("key_path") if request.metadata else None
+        if key_path is None:
+            key_path = request.name
+
+        if isinstance(key_path, str):
+            parts = [part for part in key_path.split(".") if part]
+        elif isinstance(key_path, Sequence):
+            parts = [str(part) for part in key_path]
+        else:  # pragma: no cover - defensive guard
+            raise SecretDecryptionError("Invalid 'key_path' metadata; expected string or sequence of strings.")
+
+        current = document
+        for part in parts:
+            if isinstance(current, Mapping) and part in current:
+                current = current[part]
+            else:
+                return None
+        return current
+
+    @staticmethod
+    def _redact_sensitive_output(message: str) -> str:
+        """Redact known sensitive substrings from diagnostic output."""
+        patterns = [
+            re.compile(r"arn:aws:[^\s]+", re.IGNORECASE),
+            re.compile(r"AKIA[0-9A-Z]{16}"),
+            re.compile(r"(?:/home/|/Users/)[^\s]+"),
+        ]
+        redacted = message
+        for pattern in patterns:
+            redacted = pattern.sub("[REDACTED]", redacted)
+        return redacted
+
+    def purge_cache(self, *, path: str | Path | None = None) -> None:
+        """Clear decrypted document cache entries."""
+        if path is None:
+            self._cache.clear()
+            return
+
+        target = Path(path)
+        if target in self._cache:
+            self._cache.pop(target, None)
+            return
+
+        try:
+            resolved = target.resolve()
+        except OSError:  # pragma: no cover - inaccessible paths
+            return
+        self._cache.pop(resolved, None)
+
+
+__all__ = ["SOPSProvider"]

kstlib/secrets/resolver.py

@@ -0,0 +1,221 @@
+"""SecretResolver orchestrates provider lookups."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import TYPE_CHECKING, Any
+
+from kstlib.config.loader import get_config
+from kstlib.secrets.exceptions import SecretNotFoundError
+from kstlib.secrets.models import SecretRecord, SecretRequest, SecretSource
+from kstlib.secrets.providers import configure_provider, get_provider
+
+if TYPE_CHECKING:
+    from kstlib.secrets.providers.base import SecretProvider
+
+
+class SecretResolver:
+    """Resolve secrets by delegating to a sequence of providers.
+
+    The resolver iterates through providers in order until one returns a value.
+    If no provider can resolve the secret and no default is given, a
+    ``SecretNotFoundError`` is raised (when ``required=True``).
+
+    Example:
+        >>> from kstlib.secrets.resolver import SecretResolver
+        >>> from kstlib.secrets.providers import get_provider
+        >>> from kstlib.secrets.models import SecretRequest
+        >>> resolver = SecretResolver([get_provider("environment")], name="app")
+        >>> # resolver.resolve(SecretRequest(name="API_KEY"))
+    """
+
+    def __init__(self, providers: Sequence[SecretProvider], *, name: str | None = None) -> None:
+        """Initialise the resolver with a provider cascade.
+
+        Args:
+            providers: Ordered sequence of secret providers to query.
+            name: Human-readable name for this resolver (used in error messages).
+        """
+        self._providers = list(providers)
+        self._name = name or "default"
+
+    @property
+    def name(self) -> str:
+        """Return the resolver name."""
+        return self._name
+
+    def resolve(self, request: SecretRequest) -> SecretRecord:
+        """Resolve the secret using the configured provider cascade.
+
+        Args:
+            request: The secret request to resolve.
+
+        Returns:
+            A SecretRecord with the resolved value and metadata.
+
+        Raises:
+            SecretNotFoundError: If the secret is not found and required=True.
+        """
+        for provider in self._providers:
+            record = provider.resolve(request)
+            if record is not None:
+                return record
+        if request.default is not None:
+            return self._default_record(request.default, is_async=False)
+        if request.required:
+            raise SecretNotFoundError(f"Secret '{request.name}' not found in resolver '{self._name}'")
+        return self._default_record(None, is_async=False)
+
+    async def resolve_async(self, request: SecretRequest) -> SecretRecord:
+        """Async counterpart for ``resolve``.
+
+        Args:
+            request: The secret request to resolve.
+
+        Returns:
+            A SecretRecord with the resolved value and metadata.
+
+        Raises:
+            SecretNotFoundError: If the secret is not found and required=True.
+        """
+        for provider in self._providers:
+            record = await provider.resolve_async(request)
+            if record is not None:
+                return record
+        if request.default is not None:
+            return self._default_record(request.default, is_async=True)
+        if request.required:
+            raise SecretNotFoundError(f"Secret '{request.name}' not found in resolver '{self._name}'")
+        return self._default_record(None, is_async=True)
+
+    def _default_record(self, value: Any, *, is_async: bool) -> SecretRecord:
+        metadata: dict[str, Any] = {"resolver": self._name}
+        if is_async:
+            metadata["async"] = True
+        return SecretRecord(value=value, source=SecretSource.DEFAULT, metadata=metadata)
+
+
+def get_secret_resolver(
+    config: Mapping[str, Any] | None = None,
+    *,
+    secrets: Mapping[str, Any] | None = None,
+) -> SecretResolver:
+    """Build a resolver from configuration mapping.
+
+    When no explicit provider list is given, the default cascade is:
+    ``(KwargsProvider if secrets) -> EnvironmentProvider -> KeyringProvider -> (SOPSProvider if configured)``.
+
+    Args:
+        config: Optional mapping with ``providers`` list and/or ``sops`` settings.
+            When ``None``, uses the default provider chain.
+        secrets: Optional mapping of secret overrides to inject via KwargsProvider.
+
+    Returns:
+        Configured ``SecretResolver`` instance.
+
+    Example:
+        >>> from kstlib.secrets.resolver import get_secret_resolver
+        >>> resolver = get_secret_resolver()  # uses defaults
+        >>> resolver.name
+        'default'
+    """
+    config = config or {}
+    providers: list[SecretProvider] = []
+
+    # KwargsProvider always comes first (highest priority)
+    if secrets:
+        providers.append(get_provider("kwargs", secrets=secrets))
+
+    provider_configs = config.get("providers", [])
+    if not provider_configs:
+        providers.extend([get_provider("environment"), get_provider("keyring")])
+        sops_config = config.get("sops")
+        if isinstance(sops_config, Mapping):
+            providers.append(_build_sops_provider(sops_config))
+    else:
+        for provider_cfg in provider_configs:
+            name = provider_cfg.get("name")
+            if not name:
+                raise ValueError("Provider configuration requires a 'name' field")
+            settings = provider_cfg.get("settings")
+            provider = get_provider(name, **(provider_cfg.get("options") or {}))
+            providers.append(configure_provider(provider, settings))
+    return SecretResolver(providers, name=config.get("name"))
+
+
+def resolve_secret(
+    name: str,
+    *,
+    config: Mapping[str, Any] | None = None,
+    secrets: Mapping[str, Any] | None = None,
+    **request_kwargs: Any,
+) -> SecretRecord:
+    """Resolve a secret by name using the global resolver cascade.
+
+    Args:
+        name: Identifier of the secret (``"smtp.password"`` for example).
+        config: Optional configuration mapping describing providers. When not
+            provided the function attempts to reuse the globally loaded config.
+        secrets: Optional mapping of secret overrides. These take precedence
+            over all other providers (useful for testing).
+        request_kwargs: Additional keyword arguments forwarded to
+            :class:`SecretRequest`. Supported keys are ``scope``, ``required``,
+            ``default`` and ``metadata``.
+
+    Returns:
+        A ``SecretRecord`` describing the resolved secret and its provenance.
+
+    Raises:
+        SecretNotFoundError: If the secret is not found and required=True.
+        TypeError: If unsupported keyword arguments are provided.
+
+    Example:
+        >>> from kstlib.secrets.resolver import resolve_secret
+        >>> # Override for testing
+        >>> record = resolve_secret("api.key", secrets={"api.key": "test-value"})
+        >>> record.source
+        <SecretSource.KWARGS: 'kwargs'>
+    """
+    if config is None:
+        global_config = get_config()
+        secrets_config = getattr(global_config, "secrets", None)
+        config = secrets_config.to_dict() if secrets_config is not None else None
+
+    allowed_keys = {"scope", "required", "default", "metadata"}
+    unexpected = set(request_kwargs) - allowed_keys
+    if unexpected:
+        unexpected_list = ", ".join(sorted(unexpected))
+        raise TypeError(f"Unsupported keyword arguments: {unexpected_list}")
+
+    resolver = get_secret_resolver(config, secrets=secrets)
+    scope = request_kwargs.get("scope")
+    required = request_kwargs.get("required", True)
+    default = request_kwargs.get("default")
+    metadata = request_kwargs.get("metadata")
+    request = SecretRequest(
+        name=name,
+        scope=scope,
+        required=required,
+        default=default,
+        metadata=dict(metadata) if metadata else {},
+    )
+    return resolver.resolve(request)
+
+
+def _build_sops_provider(config: Mapping[str, Any]) -> SecretProvider:
+    """Instantiate a SOPS provider from a simple mapping."""
+    option_keys = {"path", "binary", "document_format", "format"}
+    raw_options = config.get("options")
+    options = (
+        {key: value for key, value in config.items() if key in option_keys}
+        if raw_options is None
+        else dict(raw_options)
+    )
+    if "format" in options and "document_format" not in options:
+        options["document_format"] = options.pop("format")
+    settings = config.get("settings")
+    provider = get_provider("sops", **options)
+    return configure_provider(provider, settings)
+
+
+__all__ = ["SecretResolver", "get_secret_resolver"]

kstlib/secrets/sensitive.py

@@ -0,0 +1,130 @@
+"""Helpers that minimise the footprint of decrypted secrets.
+
+The :func:`sensitive` context manager temporarily exposes a secret value and
+then attempts to scrub it from memory, clear provider caches, and drop any
+remaining references.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable, Iterator, Mapping, Sequence
+from contextlib import contextmanager, suppress
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Protocol, cast
+
+if TYPE_CHECKING:
+    from kstlib.secrets.models import SecretRecord
+
+logger = logging.getLogger(__name__)
+
+LegacyPurge = Callable[[], None]
+
+
+class CachePurgeProtocol(Protocol):  # pylint: disable=too-few-public-methods
+    """Protocol implemented by providers exposing a cache purge hook."""
+
+    def purge_cache(self, *, path: str | Path | None = None) -> None:  # pragma: no cover - protocol stub
+        """Clear cached decrypted material."""
+
+
+@contextmanager
+def sensitive(
+    record: SecretRecord,
+    *,
+    providers: Sequence[CachePurgeProtocol] | None = None,
+) -> Iterator[Any]:
+    """Temporarily expose a secret and scrub it afterwards.
+
+    The context manager yields the secret value so it can be used within the
+    protected block. On exit it attempts to overwrite mutable buffers in place,
+    clears provider caches when available, and replaces the value stored in the
+    :class:`SecretRecord` with ``None`` to break lingering references.
+
+    Example:
+        >>> from kstlib.secrets.models import SecretRecord, SecretSource
+        >>> from kstlib.secrets.sensitive import sensitive
+        >>> record = SecretRecord(value=bytearray(b"api-token"), source=SecretSource.SOPS)
+        >>> with sensitive(record) as secret:
+        ...     secret[:3] = b"***"  # handle the secret
+        >>> record.value is None
+        True
+
+    Args:
+        record: Secret wrapped in a :class:`SecretRecord`.
+        providers: Optional providers whose caches should be purged after use.
+
+    Yields:
+        The decrypted secret value.
+    """
+    try:
+        yield record.value
+    finally:
+        _scrub_value(record.value)
+        record.value = None
+        metadata = record.metadata if isinstance(record.metadata, Mapping) else {}
+        _purge_providers(providers, metadata=metadata)
+
+
+def _scrub_value(value: Any) -> None:
+    """Best-effort scrubbing for mutable buffers."""
+    if value is None:
+        return
+    if isinstance(value, bytearray):
+        value[:] = b"\x00" * len(value)
+        return
+    if isinstance(value, memoryview):
+        if not value.readonly:
+            value[:] = b"\x00" * len(value)
+        value.release()
+        return
+    if hasattr(value, "clear") and hasattr(value, "__setitem__"):
+        try:
+            length = len(value)
+        except TypeError:  # pragma: no cover - objects without __len__
+            length = 0
+        for index in range(length):
+            if _try_assign(value, index, 0):
+                continue
+            _try_assign(value, index, None)
+        with suppress(AttributeError, TypeError, ValueError):
+            value.clear()
+
+
+def _purge_providers(
+    providers: Sequence[CachePurgeProtocol] | None,
+    *,
+    metadata: Mapping[str, Any] | None,
+) -> None:
+    """Invoke cache purge hooks for the supplied providers."""
+    if not providers:
+        return
+    path_hint: str | Path | None = None
+    if metadata:
+        candidate = metadata.get("path")
+        if isinstance(candidate, str | Path):
+            path_hint = candidate
+
+    for provider in providers:
+        purge = getattr(provider, "purge_cache", None)
+        if not callable(purge):
+            continue
+        try:
+            purge(path=path_hint)
+        except TypeError:
+            legacy_purge = cast("LegacyPurge", purge)
+            legacy_purge()
+        except (AttributeError, OSError, RuntimeError, ValueError) as error:  # pragma: no cover - defensive logging
+            logger.debug("Provider cache purge failed for %s", provider, exc_info=error)
+
+
+def _try_assign(target: Any, index: int, replacement: Any) -> bool:
+    """Attempt to assign ``replacement`` at ``index`` and report success."""
+    try:
+        target[index] = replacement
+    except (AttributeError, IndexError, KeyError, TypeError, ValueError):
+        return False
+    return True
+
+
+__all__ = ["CachePurgeProtocol", "sensitive"]

kstlib/secure/__init__.py

@@ -0,0 +1,23 @@
+"""Security helpers (filesystem guardrails, policies, and errors)."""
+
+from kstlib.secure import fs as _fs
+from kstlib.secure import permissions as _perms
+
+RELAXED_POLICY = _fs.RELAXED_POLICY
+STRICT_POLICY = _fs.STRICT_POLICY
+GuardPolicy = _fs.GuardPolicy
+PathGuardrails = _fs.PathGuardrails
+PathSecurityError = _fs.PathSecurityError
+
+DirectoryPermissions = _perms.DirectoryPermissions
+FilePermissions = _perms.FilePermissions
+
+__all__ = [
+    "RELAXED_POLICY",
+    "STRICT_POLICY",
+    "DirectoryPermissions",
+    "FilePermissions",
+    "GuardPolicy",
+    "PathGuardrails",
+    "PathSecurityError",
+]