ostruct-cli 0.1.0__py3-none-any.whl

ostruct/cli/path_utils.py

@@ -0,0 +1,123 @@
+"""Path validation utilities for the CLI."""
+
+import os
+from pathlib import Path
+from typing import Optional, Tuple
+
+from .errors import (
+    DirectoryNotFoundError,
+    FileNotFoundError,
+    PathSecurityError,
+    VariableNameError,
+    VariableValueError,
+)
+from .security import SecurityManager
+
+
+def validate_path_mapping(
+    mapping: str,
+    is_dir: bool = False,
+    base_dir: Optional[str] = None,
+    security_manager: Optional[SecurityManager] = None,
+) -> Tuple[str, str]:
+    """Validate a path mapping in the format "name=path".
+
+    Args:
+        mapping: The path mapping string (e.g., "myvar=/path/to/file").
+        is_dir: Whether the path is expected to be a directory (True) or file (False).
+        base_dir: Optional base directory to resolve relative paths against.
+        security_manager: Optional security manager to validate paths.
+
+    Returns:
+        A (name, path) tuple.
+
+    Raises:
+        VariableNameError: If the variable name portion is empty or invalid.
+        DirectoryNotFoundError: If is_dir=True and the path is not a directory or doesn't exist.
+        FileNotFoundError: If is_dir=False and the path is not a file or doesn't exist.
+        PathSecurityError: If the path is inaccessible or outside the allowed directory.
+        ValueError: If the format is invalid (missing "=").
+        OSError: If there is an underlying OS error (permissions, etc.).
+
+    Example:
+        >>> validate_path_mapping("config=settings.txt")  # Validates file
+        ('config', 'settings.txt')
+        >>> validate_path_mapping("data=config/", is_dir=True)  # Validates directory
+        ('data', 'config/')
+    """
+    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
+        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
+                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

ostruct/cli/progress.py

@@ -0,0 +1,105 @@
+"""Progress reporting for CLI operations."""
+
+import logging
+from typing import Any, Optional, Type
+
+logger = logging.getLogger(__name__)
+
+
+class ProgressContext:
+    """Simple context manager for output handling.
+
+    This is a minimal implementation that just handles direct output to stdout.
+    No progress reporting is implemented - it simply prints output directly.
+    """
+
+    def __init__(
+        self,
+        description: str = "Processing",
+        total: Optional[int] = None,
+        level: str = "basic",
+        output_file: Optional[str] = None,
+    ):
+        logger.debug(
+            "Initializing ProgressContext with level=%s, output_file=%s",
+            level,
+            output_file,
+        )
+        logger.debug("Description: %s, total: %s", description, total)
+        self._output_file = output_file
+        self._level = level
+        self.enabled = level != "none"
+        self.current: int = 0
+        logger.debug(
+            "ProgressContext initialized with enabled=%s", self.enabled
+        )
+
+    def __enter__(self) -> "ProgressContext":
+        logger.debug("Entering ProgressContext with level=%s", self._level)
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc_val: Optional[BaseException],
+        exc_tb: Optional[Any],
+    ) -> None:
+        logger.debug(
+            "Exiting ProgressContext. Had exception: %s", exc_type is not None
+        )
+        if exc_type:
+            logger.error(
+                "Exception in ProgressContext: %s - %s", exc_type, exc_val
+            )
+        pass
+
+    def update(self, amount: int = 1, force: bool = False) -> None:
+        """No-op update method kept for compatibility."""
+        logger.debug(
+            "Update called with amount=%d, force=%s, current=%d",
+            amount,
+            force,
+            self.current,
+        )
+        self.current += amount
+        pass
+
+    def print_output(self, text: str) -> None:
+        """Print output to stdout or file.
+
+        Args:
+            text: Text to print
+        """
+        logger.debug("print_output called with text length=%d", len(text))
+        logger.debug("First 100 chars of text: %s", text[:100] if text else "")
+        logger.debug(
+            "Output file: %s, enabled=%s, level=%s",
+            self._output_file,
+            self.enabled,
+            self._level,
+        )
+
+        try:
+            if self._output_file:
+                logger.debug("Writing to output file: %s", self._output_file)
+                with open(self._output_file, "a", encoding="utf-8") as f:
+                    logger.debug("File opened successfully, writing content")
+                    f.write(text)
+                    f.write("\n")
+                    logger.debug(
+                        "Successfully wrote %d chars to file", len(text)
+                    )
+            else:
+                logger.debug("Writing to stdout")
+                print(text)
+                logger.debug(
+                    "Successfully wrote %d chars to stdout", len(text)
+                )
+        except Exception as e:
+            logger.error("Failed to write output: %s", e)
+            raise
+
+    def step(self, description: str) -> "ProgressContext":
+        """No-op step method kept for compatibility."""
+        logger.debug("Step called with description: %s", description)
+        return self

ostruct/cli/security.py

@@ -0,0 +1,311 @@
+"""Security management for file access.
+
+This module provides security checks for file access, including:
+- Base directory restrictions
+- Allowed directory validation
+- Path traversal prevention
+- Temporary directory handling
+"""
+
+import logging
+import os
+import tempfile
+from pathlib import Path
+from typing import List, Optional, Set
+
+from .errors import DirectoryNotFoundError, PathSecurityError
+from .security_types import SecurityManagerProtocol
+
+
+def is_temp_file(path: str) -> bool:
+    """Check if a file is in a temporary directory.
+
+    Args:
+        path: Path to check (will be converted to absolute path)
+
+    Returns:
+        True if the path is in a temporary directory, False otherwise
+
+    Note:
+        This function handles platform-specific path normalization, including symlinks
+        (e.g., on macOS where /var is symlinked to /private/var).
+    """
+    # Normalize the input path (resolve symlinks)
+    abs_path = os.path.realpath(path)
+
+    # Get all potential temp directories and normalize them
+    temp_dirs = set()
+    # System temp dir (platform independent)
+    temp_dirs.add(os.path.realpath(tempfile.gettempdir()))
+
+    # Common Unix/Linux/macOS temp locations
+    unix_temp_dirs = ["/tmp", "/var/tmp", "/var/folders"]
+    for temp_dir in unix_temp_dirs:
+        if os.path.exists(temp_dir):
+            temp_dirs.add(os.path.realpath(temp_dir))
+
+    # Windows temp locations (if on Windows)
+    if os.name == "nt":
+        if "TEMP" in os.environ:
+            temp_dirs.add(os.path.realpath(os.environ["TEMP"]))
+        if "TMP" in os.environ:
+            temp_dirs.add(os.path.realpath(os.environ["TMP"]))
+
+    # Check if file is in any temp directory using normalized paths
+    abs_path_parts = os.path.normpath(abs_path).split(os.sep)
+    for temp_dir in temp_dirs:
+        temp_dir_parts = os.path.normpath(temp_dir).split(os.sep)
+        # Check if the path starts with the temp directory components
+        if len(abs_path_parts) >= len(temp_dir_parts) and all(
+            a == b
+            for a, b in zip(
+                abs_path_parts[: len(temp_dir_parts)], temp_dir_parts
+            )
+        ):
+            return True
+
+    return False
+
+
+class SecurityManager(SecurityManagerProtocol):
+    """Manages security for file access.
+
+    Validates all file access against a base directory and optional
+    allowed directories. Prevents unauthorized access and directory
+    traversal attacks.
+
+    The security model is based on:
+    1. A base directory that serves as the root for all file operations
+    2. A set of explicitly allowed directories that can be accessed outside the base directory
+    3. Special handling for temporary directories that are always allowed
+
+    All paths are normalized using realpath() to handle symlinks consistently across platforms.
+    """
+
+    def __init__(
+        self,
+        base_dir: Optional[str] = None,
+        allowed_dirs: Optional[List[str]] = None,
+    ):
+        """Initialize security manager.
+
+        Args:
+            base_dir: Base directory for file access. Defaults to current working directory.
+            allowed_dirs: Optional list of additional allowed directories
+
+        All paths are normalized using realpath to handle symlinks
+        and relative paths consistently across platforms.
+        """
+        self._base_dir = Path(os.path.realpath(base_dir or os.getcwd()))
+        self._allowed_dirs: Set[Path] = set()
+        if allowed_dirs:
+            for directory in allowed_dirs:
+                self.add_allowed_dir(directory)
+
+    @property
+    def base_dir(self) -> Path:
+        """Get the base directory."""
+        return self._base_dir
+
+    @property
+    def allowed_dirs(self) -> List[Path]:
+        """Get the list of allowed directories."""
+        return sorted(self._allowed_dirs)  # Sort for consistent ordering
+
+    def add_allowed_dir(self, directory: str) -> None:
+        """Add a directory to the set of allowed directories.
+
+        Args:
+            directory: Directory to allow access to
+
+        Raises:
+            DirectoryNotFoundError: If directory does not exist
+        """
+        real_path = Path(os.path.realpath(directory))
+        if not real_path.exists():
+            raise DirectoryNotFoundError(f"Directory not found: {directory}")
+        if not real_path.is_dir():
+            raise DirectoryNotFoundError(
+                f"Path is not a directory: {directory}"
+            )
+        self._allowed_dirs.add(real_path)
+
+    def add_allowed_dirs_from_file(self, file_path: str) -> None:
+        """Add allowed directories from a file.
+
+        Args:
+            file_path: Path to file containing allowed directories (one per line)
+
+        Raises:
+            PathSecurityError: If file_path is outside allowed directories
+            FileNotFoundError: If file does not exist
+            ValueError: If file contains invalid directories
+        """
+        real_path = Path(os.path.realpath(file_path))
+
+        # First validate the file path itself
+        try:
+            self.validate_path(
+                str(real_path), purpose="read allowed directories"
+            )
+        except PathSecurityError:
+            raise PathSecurityError.from_expanded_paths(
+                original_path=file_path,
+                expanded_path=str(real_path),
+                error_logged=True,
+                base_dir=str(self._base_dir),
+                allowed_dirs=[str(d) for d in self._allowed_dirs],
+            )
+
+        if not real_path.exists():
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+        with open(real_path) as f:
+            for line in f:
+                directory = line.strip()
+                if directory and not directory.startswith("#"):
+                    self.add_allowed_dir(directory)
+
+    def is_path_allowed(self, path: str) -> bool:
+        """Check if a path is allowed.
+
+        A path is allowed if it is:
+        1. Under the normalized base directory
+        2. Under any normalized allowed directory
+
+        The path must also exist.
+
+        Args:
+            path: Path to check
+
+        Returns:
+            bool: True if path exists and is allowed, False otherwise
+        """
+        logger = logging.getLogger("ostruct")
+        logger.debug("Checking if path is allowed: %s", path)
+        logger.debug("Base directory: %s", self._base_dir)
+        logger.debug("Allowed directories: %s", self._allowed_dirs)
+
+        try:
+            real_path = Path(os.path.realpath(path))
+            logger.debug("Resolved real path: %s", real_path)
+
+            # Check if the path exists
+            if not real_path.exists():
+                logger.debug("Path does not exist")
+                return False
+
+        except (ValueError, OSError) as e:
+            logger.debug("Failed to resolve real path: %s", e)
+            return False
+
+        try:
+            if real_path.is_relative_to(self._base_dir):
+                logger.debug("Path is relative to base directory")
+                return True
+        except ValueError:
+            logger.debug("Path is not relative to base directory")
+
+        for allowed_dir in self._allowed_dirs:
+            try:
+                if real_path.is_relative_to(allowed_dir):
+                    logger.debug(
+                        "Path is relative to allowed directory: %s",
+                        allowed_dir,
+                    )
+                    return True
+            except ValueError:
+                logger.debug(
+                    "Path is not relative to allowed directory: %s",
+                    allowed_dir,
+                )
+                continue
+
+        logger.debug("Path is not allowed")
+        return False
+
+    def validate_path(self, path: str, purpose: str = "access") -> Path:
+        """Validate and normalize a path.
+
+        Args:
+            path: Path to validate
+            purpose: Description of intended access (for error messages)
+
+        Returns:
+            Path: Normalized path if valid
+
+        Raises:
+            PathSecurityError: If path is not allowed
+        """
+        logger = logging.getLogger("ostruct")
+        logger.debug("Validating path for %s: %s", purpose, path)
+
+        try:
+            real_path = Path(os.path.realpath(path))
+            logger.debug("Resolved real path: %s", real_path)
+        except (ValueError, OSError) as e:
+            logger.error("Invalid path format: %s", e)
+            raise PathSecurityError(
+                f"Invalid path format: {e}", error_logged=True
+            )
+
+        if not self.is_path_allowed(str(real_path)):
+            logger.error(
+                "Access denied: %s is outside base directory and not in allowed directories",
+                path,
+            )
+            raise PathSecurityError.from_expanded_paths(
+                original_path=path,
+                expanded_path=str(real_path),
+                base_dir=str(self._base_dir),
+                allowed_dirs=[str(d) for d in self._allowed_dirs],
+                error_logged=True,
+            )
+
+        logger.debug("Path validation successful")
+        return real_path
+
+    def is_allowed_file(self, path: str) -> bool:
+        """Check if file access is allowed.
+
+        Args:
+            path: Path to check
+
+        Returns:
+            bool: True if file exists and is allowed
+        """
+        try:
+            real_path = Path(os.path.realpath(path))
+            return self.is_path_allowed(str(real_path)) and real_path.is_file()
+        except (ValueError, OSError):
+            return False
+
+    def is_allowed_path(self, path_str: str) -> bool:
+        """Check if string path is allowed.
+
+        Args:
+            path_str: Path string to check
+
+        Returns:
+            bool: True if path is allowed
+        """
+        try:
+            return self.is_path_allowed(path_str)
+        except (ValueError, OSError):
+            return False
+
+    def resolve_path(self, path: str) -> Path:
+        """Resolve and validate a path.
+
+        This is an alias for validate_path() for backward compatibility.
+
+        Args:
+            path: Path to resolve and validate
+
+        Returns:
+            Path: Normalized path if valid
+
+        Raises:
+            PathSecurityError: If path is not allowed
+        """
+        return self.validate_path(path)

ostruct/cli/security_types.py

@@ -0,0 +1,49 @@
+"""Security type definitions and protocols."""
+
+from pathlib import Path
+from typing import List, Protocol
+
+
+class SecurityManagerProtocol(Protocol):
+    """Protocol defining the interface for security managers."""
+
+    @property
+    def base_dir(self) -> Path:
+        """Get the base directory."""
+        ...
+
+    @property
+    def allowed_dirs(self) -> List[Path]:
+        """Get the list of allowed directories."""
+        ...
+
+    def add_allowed_dir(self, directory: str) -> None:
+        """Add a directory to the set of allowed directories."""
+        ...
+
+    def add_allowed_dirs_from_file(self, file_path: str) -> None:
+        """Add allowed directories from a file."""
+        ...
+
+    def is_path_allowed(self, path: str) -> bool:
+        """Check if a path is allowed."""
+        ...
+
+    def validate_path(self, path: str, purpose: str = "access") -> Path:
+        """Validate and normalize a path."""
+        ...
+
+    def is_allowed_file(self, path: str) -> bool:
+        """Check if file access is allowed."""
+        ...
+
+    def is_allowed_path(self, path_str: str) -> bool:
+        """Check if string path is allowed."""
+        ...
+
+    def resolve_path(self, path: str) -> Path:
+        """Resolve and validate a path.
+
+        This is an alias for validate_path() for backward compatibility.
+        """
+        ...

ostruct/cli/template_env.py

@@ -0,0 +1,55 @@
+"""Jinja2 environment factory and configuration.
+
+This module provides a centralized factory for creating consistently configured Jinja2 environments.
+"""
+
+from typing import Optional, Type
+
+import jinja2
+from jinja2 import Environment
+
+from .template_extensions import CommentExtension
+from .template_filters import register_template_filters
+
+
+def create_jinja_env(
+    *,
+    undefined: Optional[Type[jinja2.Undefined]] = None,
+    loader: Optional[jinja2.BaseLoader] = None,
+    validation_mode: bool = False,
+) -> Environment:
+    """Create a consistently configured Jinja2 environment.
+
+    Args:
+        undefined: Custom undefined class to use. Defaults to StrictUndefined.
+        loader: Template loader to use. Defaults to None.
+        validation_mode: Whether to configure the environment for validation (uses SafeUndefined).
+
+    Returns:
+        A configured Jinja2 environment.
+    """
+    if validation_mode:
+        from .template_validation import SafeUndefined
+
+        undefined = SafeUndefined
+    elif undefined is None:
+        undefined = jinja2.StrictUndefined
+
+    env = Environment(
+        loader=loader,
+        undefined=undefined,
+        autoescape=False,  # Disable HTML escaping by default
+        trim_blocks=True,
+        lstrip_blocks=True,
+        keep_trailing_newline=True,
+        extensions=[
+            "jinja2.ext.do",
+            "jinja2.ext.loopcontrols",
+            CommentExtension,
+        ],
+    )
+
+    # Register all template filters
+    register_template_filters(env)
+
+    return env

ostruct/cli/template_extensions.py

@@ -0,0 +1,51 @@
+"""Custom Jinja2 extensions for enhanced template functionality.
+
+This module provides extensions that modify Jinja2's default behavior:
+- CommentExtension: Ignores variables inside comment blocks during validation and rendering
+"""
+
+from jinja2 import nodes
+from jinja2.ext import Extension
+from jinja2.parser import Parser
+
+
+class CommentExtension(Extension):  # type: ignore[misc]
+    """Extension that ignores variables inside comment blocks.
+
+    This extension ensures that:
+    1. Contents of comment blocks are completely ignored during parsing
+    2. Variables inside comments are not validated or processed
+    3. Comments are stripped from the output
+    """
+
+    tags = {"comment"}
+
+    def parse(self, parser: Parser) -> nodes.Node:
+        """Parse a comment block, ignoring its contents.
+
+        Args:
+            parser: The Jinja2 parser instance
+
+        Returns:
+            An empty node since comments are ignored
+
+        Raises:
+            TemplateSyntaxError: If the comment block is not properly closed
+        """
+        # Get the line number for error reporting
+        lineno = parser.stream.current.lineno
+
+        # Skip the opening comment tag
+        next(parser.stream)
+
+        # Skip until we find {% endcomment %}
+        while not parser.stream.current.test("name:endcomment"):
+            if parser.stream.current.type == "eof":
+                raise parser.fail("Unclosed comment block", lineno)
+            next(parser.stream)
+
+        # Skip the endcomment tag
+        next(parser.stream)
+
+        # Return an empty string node
+        return nodes.Output([nodes.TemplateData("")]).set_lineno(lineno)