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

kstlib/secure/fs.py

@@ -0,0 +1,194 @@
+"""Filesystem guardrails utilities for securing file access.
+
+Example:
+    Basic usage with a temporary directory::
+
+        >>> import tempfile
+        >>> from kstlib.secure import PathGuardrails, STRICT_POLICY
+        >>> with tempfile.TemporaryDirectory() as tmpdir:
+        ...     guard = PathGuardrails(tmpdir, policy=STRICT_POLICY)
+        ...     guard.root.is_dir()
+        True
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import Final
+
+from kstlib.secure.permissions import DirectoryPermissions
+
+__all__ = [
+    "RELAXED_POLICY",
+    "STRICT_POLICY",
+    "GuardPolicy",
+    "PathGuardrails",
+    "PathSecurityError",
+]
+
+
+class PathSecurityError(RuntimeError):
+    """Raised when filesystem guardrails detect a security violation."""
+
+
+@dataclass(frozen=True, slots=True)
+class GuardPolicy:
+    """Configuration values defining how guardrails behave.
+
+    Attributes:
+        name: Human-friendly label used for diagnostics.
+        allow_external: When True, paths outside the root are accepted.
+        auto_create_root: Automatically create the root directory when missing.
+        enforce_permissions: Whether POSIX permissions should be validated.
+        max_permission_octal: Maximum allowed permission mask (defaults to PRIVATE).
+
+    Example:
+        >>> from kstlib.secure import GuardPolicy
+        >>> policy = GuardPolicy(name="custom", allow_external=False)
+        >>> policy.name
+        'custom'
+    """
+
+    name: str
+    allow_external: bool = False
+    auto_create_root: bool = True
+    enforce_permissions: bool = True
+    max_permission_octal: int = DirectoryPermissions.PRIVATE  # 0o700
+
+
+STRICT_POLICY: Final[GuardPolicy] = GuardPolicy(name="strict")
+RELAXED_POLICY: Final[GuardPolicy] = GuardPolicy(
+    name="relaxed",
+    allow_external=False,
+    auto_create_root=True,
+    enforce_permissions=False,
+    max_permission_octal=0o777,  # No restrictions
+)
+
+
+class PathGuardrails:
+    """Validate and resolve paths relative to a trusted root.
+
+    Example:
+        >>> import tempfile
+        >>> from kstlib.secure import PathGuardrails, RELAXED_POLICY
+        >>> with tempfile.TemporaryDirectory() as tmpdir:
+        ...     guard = PathGuardrails(tmpdir, policy=RELAXED_POLICY)
+        ...     guard.policy.name
+        'relaxed'
+    """
+
+    def __init__(self, root: str | Path, *, policy: GuardPolicy = STRICT_POLICY) -> None:
+        """Initialise guardrails rooted at *root* while enforcing *policy*.
+
+        Raises:
+            PathSecurityError: If root does not exist or is not a directory.
+        """
+        self._policy = policy
+        expanded = Path(root).expanduser()
+        if policy.auto_create_root:
+            expanded.mkdir(parents=True, exist_ok=True, mode=0o755)
+        self._root = expanded.resolve()
+        if not self._root.exists():
+            raise PathSecurityError(f"Guardrail root does not exist: {self._root}")
+        if not self._root.is_dir():
+            raise PathSecurityError(f"Guardrail root must be a directory: {self._root}")
+        self._harden_permissions(self._root)
+        self._validate_permissions(self._root)
+
+    @property
+    def root(self) -> Path:
+        """Return the resolved guardrail root directory."""
+        return self._root
+
+    @property
+    def policy(self) -> GuardPolicy:
+        """Return the policy associated with the guardrails."""
+        return self._policy
+
+    def resolve_file(self, candidate: str | Path) -> Path:
+        """Resolve *candidate* and ensure it points to an existing file.
+
+        Raises:
+            PathSecurityError: If path is not a file or is outside root.
+        """
+        path = self._resolve(candidate)
+        if not path.is_file():
+            raise PathSecurityError(f"Expected file path but found: {path}")
+        return path
+
+    def resolve_directory(self, candidate: str | Path) -> Path:
+        """Resolve *candidate* and ensure it points to an existing directory.
+
+        Raises:
+            PathSecurityError: If path is not a directory or is outside root.
+        """
+        path = self._resolve(candidate)
+        if not path.is_dir():
+            raise PathSecurityError(f"Expected directory path but found: {path}")
+        return path
+
+    def resolve_path(self, candidate: str | Path) -> Path:
+        """Resolve *candidate* relative to the guardrail root without type checks."""
+        return self._resolve(candidate, require_exists=False)
+
+    def relax(self, *, allow_external: bool | None = None) -> PathGuardrails:
+        """Return a new guardrail instance with adjusted external allowances."""
+        new_policy = replace(
+            self._policy,
+            allow_external=self._policy.allow_external if allow_external is None else allow_external,
+        )
+        return PathGuardrails(self._root, policy=new_policy)
+
+    def _resolve(self, candidate: str | Path, *, require_exists: bool = True) -> Path:
+        path = Path(candidate).expanduser()
+        if not path.is_absolute():
+            path = self._root / path
+        resolved = path.resolve()
+        self._ensure_within_root(resolved)
+        if require_exists and not resolved.exists():
+            raise PathSecurityError(f"Resolved path does not exist: {resolved}")
+        return resolved
+
+    def _ensure_within_root(self, path: Path) -> None:
+        if self._policy.allow_external:
+            return
+        if os.name == "nt" and self._root.drive and path.drive.lower() != self._root.drive.lower():
+            raise PathSecurityError(f"Path is on a different drive: {path}")
+        try:
+            path.relative_to(self._root)
+        except ValueError as exc:
+            raise PathSecurityError(f"Path escapes guardrail root: {path}") from exc
+
+    def _validate_permissions(self, directory: Path) -> None:
+        if not self._policy.enforce_permissions:
+            return
+        if os.name != "posix":
+            return
+        # POSIX-only path - tested with real POSIX tests on Linux/macOS
+        mode = directory.stat().st_mode  # pragma: no cover - POSIX only
+        if stat.S_IMODE(mode) & ~self._policy.max_permission_octal:  # pragma: no cover - POSIX only
+            raise PathSecurityError(  # pragma: no cover - POSIX only
+                f"Directory {directory} exceeds allowed permissions {oct(self._policy.max_permission_octal)}"
+            )
+
+    def _harden_permissions(self, directory: Path) -> None:
+        if not self._policy.enforce_permissions:
+            return
+        if os.name != "posix":
+            return
+        # POSIX-only path - tested with real POSIX tests on Linux/macOS
+        current_mode = stat.S_IMODE(directory.stat().st_mode)  # pragma: no cover - POSIX only
+        allowed_mask = self._policy.max_permission_octal  # pragma: no cover - POSIX only
+        if current_mode & ~allowed_mask == 0:  # pragma: no cover - POSIX only
+            return  # pragma: no cover - POSIX only
+        desired_mode = current_mode & allowed_mask  # pragma: no cover - POSIX only
+        try:  # pragma: no cover - POSIX only
+            directory.chmod(desired_mode)  # pragma: no cover - POSIX only
+        except PermissionError as exc:  # pragma: no cover - POSIX only, env-specific
+            raise PathSecurityError(
+                f"Unable to adjust permissions for {directory}; requires <= {oct(allowed_mask)}"
+            ) from exc

kstlib/secure/permissions.py

@@ -0,0 +1,70 @@
+"""File permission constants for secure file operations.
+
+This module centralizes POSIX permission values to avoid magic numbers
+scattered throughout the codebase.
+
+Note:
+    On Windows, only read-only vs read-write distinction is supported.
+    ``0o400`` becomes ``0o444`` (read-only attribute).
+
+Example:
+    >>> from kstlib.secure.permissions import FilePermissions  # doctest: +SKIP
+    >>> path.chmod(FilePermissions.READONLY)  # doctest: +SKIP
+"""
+
+# pylint: disable=too-few-public-methods
+# Justification: These classes are namespace containers for POSIX permission
+# constants, not behavioral objects. They exist to avoid magic numbers and
+# provide grouped, documented constants (e.g., FilePermissions.READONLY).
+
+from __future__ import annotations
+
+
+class FilePermissions:
+    """POSIX file permission constants.
+
+    Attributes:
+        READONLY: Owner read-only (0o400). Use for sensitive files like tokens,
+            private keys, and secrets. File cannot be modified after creation.
+        READONLY_ALL: Read-only for all users (0o444). Use for public documents
+            like certificates, CSRs, and public keys.
+        OWNER_RW: Owner read-write (0o600). Use for files that need to be
+            modified, or temporarily to unlock read-only files before deletion.
+        OWNER_RWX: Owner read-write-execute (0o700). Use for directories
+            containing sensitive files.
+    """
+
+    # Read-only for owner only - private keys, tokens, secrets
+    READONLY: int = 0o400
+
+    # Read-only for everyone - certificates, public keys
+    READONLY_ALL: int = 0o444
+
+    # Owner read-write - general sensitive files, unlock for deletion
+    OWNER_RW: int = 0o600
+
+    # Owner full access - directories
+    OWNER_RWX: int = 0o700
+
+
+class DirectoryPermissions:
+    """POSIX directory permission constants.
+
+    Attributes:
+        PRIVATE: Owner-only access (0o700). Use for directories containing
+            sensitive files like tokens or secrets.
+        SHARED_READ: Owner full, group/others read+execute (0o755).
+            Use for directories with public content.
+    """
+
+    # Private directory - only owner can access
+    PRIVATE: int = 0o700
+
+    # Shared read - owner full, others can read/traverse
+    SHARED_READ: int = 0o755
+
+
+__all__ = [
+    "DirectoryPermissions",
+    "FilePermissions",
+]

kstlib/ssl.py

@@ -0,0 +1,347 @@
+"""Global SSL configuration for kstlib.
+
+This module provides centralized SSL/TLS configuration with deep defense
+validation for CA bundle paths. All HTTP clients (rapi, auth, alerts)
+can use this module for consistent SSL configuration.
+
+Configuration cascade (highest to lowest priority):
+    1. kwargs passed directly to functions
+    2. Module-specific config (e.g., auth.providers.corporate.ssl_verify)
+    3. Global ssl config from kstlib.conf.yml
+    4. Secure defaults (verify=True)
+
+Example:
+    Global config in kstlib.conf.yml::
+
+        ssl:
+          verify: true
+          ca_bundle: /path/to/ca-bundle.crt  # null by default
+
+    Usage in code::
+
+        from kstlib.ssl import get_ssl_config, build_ssl_context
+
+        # Get global config
+        ssl_cfg = get_ssl_config()
+        print(ssl_cfg.verify)  # True
+
+        # Build context for httpx (respects cascade)
+        verify = build_ssl_context(ssl_verify=False)  # kwargs override
+        async with httpx.AsyncClient(verify=verify) as client:
+            ...
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from kstlib.config import get_config
+from kstlib.logging import TRACE_LEVEL, get_logger
+
+__all__ = [
+    "SSLConfig",
+    "build_ssl_context",
+    "get_ssl_config",
+    "validate_ca_bundle_path",
+    "validate_ssl_verify",
+]
+
+logger = get_logger(__name__)
+
+# Minimum size for a valid PEM certificate (header + minimal content)
+MIN_PEM_SIZE = 50
+
+
+@dataclass(frozen=True, slots=True)
+class SSLConfig:
+    """SSL/TLS configuration container.
+
+    Immutable dataclass holding SSL settings. Use the ``httpx_verify`` property
+    to get the appropriate value for httpx Client/AsyncClient.
+
+    Attributes:
+        verify: Whether to verify SSL certificates.
+        ca_bundle: Path to custom CA bundle file (None = system default).
+
+    Example:
+        >>> config = SSLConfig(verify=True, ca_bundle=None)
+        >>> config.httpx_verify
+        True
+        >>> config = SSLConfig(verify=True, ca_bundle="/path/to/ca.pem")
+        >>> config.httpx_verify
+        '/path/to/ca.pem'
+    """
+
+    verify: bool
+    ca_bundle: str | None
+
+    @property
+    def httpx_verify(self) -> bool | str:
+        """Return the appropriate verify value for httpx.
+
+        If a CA bundle is configured, returns the path string.
+        Otherwise, returns the boolean verify setting.
+
+        Returns:
+            CA bundle path if set, otherwise verify boolean.
+        """
+        if self.ca_bundle:
+            return self.ca_bundle
+        return self.verify
+
+
+def get_ssl_config() -> SSLConfig:
+    """Load SSL configuration from kstlib.conf.yml.
+
+    Returns the global SSL settings from configuration file.
+    Falls back to secure defaults if not configured.
+
+    Returns:
+        SSLConfig with verify and ca_bundle settings.
+
+    Example:
+        >>> config = get_ssl_config()  # doctest: +SKIP
+        >>> config.verify  # doctest: +SKIP
+        True
+    """
+    config = get_config()
+    ssl_section = config.get("ssl", {})  # type: ignore[no-untyped-call]
+
+    verify = ssl_section.get("verify", True)
+    ca_bundle = ssl_section.get("ca_bundle")
+
+    # Validate loaded values
+    verify = validate_ssl_verify(verify)
+
+    if ca_bundle is not None:
+        ca_bundle = validate_ca_bundle_path(ca_bundle)
+
+    return SSLConfig(verify=verify, ca_bundle=ca_bundle)
+
+
+def build_ssl_context(
+    ssl_verify: bool | None = None,
+    ssl_ca_bundle: str | None = None,
+) -> bool | str:
+    """Build SSL context for httpx with cascade priority.
+
+    Cascade order (highest priority first):
+        1. Explicit kwargs (ssl_verify, ssl_ca_bundle)
+        2. Global config from kstlib.conf.yml
+        3. Secure default (verify=True)
+
+    Args:
+        ssl_verify: Override SSL verification (True/False).
+        ssl_ca_bundle: Override CA bundle path.
+
+    Returns:
+        Value suitable for httpx verify parameter:
+        - bool: True/False for system CA verification
+        - str: Path to custom CA bundle
+
+    Example:
+        >>> # Use global config
+        >>> verify = build_ssl_context()  # doctest: +SKIP
+
+        >>> # Override with kwargs
+        >>> verify = build_ssl_context(ssl_verify=False)  # doctest: +SKIP
+        >>> verify  # doctest: +SKIP
+        False
+
+        >>> # Custom CA bundle
+        >>> verify = build_ssl_context(ssl_ca_bundle="/path/to/ca.pem")  # doctest: +SKIP
+    """
+    # Load global config as base
+    global_config = get_ssl_config()
+
+    # Determine effective values (kwargs override global)
+    effective_verify = ssl_verify if ssl_verify is not None else global_config.verify
+    effective_ca_bundle = ssl_ca_bundle if ssl_ca_bundle is not None else global_config.ca_bundle
+
+    # Validate kwargs if provided
+    if ssl_verify is not None:
+        effective_verify = validate_ssl_verify(ssl_verify)
+
+    if ssl_ca_bundle is not None:
+        effective_ca_bundle = validate_ca_bundle_path(ssl_ca_bundle)
+
+    # Build result
+    if effective_ca_bundle:
+        if logger.isEnabledFor(TRACE_LEVEL):
+            logger.log(TRACE_LEVEL, "[SSL] Using CA bundle: %s", effective_ca_bundle)
+        return effective_ca_bundle
+
+    if logger.isEnabledFor(TRACE_LEVEL):
+        logger.log(TRACE_LEVEL, "[SSL] Verify: %s", effective_verify)
+
+    return effective_verify
+
+
+def validate_ssl_verify(value: Any) -> bool:
+    """Validate ssl_verify with strict type check.
+
+    Ensures the value is a boolean and logs a security warning
+    if certificate verification is disabled.
+
+    Args:
+        value: Value to validate (should be bool).
+
+    Returns:
+        Validated boolean value.
+
+    Raises:
+        TypeError: If value is not a bool (YAML may pass "true" string).
+
+    Example:
+        >>> validate_ssl_verify(True)
+        True
+        >>> validate_ssl_verify("true")  # doctest: +IGNORE_EXCEPTION_DETAIL
+        Traceback (most recent call last):
+        TypeError: ssl_verify must be bool, got str: 'true'
+    """
+    if not isinstance(value, bool):
+        msg = f"ssl_verify must be bool, got {type(value).__name__}: {value!r}"
+        raise TypeError(msg)
+
+    if not value:
+        logger.warning(
+            "[SECURITY] ssl_verify=False disables certificate validation. "
+            "This exposes you to MITM attacks. Use only for development."
+        )
+
+    return value
+
+
+def _validate_ca_bundle_string(path_str: str) -> None:
+    """Validate CA bundle path string (layers 1-3).
+
+    Args:
+        path_str: Path string to validate.
+
+    Raises:
+        TypeError: If path is not a string.
+        ValueError: If path contains null bytes or is empty.
+    """
+    # Layer 1: Type check
+    path_value: Any = path_str
+    if not isinstance(path_value, str):
+        msg = f"ssl_ca_bundle must be str, got {type(path_value).__name__}"
+        raise TypeError(msg)
+
+    # Layer 2: Null byte injection
+    if "\x00" in path_str:
+        msg = "ssl_ca_bundle path contains null byte (potential injection attack)"
+        raise ValueError(msg)
+
+    # Layer 3: Empty string
+    if not path_str.strip():
+        msg = "ssl_ca_bundle cannot be empty string"
+        raise ValueError(msg)
+
+
+def _resolve_ca_bundle_path(path_str: str) -> Path:
+    """Resolve CA bundle path (layer 4).
+
+    Args:
+        path_str: Path string to resolve.
+
+    Returns:
+        Resolved Path object.
+
+    Raises:
+        ValueError: If path does not exist or cannot be accessed.
+    """
+    try:
+        return Path(path_str).expanduser().resolve(strict=True)
+    except FileNotFoundError:
+        msg = f"ssl_ca_bundle path does not exist: {path_str}"
+        raise ValueError(msg) from None
+    except OSError as e:
+        msg = f"ssl_ca_bundle path error: {path_str} ({e})"
+        raise ValueError(msg) from None
+
+
+def _validate_ca_bundle_file(ca_path: Path, original_path: str) -> int:
+    """Validate CA bundle file properties (layers 5-7).
+
+    Args:
+        ca_path: Resolved path to CA bundle file.
+        original_path: Original path string for error messages.
+
+    Returns:
+        File size in bytes.
+
+    Raises:
+        ValueError: If file is invalid.
+    """
+    # Layer 5: File type
+    if not ca_path.is_file():
+        msg = f"ssl_ca_bundle must be a file, not directory: {original_path}"
+        raise ValueError(msg)
+
+    # Layer 6: Readable
+    if not os.access(ca_path, os.R_OK):
+        msg = f"ssl_ca_bundle file is not readable: {original_path}"
+        raise ValueError(msg)
+
+    # Layer 7: PEM format validation
+    file_size = ca_path.stat().st_size
+    if file_size < MIN_PEM_SIZE:
+        msg = f"ssl_ca_bundle file too small ({file_size} bytes): {original_path}"
+        raise ValueError(msg)
+
+    try:
+        with ca_path.open("r", encoding="utf-8") as f:
+            header = f.read(1024)
+            if "-----BEGIN" not in header:
+                msg = f"ssl_ca_bundle does not appear to be PEM format: {original_path}"
+                raise ValueError(msg)
+    except UnicodeDecodeError:
+        msg = f"ssl_ca_bundle is not valid text/PEM file: {original_path}"
+        raise ValueError(msg) from None
+
+    return file_size
+
+
+def validate_ca_bundle_path(path_str: str) -> str:
+    """Validate and normalize CA bundle path with deep defense.
+
+    Performs 7 layers of security validation:
+        1. Type check (must be string)
+        2. Null byte injection check
+        3. Empty/whitespace check
+        4. Path existence check
+        5. File type check (not directory)
+        6. Readability check
+        7. PEM format validation
+
+    Args:
+        path_str: Path to CA bundle file.
+
+    Returns:
+        Normalized absolute path (symlinks resolved).
+
+    Raises:
+        TypeError: If path is not a string.
+        ValueError: If validation fails at any layer.
+
+    Example:
+        >>> validate_ca_bundle_path("/etc/ssl/certs/ca-certificates.crt")  # doctest: +SKIP
+        '/etc/ssl/certs/ca-certificates.crt'
+    """
+    # Layers 1-3: String validation
+    _validate_ca_bundle_string(path_str)
+
+    # Layer 4: Path resolution
+    ca_path = _resolve_ca_bundle_path(path_str)
+
+    # Layers 5-7: File validation
+    file_size = _validate_ca_bundle_file(ca_path, path_str)
+
+    if logger.isEnabledFor(TRACE_LEVEL):
+        logger.log(TRACE_LEVEL, "[SSL] CA bundle validated: %s (%d bytes)", ca_path, file_size)
+
+    return str(ca_path)

kstlib/ui/__init__.py

@@ -0,0 +1,23 @@
+"""UI helper utilities for kstlib."""
+
+from kstlib.ui.exceptions import PanelRenderingError, SpinnerError, TableRenderingError
+from kstlib.ui.panels import PanelManager
+from kstlib.ui.spinner import (
+    Spinner,
+    SpinnerAnimationType,
+    SpinnerPosition,
+    SpinnerStyle,
+)
+from kstlib.ui.tables import TableBuilder
+
+__all__ = [
+    "PanelManager",
+    "PanelRenderingError",
+    "Spinner",
+    "SpinnerAnimationType",
+    "SpinnerError",
+    "SpinnerPosition",
+    "SpinnerStyle",
+    "TableBuilder",
+    "TableRenderingError",
+]

kstlib/ui/exceptions.py

@@ -0,0 +1,26 @@
+"""Specialised exceptions raised by the ``kstlib.ui`` helpers."""
+
+from __future__ import annotations
+
+__all__ = [
+    "PanelRenderingError",
+    "SpinnerError",
+    "TableRenderingError",
+]
+
+
+class PanelRenderingError(RuntimeError):
+    """Raised when building a Rich panel fails.
+
+    The error captures situations where the ``PanelManager`` cannot resolve
+    the requested preset, where override values are invalid, or when the
+    payload cannot be converted into a Rich renderable.
+    """
+
+
+class TableRenderingError(RuntimeError):
+    """Raised when building a Rich table fails."""
+
+
+class SpinnerError(RuntimeError):
+    """Raised when the spinner encounters an error."""