ostruct-cli 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

ostruct/cli/path_utils.py

@@ -1,17 +1,16 @@
 """Path validation utilities for the CLI."""
 
-import os
 from pathlib import Path
 from typing import Optional, Tuple
 
-from .errors import (
+from ostruct.cli.errors import (
     DirectoryNotFoundError,
     FileNotFoundError,
-    PathSecurityError,
     VariableNameError,
     VariableValueError,
 )
-from .security import SecurityManager
+from ostruct.cli.security.errors import PathSecurityError, SecurityErrorReasons
+from ostruct.cli.security.security_manager import SecurityManager
 
 
 def validate_path_mapping(
@@ -45,79 +44,61 @@ def validate_path_mapping(
         >>> validate_path_mapping("data=config/", is_dir=True)  # Validates directory
         ('data', 'config/')
     """
+    # Split into name and path parts
     try:
-        if not mapping or "=" not in mapping:
-            raise ValueError("Invalid mapping format")
-
-        name, path = mapping.split("=", 1)
-        if not name:
-            raise VariableNameError(
-                f"Empty name in {'directory' if is_dir else 'file'} mapping"
-            )
-
-        if not path:
-            raise VariableValueError("Path cannot be empty")
-
-        # Expand user home directory and environment variables
-        path = os.path.expanduser(os.path.expandvars(path))
-
-        # Convert to Path object and resolve against base_dir if provided
-        path_obj = Path(path)
-        if base_dir:
-            path_obj = Path(base_dir) / path_obj
-
-        # Resolve the path to catch directory traversal attempts
-        try:
-            resolved_path = path_obj.resolve()
-        except OSError as e:
-            raise OSError(f"Failed to resolve path: {e}")
-
-        # Check if path exists
-        if not resolved_path.exists():
-            if is_dir:
-                raise DirectoryNotFoundError(f"Directory not found: {path!r}")
-            else:
-                raise FileNotFoundError(f"File not found: {path!r}")
-
-        # Check if path is correct type
-        if is_dir and not resolved_path.is_dir():
-            raise DirectoryNotFoundError(f"Path is not a directory: {path!r}")
-        elif not is_dir and not resolved_path.is_file():
-            raise FileNotFoundError(f"Path is not a file: {path!r}")
-
-        # Check if path is accessible
+        name, path_str = mapping.split("=", 1)
+    except ValueError:
+        raise ValueError(f"Invalid mapping format (missing '='): {mapping}")
+
+    # Validate name
+    name = name.strip()
+    if not name:
+        raise VariableNameError("Variable name cannot be empty")
+    if not name.isidentifier():
+        raise VariableNameError(f"Invalid variable name: {name}")
+
+    # Normalize path
+    path_str = path_str.strip()
+    if not path_str:
+        raise VariableValueError("Path cannot be empty")
+
+    # Create a Path object
+    path = Path(path_str)
+    if not path.is_absolute() and base_dir:
+        path = Path(base_dir) / path
+
+    # Validate path with security manager if provided
+    if security_manager:
         try:
-            if is_dir:
-                os.listdir(str(resolved_path))
-            else:
-                with open(str(resolved_path), "r", encoding="utf-8") as f:
-                    f.read(1)
-        except OSError as e:
-            if e.errno == 13:  # Permission denied
+            path = security_manager.validate_path(path)
+        except PathSecurityError as e:
+            if (
+                e.context.get("reason")
+                == SecurityErrorReasons.PATH_OUTSIDE_ALLOWED
+            ):
                 raise PathSecurityError(
-                    f"Permission denied accessing path: {path!r}"
-                )
-            raise
-
-        # Check security constraints
-        if security_manager:
-            if not security_manager.is_path_allowed(str(resolved_path)):
-                raise PathSecurityError.from_expanded_paths(
-                    original_path=str(path),
-                    expanded_path=str(resolved_path),
-                    base_dir=str(security_manager.base_dir),
-                    allowed_dirs=[
-                        str(d) for d in security_manager.allowed_dirs
-                    ],
-                )
-
-        # Return the original path to maintain relative paths in the output
-        return name, path
-
-    except ValueError as e:
-        if "not enough values to unpack" in str(e):
-            raise VariableValueError(
-                f"Invalid {'directory' if is_dir else 'file'} mapping "
-                f"(expected name=path format): {mapping!r}"
-            )
-        raise
+                    f"Path '{path}' is outside the base directory and not in allowed directories",
+                    path=str(path),
+                    context=e.context,
+                ) from e
+            raise PathSecurityError(
+                f"Path validation failed: {e}",
+                path=str(path),
+                context=e.context,
+            ) from e
+
+    # Check path existence and type
+    if not path.exists():
+        if is_dir:
+            raise DirectoryNotFoundError(f"Directory not found: {path}")
+        raise FileNotFoundError(f"File not found: {path}")
+
+    # Check path type
+    if is_dir and not path.is_dir():
+        raise DirectoryNotFoundError(
+            f"Path exists but is not a directory: {path}"
+        )
+    elif not is_dir and not path.is_file():
+        raise FileNotFoundError(f"Path exists but is not a file: {path}")
+
+    return name, str(path)

ostruct/cli/security/__init__.py

@@ -0,0 +1,32 @@
+"""Security package for file access management.
+
+This package provides a comprehensive set of security features for file access:
+- Path normalization and validation
+- Safe path joining
+- Directory traversal prevention
+- Symlink resolution with security checks
+- Case sensitivity handling
+- Temporary path management
+"""
+
+from .allowed_checker import is_path_in_allowed_dirs
+from .case_manager import CaseManager
+from .errors import (
+    DirectoryNotFoundError,
+    PathSecurityError,
+    SecurityErrorReasons,
+)
+from .normalization import normalize_path
+from .safe_joiner import safe_join
+from .security_manager import SecurityManager
+
+__all__ = [
+    "normalize_path",
+    "safe_join",
+    "is_path_in_allowed_dirs",
+    "CaseManager",
+    "PathSecurityError",
+    "DirectoryNotFoundError",
+    "SecurityErrorReasons",
+    "SecurityManager",
+]

ostruct/cli/security/allowed_checker.py

@@ -0,0 +1,47 @@
+"""Allowed directory checker module.
+
+This module provides functionality to verify that a given path is within
+one of a set of allowed directories.
+"""
+
+from pathlib import Path
+from typing import List, Union
+
+from .normalization import normalize_path
+
+
+def is_path_in_allowed_dirs(
+    path: Union[str, Path], allowed_dirs: List[Path]
+) -> bool:
+    """Check if a given path is inside any of the allowed directories.
+
+    This function normalizes both the input path and allowed directories
+    before comparison to ensure consistent results across platforms.
+
+    Args:
+        path: The path to check.
+        allowed_dirs: A list of allowed directory paths.
+
+    Returns:
+        True if path is within one of the allowed directories; False otherwise.
+
+    Example:
+        >>> allowed = [Path("/base"), Path("/tmp")]
+        >>> is_path_in_allowed_dirs("/base/file.txt", allowed)
+        True
+        >>> is_path_in_allowed_dirs("/etc/passwd", allowed)
+        False
+    """
+    norm_path = normalize_path(path)
+    norm_allowed = [normalize_path(d) for d in allowed_dirs]
+
+    for allowed in norm_allowed:
+        try:
+            # If path.relative_to(allowed) does not raise an error,
+            # then path is within allowed.
+            norm_path.relative_to(allowed)
+            return True
+        except ValueError:
+            continue
+
+    return False

ostruct/cli/security/case_manager.py

@@ -0,0 +1,75 @@
+"""Case management module.
+
+This module provides a class for tracking and preserving the original case
+of file paths on case-insensitive systems.
+"""
+
+from pathlib import Path
+from threading import Lock
+from typing import Dict
+
+
+class CaseManager:
+    """Manages original case preservation for paths.
+
+    This class provides a thread-safe way to track original case preservation
+    without modifying Path objects. This is particularly important on
+    case-insensitive systems (macOS, Windows) where we normalize paths
+    to lowercase but want to preserve the original case for display.
+
+    Example:
+        >>> CaseManager.set_original_case(Path("/tmp/file.txt"), "/TMP/File.txt")
+        >>> CaseManager.get_original_case(Path("/tmp/file.txt"))
+        '/TMP/File.txt'
+    """
+
+    _case_mapping: Dict[str, str] = {}
+    _lock = Lock()
+
+    @classmethod
+    def set_original_case(
+        cls, normalized_path: Path, original_case: str
+    ) -> None:
+        """Store the original case for a normalized path.
+
+        Args:
+            normalized_path: The normalized (potentially lowercased) Path.
+            original_case: The original path string with its original case.
+
+        Raises:
+            TypeError: If normalized_path or original_case is None.
+        """
+        if normalized_path is None:
+            raise TypeError("normalized_path cannot be None")
+        if original_case is None:
+            raise TypeError("original_case cannot be None")
+
+        with cls._lock:
+            cls._case_mapping[str(normalized_path)] = original_case
+
+    @classmethod
+    def get_original_case(cls, normalized_path: Path) -> str:
+        """Retrieve the original case for a normalized path.
+
+        Args:
+            normalized_path: The normalized Path.
+
+        Returns:
+            The original case string if stored; otherwise the normalized path string.
+
+        Raises:
+            TypeError: If normalized_path is None.
+        """
+        if normalized_path is None:
+            raise TypeError("normalized_path cannot be None")
+
+        with cls._lock:
+            return cls._case_mapping.get(
+                str(normalized_path), str(normalized_path)
+            )
+
+    @classmethod
+    def clear(cls) -> None:
+        """Clear all stored case mappings."""
+        with cls._lock:
+            cls._case_mapping.clear()

ostruct/cli/security/errors.py

@@ -0,0 +1,184 @@
+"""Error definitions for the security package.
+
+This module defines custom exceptions and error reason constants used throughout
+the security modules.
+"""
+
+from typing import Any, Dict, List, Optional
+
+
+class PathSecurityError(Exception):
+    """Base exception for security-related errors.
+
+    This class provides rich error information for security-related issues,
+    including context and error wrapping capabilities.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        path: str = "",
+        context: Optional[Dict[str, Any]] = None,
+        error_logged: bool = False,
+    ) -> None:
+        """Initialize the error.
+
+        Args:
+            message: The error message.
+            path: The path that caused the error.
+            context: Additional context about the error.
+            error_logged: Whether this error has already been logged.
+        """
+        super().__init__(message)
+        self.path = path
+        self.context = context or {}
+        self._error_logged = error_logged
+        self._wrapped = False
+
+    def __str__(self) -> str:
+        """Format the error message with context if available."""
+        msg = super().__str__()
+
+        # Add expanded path information if available
+        if self.context:
+            if (
+                "original_path" in self.context
+                and "expanded_path" in self.context
+            ):
+                msg = (
+                    f"{msg}\n"
+                    f"Original path: {self.context['original_path']}\n"
+                    f"Expanded path: {self.context['expanded_path']}"
+                )
+            if "base_dir" in self.context:
+                msg = f"{msg}\nBase directory: {self.context['base_dir']}"
+            if "allowed_dirs" in self.context:
+                msg = f"{msg}\nAllowed directories: {self.context['allowed_dirs']!r}"
+
+        return msg
+
+    @property
+    def has_been_logged(self) -> bool:
+        """Whether this error has been logged."""
+        return self._error_logged
+
+    @has_been_logged.setter
+    def has_been_logged(self, value: bool) -> None:
+        """Set whether this error has been logged."""
+        self._error_logged = value
+
+    @property
+    def wrapped(self) -> bool:
+        """Whether this error is wrapping another error."""
+        return self._wrapped
+
+    def format_with_context(
+        self,
+        original_path: str,
+        expanded_path: str,
+        base_dir: str,
+        allowed_dirs: List[str],
+    ) -> str:
+        """Format the error message with additional context.
+
+        Args:
+            original_path: The original path that caused the error
+            expanded_path: The expanded/absolute path
+            base_dir: The base directory for security checks
+            allowed_dirs: List of allowed directories
+
+        Returns:
+            A formatted error message with context
+        """
+        lines = [
+            str(self),
+            f"Original path: {original_path}",
+            f"Expanded path: {expanded_path}",
+            f"Base directory: {base_dir}",
+            f"Allowed directories: {allowed_dirs}",
+            "Use --allowed-dir to add more allowed directories",
+        ]
+        return "\n".join(lines)
+
+    @classmethod
+    def wrap_error(
+        cls, message: str, original: "PathSecurityError"
+    ) -> "PathSecurityError":
+        """Wrap an existing error with additional context.
+
+        Args:
+            message: The new error message
+            original: The original error to wrap
+
+        Returns:
+            A new PathSecurityError instance wrapping the original
+        """
+        wrapped = cls(
+            f"{message}: {str(original)}",
+            path=original.path,
+            context=original.context,
+            error_logged=original.has_been_logged,
+        )
+        wrapped._wrapped = True
+        return wrapped
+
+    @classmethod
+    def from_expanded_paths(
+        cls,
+        original_path: str,
+        expanded_path: str,
+        base_dir: str,
+        allowed_dirs: List[str],
+        error_logged: bool = False,
+    ) -> "PathSecurityError":
+        """Create an error instance with expanded path information.
+
+        Args:
+            original_path: The original path that caused the error
+            expanded_path: The expanded/absolute path
+            base_dir: The base directory for security checks
+            allowed_dirs: List of allowed directories
+            error_logged: Whether this error has already been logged
+
+        Returns:
+            A new PathSecurityError instance with expanded path context
+        """
+        message = f"Path '{original_path}' is outside the base directory and not in allowed directories"
+        context = {
+            "original_path": original_path,
+            "expanded_path": expanded_path,
+            "base_dir": base_dir,
+            "allowed_dirs": allowed_dirs,
+        }
+        return cls(
+            message,
+            path=original_path,
+            context=context,
+            error_logged=error_logged,
+        )
+
+
+class DirectoryNotFoundError(PathSecurityError):
+    """Raised when a directory that is expected to exist does not."""
+
+
+class SecurityErrorReasons:
+    """Constants for common security error reasons."""
+
+    # Path validation errors
+    PATH_TRAVERSAL = "path_traversal"
+    UNSAFE_UNICODE = "unsafe_unicode"
+    NORMALIZATION_ERROR = "normalization_error"
+    CASE_MISMATCH = "case_mismatch"
+
+    # Symlink-related errors
+    SYMLINK_LOOP = "symlink_loop"
+    SYMLINK_ERROR = "symlink_error"
+    SYMLINK_TARGET_NOT_ALLOWED = "symlink_target_not_allowed"
+    SYMLINK_MAX_DEPTH = "symlink_max_depth"
+    SYMLINK_BROKEN = "symlink_broken"
+
+    # Directory access errors
+    PATH_NOT_IN_BASE = "path_not_in_base"
+    PATH_OUTSIDE_ALLOWED = "path_outside_allowed"
+    TEMP_PATHS_NOT_ALLOWED = "temp_paths_not_allowed"

ostruct/cli/security/normalization.py

@@ -0,0 +1,161 @@
+"""Path normalization module.
+
+This module provides functions to normalize file paths by:
+- Performing Unicode normalization (NFKC)
+- Normalizing path separators and redundant parts
+- Converting relative paths to absolute paths
+- Validating Unicode safety
+
+Security Design Choices:
+1. Unicode Normalization:
+   - Uses NFKC form for maximum compatibility
+   - Blocks known unsafe Unicode characters
+   - Basic protection against homograph attacks
+   - Does not handle all possible confusable sequences
+
+2. Path Separators:
+   - Normalizes to forward slashes
+   - Collapses multiple slashes
+   - Converts backslashes on all platforms
+   - Note: This breaks Windows UNC and device paths
+
+3. Parent Directory References:
+   - Allows ".." components in raw input
+   - Security checks done after path resolution
+   - Directory traversal prevented by final path validation
+
+4. Absolute Paths:
+   - Converts relative to absolute using CWD
+   - No environment variable expansion
+   - No home directory (~) expansion
+   - Thread-safety warning for CWD operations
+
+Known Limitations:
+1. Windows-Specific:
+   - UNC paths (r"\\\\server\\share") break when normalized
+   - Device paths (r"\\\\?\\", r"\\\\.") become invalid
+   - Drive-relative paths may resolve incorrectly
+   - Reserved names (CON, NUL, etc.) not handled
+   - ADS (:stream) not detected
+   - Case sensitivity not handled (delegated to CaseManager)
+
+2. Unicode Handling:
+   - Some confusable characters may pass checks
+   - Zero-width characters not fully covered
+   - Advanced homograph attacks possible
+   - Duplicate entries in safety pattern need review
+
+3. Threading:
+   - CWD operations not thread-safe
+   - Race conditions possible during path resolution
+"""
+
+import os
+import re
+import unicodedata
+from pathlib import Path
+from typing import Union
+
+from .errors import PathSecurityError, SecurityErrorReasons
+
+# Patterns for path normalization and validation
+_UNICODE_SAFETY_PATTERN = re.compile(
+    r"[\u0000-\u001F\u007F-\u009F\u2028-\u2029\u0085]"  # Control chars and line separators
+    r"|\.{2,}"  # Directory traversal attempts
+    r"|[\u2024\u2025\uFE52\u2024\u2025\u2026\uFE19\uFE30\uFE52\uFF0E\uFF61]"  # Alternative dots and separators
+)
+_BACKSLASH_PATTERN = re.compile(r"\\")
+_MULTIPLE_SLASH_PATTERN = re.compile(r"/+")
+
+
+def normalize_path(path: Union[str, Path]) -> Path:
+    """Normalize a path string with security checks.
+
+    This function:
+    1. Converts to Unicode NFKC form
+    2. Checks for unsafe Unicode characters
+    3. Normalizes path separators
+    4. Uses os.path.normpath to collapse redundant separators and dots
+    5. Converts to absolute path if needed
+    6. Returns a pathlib.Path object
+
+    Security Features:
+    - Unicode NFKC normalization
+    - Blocks unsafe Unicode characters
+    - Normalizes path separators
+    - Converts to absolute paths
+
+    Design Choices:
+    - No environment variable expansion
+    - No home directory (~) expansion
+    - No symlink resolution (handled separately)
+    - Case sensitivity handled by CaseManager
+    - Thread-safety warning: CWD operations are not atomic
+
+    Args:
+        path: A string or Path object representing a file path.
+
+    Returns:
+        A pathlib.Path object for the normalized absolute path.
+
+    Raises:
+        PathSecurityError: If the path contains unsafe Unicode characters.
+        TypeError: If path is None.
+
+    Note:
+        This function has known limitations with Windows paths:
+        - UNC paths are not properly handled
+        - Device paths are not supported
+        - Drive-relative paths may resolve incorrectly
+        - Reserved names are not checked
+        - ADS is not detected
+    """
+    if path is None:
+        raise TypeError("Path cannot be None")
+
+    path_str = str(path)
+
+    # Unicode normalization
+    try:
+        normalized = unicodedata.normalize("NFKC", path_str)
+    except Exception as e:
+        raise PathSecurityError(
+            "Unicode normalization failed",
+            path=path_str,
+            context={
+                "reason": SecurityErrorReasons.UNSAFE_UNICODE,
+                "error": str(e),
+            },
+        ) from e
+
+    # Check for unsafe characters and directory traversal
+    if match := _UNICODE_SAFETY_PATTERN.search(normalized):
+        matched_text = match.group(0)
+        if ".." in matched_text:
+            raise PathSecurityError(
+                "Directory traversal not allowed",
+                path=path_str,
+                context={
+                    "reason": SecurityErrorReasons.PATH_TRAVERSAL,
+                    "matched": matched_text,
+                },
+            )
+        else:
+            raise PathSecurityError(
+                "Path contains unsafe characters",
+                path=path_str,
+                context={
+                    "reason": SecurityErrorReasons.UNSAFE_UNICODE,
+                    "matched": matched_text,
+                },
+            )
+
+    # Normalize path separators
+    normalized = _BACKSLASH_PATTERN.sub("/", normalized)
+    normalized = _MULTIPLE_SLASH_PATTERN.sub("/", normalized)
+
+    # Convert to absolute path if needed
+    if not os.path.isabs(normalized):
+        normalized = os.path.abspath(normalized)
+
+    return Path(normalized)