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

ostruct/cli/security/windows_paths.py

@@ -0,0 +1,404 @@
+"""Windows path handling and validation.
+
+This module provides functions for handling Windows-specific path features:
+- Device paths (r"\\\\?\\", r"\\\\.")
+- Drive-relative paths (C:folder)
+- Reserved names (CON, PRN, etc.)
+- UNC paths (r"\\\\server\\share")
+- Alternate Data Streams (file.txt:stream)
+
+Security Design Choices:
+1. Device Paths:
+   - Explicitly blocked for security
+   - No support for extended-length paths
+   - No direct device access allowed
+
+2. Drive Paths:
+   - Drive-relative paths must include separator
+   - Drive absolute paths are allowed
+   - Drive letters must be A-Z (case insensitive)
+
+3. Reserved Names:
+   - All Windows reserved names blocked
+   - Case-insensitive matching
+   - Blocked with or without extensions
+
+4. UNC Paths:
+   - Must be complete (server and share)
+   - No device paths in UNC format
+   - Normalized to forward slashes
+
+5. Alternate Data Streams:
+   - All ADS access is blocked
+   - No exceptions for Zone.Identifier
+   - Blocks both read and write
+
+Known Limitations:
+1. Path Length:
+   - No extended-length path support
+   - Standard Windows MAX_PATH limits
+   - No workarounds for long paths
+
+2. Network:
+   - No special handling for DFS
+   - No support for administrative shares
+   - Basic UNC validation only
+
+3. Security:
+   - Some rare path formats may bypass checks
+   - Complex NTFS features not handled
+   - Limited reparse point support
+"""
+
+import logging
+import os
+import re
+from pathlib import Path, WindowsPath
+from typing import Optional, Union
+
+from .errors import PathSecurityError, SecurityErrorReasons
+
+logger = logging.getLogger(__name__)
+
+# Windows path length limits
+MAX_PATH = 260
+EXTENDED_MAX_PATH = 32767
+
+# Regex patterns for Windows path features
+_WINDOWS_DEVICE_PATH = re.compile(
+    r"^(?:\\\\|//)[?.](?:\\|/)(?!UNC(?:\\|/))",  # Match device paths but exclude UNC
+    flags=re.IGNORECASE,
+)
+
+_WINDOWS_DRIVE_RELATIVE = re.compile(
+    r"(?:^|[/\\])[A-Za-z]:(?![/\\])|"  # C:folder or \C:folder but not C:\folder
+    r"^/[A-Za-z]:(?![/\\])"  # /C:folder variants
+)
+
+_WINDOWS_RESERVED_NAMES = re.compile(
+    r"^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])"  # Base names
+    r"(\.[^\\/:*?\"<>|]*)?$",  # Optional extension
+    re.IGNORECASE,
+)
+
+_WINDOWS_UNC = re.compile(
+    r"^\\\\[^?.\\/][^\\/]*\\[^\\/]+(?:\\.*)?|"  # \\server\share[\anything]
+    r"^//[^?./][^/]*/[^/]+(?:/.*)?$"  # //server/share[/anything]
+)
+
+_WINDOWS_INCOMPLETE_UNC = re.compile(
+    r"^\\\\[^?.\\/][^\\/]*(?:\\[^\\/]+)?$|"  # \\server or \\server\incomplete
+    r"^//[^?./][^/]*(?:/[^/]+)?$"  # //server or //server/incomplete variants
+)
+
+_WINDOWS_ADS = re.compile(
+    r":[^/\\<>:\"|?*]+$|"  # Basic ADS
+    r":Zone\.Identifier$|"  # Zone.Identifier
+    r":[^/\\<>:\"|?*]+:[^/\\]+$"  # Multiple stream segments
+)
+
+_WINDOWS_INVALID_CHARS = re.compile(
+    r'[<>"|?*]|'  # Standard invalid chars except colon
+    r"(?<!^[A-Za-z]):|"  # Colon except after drive letter at start
+    r"[\x00-\x1F]"  # Control chars
+)
+
+_WINDOWS_TRAILING = re.compile(r"[. ]+$")  # Trailing dots/spaces
+
+
+def is_windows_path(path: Union[str, Path]) -> bool:
+    """Check if path uses Windows-specific features.
+
+    Security Note:
+    - Detects device paths (r"\\?\\" and r"\\.\\") in both slash formats
+    - Case insensitive to handle drive letters
+    """
+    path_str = str(path)
+
+    # Normalize slashes for consistent matching
+    normalized_path = path_str.replace("\\", "/")
+
+    # Check for device paths first before any processing
+    if _WINDOWS_DEVICE_PATH.match(path_str) or _WINDOWS_DEVICE_PATH.match(
+        normalized_path
+    ):
+        logger.debug("Windows device path detected: %r", path_str)
+        return True
+
+    # Rest of the function remains unchanged
+    basename = os.path.basename(path_str)
+    is_drive_relative = bool(_WINDOWS_DRIVE_RELATIVE.search(path_str))
+    is_unc = bool(_WINDOWS_UNC.search(path_str))
+    is_ads = bool(_WINDOWS_ADS.search(path_str))
+    is_reserved = bool(_WINDOWS_RESERVED_NAMES.match(basename))
+
+    logger.debug(
+        "Windows path check for %r: drive_relative=%s, unc=%s, ads=%s, reserved=%s",
+        path_str,
+        is_drive_relative,
+        is_unc,
+        is_ads,
+        is_reserved,
+    )
+
+    return bool(is_drive_relative or is_unc or is_ads or is_reserved)
+
+
+def normalize_windows_path(path: Union[str, Path]) -> Path:
+    """Normalize a path using Windows-specific rules.
+
+    This function:
+    1. Converts to Path with Windows semantics
+    2. Resolves to absolute path
+    3. Normalizes separators and case
+    4. Removes redundant separators and dots
+
+    Args:
+        path: Path to normalize
+
+    Returns:
+        Normalized Path
+
+    Raises:
+        PathSecurityError: If path cannot be normalized
+    """
+    try:
+        logger.debug("Normalizing Windows path: %r", path)
+
+        # Convert to string and normalize all slashes to forward slashes first
+        path_str = str(path)
+        # Replace all backslashes with forward slashes for consistent handling
+        path_str = path_str.replace("\\", "/")
+        # Collapse multiple slashes to single slash, except for UNC prefixes
+        path_str = re.sub(r"(?<!^)//+", "/", path_str)
+        logger.debug("Normalized slashes: %r", path_str)
+
+        # Use regular Path on non-Windows systems
+        path_cls = WindowsPath if os.name == "nt" else Path
+
+        # Convert back to backslashes for Windows path handling
+        if os.name == "nt":
+            path_str = path_str.replace("/", "\\")
+            # Preserve UNC path double backslashes
+            if path_str.startswith("\\") and not path_str.startswith("\\\\"):
+                path_str = "\\" + path_str
+
+        normalized = path_cls(path_str)
+        logger.debug(
+            "Created path object: %r (class=%s)", normalized, path_cls.__name__
+        )
+
+        if os.name == "nt":
+            # Check if resolve() would exceed MAX_PATH
+            resolved = normalized.resolve()
+            resolved_str = str(resolved)
+            # If resolve() added \\?\ prefix or path is too long, reject it
+            if (
+                resolved_str.startswith("\\\\?\\")
+                or len(resolved_str) > MAX_PATH
+            ):
+                raise PathSecurityError(
+                    f"Path would exceed maximum length of {MAX_PATH} characters after resolution",
+                    path=str(path),
+                    context={
+                        "reason": SecurityErrorReasons.NORMALIZATION_ERROR
+                    },
+                )
+            normalized = resolved
+            logger.debug("Resolved on Windows: %r", normalized)
+        else:
+            # On non-Windows, just normalize the path
+            normalized = Path(os.path.normpath(path_str))
+            logger.debug("Normalized on non-Windows: %r", normalized)
+
+        return normalized
+    except PathSecurityError:
+        raise
+    except Exception as e:
+        logger.error(
+            "Failed to normalize Windows path %r: %s", path, e, exc_info=True
+        )
+        raise PathSecurityError(
+            f"Failed to normalize Windows path: {e}",
+            path=str(path),
+            context={"reason": SecurityErrorReasons.NORMALIZATION_ERROR},
+        )
+
+
+def validate_windows_path(path: Union[str, Path]) -> Optional[str]:
+    """Validate a path for Windows-specific security issues.
+
+    Performs checks in order:
+    1. Device paths (blocked)
+    2. Path normalization
+    3. Other Windows-specific checks
+
+    Returns an error message if the path:
+    - Uses device paths (r"\\\\?\\", r"\\\\.")
+    - Uses drive-relative paths (C:folder)
+    - Contains reserved names (CON, PRN, etc.)
+    - Uses UNC paths (r"\\\\server\\share")
+    - Contains Alternate Data Streams (file.txt:stream)
+    - Exceeds maximum path length
+    - Contains invalid characters
+    - Has trailing dots or spaces
+
+    Returns None if the path is valid.
+    """
+    logger.debug("Validating Windows path: %r", path)
+
+    # Initial checks on raw path string
+    path_str = str(path)
+
+    # Normalize slashes for consistent matching
+    normalized_path = path_str.replace("\\", "/")
+
+    # Check for device paths before any processing
+    if _WINDOWS_DEVICE_PATH.match(path_str) or _WINDOWS_DEVICE_PATH.match(
+        normalized_path
+    ):
+        logger.debug("Device path detected in original path: %r", path_str)
+        return "Device paths not allowed"
+
+    # Check for incomplete UNC paths before normalization
+    if _WINDOWS_INCOMPLETE_UNC.search(path_str):
+        logger.debug("Incomplete UNC path detected: %r", path_str)
+        return "Incomplete UNC path"
+
+    # Then normalize the path for other checks
+    try:
+        normalized_str = str(normalize_windows_path(path))
+        logger.debug("Normalized path: %r", normalized_str)
+
+        # Check for device paths again after normalization
+        if _WINDOWS_DEVICE_PATH.match(normalized_str):
+            logger.debug(
+                "Device path detected after normalization: %r", normalized_str
+            )
+            return "Device paths not allowed"
+
+    except PathSecurityError as e:
+        logger.debug("Path normalization failed: %s", e)
+        return str(e)
+
+    # Check path length
+    if len(normalized_str) > MAX_PATH:
+        msg = f"Path exceeds maximum length of {MAX_PATH} characters"
+        logger.debug("Path too long: %s", msg)
+        return msg
+
+    if _WINDOWS_DRIVE_RELATIVE.search(normalized_str):
+        logger.debug("Drive-relative path detected: %r", normalized_str)
+        return "Drive-relative paths must include separator"
+
+    # Check for complete UNC paths
+    if _WINDOWS_UNC.search(normalized_str):
+        logger.debug("UNC path detected: %r", normalized_str)
+        return "UNC paths not allowed"
+
+    if _WINDOWS_ADS.search(normalized_str):
+        logger.debug("Alternate Data Stream detected: %r", normalized_str)
+        return "Alternate Data Streams not allowed"
+
+    # Check each path component
+    try:
+        parts = (
+            Path(normalized_str).parts
+            if os.name != "nt"
+            else WindowsPath(normalized_str).parts
+        )
+        logger.debug("Path components: %r", parts)
+
+        for part in parts:
+            # Check for reserved names
+            if _WINDOWS_RESERVED_NAMES.match(part):
+                logger.debug("Reserved name detected: %r", part)
+                return "Windows reserved names not allowed"
+
+            # Check for invalid characters
+            if _WINDOWS_INVALID_CHARS.search(part):
+                msg = f"Invalid characters in path component '{part}'"
+                logger.debug("Invalid characters: %s", msg)
+                return msg
+
+            # Check for trailing dots/spaces
+            if _WINDOWS_TRAILING.search(part):
+                msg = f"Trailing dots or spaces not allowed in '{part}'"
+                logger.debug("Trailing dots/spaces: %s", msg)
+                return msg
+    except Exception as e:
+        logger.error("Failed to check path components: %s", e, exc_info=True)
+        return f"Failed to validate path components: {e}"
+
+    logger.debug("Path validation successful: %r", normalized_str)
+    return None
+
+
+def resolve_windows_symlink(path: Path) -> Optional[Path]:
+    """Resolve a Windows symlink or reparse point.
+
+    This is a Windows-specific helper for symlink resolution that handles:
+    - NTFS symbolic links
+    - NTFS junction points
+    - NTFS mount points
+    - Other reparse points
+
+    Args:
+        path: The path to resolve.
+
+    Returns:
+        Resolved Path if successful, None if not a Windows symlink.
+
+    Note:
+        This function requires Windows and elevated privileges for some
+        reparse point operations.
+
+    Security Note:
+        By default, this function only handles regular symlinks.
+        For security reasons, other reparse points (junctions, mount points)
+        are not resolved by default as they can bypass directory restrictions.
+        If you need to handle these, implement proper security checks in the
+        calling code.
+    """
+    if os.name != "nt":
+        return None
+
+    try:
+        # Try to resolve as a regular symlink first
+        if path.is_symlink():
+            target = Path(os.readlink(path))
+            logger.debug("Resolved symlink %r to %r", path, target)
+            return target
+
+        # Check if it's a reparse point but not a symlink
+        # This requires using Windows APIs, so we just warn about it
+        if hasattr(path, "is_mount") and path.is_mount():
+            logger.warning(
+                "Path %r is a mount point/junction - not resolving for security",
+                path,
+            )
+            return None
+
+        # For any other reparse points, log a warning
+        try:
+            import ctypes
+
+            attrs = ctypes.windll.kernel32.GetFileAttributesW(str(path))  # type: ignore[attr-defined]
+            is_reparse = bool(
+                attrs != -1 and attrs & 0x400
+            )  # FILE_ATTRIBUTE_REPARSE_POINT
+            if is_reparse:
+                logger.warning(
+                    "Path %r is a reparse point - not resolving for security",
+                    path,
+                )
+                return None
+        except Exception:
+            # If we can't check reparse attributes, assume it's not a reparse point
+            pass
+
+        return None
+
+    except OSError as e:
+        logger.debug("Failed to resolve Windows symlink %r: %s", path, e)
+        return None

ostruct/cli/template_filters.py

@@ -544,9 +544,9 @@ def format_code(
     """Format code with syntax highlighting.
 
     Args:
-        text (str): The code text to format
-        output_format (str): The output format ('terminal', 'html', or 'plain')
-        language (str): The programming language for syntax highlighting
+        text: The code text to format
+        output_format: The output format ('terminal', 'html', or 'plain')
+        language: The programming language for syntax highlighting
 
     Returns:
         str: Formatted code string
@@ -580,10 +580,13 @@ def format_code(
         else:  # plain
             formatter = NullFormatter[str]()
 
-        return highlight(text, lexer, formatter)
+        result = highlight(text, lexer, formatter)
+        if isinstance(result, bytes):
+            return result.decode("utf-8")
+        return str(result)
     except Exception as e:
         logger.error(f"Error formatting code: {e}")
-        return text
+        return str(text)
 
 
 def register_template_filters(env: Environment) -> None:

{ostruct_cli-0.3.0.dist-info → ostruct_cli-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: ostruct-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: CLI for OpenAI Structured Output
 Author: Yaniv Golan
 Author-email: yaniv@golan.name
@@ -16,7 +16,8 @@ Requires-Dist: chardet (>=5.0.0,<6.0.0)
 Requires-Dist: click (>=8.1.7,<9.0.0)
 Requires-Dist: ijson (>=3.2.3,<4.0.0)
 Requires-Dist: jsonschema (>=4.23.0,<5.0.0)
-Requires-Dist: openai-structured (>=1.0.0,<2.0.0)
+Requires-Dist: openai (>=1.0.0,<2.0.0)
+Requires-Dist: openai-structured (>=1.3.0,<2.0.0)
 Requires-Dist: pydantic (>=2.6.3,<3.0.0)
 Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
 Requires-Dist: tiktoken (>=0.8.0,<0.9.0)
@@ -28,8 +29,8 @@ Description-Content-Type: text/markdown
 # ostruct-cli
 
 [![PyPI version](https://badge.fury.io/py/ostruct-cli.svg)](https://badge.fury.io/py/ostruct-cli)
-[![Python Versions](https://img.shields.io/pypi/pyversions/ostruct-cli.svg)](https://pypi.org/project/ostruct-cli/)
-[![Documentation Status](https://readthedocs.org/projects/ostruct-cli/badge/?version=latest)](https://ostruct-cli.readthedocs.io/en/latest/?badge=latest)
+[![Python Versions](https://img.shields.io/pypi/pyversions/ostruct-cli.svg)](https://pypi.org/project/ostruct-cli)
+[![Documentation Status](https://readthedocs.org/projects/ostruct/badge/?version=latest)](https://ostruct.readthedocs.io/en/latest/?badge=latest)
 [![CI](https://github.com/yaniv-golan/ostruct/actions/workflows/ci.yml/badge.svg)](https://github.com/yaniv-golan/ostruct/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
@@ -126,7 +127,7 @@ All debug and error logs are written to:
 - `~/.ostruct/logs/ostruct.log`: General application logs
 - `~/.ostruct/logs/openai_stream.log`: OpenAI streaming operations logs
 
-For more detailed documentation and examples, visit our [documentation](https://ostruct-cli.readthedocs.io/).
+For more detailed documentation and examples, visit our [documentation](https://ostruct.readthedocs.io/).
 
 ## Development
 

ostruct_cli-0.4.0.dist-info/RECORD

@@ -0,0 +1,36 @@
+ostruct/__init__.py,sha256=X6zo6V7ZNMv731Wi388aTVQngD1410ExGwGx4J6lpyo,187
+ostruct/cli/__init__.py,sha256=sYHKT6o1kFy1acbXejzAvVm8Cy8U91Yf1l4DlzquHKg,409
+ostruct/cli/cache_manager.py,sha256=ej3KrRfkKKZ_lEp2JswjbJ5bW2ncsvna9NeJu81cqqs,5192
+ostruct/cli/cli.py,sha256=kh2_P8O7BAbu7qWB64d1qH0rgWSJZuyxn4MdXd13h4I,65574
+ostruct/cli/click_options.py,sha256=rrx04tiZmOu2103k0WJMNtc4ZYGpDftD9DjtGCVaNW0,7551
+ostruct/cli/errors.py,sha256=lr8c4nkRCZZ5QoWHMZxX4B22CNoaoL1JJx8Y8WTt53Y,10448
+ostruct/cli/file_info.py,sha256=xafeONqhUC7D9OPVuDIlc-44KcrPjdEBVmHN69CEtzs,13838
+ostruct/cli/file_list.py,sha256=OiOl0NfkrWipZEdtRAf4eDJGDo2kyWdurxmU2k4KaZ0,11438
+ostruct/cli/file_utils.py,sha256=On5zjqTx0qKlcZBbt1SNaq7HXtEON5_vyeTFE4UsCFg,22075
+ostruct/cli/path_utils.py,sha256=RzGO-QOrp__NtDcIfAjfKl71NSXz3m_pb07UybgF8ro,3681
+ostruct/cli/progress.py,sha256=rj9nVEco5UeZORMbzd7mFJpFGJjbH9KbBFh5oTE5Anw,3415
+ostruct/cli/security/__init__.py,sha256=CQpkCgTFYlA1p6atpQeNgIKtE4LZGUKt4EbytbGKpCs,846
+ostruct/cli/security/allowed_checker.py,sha256=y_R1UIJeGr1Ah1jlsg8t6aO28DnOfLqSH0wqmlVhx5A,1369
+ostruct/cli/security/case_manager.py,sha256=I_ZJSyntLuGx5qVzze559CI-OxsaNPSibkAN8zZ7PvE,2345
+ostruct/cli/security/errors.py,sha256=hDYKxo7V600ibXtXbrDoCbLNL7MEkarZEQbO2QYfTnI,5859
+ostruct/cli/security/normalization.py,sha256=qevvxW3hHDtD1cVvDym8LJEQD1AKenVB-0ZvjCYjn5E,5242
+ostruct/cli/security/safe_joiner.py,sha256=PHowCeBAkfHfPqRwuO5Com0OemGuq3cHkdu2p9IYNT0,7107
+ostruct/cli/security/security_manager.py,sha256=KkI-fApKoDfRD7HSlz_H5LrIMbM5Rz9aP727t4Q_b5g,12770
+ostruct/cli/security/symlink_resolver.py,sha256=wtZdJ_T_0FOy6B1P5ty1odEXQk9vr8BzlWeAFD4huJE,16744
+ostruct/cli/security/types.py,sha256=15yuG_T4CXyAFFFdSWLjVS7ACmDGIPXhQpZ8awcDwCQ,2991
+ostruct/cli/security/windows_paths.py,sha256=qxC2H2kLwtmQ7YePYde3UrmOJcGnsLEebDLh242sUaI,13453
+ostruct/cli/template_env.py,sha256=S2ZvxuMQMicodSVqUhrw0kOzbNmlpQjSHtWlOwjXCms,1538
+ostruct/cli/template_extensions.py,sha256=tJN3HGAS2yzGI8Up6STPday8NVL0VV6UCClBrtDKYr0,1623
+ostruct/cli/template_filters.py,sha256=wZiR08e2_2SW28B7_tTU3wiij_KTCx3CCvlg-P2q7mk,19126
+ostruct/cli/template_io.py,sha256=yUWO-8rZnSdX97DTMSEX8fG9CP1ISsOhm2NZN3Fab9A,8821
+ostruct/cli/template_rendering.py,sha256=GrQAcKpGe6QEjSVQkOjpegMcor9LzVUikGmmEVgiWCE,12391
+ostruct/cli/template_schema.py,sha256=ckH4rUZnEgfm_BHS9LnMGr8LtDxRmZ0C6UBVrSp8KTc,19604
+ostruct/cli/template_utils.py,sha256=QGgewxU_Tgn81J5U-Y4xfi67CkN2dEqXI7PsaNiI9es,7812
+ostruct/cli/template_validation.py,sha256=q3ACw4TscdekJb3Z3CTYw0YPEYttqjKjm74ap4lWtU4,11737
+ostruct/cli/utils.py,sha256=1UCl4rHjBWKR5EKugvlVGHiHjO3XXmqvkgeAUSyIPDU,831
+ostruct/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ostruct_cli-0.4.0.dist-info/LICENSE,sha256=QUOY6QCYVxAiH8vdrUTDqe3i9hQ5bcNczppDSVpLTjk,1068
+ostruct_cli-0.4.0.dist-info/METADATA,sha256=Khg3pmpYFixNMW_RrpF9bfD_ZRJDjAqP4VDWDdMcBhY,5405
+ostruct_cli-0.4.0.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
+ostruct_cli-0.4.0.dist-info/entry_points.txt,sha256=NFq9IuqHVTem0j9zKjV8C1si_zGcP1RL6Wbvt9fUDXw,48
+ostruct_cli-0.4.0.dist-info/RECORD,,