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

kstlib/cli/commands/secrets/encrypt.py

@@ -0,0 +1,242 @@
+"""Encrypt command for secrets subsystem."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import typer
+
+from kstlib.cli.common import (
+    CommandResult,
+    CommandStatus,
+    console,
+    exit_with_result,
+    render_result,
+)
+
+from .common import (
+    AGE_RECIPIENT_OPTION,
+    CONFIG_OPTION,
+    DATA_KEY_OPTION,
+    ENCRYPT_SOURCE_ARG,
+    FORCE_OPTION,
+    FORMATS_OPTION,
+    KMS_KEY_OPTION,
+    OUT_OPTION,
+    QUIET_OPTION,
+    SHRED_CHUNK_SIZE_OPTION,
+    SHRED_METHOD_OPTION,
+    SHRED_OPTION,
+    SHRED_PASSES_OPTION,
+    SHRED_ZERO_LAST_OPTION,
+    EncryptCommandOptions,
+    SecureDeleteCLIOptions,
+    format_arguments,
+    resolve_sops_binary,
+    run_sops_command,
+    shred_file,
+)
+
+if TYPE_CHECKING:
+    from subprocess import CompletedProcess
+
+    from kstlib.utils.secure_delete import SecureDeleteReport
+
+
+def _ensure_encrypt_destination(options: EncryptCommandOptions) -> None:
+    """Abort when the target output is not writable."""
+    if options.out is None or not options.out.exists() or options.force:
+        return
+
+    result = CommandResult(
+        status=CommandStatus.ERROR,
+        message=f"Refuse to overwrite existing file: {options.out} (use --force).",
+    )
+    exit_with_result(result, options.quiet, exit_code=1)
+
+
+def _run_encrypt_command(source: Path, options: EncryptCommandOptions) -> CompletedProcess[str]:
+    """Execute the ``sops`` encryption command and handle failures."""
+    try:
+        completed = run_sops_command(
+            options.binary,
+            _build_encrypt_args(source, options),
+        )
+    except FileNotFoundError as exc:
+        result = CommandResult(
+            status=CommandStatus.ERROR,
+            message=(f"SOPS binary '{options.binary}' not found. Install it or set secrets.sops.binary in the config."),
+        )
+        exit_with_result(result, options.quiet, exit_code=1, cause=exc)
+
+    if completed.returncode != 0:
+        message = completed.stderr.strip() or completed.stdout.strip() or "sops command failed"
+        result = CommandResult(status=CommandStatus.ERROR, message=message)
+        exit_with_result(result, options.quiet, exit_code=1)
+
+    return completed
+
+
+def _maybe_print_encrypt_output(completed: CompletedProcess[str], options: EncryptCommandOptions) -> None:
+    """Display stdout emitted by ``sops`` when appropriate."""
+    if options.out is not None:
+        return
+    if options.quiet or not completed.stdout:
+        return
+    console.print(completed.stdout.rstrip("\n"))
+
+
+def _handle_shred_request(source: Path, options: EncryptCommandOptions) -> SecureDeleteReport | None:
+    """Perform secure delete when requested, aborting on failure."""
+    if not options.shred.enabled:
+        return None
+
+    shred_opts = options.shred
+    report = shred_file(
+        source,
+        method=shred_opts.method,
+        passes=shred_opts.passes,
+        zero_last_pass=shred_opts.zero_last_pass,
+        chunk_size=shred_opts.chunk_size,
+    )
+
+    if report.success:
+        return report
+
+    reason = f" {report.message}" if report.message else ""
+    result = CommandResult(
+        status=CommandStatus.ERROR,
+        message=f"Failed to remove cleartext source '{source}'.{reason}",
+    )
+    return exit_with_result(result, options.quiet, exit_code=1)
+
+
+def _compose_encrypt_success_message(
+    source: Path,
+    options: EncryptCommandOptions,
+    report: SecureDeleteReport | None,
+) -> str:
+    """Return the final success message for ``encrypt``."""
+    target_info = str(options.out) if options.out else "stdout"
+    message = f"Encrypted secrets written to {target_info}."
+
+    if report is not None:
+        detail = f"{report.method.value} ({report.passes} passes)"
+        if report.command:
+            detail += f" via {' '.join(report.command)}"
+        return message + f" Cleartext source '{source}' removed using {detail}."
+
+    if not options.shred.enabled:
+        message += f" Cleartext source '{source}' still exists; run 'kstlib secrets shred {source}' to remove it."
+
+    return message
+
+
+def _build_encrypt_args(
+    source: Path,
+    options: EncryptCommandOptions,
+) -> list[str]:
+    """Build arguments for ``sops --encrypt``."""
+    arguments = _base_encrypt_args(options)
+    arguments.extend(format_arguments(*options.formats))
+    arguments.extend(_recipient_flags(options))
+    arguments.extend(_key_flags(options))
+    arguments.append(str(source))
+    return arguments
+
+
+def _base_encrypt_args(options: EncryptCommandOptions) -> list[str]:
+    """Return base arguments shared by every encrypt invocation."""
+    arguments: list[str] = []
+    if options.config is not None:
+        arguments.extend(["--config", str(options.config)])
+    arguments.append("--encrypt")
+    if options.out is not None:
+        arguments.extend(["--output", str(options.out)])
+    return arguments
+
+
+def _recipient_flags(options: EncryptCommandOptions) -> list[str]:
+    """Return age or KMS recipient flag arguments."""
+    arguments: list[str] = []
+    if options.age_recipients:
+        for recipient in options.age_recipients:
+            arguments.extend(["--age", recipient])
+    if options.kms_keys:
+        for kms_key in options.kms_keys:
+            arguments.extend(["--kms", kms_key])
+    return arguments
+
+
+def _key_flags(options: EncryptCommandOptions) -> list[str]:
+    """Return raw data key flag arguments."""
+    arguments: list[str] = []
+    if options.data_keys:
+        for data_key in options.data_keys:
+            arguments.extend(["--key", data_key])
+    return arguments
+
+
+def _execute_encrypt(source: Path, options: EncryptCommandOptions) -> None:
+    """Perform the encryption workflow using the provided options."""
+    _ensure_encrypt_destination(options)
+    completed = _run_encrypt_command(source, options)
+    _maybe_print_encrypt_output(completed, options)
+    shred_report = _handle_shred_request(source, options)
+    message = _compose_encrypt_success_message(source, options, shred_report)
+    result = CommandResult(status=CommandStatus.OK, message=message)
+    if options.quiet:
+        raise typer.Exit(code=0)
+    render_result(result)
+
+
+# pylint: disable=too-many-arguments,too-many-positional-arguments,too-many-locals
+def encrypt(
+    source: Path = ENCRYPT_SOURCE_ARG,
+    *,
+    out: Path | None = OUT_OPTION,
+    config: Path | None = CONFIG_OPTION,
+    formats: tuple[str, str] = FORMATS_OPTION,
+    force: bool = FORCE_OPTION,
+    quiet: bool = QUIET_OPTION,
+    shred_enabled: bool = SHRED_OPTION,
+    shred_method: str | None = SHRED_METHOD_OPTION,
+    shred_passes: int | None = SHRED_PASSES_OPTION,
+    shred_zero_last_pass: bool | None = SHRED_ZERO_LAST_OPTION,
+    shred_chunk_size: int | None = SHRED_CHUNK_SIZE_OPTION,
+    age_recipient: list[str] | None = AGE_RECIPIENT_OPTION,
+    kms_key: list[str] | None = KMS_KEY_OPTION,
+    key: list[str] | None = DATA_KEY_OPTION,
+) -> None:
+    """Encrypt a cleartext file using sops."""
+    binary = resolve_sops_binary()
+    effective_config = config
+    if effective_config is None:
+        default_config = Path.home() / ".sops.yaml"
+        if default_config.exists():
+            effective_config = default_config
+
+    options = EncryptCommandOptions(
+        out=out,
+        binary=binary,
+        config=effective_config,
+        formats=formats,
+        force=force,
+        quiet=quiet,
+        shred=SecureDeleteCLIOptions(
+            enabled=shred_enabled,
+            method=shred_method,
+            passes=shred_passes,
+            zero_last_pass=shred_zero_last_pass,
+            chunk_size=shred_chunk_size,
+        ),
+        age_recipients=tuple(age_recipient or []),
+        kms_keys=tuple(kms_key or []),
+        data_keys=tuple(key or []),
+    )
+
+    _execute_encrypt(source, options)
+
+
+__all__ = ["encrypt"]

kstlib/cli/commands/secrets/shred.py

@@ -0,0 +1,96 @@
+"""Shred command for secrets subsystem."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import typer
+
+from kstlib.cli.common import (
+    CommandResult,
+    CommandStatus,
+    exit_with_result,
+    render_result,
+)
+
+from .common import (
+    SHRED_CMD_CHUNK_SIZE_OPTION,
+    SHRED_CMD_METHOD_OPTION,
+    SHRED_CMD_PASSES_OPTION,
+    SHRED_CMD_QUIET_OPTION,
+    SHRED_CMD_ZERO_LAST_OPTION,
+    SHRED_FORCE_OPTION,
+    SHRED_TARGET_ARG,
+    ShredCommandOptions,
+    shred_file,
+)
+
+if TYPE_CHECKING:
+    from pathlib import Path
+else:  # pragma: no cover - runtime alias for Typer conversions
+    import pathlib
+
+    Path = pathlib.Path
+
+
+def _execute_shred(target: Path, options: ShredCommandOptions) -> None:
+    """Perform the shredding workflow using the provided options."""
+    if not options.force:
+        confirmed = typer.confirm(f"Remove '{target}' permanently?", default=False)
+        if not confirmed:
+            result = CommandResult(
+                status=CommandStatus.WARNING,
+                message=f"Shred aborted; file '{target}' not removed.",
+            )
+            exit_with_result(result, options.quiet, exit_code=1)
+
+    report = shred_file(
+        target,
+        method=options.method,
+        passes=options.passes,
+        zero_last_pass=options.zero_last_pass,
+        chunk_size=options.chunk_size,
+    )
+    if not report.success:
+        result = CommandResult(
+            status=CommandStatus.ERROR,
+            message=report.message or f"Failed to remove '{target}'. Check permissions and try again.",
+        )
+        exit_with_result(result, options.quiet, exit_code=1)
+
+    detail = f"{report.method.value} ({report.passes} passes)"
+    if report.command:
+        detail += f" via {' '.join(report.command)}"
+    result = CommandResult(
+        status=CommandStatus.OK,
+        message=f"Secret file '{target}' removed using {detail}.",
+    )
+    if options.quiet:
+        raise typer.Exit(code=0)
+    render_result(result)
+
+
+# pylint: disable=too-many-arguments,too-many-positional-arguments
+def shred(
+    target: Path = SHRED_TARGET_ARG,
+    *,
+    force: bool = SHRED_FORCE_OPTION,
+    method: str | None = SHRED_CMD_METHOD_OPTION,
+    passes: int | None = SHRED_CMD_PASSES_OPTION,
+    zero_last_pass: bool | None = SHRED_CMD_ZERO_LAST_OPTION,
+    chunk_size: int | None = SHRED_CMD_CHUNK_SIZE_OPTION,
+    quiet: bool = SHRED_CMD_QUIET_OPTION,
+) -> None:
+    """Remove a secrets file from disk."""
+    options = ShredCommandOptions(
+        force=force,
+        method=method,
+        passes=passes,
+        zero_last_pass=zero_last_pass,
+        chunk_size=chunk_size,
+        quiet=quiet,
+    )
+    _execute_shred(target, options)
+
+
+__all__ = ["shred"]

kstlib/cli/common.py

@@ -0,0 +1,86 @@
+"""Shared CLI utilities for kstlib commands."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, NoReturn
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.pretty import Pretty
+
+console = Console()
+
+
+class CommandStatus(str, Enum):
+    """Represents the outcome of a CLI command."""
+
+    OK = "ok"
+    WARNING = "warning"
+    ERROR = "error"
+
+
+@dataclass(slots=True)
+class CommandResult:
+    """Summary payload produced by a command handler."""
+
+    status: CommandStatus
+    message: str
+    payload: dict[str, Any] | None = None
+
+
+STYLE_MAP = {
+    CommandStatus.OK: "green",
+    CommandStatus.WARNING: "yellow",
+    CommandStatus.ERROR: "red",
+}
+
+
+def render_result(result: CommandResult) -> None:
+    """Render a command result using Rich components."""
+    style = STYLE_MAP[result.status]
+    console.print(Panel(result.message, title=result.status.value.upper(), style=style, border_style=style))
+    if result.payload is not None:
+        console.print(Pretty(result.payload))
+
+
+def emit_result(result: CommandResult, quiet: bool) -> None:
+    """Output a command result honoring the quiet flag."""
+    if quiet:
+        console.print(result.message, style=STYLE_MAP[result.status])
+    else:
+        render_result(result)
+
+
+def exit_with_result(
+    result: CommandResult,
+    quiet: bool,
+    exit_code: int,
+    *,
+    cause: Exception | None = None,
+) -> NoReturn:
+    """Render ``result`` and raise ``typer.Exit`` with ``exit_code``."""
+    emit_result(result, quiet)
+    if cause is None:
+        raise typer.Exit(code=exit_code)
+    raise typer.Exit(code=exit_code) from cause
+
+
+def exit_error(message: str) -> NoReturn:
+    """Render an error result and exit with code 1."""
+    render_result(CommandResult(status=CommandStatus.ERROR, message=message))
+    raise typer.Exit(code=1)
+
+
+__all__ = [
+    "STYLE_MAP",
+    "CommandResult",
+    "CommandStatus",
+    "console",
+    "emit_result",
+    "exit_error",
+    "exit_with_result",
+    "render_result",
+]

kstlib/config/__init__.py

@@ -0,0 +1,76 @@
+"""Configuration management module.
+
+This module provides flexible configuration loading from various file formats
+with support for includes, environment variables, and cascading search.
+
+SOPS Integration:
+    Files with .sops.yml, .sops.yaml, .sops.json, or .sops.toml extensions
+    are automatically decrypted via the SOPS binary when loaded.
+"""
+
+# pylint: disable=duplicate-code
+from kstlib.config.exceptions import (
+    ConfigCircularIncludeError,
+    ConfigError,
+    ConfigFileNotFoundError,
+    ConfigFormatError,
+    ConfigIncludeDepthError,
+    ConfigNotLoadedError,
+    ConfigSopsError,
+    ConfigSopsNotAvailableError,
+    KstlibError,
+)
+from kstlib.config.export import (
+    ConfigExportError,
+    ConfigExportOptions,
+    ConfigExportResult,
+    export_configuration,
+)
+from kstlib.config.loader import (
+    CONFIG_FILENAME,
+    ConfigLoader,
+    clear_config,
+    get_config,
+    load_config,
+    load_from_env,
+    load_from_file,
+    require_config,
+)
+from kstlib.config.sops import (
+    SopsDecryptor,
+    get_decryptor,
+    get_real_extension,
+    has_encrypted_values,
+    is_sops_file,
+    reset_decryptor,
+)
+
+__all__ = [
+    "CONFIG_FILENAME",
+    "ConfigCircularIncludeError",
+    "ConfigError",
+    "ConfigExportError",
+    "ConfigExportOptions",
+    "ConfigExportResult",
+    "ConfigFileNotFoundError",
+    "ConfigFormatError",
+    "ConfigIncludeDepthError",
+    "ConfigLoader",
+    "ConfigNotLoadedError",
+    "ConfigSopsError",
+    "ConfigSopsNotAvailableError",
+    "KstlibError",
+    "SopsDecryptor",
+    "clear_config",
+    "export_configuration",
+    "get_config",
+    "get_decryptor",
+    "get_real_extension",
+    "has_encrypted_values",
+    "is_sops_file",
+    "load_config",
+    "load_from_env",
+    "load_from_file",
+    "require_config",
+    "reset_decryptor",
+]

kstlib/config/exceptions.py

@@ -0,0 +1,110 @@
+"""
+Exception hierarchy for kstlib.
+
+All kstlib exceptions inherit from KstlibError, allowing users to catch
+all kstlib-specific errors with a single except clause.
+
+Example:
+    try:
+        config = load_config()
+    except KstlibError as e:
+        # Catch any kstlib error
+        print(f"Error: {e}")
+"""
+
+
+class KstlibError(Exception):
+    """
+    Base exception for all kstlib errors.
+
+    All kstlib-specific exceptions inherit from this class,
+    allowing for easy catching of any kstlib error.
+    """
+
+
+# ============================================================================
+# Configuration module exceptions
+# ============================================================================
+
+
+class ConfigError(KstlibError):
+    """
+    Base exception for configuration-related errors.
+
+    All config module exceptions inherit from this class.
+    """
+
+
+class ConfigFileNotFoundError(ConfigError, FileNotFoundError):
+    """
+    Configuration file not found at specified location.
+
+    Raised when attempting to load a config file that doesn't exist.
+    """
+
+
+class ConfigFormatError(ConfigError, ValueError):
+    """
+    Invalid configuration format or unsupported file type.
+
+    Raised when:
+    - File extension is not supported (.xml, etc.)
+    - Format mismatch in strict mode (YAML including JSON)
+    - Invalid content that cannot be parsed
+    """
+
+
+class ConfigCircularIncludeError(ConfigError, ValueError):
+    """
+    Circular include detected in configuration files.
+
+    Raised when an include chain creates a cycle (A includes B, B includes A).
+    """
+
+
+class ConfigIncludeDepthError(ConfigError, ValueError):
+    """
+    Include depth limit exceeded.
+
+    Raised when config includes are nested too deeply, which may indicate
+    a misconfiguration or an attempt to exhaust resources.
+    """
+
+
+class ConfigNotLoadedError(ConfigError, RuntimeError):
+    """
+    Configuration not loaded yet.
+
+    Raised by require_config() when attempting to access config
+    before it has been loaded via get_config() or load_config().
+    """
+
+
+class ConfigSopsError(ConfigError):
+    """
+    SOPS decryption failed for a configuration file.
+
+    Raised when SOPS binary fails to decrypt a .sops.* file.
+    """
+
+
+class ConfigSopsNotAvailableError(ConfigSopsError):
+    """
+    SOPS binary not installed or not found in PATH.
+
+    Raised when attempting to decrypt a .sops.* file but the SOPS
+    binary is not available. Install from https://github.com/getsops/sops
+    """
+
+
+__all__ = [
+    "ConfigCircularIncludeError",
+    "ConfigError",
+    "ConfigFileNotFoundError",
+    "ConfigFormatError",
+    "ConfigIncludeDepthError",
+    "ConfigNotLoadedError",
+    "ConfigSopsError",
+    "ConfigSopsNotAvailableError",
+    "KstlibError",
+]