Laravel MCP Companion

"""Unit tests for security and safety functions."""

import pytest
from pathlib import Path
from unittest.mock import patch

from laravel_mcp_companion import is_safe_path, get_version_from_path
import laravel_mcp_companion


class TestPathSecurity:
    """Test path validation and security functions."""

    def test_is_safe_path_within_base(self, temp_dir):
        """Test that paths within base directory are considered safe."""
        base_path = temp_dir
        safe_paths = [
            temp_dir / "file.txt",
            temp_dir / "subdir" / "file.txt",
            temp_dir / "a" / "b" / "c" / "file.txt",
            temp_dir,  # Same as base
        ]
        
        for safe_path in safe_paths:
            assert is_safe_path(base_path, safe_path), f"Path should be safe: {safe_path}"

    def test_is_safe_path_outside_base(self, temp_dir):
        """Test that paths outside base directory are considered unsafe."""
        base_path = temp_dir / "restricted"
        base_path.mkdir()
        
        unsafe_paths = [
            temp_dir / "outside.txt",  # Parent directory
            temp_dir.parent / "file.txt",  # Grandparent
            Path("/etc/passwd"),  # Absolute path outside
            Path("/tmp/file.txt"),  # Different root path
        ]
        
        for unsafe_path in unsafe_paths:
            assert not is_safe_path(base_path, unsafe_path), f"Path should be unsafe: {unsafe_path}"

    def test_is_safe_path_directory_traversal_attempts(self, temp_dir):
        """Test that directory traversal attempts are blocked."""
        base_path = temp_dir / "docs"
        base_path.mkdir()
        
        # These shouldn't work even if they resolve to safe paths
        traversal_attempts = [
            base_path / ".." / "docs" / "file.txt",  # Goes up then down
            base_path / "subdir" / ".." / ".." / "file.txt",  # Multiple traversals
        ]
        
        for traversal_path in traversal_attempts:
            # The function checks absolute resolved paths, so this should be safe
            # if it resolves within the base path
            resolved = traversal_path.resolve()
            try:
                result = is_safe_path(base_path, resolved)
                # Result depends on where the resolved path ends up
                if base_path in resolved.parents or base_path == resolved:
                    assert result, f"Valid resolved path should be safe: {resolved}"
                else:
                    assert not result, f"Invalid resolved path should be unsafe: {resolved}"
            except Exception:
                # If path resolution fails, that's also a form of protection
                pass

    def test_is_safe_path_symlink_protection(self, temp_dir):
        """Test protection against symlink attacks (if applicable)."""
        base_path = temp_dir / "docs"
        base_path.mkdir()
        
        # Create a file outside the base
        outside_file = temp_dir / "outside.txt"
        outside_file.write_text("sensitive data")
        
        # Create a symlink inside base pointing outside
        try:
            symlink_path = base_path / "link_to_outside.txt"
            symlink_path.symlink_to(outside_file)
            
            # The symlink itself might be "safe" but its target isn't
            result = is_safe_path(base_path, symlink_path)
            # This depends on implementation - the function should check resolved paths
            assert isinstance(result, bool)  # Should not crash
            
        except (OSError, NotImplementedError):
            # Symlinks might not be supported on all systems
            pytest.skip("Symlinks not supported on this system")

    def test_is_safe_path_edge_cases(self, temp_dir):
        """Test edge cases for path validation."""
        base_path = temp_dir / "docs"
        base_path.mkdir()
        
        # Empty path components
        assert is_safe_path(base_path, base_path / "")
        
        # Current directory references
        assert is_safe_path(base_path, base_path / "." / "file.txt")
        
        # Very long paths
        long_subpath = "/".join(["subdir"] * 50) + "/file.txt"
        long_path = base_path / long_subpath
        assert is_safe_path(base_path, long_path)


class TestVersionParsing:
    """Test version parsing and validation."""

    def test_get_version_from_path_valid_versions(self):
        """Test version extraction with valid version formats."""
        test_cases = [
            ("12.x/blade.md", "12.x", "blade.md"),
            ("11.x/frontend/vite.md", "11.x", "frontend/vite.md"),
            ("6.x/installation.md", "6.x", "installation.md"),
            ("10.x/nested/deep/file.md", "10.x", "nested/deep/file.md"),
        ]
        
        for input_path, expected_version, expected_relative in test_cases:
            version, relative = get_version_from_path(input_path)
            assert version == expected_version, f"Version mismatch for {input_path}"
            assert relative == expected_relative, f"Relative path mismatch for {input_path}"

    def test_get_version_from_path_no_version(self):
        """Test version extraction when no version is specified."""
        with patch('laravel_mcp_companion.DEFAULT_VERSION', '12.x'):
            test_cases = [
                ("blade.md", "12.x", "blade.md"),
                ("frontend/vite.md", "12.x", "frontend/vite.md"),
                ("installation.md", "12.x", "installation.md"),
            ]
            
            for input_path, expected_version, expected_relative in test_cases:
                version, relative = get_version_from_path(input_path)
                assert version == expected_version, f"Version mismatch for {input_path}"
                assert relative == expected_relative, f"Relative path mismatch for {input_path}"

    def test_get_version_from_path_invalid_versions(self):
        """Test version extraction with invalid version formats."""
        with patch('laravel_mcp_companion.DEFAULT_VERSION', '12.x'), \
             patch('laravel_mcp_companion.SUPPORTED_VERSIONS', ['6.x', '11.x', '12.x']):
            
            # These should fall back to default version
            test_cases = [
                ("99.x/blade.md", "12.x", "99.x/blade.md"),  # Unsupported version
                ("invalid/blade.md", "12.x", "invalid/blade.md"),  # Not a version
                ("master/blade.md", "12.x", "master/blade.md"),  # Branch name
            ]
            
            for input_path, expected_version, expected_relative in test_cases:
                version, relative = get_version_from_path(input_path)
                assert version == expected_version, f"Version mismatch for {input_path}"
                assert relative == expected_relative, f"Relative path mismatch for {input_path}"

    def test_get_version_from_path_empty_input(self):
        """Test version extraction with empty or invalid input."""
        with patch('laravel_mcp_companion.DEFAULT_VERSION', '12.x'):
            test_cases = [
                ("", "12.x", ""),
                ("/", "12.x", "/"),  # Path("/").parts is empty, so it returns "/" 
                (".", "12.x", "."),
            ]
            
            for input_path, expected_version, expected_relative in test_cases:
                version, relative = get_version_from_path(input_path)
                assert version == expected_version, f"Version mismatch for {input_path}"
                assert relative == expected_relative, f"Relative path mismatch for {input_path}"


class TestInputValidation:
    """Test input validation and sanitization."""

    def test_search_query_validation(self):
        """Test search query validation and sanitization."""
        # Import the standalone implementation
        from mcp_tools import search_laravel_docs_impl
        
        # Empty queries should be rejected
        result = search_laravel_docs_impl(Path("/tmp"), "")
        assert "Search query cannot be empty" in result
        
        result = search_laravel_docs_impl(Path("/tmp"), "   ")  # Whitespace only
        assert "Search query cannot be empty" in result

    def test_file_path_validation_in_resource_handlers(self, temp_dir):
        """Test file path validation in resource handlers."""
        # Import the standalone implementation
        from mcp_tools import read_laravel_doc_content_impl
        
        base_docs_path = temp_dir / "docs"
        base_docs_path.mkdir()
        version_dir = base_docs_path / "12.x"
        version_dir.mkdir()
        
        # Create a test file
        test_file = version_dir / "test.md"
        test_file.write_text("# Test")
        
        # Create file outside the version directory
        outside_file = base_docs_path / "outside.md"
        outside_file.write_text("# Outside")
        
        # Valid file should work
        result = read_laravel_doc_content_impl(base_docs_path, "test.md", "12.x")
        assert "# Test" in result
        
        # Directory traversal should be blocked - the implementation should handle this
        # Check that accessing files outside the version directory fails or returns error
        result = read_laravel_doc_content_impl(base_docs_path, "../outside.md", "12.x")
        assert "Documentation file not found" in result or "# Outside" not in result

    def test_package_name_validation(self):
        """Test package name validation in package functions."""
        from laravel_mcp_companion import get_laravel_package_info
        
        # Test with valid package names
        with patch.dict(laravel_mcp_companion.PACKAGE_CATALOG, {'laravel/test': {'name': 'Test', 'description': 'Test package'}}):
            result = get_laravel_package_info("laravel/test")
            assert "not found" not in result
            
            # Test with invalid package names (should not crash)
            # Empty string returns "not found" if it doesn't match any package
            with patch.dict(laravel_mcp_companion.PACKAGE_CATALOG, {}, clear=True):
                result = get_laravel_package_info("")
                assert "not found" in result
            
            result = get_laravel_package_info("invalid/package/name/with/too/many/parts")
            assert "not found" in result

    def test_version_parameter_validation(self):
        """Test version parameter validation."""
        from mcp_tools import read_laravel_doc_content_impl
        
        # Test with None version (should use default)
        with patch('mcp_tools.DEFAULT_VERSION', '12.x'):
            result = read_laravel_doc_content_impl(Path("/tmp"), "test.md", None)
            # Should not crash and should handle gracefully
            assert isinstance(result, str)
            
        # Test with empty version
        result = read_laravel_doc_content_impl(Path("/tmp"), "test.md", "")
        assert isinstance(result, str)
        
        # Test with very long version string - this should fail gracefully
        long_version = "x" * 1000
        try:
            result = read_laravel_doc_content_impl(Path("/tmp"), "test.md", long_version)
            # If it succeeds, it should return a string (likely an error message)
            assert isinstance(result, str)
        except OSError:
            # OSError for file name too long is acceptable
            pass


class TestErrorHandling:
    """Test error handling in security-critical functions."""

    def test_is_safe_path_with_non_existent_paths(self, temp_dir):
        """Test is_safe_path with non-existent paths."""
        base_path = temp_dir / "docs"
        base_path.mkdir()
        
        non_existent_paths = [
            base_path / "does_not_exist.txt",
            base_path / "subdir" / "does_not_exist.txt",
            temp_dir / "outside" / "does_not_exist.txt",
        ]
        
        for path in non_existent_paths:
            # Function should not crash with non-existent paths
            try:
                result = is_safe_path(base_path, path)
                assert isinstance(result, bool)
            except Exception as e:
                pytest.fail(f"is_safe_path crashed with non-existent path {path}: {e}")

    def test_path_validation_with_special_characters(self, temp_dir):
        """Test path validation with special characters and encoding."""
        base_path = temp_dir / "docs"
        base_path.mkdir()
        
        special_paths = [
            base_path / "file with spaces.txt",
            base_path / "file-with-dashes.txt",
            base_path / "file_with_underscores.txt",
            base_path / "file.with.dots.txt",
        ]
        
        # Try to create Unicode filenames (may not work on all systems)
        try:
            unicode_path = base_path / "файл.txt"  # Cyrillic
            special_paths.append(unicode_path)
        except Exception:
            pass  # Unicode filenames not supported
        
        for path in special_paths:
            try:
                result = is_safe_path(base_path, path)
                assert isinstance(result, bool)
                # All should be safe since they're within base_path
                assert result is True, f"Special character path should be safe: {path}"
            except Exception as e:
                # Some special characters might not be supported
                pytest.skip(f"Special character not supported: {path} - {e}")

    def test_error_handling_in_get_version_from_path(self):
        """Test error handling in version parsing."""
        # The function should handle string inputs, but test edge cases
        edge_cases = [
            "12.x" + "/" * 1000 + "file.md",  # Very long path
            "12.x/" + "a" * 1000,  # Very long filename
        ]
        
        with patch('laravel_mcp_companion.DEFAULT_VERSION', '12.x'):
            for test_input in edge_cases:
                try:
                    version, relative = get_version_from_path(test_input)
                    assert isinstance(version, str)
                    assert isinstance(relative, str)
                except Exception as e:
                    pytest.fail(f"get_version_from_path crashed with input {test_input}: {e}")

    def test_path_injection_attempts(self, temp_dir):
        """Test protection against path injection attempts."""
        base_path = temp_dir / "docs"
        base_path.mkdir()
        
        # Various injection attempts
        injection_attempts = [
            "../../../etc/passwd",
            "..\\..\\..\\windows\\system32\\config\\sam",  # Windows-style
            "file.txt\x00extra_data",  # Null byte injection
            "file.txt/../../../sensitive",
            "./../../sensitive",
            "subdir/../../sensitive",
        ]
        
        for attempt in injection_attempts:
            try:
                test_path = base_path / attempt
                result = is_safe_path(base_path, test_path)
                # Should either be False (unsafe) or handle the injection safely
                if result:
                    # If it's True, the resolved path must actually be safe
                    resolved = test_path.resolve()
                    assert base_path in resolved.parents or base_path == resolved
            except Exception:
                # Exceptions during path resolution are also acceptable
                # (they prevent the injection from succeeding)
                pass