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

kstlib/config/sops.py

@@ -0,0 +1,287 @@
+"""SOPS decryption support for configuration files.
+
+This module provides transparent SOPS decryption for configuration files
+with .sops.yml, .sops.yaml, .sops.json, or .sops.toml extensions.
+
+Features:
+- Automatic detection of SOPS files by extension
+- LRU cache with mtime-based invalidation
+- Graceful degradation when SOPS is not available
+- Warning detection for unencrypted ENC[...] values
+
+Example:
+    >>> from kstlib.config.sops import is_sops_file, get_decryptor
+    >>> from pathlib import Path
+    >>> is_sops_file(Path("secrets.sops.yml"))
+    True
+    >>> is_sops_file(Path("config.yml"))
+    False
+"""
+
+from __future__ import annotations
+
+import logging
+import pathlib
+import shutil
+import subprocess
+from collections import OrderedDict
+from typing import Any
+
+from kstlib.config.exceptions import ConfigSopsError, ConfigSopsNotAvailableError
+from kstlib.limits import (
+    DEFAULT_MAX_SOPS_CACHE_ENTRIES,
+    HARD_MAX_SOPS_CACHE_ENTRIES,
+)
+
+logger = logging.getLogger(__name__)
+
+SOPS_FILE_PATTERNS: tuple[str, ...] = (
+    ".sops.yml",
+    ".sops.yaml",
+    ".sops.json",
+    ".sops.toml",
+)
+
+ENC_MARKER = "ENC[AES256_GCM,"
+
+
+def is_sops_file(path: pathlib.Path) -> bool:
+    """Check if file should be decrypted via SOPS based on extension.
+
+    Args:
+        path: Path to the configuration file.
+
+    Returns:
+        True if the file has a SOPS extension (.sops.yml, .sops.yaml, etc.).
+
+    Examples:
+        >>> from pathlib import Path
+        >>> is_sops_file(Path("secrets.sops.yml"))
+        True
+        >>> is_sops_file(Path("config.yml"))
+        False
+        >>> is_sops_file(Path("data.sops.json"))
+        True
+    """
+    name = path.name.lower()
+    return any(name.endswith(ext) for ext in SOPS_FILE_PATTERNS)
+
+
+def get_real_extension(path: pathlib.Path) -> str:
+    """Extract actual format extension, ignoring .sops prefix.
+
+    For SOPS files like 'secrets.sops.yml', returns '.yml'.
+    For non-SOPS files, returns the normal suffix.
+
+    Args:
+        path: Path to the configuration file.
+
+    Returns:
+        The real format extension (e.g., '.yml', '.json', '.toml').
+
+    Examples:
+        >>> from pathlib import Path
+        >>> get_real_extension(Path("secrets.sops.yml"))
+        '.yml'
+        >>> get_real_extension(Path("config.sops.json"))
+        '.json'
+        >>> get_real_extension(Path("normal.yml"))
+        '.yml'
+    """
+    name = path.name.lower()
+    for marker in (".sops", ".enc"):
+        if marker in name:
+            idx = name.rfind(marker)
+            return name[idx + len(marker) :]
+    return path.suffix.lower()
+
+
+def has_encrypted_values(data: Any, path: str = "") -> list[str]:
+    """Recursively find keys containing ENC[AES256_GCM,...] values.
+
+    This function detects SOPS-encrypted values that were not decrypted,
+    typically because the file was loaded without SOPS decryption.
+
+    Args:
+        data: The parsed configuration data to inspect.
+        path: Current key path (for recursion, start with empty string).
+
+    Returns:
+        List of dotted key paths containing encrypted values.
+
+    Examples:
+        >>> has_encrypted_values({"key": "ENC[AES256_GCM,data...]"})
+        ['key']
+        >>> has_encrypted_values({"db": {"password": "ENC[AES256_GCM,...]"}})
+        ['db.password']
+        >>> has_encrypted_values({"normal": "value"})
+        []
+    """
+    found: list[str] = []
+    if isinstance(data, str) and ENC_MARKER in data:
+        found.append(path or "<root>")
+    elif isinstance(data, dict):
+        for k, v in data.items():
+            found.extend(has_encrypted_values(v, f"{path}.{k}" if path else k))
+    elif isinstance(data, list):
+        for i, item in enumerate(data):
+            found.extend(has_encrypted_values(item, f"{path}[{i}]"))
+    return found
+
+
+class SopsDecryptor:
+    """Lightweight SOPS decryptor with LRU cache.
+
+    This class provides SOPS file decryption with:
+    - Configurable binary path
+    - LRU cache with mtime-based invalidation
+    - Clear error messages for troubleshooting
+
+    Attributes:
+        binary: Name or path of the SOPS binary.
+        max_cache: Maximum cache entries (clamped to hard limit).
+
+    Examples:
+        >>> decryptor = SopsDecryptor()  # doctest: +SKIP
+        >>> content = decryptor.decrypt_file(Path("secrets.sops.yml"))  # doctest: +SKIP
+    """
+
+    def __init__(
+        self,
+        binary: str = "sops",
+        max_cache_entries: int = DEFAULT_MAX_SOPS_CACHE_ENTRIES,
+    ) -> None:
+        """Initialize the SOPS decryptor.
+
+        Args:
+            binary: Name or path of the SOPS binary.
+            max_cache_entries: Maximum number of cached decrypted files.
+        """
+        self._binary = binary
+        self._max_cache = min(max_cache_entries, HARD_MAX_SOPS_CACHE_ENTRIES)
+        self._cache: OrderedDict[pathlib.Path, tuple[float, str]] = OrderedDict()
+
+    @property
+    def binary(self) -> str:
+        """Return the configured SOPS binary name."""
+        return self._binary
+
+    @property
+    def max_cache(self) -> int:
+        """Return the maximum cache size."""
+        return self._max_cache
+
+    def decrypt_file(self, path: pathlib.Path) -> str:
+        """Decrypt a SOPS-encrypted file and return content as string.
+
+        Args:
+            path: Path to the SOPS-encrypted file.
+
+        Returns:
+            Decrypted file content as a string.
+
+        Raises:
+            ConfigSopsNotAvailableError: If SOPS binary is not found.
+            ConfigSopsError: If decryption fails.
+        """
+        resolved = path.resolve()
+        mtime = resolved.stat().st_mtime
+
+        # Cache hit?
+        cached = self._cache.get(resolved)
+        if cached and cached[0] == mtime:
+            self._cache.move_to_end(resolved)
+            logger.debug("SOPS cache hit for: %s", path.name)
+            return cached[1]
+
+        # Find binary
+        binary_path = shutil.which(self._binary)
+        if binary_path is None:
+            raise ConfigSopsNotAvailableError(
+                f"SOPS binary '{self._binary}' not found in PATH. Install from https://github.com/getsops/sops"
+            )
+
+        # Decrypt - binary_path is validated via shutil.which()
+        # resolved is a Path object from user config (trusted source)
+        result = subprocess.run(
+            [binary_path, "--decrypt", str(resolved)],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=30,
+        )
+
+        if result.returncode != 0:
+            raise ConfigSopsError(f"Failed to decrypt '{path.name}': {result.stderr.strip()}")
+
+        content = result.stdout
+
+        # Update cache with LRU eviction
+        self._cache[resolved] = (mtime, content)
+        self._cache.move_to_end(resolved)
+        while len(self._cache) > self._max_cache:
+            self._cache.popitem(last=False)
+
+        logger.debug("SOPS decrypted and cached: %s", path.name)
+        return content
+
+    def purge_cache(self, path: pathlib.Path | None = None) -> None:
+        """Clear cache entries.
+
+        Args:
+            path: If provided, only clear this specific path.
+                  If None, clear all cached entries.
+        """
+        if path is None:
+            self._cache.clear()
+            logger.debug("SOPS cache cleared")
+        else:
+            removed = self._cache.pop(path.resolve(), None)
+            if removed:
+                logger.debug("SOPS cache entry removed: %s", path.name)
+
+    @property
+    def cache_size(self) -> int:
+        """Return the current number of cached entries."""
+        return len(self._cache)
+
+
+# Global singleton
+_decryptor: SopsDecryptor | None = None
+
+
+def get_decryptor(binary: str = "sops") -> SopsDecryptor:
+    """Get or create global SOPS decryptor singleton.
+
+    Args:
+        binary: SOPS binary name (only used on first call).
+
+    Returns:
+        The global SopsDecryptor instance.
+
+    Examples:
+        >>> decryptor = get_decryptor()  # doctest: +SKIP
+        >>> content = decryptor.decrypt_file(path)  # doctest: +SKIP
+    """
+    global _decryptor
+    if _decryptor is None:
+        _decryptor = SopsDecryptor(binary=binary)
+    return _decryptor
+
+
+def reset_decryptor() -> None:
+    """Reset the global decryptor singleton (for testing)."""
+    global _decryptor
+    _decryptor = None
+
+
+__all__ = [
+    "ENC_MARKER",
+    "SOPS_FILE_PATTERNS",
+    "SopsDecryptor",
+    "get_decryptor",
+    "get_real_extension",
+    "has_encrypted_values",
+    "is_sops_file",
+    "reset_decryptor",
+]

kstlib/db/__init__.py

@@ -0,0 +1,54 @@
+"""Async database module for SQLite/SQLCipher.
+
+Provides:
+- AsyncDatabase: High-level async interface
+- ConnectionPool: Connection pooling with retry
+- SQLCipher encryption via SOPS integration
+
+Examples:
+    Basic in-memory database:
+
+    >>> from kstlib.db import AsyncDatabase
+    >>> db = AsyncDatabase(":memory:")
+
+    Encrypted database with SOPS:
+
+    >>> db = AsyncDatabase(  # doctest: +SKIP
+    ...     "app.db",
+    ...     cipher_sops="secrets.yml",
+    ...     cipher_sops_key="database_key"
+    ... )
+
+    Usage as context manager:
+
+    >>> async with AsyncDatabase(":memory:") as db:  # doctest: +SKIP
+    ...     await db.execute("CREATE TABLE test (id INTEGER)")
+    ...     await db.execute("INSERT INTO test VALUES (?)", (1,))
+    ...     row = await db.fetch_one("SELECT * FROM test")
+"""
+
+from kstlib.db.aiosqlcipher import is_sqlcipher_available
+from kstlib.db.cipher import apply_cipher_key, resolve_cipher_key
+from kstlib.db.database import AsyncDatabase
+from kstlib.db.exceptions import (
+    DatabaseConnectionError,
+    DatabaseError,
+    EncryptionError,
+    PoolExhaustedError,
+    TransactionError,
+)
+from kstlib.db.pool import ConnectionPool, PoolStats
+
+__all__ = [
+    "AsyncDatabase",
+    "ConnectionPool",
+    "DatabaseConnectionError",
+    "DatabaseError",
+    "EncryptionError",
+    "PoolExhaustedError",
+    "PoolStats",
+    "TransactionError",
+    "apply_cipher_key",
+    "is_sqlcipher_available",
+    "resolve_cipher_key",
+]

kstlib/db/aiosqlcipher.py

@@ -0,0 +1,137 @@
+"""Async SQLCipher wrapper built on top of aiosqlite.
+
+Provides async database connections with SQLCipher AES-256 encryption.
+This module wraps aiosqlite to use sqlcipher3 instead of standard sqlite3.
+
+Requirements:
+    pip install kstlib[db-crypto]  # Installs sqlcipher3
+
+Examples:
+    Basic encrypted connection::
+
+        import asyncio
+        from kstlib.db.aiosqlcipher import connect
+
+        async def main():
+            async with connect(":memory:", cipher_key="secret") as db:
+                await db.execute("CREATE TABLE test (id INTEGER)")
+
+        asyncio.run(main())
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from kstlib.db.exceptions import EncryptionError
+
+if TYPE_CHECKING:
+    from aiosqlite import Connection
+
+__all__ = ["connect", "is_sqlcipher_available"]
+
+log = logging.getLogger(__name__)
+
+
+def is_sqlcipher_available() -> bool:
+    """Check if sqlcipher3 is installed and available.
+
+    Returns:
+        True if sqlcipher3 can be imported.
+
+    Examples:
+        >>> is_sqlcipher_available()  # doctest: +SKIP
+        True
+    """
+    try:
+        import sqlcipher3  # noqa: F401
+
+        return True
+    except ImportError:
+        return False
+
+
+def connect(
+    database: str | Path,
+    *,
+    cipher_key: str,
+    iter_chunk_size: int = 64,
+    **kwargs: Any,
+) -> Connection:
+    """Create an async connection to an encrypted SQLite database.
+
+    This function is a drop-in replacement for aiosqlite.connect() that
+    uses SQLCipher for AES-256 encryption. The cipher key is applied
+    immediately after connection using PRAGMA key.
+
+    Args:
+        database: Path to database file or ":memory:" for in-memory.
+        cipher_key: Encryption key for SQLCipher (required).
+        iter_chunk_size: Rows to fetch per iteration (default: 64).
+        **kwargs: Additional arguments passed to sqlcipher3.connect().
+
+    Returns:
+        Async Connection object (same interface as aiosqlite.Connection).
+
+    Raises:
+        EncryptionError: If sqlcipher3 is not installed or key is empty.
+        sqlite3.DatabaseError: If database exists but key is wrong.
+
+    Examples:
+        >>> async with connect("app.db", cipher_key="secret") as db:  # doctest: +SKIP
+        ...     await db.execute("CREATE TABLE users (id INTEGER)")
+
+        >>> # With SOPS key resolution:
+        >>> from kstlib.db.cipher import resolve_cipher_key
+        >>> key = resolve_cipher_key(sops_path="secrets.yml")  # doctest: +SKIP
+        >>> async with connect("app.db", cipher_key=key) as db:  # doctest: +SKIP
+        ...     pass
+    """
+    if not cipher_key:
+        raise EncryptionError("cipher_key is required for encrypted connections")
+
+    # Import sqlcipher3 (fail early if not installed)
+    try:
+        import sqlcipher3
+    except ImportError as e:
+        raise EncryptionError("sqlcipher3 is not installed. Install with: pip install kstlib[db-crypto]") from e
+
+    # Import aiosqlite Connection class (we reuse its async machinery)
+    from aiosqlite.core import Connection
+
+    # Resolve path
+    db_path = str(database) if isinstance(database, Path) else database
+
+    def connector() -> sqlcipher3.Connection:
+        """Create encrypted connection with key already applied.
+
+        This runs in a worker thread (via aiosqlite).
+        """
+        # Enable autocommit by default (isolation_level=None)
+        # This ensures data is persisted immediately without explicit commit
+        # User can override by passing isolation_level in kwargs
+        connect_kwargs = {"isolation_level": None, **kwargs}
+
+        # Connect using sqlcipher3 (NOT standard sqlite3)
+        conn = sqlcipher3.connect(db_path, **connect_kwargs)
+
+        # Apply encryption key (MUST be first operation)
+        # Escape single quotes to prevent SQL injection
+        escaped_key = cipher_key.replace("'", "''")
+        conn.execute(f"PRAGMA key = '{escaped_key}'")
+
+        # Verify key works by reading schema
+        # This will raise DatabaseError if key is wrong
+        try:
+            conn.execute("SELECT count(*) FROM sqlite_master")
+        except Exception as e:
+            conn.close()
+            raise EncryptionError(f"Invalid cipher key or corrupted database: {e}") from e
+
+        log.debug("SQLCipher connection established: %s", db_path)
+        return conn
+
+    # Return aiosqlite Connection with our custom connector
+    return Connection(connector, iter_chunk_size)

kstlib/db/cipher.py

@@ -0,0 +1,112 @@
+"""SQLCipher integration with SOPS secret resolution.
+
+Provides secure key management for encrypted SQLite databases.
+Keys can be loaded from:
+- Direct passphrase
+- Environment variable
+- SOPS-encrypted file via kstlib.secrets
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from kstlib.db.exceptions import EncryptionError
+
+if TYPE_CHECKING:
+    import sqlite3
+    from pathlib import Path
+
+log = logging.getLogger(__name__)
+
+
+def resolve_cipher_key(
+    *,
+    passphrase: str | None = None,
+    env_var: str | None = None,
+    sops_path: str | Path | None = None,
+    sops_key: str = "db_key",
+) -> str:
+    """Resolve encryption key from various sources.
+
+    Priority: passphrase > env_var > sops_path
+
+    Args:
+        passphrase: Direct passphrase string.
+        env_var: Environment variable name containing the key.
+        sops_path: Path to SOPS-encrypted file.
+        sops_key: Key name within SOPS file (default: "db_key").
+
+    Returns:
+        Resolved encryption key.
+
+    Raises:
+        EncryptionError: If no key source provided or resolution fails.
+
+    Examples:
+        >>> key = resolve_cipher_key(passphrase="my-secret-key")
+        >>> len(key) > 0
+        True
+    """
+    # Direct passphrase (highest priority)
+    if passphrase:
+        return passphrase
+
+    # Environment variable
+    if env_var:
+        import os
+
+        key = os.environ.get(env_var)
+        if key:
+            log.debug("Resolved cipher key from env var: %s", env_var)
+            return key
+        raise EncryptionError(f"Environment variable '{env_var}' not set or empty")
+
+    # SOPS file
+    if sops_path:
+        try:
+            from kstlib.secrets.models import SecretRequest
+            from kstlib.secrets.providers.sops import SOPSProvider
+
+            provider = SOPSProvider(path=sops_path)
+            request = SecretRequest(name=sops_key, required=True)
+            record = provider.resolve(request)
+            if record is None or record.value is None:
+                raise EncryptionError(f"Key '{sops_key}' not found in SOPS file")
+            log.debug("Resolved cipher key from SOPS: %s", sops_path)
+            return str(record.value)
+        except ImportError as e:
+            raise EncryptionError("kstlib.secrets required for SOPS support") from e
+        except Exception as e:
+            raise EncryptionError(f"Failed to resolve SOPS key: {e}") from e
+
+    raise EncryptionError("No encryption key source provided. Specify passphrase, env_var, or sops_path.")
+
+
+def apply_cipher_key(conn: sqlite3.Connection, key: str) -> None:
+    """Apply SQLCipher key to a connection.
+
+    Args:
+        conn: SQLite connection object.
+        key: Encryption key to apply.
+
+    Raises:
+        EncryptionError: If key application fails.
+    """
+    try:
+        # SQLCipher PRAGMA to set key
+        # Escape single quotes to prevent SQL injection
+        escaped_key = key.replace("'", "''")
+        cursor = conn.execute(f"PRAGMA key = '{escaped_key}'")
+        cursor.close()
+        # Verify key works by reading schema
+        cursor = conn.execute("SELECT count(*) FROM sqlite_master")
+        cursor.fetchone()
+        cursor.close()
+        log.debug("SQLCipher key applied successfully")
+    except Exception as e:
+        raise EncryptionError(f"Failed to apply cipher key: {e}") from e
+
+
+__all__ = ["apply_cipher_key", "resolve_cipher_key"]