Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

56.1 KB
Raw Blame
"""
Tests for research_library.utils module.

Tests path traversal protection and utility functions.
"""

from pathlib import Path
from unittest.mock import patch, Mock

import pytest

from local_deep_research.constants import (
    FILE_PATH_METADATA_ONLY,
    FILE_PATH_TEXT_ONLY,
    FILE_PATH_BLOB_DELETED,
)


class TestGetAbsoluteLibraryPath:
    """Tests for get_absolute_library_path function."""

    def test_valid_relative_path_returns_absolute_path(self, tmp_path):
        """Valid relative paths should return absolute paths."""
        from local_deep_research.research_library.utils import (
            get_absolute_library_path,
        )

        with patch(
            "local_deep_research.research_library.utils.get_library_storage_path"
        ) as mock_storage:
            mock_storage.return_value = tmp_path

            result = get_absolute_library_path("pdfs/test.pdf", "testuser")

            assert result is not None
            assert result == tmp_path / "pdfs/test.pdf"

    def test_path_traversal_with_dotdot_returns_none(self, tmp_path):
        """Path traversal attempts with .. should return None."""
        from local_deep_research.research_library.utils import (
            get_absolute_library_path,
        )

        with patch(
            "local_deep_research.research_library.utils.get_library_storage_path"
        ) as mock_storage:
            mock_storage.return_value = tmp_path

            result = get_absolute_library_path(
                "../../../etc/passwd", "testuser"
            )

            assert result is None

    def test_path_traversal_with_nested_dotdot_returns_none(self, tmp_path):
        """Path traversal with nested .. should return None."""
        from local_deep_research.research_library.utils import (
            get_absolute_library_path,
        )

        with patch(
            "local_deep_research.research_library.utils.get_library_storage_path"
        ) as mock_storage:
            mock_storage.return_value = tmp_path

            # Various traversal attempts using actual .. patterns
            traversal_paths = [
                "pdfs/../../secret.txt",
                "./../../etc/passwd",
                "subdir/../../../etc/passwd",
            ]

            for path in traversal_paths:
                result = get_absolute_library_path(path, "testuser")
                assert result is None, f"Path '{path}' should have been blocked"

    def test_absolute_path_outside_root_returns_none(self, tmp_path):
        """Absolute paths outside library root should return None."""
        from local_deep_research.research_library.utils import (
            get_absolute_library_path,
        )

        with patch(
            "local_deep_research.research_library.utils.get_library_storage_path"
        ) as mock_storage:
            mock_storage.return_value = tmp_path

            result = get_absolute_library_path("/etc/passwd", "testuser")

            assert result is None

    def test_empty_path_returns_none(self, tmp_path):
        """Empty path should return None."""
        from local_deep_research.research_library.utils import (
            get_absolute_library_path,
        )

        with patch(
            "local_deep_research.research_library.utils.get_library_storage_path"
        ) as mock_storage:
            mock_storage.return_value = tmp_path

            result = get_absolute_library_path("", "testuser")

            assert result is None

    def test_nested_valid_path_returns_correct_path(self, tmp_path):
        """Deeply nested valid paths should work correctly."""
        from local_deep_research.research_library.utils import (
            get_absolute_library_path,
        )

        with patch(
            "local_deep_research.research_library.utils.get_library_storage_path"
        ) as mock_storage:
            mock_storage.return_value = tmp_path

            result = get_absolute_library_path(
                "pdfs/2024/01/document.pdf", "testuser"
            )

            assert result is not None
            assert result == tmp_path / "pdfs/2024/01/document.pdf"

    def test_symlink_blocked(self, tmp_path):
        """Symlinks should be blocked in get_absolute_library_path."""
        import pytest

        from local_deep_research.research_library.utils import (
            get_absolute_library_path,
        )

        # Create a symlink inside library root pointing outside
        link_path = tmp_path / "evil_link"
        try:
            link_path.symlink_to("/etc/passwd")
        except OSError:
            pytest.skip("Cannot create symlinks in this environment")

        with patch(
            "local_deep_research.research_library.utils.get_library_storage_path"
        ) as mock_storage:
            mock_storage.return_value = tmp_path

            result = get_absolute_library_path("evil_link", "testuser")
            assert result is None


class TestGetAbsolutePathFromSettings:
    """Tests for get_absolute_path_from_settings function."""

    def test_valid_relative_path_returns_absolute_path(self, tmp_path):
        """Valid relative paths should return absolute paths."""
        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
        )

        mock_settings = Mock()
        mock_settings.get_setting.return_value = str(tmp_path)

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=mock_settings,
        ):
            result = get_absolute_path_from_settings("pdfs/test.pdf", "alice")

            assert result is not None
            assert result == tmp_path / "alice" / "pdfs/test.pdf"

    def test_empty_path_returns_library_root(self, tmp_path):
        """Empty path should return the library root."""
        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
        )

        mock_settings = Mock()
        mock_settings.get_setting.return_value = str(tmp_path)

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=mock_settings,
        ):
            result = get_absolute_path_from_settings("")

            assert result is not None
            assert result == tmp_path

    def test_path_traversal_returns_none(self, tmp_path):
        """Path traversal attempts should return None."""
        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
        )

        mock_settings = Mock()
        mock_settings.get_setting.return_value = str(tmp_path)

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=mock_settings,
        ):
            traversal_paths = [
                "../../../etc/passwd",
                "pdfs/../../secret.txt",
            ]

            for path in traversal_paths:
                result = get_absolute_path_from_settings(path, "alice")
                assert result is None, f"Path '{path}' should have been blocked"

    def test_symlink_blocked(self, tmp_path):
        """Symlinks should be blocked in get_absolute_path_from_settings."""
        import pytest

        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
        )

        # Create a symlink inside library root pointing outside
        (tmp_path / "alice").mkdir()
        link_path = tmp_path / "alice" / "evil_link"
        try:
            link_path.symlink_to("/etc/passwd")
        except OSError:
            pytest.skip("Cannot create symlinks in this environment")

        mock_settings = Mock()
        mock_settings.get_setting.return_value = str(tmp_path)

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=mock_settings,
        ):
            result = get_absolute_path_from_settings("evil_link", "alice")
            assert result is None


class TestLibraryServiceSafeAbsolutePath:
    """Tests for LibraryService._get_safe_absolute_path method."""

    def test_metadata_only_returns_none(self):
        """metadata_only marker should return None."""
        from local_deep_research.research_library.services.library_service import (
            LibraryService,
        )

        service = LibraryService("testuser")

        result = service._get_safe_absolute_path(FILE_PATH_METADATA_ONLY)

        assert result is None

    def test_text_only_not_stored_returns_none(self):
        """text_only_not_stored marker should return None."""
        from local_deep_research.research_library.services.library_service import (
            LibraryService,
        )

        service = LibraryService("testuser")

        result = service._get_safe_absolute_path(FILE_PATH_TEXT_ONLY)

        assert result is None

    def test_empty_path_returns_none(self):
        """Empty path should return None."""
        from local_deep_research.research_library.services.library_service import (
            LibraryService,
        )

        service = LibraryService("testuser")

        result = service._get_safe_absolute_path("")

        assert result is None

    def test_none_path_returns_none(self):
        """None path should return None."""
        from local_deep_research.research_library.services.library_service import (
            LibraryService,
        )

        service = LibraryService("testuser")

        result = service._get_safe_absolute_path(None)

        assert result is None

    def test_valid_path_returns_string(self, tmp_path):
        """Valid paths should return a string."""
        from local_deep_research.research_library.services.library_service import (
            LibraryService,
        )

        mock_settings = Mock()
        mock_settings.get_setting.return_value = str(tmp_path)

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=mock_settings,
        ):
            service = LibraryService("testuser")

            result = service._get_safe_absolute_path("pdfs/test.pdf")

            assert result is not None
            assert isinstance(result, str)
            # Per-user isolation (#5521) puts library files under the
            # user's own subdirectory, not the bare shared root.
            assert result == str(tmp_path / "testuser" / "pdfs/test.pdf")

    def test_path_traversal_returns_none(self, tmp_path):
        """Path traversal attempts should return None."""
        from local_deep_research.research_library.services.library_service import (
            LibraryService,
        )

        mock_settings = Mock()
        mock_settings.get_setting.return_value = str(tmp_path)

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=mock_settings,
        ):
            service = LibraryService("testuser")

            result = service._get_safe_absolute_path("../../../etc/passwd")

            assert result is None


class TestPDFStorageManagerSafeFilePath:
    """Tests for PDFStorageManager._get_safe_file_path method."""

    def test_valid_path_returns_path_object(self, tmp_path):
        """Valid relative paths should return Path objects."""
        from local_deep_research.research_library.services.pdf_storage_manager import (
            PDFStorageManager,
        )

        manager = PDFStorageManager(
            library_root=tmp_path,
            storage_mode="filesystem",
        )

        result = manager._get_safe_file_path("pdfs/test.pdf")

        assert result is not None
        assert isinstance(result, Path)
        assert result == tmp_path / "pdfs/test.pdf"

    def test_metadata_only_returns_none(self, tmp_path):
        """metadata_only marker should return None."""
        from local_deep_research.research_library.services.pdf_storage_manager import (
            PDFStorageManager,
        )

        manager = PDFStorageManager(
            library_root=tmp_path,
            storage_mode="filesystem",
        )

        result = manager._get_safe_file_path(FILE_PATH_METADATA_ONLY)

        assert result is None

    def test_text_only_not_stored_returns_none(self, tmp_path):
        """text_only_not_stored marker should return None."""
        from local_deep_research.research_library.services.pdf_storage_manager import (
            PDFStorageManager,
        )

        manager = PDFStorageManager(
            library_root=tmp_path,
            storage_mode="filesystem",
        )

        result = manager._get_safe_file_path(FILE_PATH_TEXT_ONLY)

        assert result is None

    def test_empty_path_returns_none(self, tmp_path):
        """Empty path should return None."""
        from local_deep_research.research_library.services.pdf_storage_manager import (
            PDFStorageManager,
        )

        manager = PDFStorageManager(
            library_root=tmp_path,
            storage_mode="filesystem",
        )

        result = manager._get_safe_file_path("")

        assert result is None

    def test_path_traversal_returns_none(self, tmp_path):
        """Path traversal attempts should return None."""
        from local_deep_research.research_library.services.pdf_storage_manager import (
            PDFStorageManager,
        )

        manager = PDFStorageManager(
            library_root=tmp_path,
            storage_mode="filesystem",
        )

        traversal_paths = [
            "../../../etc/passwd",
            "pdfs/../../secret.txt",
        ]

        for path in traversal_paths:
            result = manager._get_safe_file_path(path)
            assert result is None, f"Path '{path}' should have been blocked"

    def test_none_path_returns_none(self, tmp_path):
        """None path should return None."""
        from local_deep_research.research_library.services.pdf_storage_manager import (
            PDFStorageManager,
        )

        manager = PDFStorageManager(
            library_root=tmp_path,
            storage_mode="filesystem",
        )

        result = manager._get_safe_file_path(None)

        assert result is None


class TestPathTraversalIntegration:
    """Integration tests for path traversal protection across components."""

    def test_malicious_document_file_path_blocked_in_has_pdf(self, tmp_path):
        """PDFStorageManager.has_pdf should handle malicious paths safely."""
        from unittest.mock import patch

        from local_deep_research.research_library.services.pdf_storage_manager import (
            PDFStorageManager,
        )

        manager = PDFStorageManager(
            library_root=tmp_path,
            storage_mode="filesystem",
        )

        # Create a mock document with malicious file_path
        mock_doc = Mock()
        mock_doc.file_type = "pdf"
        mock_doc.file_path = "../../../etc/passwd"

        mock_session = Mock()
        mock_session.query.return_value.filter_by.return_value.first.return_value = None

        # Patch DocumentBlob so its .id attribute is accessible outside SQLAlchemy
        mock_blob_class = Mock()
        with patch(
            "local_deep_research.database.models.library.DocumentBlob",
            mock_blob_class,
        ):
            # Should not raise an error, just return False
            result = manager.has_pdf(mock_doc, mock_session)

        assert result is False

    def test_malicious_document_file_path_blocked_in_load(self, tmp_path):
        """PDFStorageManager._load_from_filesystem should handle malicious paths."""
        from local_deep_research.research_library.services.pdf_storage_manager import (
            PDFStorageManager,
        )

        manager = PDFStorageManager(
            library_root=tmp_path,
            storage_mode="filesystem",
        )

        # Create a mock document with malicious file_path
        mock_doc = Mock()
        mock_doc.file_path = "../../../etc/passwd"

        # Should return None, not raise or attempt to read /etc/passwd
        result = manager._load_from_filesystem(mock_doc)

        assert result is None

    def test_malicious_document_file_path_blocked_in_delete(self, tmp_path):
        """PDFStorageManager.delete_pdf should handle malicious paths safely."""
        from local_deep_research.research_library.services.pdf_storage_manager import (
            PDFStorageManager,
        )

        # A user context is required for destructive filesystem ops (delete
        # fails closed without one); the traversal path must still be blocked.
        manager = PDFStorageManager(
            library_root=tmp_path,
            storage_mode="filesystem",
            username="alice",
        )

        # Create a mock document with malicious file_path
        mock_doc = Mock()
        mock_doc.file_path = "../../../etc/passwd"
        mock_doc.storage_mode = "filesystem"

        mock_session = Mock()
        mock_session.query.return_value.filter_by.return_value.first.return_value = None

        # Should not raise an error or delete /etc/passwd
        result = manager.delete_pdf(mock_doc, mock_session)

        # Should return True (successful "deletion" since there was nothing to delete)
        # The important thing is it doesn't try to delete outside the library
        assert result is True

    def test_is_already_downloaded_handles_malicious_path(self, tmp_path):
        """DownloadService.is_already_downloaded should not crash on malicious paths."""
        from local_deep_research.research_library.services.download_service import (
            DownloadService,
        )
        from local_deep_research.database.models.download_tracker import (
            DownloadTracker,
        )

        # Create a mock tracker with malicious file_path
        mock_tracker = Mock(spec=DownloadTracker)
        mock_tracker.file_path = "../../../etc/passwd"
        mock_tracker.is_downloaded = True

        mock_session = Mock()
        mock_session.query.return_value.filter_by.return_value.first.return_value = mock_tracker

        mock_settings = Mock()
        mock_settings.get_setting.return_value = str(tmp_path)

        with (
            patch(
                "local_deep_research.utilities.db_utils.get_settings_manager",
                return_value=mock_settings,
            ),
            patch(
                "local_deep_research.research_library.services.download_service.get_user_db_session"
            ) as mock_db_session,
        ):
            # Make the context manager return our mock session
            mock_db_session.return_value.__enter__ = Mock(
                return_value=mock_session
            )
            mock_db_session.return_value.__exit__ = Mock(return_value=False)

            service = DownloadService.__new__(DownloadService)
            service.username = "testuser"
            service.password = None

            # Should not raise AttributeError on None.exists()
            # Should return (False, None) because path traversal is blocked
            result = service.is_already_downloaded(
                "https://example.com/doc.pdf"
            )

            assert result == (False, None)


class TestPathTraversalAttackVectors:
    """Test various path traversal attack vectors are blocked."""

    def test_simple_dotdot_traversal(self, tmp_path):
        """Basic ../ traversal should be blocked."""
        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
        )

        mock_settings = Mock()
        mock_settings.get_setting.return_value = str(tmp_path)

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=mock_settings,
        ):
            attacks = [
                "../secret.txt",
                "../../secret.txt",
                "../../../etc/passwd",
                "../../../../etc/shadow",
            ]
            for attack in attacks:
                result = get_absolute_path_from_settings(attack, "alice")
                assert result is None, f"Attack '{attack}' should be blocked"

    def test_nested_traversal_escaping_root(self, tmp_path):
        """Traversal that escapes library root should be blocked."""
        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
        )

        mock_settings = Mock()
        mock_settings.get_setting.return_value = str(tmp_path)

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=mock_settings,
        ):
            # These paths escape the library root
            attacks = [
                "pdfs/../../../etc/passwd",
                "documents/subfolder/../../../../../../tmp/evil",
                "a/b/c/d/../../../../../../../../etc/passwd",
            ]
            for attack in attacks:
                result = get_absolute_path_from_settings(attack, "alice")
                assert result is None, f"Attack '{attack}' should be blocked"

    def test_traversal_staying_in_root_is_allowed(self, tmp_path):
        """Traversal that stays within library root should be allowed."""
        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
        )

        mock_settings = Mock()
        mock_settings.get_setting.return_value = str(tmp_path)

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=mock_settings,
        ):
            # This path uses .. but stays within library root
            # valid/path/to/../../../outside resolves to "outside" which is in root
            result = get_absolute_path_from_settings(
                "valid/path/to/../../../outside", "alice"
            )
            # This remains inside the requesting user's root.
            assert result is not None
            assert result == tmp_path / "alice" / "outside"

    def test_absolute_path_injection(self, tmp_path):
        """Absolute paths should be blocked."""
        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
        )

        mock_settings = Mock()
        mock_settings.get_setting.return_value = str(tmp_path)

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=mock_settings,
        ):
            attacks = [
                "/etc/passwd",
                "/etc/shadow",
                "/root/.ssh/id_rsa",
                "/var/log/auth.log",
            ]
            for attack in attacks:
                result = get_absolute_path_from_settings(attack, "alice")
                assert result is None, f"Attack '{attack}' should be blocked"

    def test_dot_current_dir_traversal(self, tmp_path):
        """Traversal using ./ patterns should be blocked when escaping."""
        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
        )

        mock_settings = Mock()
        mock_settings.get_setting.return_value = str(tmp_path)

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=mock_settings,
        ):
            attacks = [
                "./../../../etc/passwd",
                "./././../../../etc/passwd",
                "././../secret.txt",
            ]
            for attack in attacks:
                result = get_absolute_path_from_settings(attack, "alice")
                assert result is None, f"Attack '{attack}' should be blocked"

    def test_double_slash_traversal(self, tmp_path):
        """Double slashes with traversal should be handled."""
        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
        )

        mock_settings = Mock()
        mock_settings.get_setting.return_value = str(tmp_path)

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=mock_settings,
        ):
            # These should be blocked due to .. patterns
            attacks = [
                "..//..//etc/passwd",
                "pdfs//..//..//secret.txt",
            ]
            for attack in attacks:
                result = get_absolute_path_from_settings(attack, "alice")
                assert result is None, f"Attack '{attack}' should be blocked"

    def test_backslash_traversal_windows_style(self, tmp_path):
        """Windows-style backslash traversal - safe on Linux, blocked on Windows.

        On Linux, backslashes are valid filename characters, not path separators.
        So '..\\..\\etc\\passwd' is treated as a literal filename, which is safe.
        On Windows, werkzeug's safe_join would block these.
        """
        import sys

        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
        )

        mock_settings = Mock()
        mock_settings.get_setting.return_value = str(tmp_path)

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=mock_settings,
        ):
            attacks = [
                "..\\..\\..\\etc\\passwd",
                "..\\..\\windows\\win.ini",
            ]
            for attack in attacks:
                result = get_absolute_path_from_settings(attack, "alice")
                if sys.platform == "win32":
                    # On Windows, these should be blocked
                    assert result is None, (
                        f"Attack '{attack}' should be blocked"
                    )
                else:
                    # On Linux, backslashes are literal - path stays in library
                    if result is not None:
                        assert str(tmp_path) in str(result)

    def test_mixed_slash_with_real_traversal(self, tmp_path):
        """Mixed slash patterns with real .. traversal should be blocked."""
        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
        )

        mock_settings = Mock()
        mock_settings.get_setting.return_value = str(tmp_path)

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=mock_settings,
        ):
            # These contain real forward-slash traversal that escapes root
            attacks = [
                "pdfs/../../../etc/passwd",
                "subdir/../../../../../../etc/passwd",
            ]
            for attack in attacks:
                result = get_absolute_path_from_settings(attack, "alice")
                assert result is None, f"Attack '{attack}' should be blocked"

    def test_mangled_patterns_stay_in_library(self, tmp_path):
        """Mangled patterns like '..../' don't escape library.

        Pattern '....' is treated as a literal directory name, not traversal.
        These patterns are safe because they stay within the library root.
        """
        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
        )

        mock_settings = Mock()
        mock_settings.get_setting.return_value = str(tmp_path)

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=mock_settings,
        ):
            # These don't actually traverse - '....' is a literal dirname
            patterns = [
                "....//....//file.pdf",
                "..../file.pdf",
            ]
            for pattern in patterns:
                result = get_absolute_path_from_settings(pattern, "alice")
                # These are allowed because they stay in library
                if result is not None:
                    assert str(tmp_path) in str(result)

    def test_null_byte_injection(self, tmp_path):
        """Null byte injection should be blocked or handled safely.

        Null bytes (%00) can truncate paths in some languages (PHP < 5.3.4).
        While Python handles this better, we should still test it.
        """
        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
        )

        mock_settings = Mock()
        mock_settings.get_setting.return_value = str(tmp_path)

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=mock_settings,
        ):
            # Null byte injection patterns
            attacks = [
                "../../../etc/passwd\x00.pdf",
                "pdfs/test.pdf\x00/../../../etc/passwd",
                "../../../etc/passwd%00.pdf",  # URL-encoded null (if decoded)
            ]
            for attack in attacks:
                result = get_absolute_path_from_settings(attack, "alice")
                assert result is None, (
                    f"Null byte attack '{attack!r}' should be blocked"
                )

    def test_unc_path_injection_windows(self, tmp_path):
        """UNC paths (Windows network shares) should be blocked.

        UNC paths like \\\\server\\share can be used for SSRF or credential theft.
        """
        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
        )

        mock_settings = Mock()
        mock_settings.get_setting.return_value = str(tmp_path)

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=mock_settings,
        ):
            # UNC path patterns
            attacks = [
                "\\\\attacker.com\\share\\malicious.pdf",
                "\\\\localhost\\c$\\windows\\win.ini",
                "//attacker.com/share/file.pdf",
            ]
            for attack in attacks:
                result = get_absolute_path_from_settings(attack, "alice")
                # Should be blocked or stay within library
                if result is not None:
                    assert str(tmp_path) in str(result), (
                        f"Attack '{attack}' resulted in path outside library"
                    )

    def test_dot_segment_variations(self, tmp_path):
        """Various dot segment patterns should be handled.

        Tests patterns like '...' and '....' which some systems mishandle.
        """
        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
        )

        mock_settings = Mock()
        mock_settings.get_setting.return_value = str(tmp_path)

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=mock_settings,
        ):
            # Various dot patterns
            attacks = [
                ".../.../.../etc/passwd",
                "..../..../etc/passwd",
                "..;/..;/..;/etc/passwd",  # Tomcat bypass
            ]
            for attack in attacks:
                result = get_absolute_path_from_settings(attack, "alice")
                # These are unusual patterns - should either be blocked or safe
                if result is not None:
                    assert str(tmp_path) in str(result), (
                        f"Attack '{attack}' resulted in path outside library"
                    )


class TestPathTraversalEdgeCases:
    """Test edge cases and boundary conditions."""

    def test_whitespace_paths(self, tmp_path):
        """Paths with only whitespace should be handled."""
        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
        )

        mock_settings = Mock()
        mock_settings.get_setting.return_value = str(tmp_path)

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=mock_settings,
        ):
            # Whitespace-only paths should return None or be sanitized
            whitespace_paths = ["   ", "\t", "\n", "  \t\n  "]
            for path in whitespace_paths:
                result = get_absolute_path_from_settings(path, "alice")
                # After strip(), these become empty, which should return library_root
                # or None depending on implementation
                assert result is None or result == tmp_path / "alice"

    def test_path_with_spaces(self, tmp_path):
        """Valid paths with spaces should work."""
        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
        )

        mock_settings = Mock()
        mock_settings.get_setting.return_value = str(tmp_path)

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=mock_settings,
        ):
            result = get_absolute_path_from_settings(
                "pdfs/my document.pdf", "alice"
            )
            assert result is not None
            assert result == tmp_path / "alice" / "pdfs/my document.pdf"

    def test_path_with_special_characters(self, tmp_path):
        """Paths with allowed special characters should work."""
        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
        )

        mock_settings = Mock()
        mock_settings.get_setting.return_value = str(tmp_path)

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=mock_settings,
        ):
            # Valid special characters
            valid_paths = [
                "pdfs/test-file.pdf",
                "pdfs/test_file.pdf",
                "pdfs/test.file.pdf",
            ]
            for path in valid_paths:
                result = get_absolute_path_from_settings(path, "alice")
                assert result is not None, f"Path '{path}' should be allowed"
                assert result == tmp_path / "alice" / path

    def test_very_long_path(self, tmp_path):
        """Very long paths should be handled without crashing."""
        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
        )

        mock_settings = Mock()
        mock_settings.get_setting.return_value = str(tmp_path)

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=mock_settings,
        ):
            # Create a very long but valid path
            long_path = "/".join(["subdir"] * 50) + "/file.pdf"
            result = get_absolute_path_from_settings(long_path, "alice")
            # Should either work or fail gracefully (no crash)
            assert result is None or isinstance(result, Path)

    def test_unicode_path(self, tmp_path):
        """Unicode paths should be handled."""
        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
        )

        mock_settings = Mock()
        mock_settings.get_setting.return_value = str(tmp_path)

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=mock_settings,
        ):
            # Unicode filenames are common
            unicode_paths = [
                "pdfs/документ.pdf",  # Russian
                "pdfs/文档.pdf",  # Chinese
                "pdfs/ドキュメント.pdf",  # Japanese
            ]
            for path in unicode_paths:
                # Should not crash - just verify no exception is raised
                _ = get_absolute_path_from_settings(path, "alice")
                # Result depends on filesystem support


class TestCascadeHelperPathSafety:
    """Test CascadeHelper path handling."""

    def test_delete_filesystem_file_rejects_special_markers(self):
        """CascadeHelper should reject special path markers."""
        from local_deep_research.research_library.deletion.utils.cascade_helper import (
            CascadeHelper,
        )

        markers = [
            FILE_PATH_METADATA_ONLY,
            FILE_PATH_TEXT_ONLY,
            FILE_PATH_BLOB_DELETED,
        ]
        for marker in markers:
            result = CascadeHelper.delete_filesystem_file(marker)
            assert result is False, f"Marker '{marker}' should be rejected"

    def test_delete_filesystem_file_handles_none(self):
        """CascadeHelper should handle None path."""
        from local_deep_research.research_library.deletion.utils.cascade_helper import (
            CascadeHelper,
        )

        result = CascadeHelper.delete_filesystem_file(None)
        assert result is False

    def test_delete_filesystem_file_handles_empty_string(self):
        """CascadeHelper should handle empty string path."""
        from local_deep_research.research_library.deletion.utils.cascade_helper import (
            CascadeHelper,
        )

        result = CascadeHelper.delete_filesystem_file("")
        assert result is False

    def test_delete_filesystem_file_nonexistent_returns_false(self, tmp_path):
        """CascadeHelper should return False for nonexistent files."""
        from local_deep_research.research_library.deletion.utils.cascade_helper import (
            CascadeHelper,
        )

        result = CascadeHelper.delete_filesystem_file(
            str(tmp_path / "nonexistent.pdf")
        )
        assert result is False

    def test_delete_filesystem_file_deletes_valid_file(self, tmp_path):
        """CascadeHelper should delete valid files."""
        from local_deep_research.research_library.deletion.utils.cascade_helper import (
            CascadeHelper,
        )

        # Create a test file
        test_file = tmp_path / "test.pdf"
        test_file.write_text("test content")
        assert test_file.exists()

        result = CascadeHelper.delete_filesystem_file(str(test_file))

        assert result is True
        assert not test_file.exists()


def _symlinked_pdfs_library(tmp_path, username=None):
    """Create the sanctioned "<library_root>/pdfs onto a bigger disk" layout.

    Returns ``(library_root, big_disk_pdfs)`` with the ``pdfs`` symlink
    under the optional per-user directory, mirroring the layout
    pinned on the save side by
    ``test_saves_to_symlinked_pdfs_directory``. Skips the test when the
    environment cannot create directory symlinks.
    """
    library_root = tmp_path / "library"
    library_root.mkdir()
    user_root = library_root / username if username else library_root
    user_root.mkdir(exist_ok=True)
    big_disk_pdfs = tmp_path / "big_disk_pdfs"
    big_disk_pdfs.mkdir()
    try:
        (user_root / "pdfs").symlink_to(big_disk_pdfs, target_is_directory=True)
    except (OSError, NotImplementedError):
        pytest.skip("Cannot create directory symlinks in this environment")
    return library_root, big_disk_pdfs


class TestTrustedPdfsSymlinkLayout:
    """The sanctioned pdfs-symlink layout must keep resolving via utils.

    The GHSA-gv87-qcw7-gjr8 realpath containment in validate_safe_path
    refuses a stored ``pdfs/<name>`` path whose ``<root>/pdfs`` is a
    symlink out of the root — the trusted-leaf carve-out must therefore
    apply to the settings/utils resolution path (deletion, download
    dedupe, text extraction, open-location, integrity sweep), not only
    to PDFStorageManager on the write side.
    """

    def test_get_absolute_library_path_resolves_stored_pdfs_path(
        self, tmp_path
    ):
        """A stored "pdfs/<name>" path resolves (not None) through
        get_absolute_library_path, against the RESOLVED pdfs target."""
        from local_deep_research.research_library.utils import (
            get_absolute_library_path,
        )

        library_root, big_disk_pdfs = _symlinked_pdfs_library(tmp_path)
        stored = big_disk_pdfs / "stored.pdf"
        stored.write_bytes(b"%PDF-1.4 fake")

        with patch(
            "local_deep_research.research_library.utils.get_library_storage_path"
        ) as mock_storage:
            mock_storage.return_value = library_root

            result = get_absolute_library_path("pdfs/stored.pdf", "testuser")

        assert result is not None
        assert result.is_file()
        # Containment ran against the resolved pdfs directory, so the
        # returned path is the real location on the bigger disk.
        assert result == stored.resolve()

    def test_get_absolute_path_from_settings_resolves_stored_pdfs_path(
        self, tmp_path
    ):
        """A stored "pdfs/<name>" path resolves (not None) through
        get_absolute_path_from_settings (download dedupe, text
        extraction, integrity sweep all resolve through here)."""
        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
        )

        library_root, big_disk_pdfs = _symlinked_pdfs_library(
            tmp_path, username="alice"
        )
        stored = big_disk_pdfs / "stored.pdf"
        stored.write_bytes(b"%PDF-1.4 fake")

        mock_settings = Mock()
        mock_settings.get_setting.side_effect = lambda key, default=None: (
            str(library_root)
            if key == "research_library.storage_path"
            else default
        )

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=mock_settings,
        ):
            result = get_absolute_path_from_settings("pdfs/stored.pdf", "alice")

        assert result is not None
        assert result.is_file()
        assert result == stored.resolve()

    def test_utils_resolved_deletion_path_unlinks_real_file(self, tmp_path):
        """The utils-resolved path names the REAL file on the bigger disk.

        Resolver half only. LibraryService.delete_document unlinks the
        path get_absolute_path_from_settings returns; without the
        trusted-leaf carve-out the realpath containment makes that
        resolution return None, so the unlink is skipped and the PDF is
        left on the big disk. DocumentDeletionService additionally
        re-checks its unlink against get_containment_root_from_settings;
        that flow is pinned end to end by TestSanctionedPdfsLayoutDeletion
        in tests/research_library/deletion/services/test_document_deletion.py.
        """
        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
        )

        library_root, big_disk_pdfs = _symlinked_pdfs_library(
            tmp_path, username="alice"
        )
        stored = big_disk_pdfs / "5.pdf"
        stored.write_bytes(b"%PDF-1.4 fake")

        mock_settings = Mock()
        mock_settings.get_setting.side_effect = lambda key, default=None: (
            str(library_root)
            if key == "research_library.storage_path"
            else default
        )

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=mock_settings,
        ):
            file_path = get_absolute_path_from_settings("pdfs/5.pdf", "alice")

        assert file_path is not None
        assert file_path.is_file()
        file_path.unlink()
        assert not stored.exists()

    def test_escape_symlink_outside_trusted_leaf_still_blocked(self, tmp_path):
        """A symlink NOT under the trusted pdfs leaf still fails closed."""
        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
        )

        library_root, _ = _symlinked_pdfs_library(tmp_path, username="alice")
        try:
            (library_root / "alice" / "evil").symlink_to("/etc")
        except (OSError, NotImplementedError):
            pytest.skip("Cannot create symlinks in this environment")

        mock_settings = Mock()
        mock_settings.get_setting.side_effect = lambda key, default=None: (
            str(library_root)
            if key == "research_library.storage_path"
            else default
        )

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=mock_settings,
        ):
            result = get_absolute_path_from_settings("evil/passwd", "alice")

        assert result is None

    def test_second_level_escape_inside_resolved_pdfs_still_blocked(
        self, tmp_path
    ):
        """A symlink planted INSIDE the resolved pdfs target and pointing
        outside it still fails closed (containment against the resolved
        pdfs directory, not a blanket trust of the big disk)."""
        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
        )

        library_root, big_disk_pdfs = _symlinked_pdfs_library(
            tmp_path, username="alice"
        )
        try:
            (big_disk_pdfs / "evil").symlink_to("/etc")
        except (OSError, NotImplementedError):
            pytest.skip("Cannot create symlinks in this environment")

        mock_settings = Mock()
        mock_settings.get_setting.side_effect = lambda key, default=None: (
            str(library_root)
            if key == "research_library.storage_path"
            else default
        )

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=mock_settings,
        ):
            result = get_absolute_path_from_settings(
                "pdfs/evil/passwd", "alice"
            )

        assert result is None


def _settings_with_storage_path(library_root):
    """A settings manager whose library storage path is ``library_root``."""
    settings = Mock()
    settings.get_setting.side_effect = lambda key, default=None: (
        str(library_root) if key == "research_library.storage_path" else default
    )
    return settings


class TestStoredPdfsPathSpellings:
    """The trusted-leaf test reads a stored path as validate_safe_path
    does, so redundant separators, surrounding whitespace and ``.``/``..``
    segments that collapse to ``pdfs/<name>`` still resolve in the
    symlinked layout, as they did before the containment check."""

    @pytest.mark.parametrize(
        "stored",
        ["pdfs//5.pdf", " pdfs/5.pdf", "pdfs/../pdfs/5.pdf", "pdfs/./5.pdf"],
    )
    def test_equivalent_spellings_resolve_to_the_stored_file(
        self, tmp_path, stored
    ):
        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
        )

        library_root, big_disk_pdfs = _symlinked_pdfs_library(
            tmp_path, username="alice"
        )
        target = big_disk_pdfs / "5.pdf"
        target.write_bytes(b"%PDF-1.4 fake")

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=_settings_with_storage_path(library_root),
        ):
            resolved = get_absolute_path_from_settings(stored, "alice")

        assert resolved == target.resolve()

    @pytest.mark.parametrize(
        "stored",
        [
            "pdfs/../../5.pdf",
            "pdfs//..//..//5.pdf",
            "pdfs/./../../5.pdf",
            "/pdfs/5.pdf",
        ],
    )
    def test_traversal_spellings_still_fail_closed(self, tmp_path, stored):
        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
        )

        library_root, big_disk_pdfs = _symlinked_pdfs_library(
            tmp_path, username="alice"
        )
        (big_disk_pdfs / "5.pdf").write_bytes(b"%PDF-1.4 fake")
        # A file where the traversal lands (outside alice's root).
        (library_root / "5.pdf").write_bytes(b"another user's file")

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=_settings_with_storage_path(library_root),
        ):
            resolved = get_absolute_path_from_settings(stored, "alice")

        assert resolved is None


class TestWindowsStoredPdfsPaths:
    """PDFStorageManager stores ``str(path.relative_to(library_root))``,
    which is ``pdfs\\<name>`` on Windows. The trusted-leaf test must split
    that on the backslash, as it splits ``pdfs/<name>`` on POSIX. When it
    split on "/" only, the read resolver and the unlink boundary both used
    the library root for such a path, so in the symlinked layout the PDF
    was refused. ``_STORED_PATH_MODULE`` is set to ``ntpath`` here to read
    stored paths the way a Windows host does."""

    @pytest.fixture
    def windows_separators(self, monkeypatch):
        import ntpath

        from local_deep_research.research_library import utils

        monkeypatch.setattr(utils, "_STORED_PATH_MODULE", ntpath)

    @pytest.mark.parametrize(
        "stored",
        [
            "pdfs\\5.pdf",
            "pdfs\\\\5.pdf",
            " pdfs\\5.pdf",
            "pdfs\\..\\pdfs\\5.pdf",
            "pdfs\\.\\5.pdf",
            "pdfs/5.pdf",
        ],
    )
    def test_the_stored_pdf_and_its_boundary_use_the_pdfs_directory(
        self, tmp_path, windows_separators, stored
    ):
        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
            get_containment_root_from_settings,
        )

        library_root, big_disk_pdfs = _symlinked_pdfs_library(
            tmp_path, username="alice"
        )
        target = big_disk_pdfs / "5.pdf"
        target.write_bytes(b"%PDF-1.4 fake")

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=_settings_with_storage_path(library_root),
        ):
            resolved = get_absolute_path_from_settings(stored, "alice")
            boundary = get_containment_root_from_settings(stored, "alice")

        assert resolved == target.resolve()
        assert boundary == big_disk_pdfs.resolve()

    def test_the_remainder_uses_forward_slashes_only(
        self, tmp_path, windows_separators
    ):
        """werkzeug's safe_join refuses a backslash on Windows, so the part
        validated against the pdfs directory must not carry one."""
        from local_deep_research.research_library.utils import (
            _containment_base,
        )

        user_root = tmp_path / "alice"
        (user_root / "pdfs").mkdir(parents=True)

        assert _containment_base("pdfs\\sub\\5.pdf", user_root) == (
            user_root / "pdfs",
            "sub/5.pdf",
        )

    @pytest.mark.parametrize(
        "stored",
        [
            "pdfs\\..\\..\\5.pdf",
            "pdfs\\\\..\\\\..\\\\5.pdf",
            "pdfs\\.\\..\\..\\5.pdf",
            "pdfs\\sub\\..\\..\\..\\5.pdf",
            "..\\pdfs\\5.pdf",
            "\\pdfs\\5.pdf",
            "\\\\pdfs\\5.pdf",
            "pdfs\\..",
            "pdfs\\",
        ],
    )
    def test_traversal_spellings_skip_the_carve_out(
        self, tmp_path, windows_separators, stored
    ):
        """They are checked unchanged against the user root, where
        werkzeug's safe_join refuses any backslash on Windows."""
        from local_deep_research.research_library.utils import (
            _containment_base,
        )

        user_root = tmp_path / "alice"
        (user_root / "pdfs").mkdir(parents=True)

        assert _containment_base(stored, user_root) == (user_root, stored)

    def test_an_escape_inside_the_resolved_pdfs_target_is_refused(
        self, tmp_path, windows_separators
    ):
        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
        )

        library_root, big_disk_pdfs = _symlinked_pdfs_library(
            tmp_path, username="alice"
        )
        outside = tmp_path / "outside"
        outside.mkdir()
        (outside / "secret.pdf").write_bytes(b"outside the pdfs directory")
        try:
            (big_disk_pdfs / "evil").symlink_to(
                outside, target_is_directory=True
            )
        except (OSError, NotImplementedError):
            pytest.skip("Cannot create symlinks in this environment")

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=_settings_with_storage_path(library_root),
        ):
            resolved = get_absolute_path_from_settings(
                "pdfs\\evil\\secret.pdf", "alice"
            )

        assert resolved is None

    def test_a_backslash_stays_a_filename_character_on_posix(
        self, tmp_path, monkeypatch
    ):
        import posixpath

        from local_deep_research.research_library import utils

        monkeypatch.setattr(utils, "_STORED_PATH_MODULE", posixpath)
        user_root = tmp_path / "alice"
        (user_root / "pdfs").mkdir(parents=True)

        assert utils._containment_base("pdfs\\5.pdf", user_root) == (
            user_root,
            "pdfs\\5.pdf",
        )


class TestContainmentRootFromSettings:
    """get_containment_root_from_settings returns, already resolved, the
    directory the resolver confines a stored path to. DocumentDeletionService
    passes it to CascadeHelper.delete_filesystem_file as ``allowed_root``
    with ``allowed_root_is_resolved=True``."""

    def test_pdfs_paths_use_the_pdfs_directory_and_others_the_user_root(
        self, tmp_path
    ):
        from local_deep_research.research_library.deletion.utils.cascade_helper import (
            CascadeHelper,
        )
        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
            get_containment_root_from_settings,
        )

        library_root, big_disk_pdfs = _symlinked_pdfs_library(
            tmp_path, username="alice"
        )
        user_root = library_root.resolve() / "alice"
        (big_disk_pdfs / "5.pdf").write_bytes(b"%PDF-1.4 fake")

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=_settings_with_storage_path(library_root),
        ):
            file_path = get_absolute_path_from_settings("pdfs/5.pdf", "alice")
            pdfs_root = get_containment_root_from_settings(
                "pdfs/5.pdf", "alice"
            )
            other_root = get_containment_root_from_settings(
                "notes/5.pdf", "alice"
            )

        # The boundary comes back resolved: the pdfs link's target.
        assert pdfs_root == big_disk_pdfs.resolve()
        assert other_root == user_root
        # The unlink re-check accepts the PDF against its own boundary...
        assert CascadeHelper._resolved_containment_ok(
            file_path, pdfs_root, allowed_root_is_resolved=True
        )
        # ...but the big disk is not trusted for any other stored path.
        assert not CascadeHelper._resolved_containment_ok(
            file_path, other_root, allowed_root_is_resolved=True
        )

    @pytest.mark.parametrize("leaf", ["regular-file", "dangling-symlink"])
    def test_a_pdfs_leaf_that_is_not_a_directory_keeps_the_user_root(
        self, tmp_path, leaf
    ):
        from local_deep_research.research_library.utils import (
            get_absolute_path_from_settings,
            get_containment_root_from_settings,
        )

        library_root = tmp_path / "library"
        user_root = library_root / "alice"
        user_root.mkdir(parents=True)
        if leaf == "regular-file":
            (user_root / "pdfs").write_bytes(b"not a directory")
        else:
            try:
                (user_root / "pdfs").symlink_to(
                    tmp_path / "missing", target_is_directory=True
                )
            except (OSError, NotImplementedError):
                pytest.skip("Cannot create symlinks in this environment")

        with patch(
            "local_deep_research.utilities.db_utils.get_settings_manager",
            return_value=_settings_with_storage_path(library_root),
        ):
            boundary = get_containment_root_from_settings("pdfs/5.pdf", "alice")
            resolved = get_absolute_path_from_settings("pdfs/5.pdf", "alice")

        assert boundary == user_root.resolve()
        # Either way resolution fails closed: the dangling link leaves the
        # user root, and a path below a regular file cannot be resolved
        # (ENOTDIR) and so is refused rather than compared half resolved.
        assert resolved is None

    def test_an_unresolvable_pdfs_leaf_keeps_the_user_root(
        self, tmp_path, monkeypatch
    ):
        from local_deep_research.research_library.utils import (
            _containment_base,
        )

        user_root = tmp_path / "alice"
        (user_root / "pdfs").mkdir(parents=True)
        real_resolve = Path.resolve

        def resolve(path, *args, **kwargs):
            if path == user_root / "pdfs":
                raise OSError("unresolvable leaf")
            return real_resolve(path, *args, **kwargs)

        monkeypatch.setattr(Path, "resolve", resolve)

        assert _containment_base("pdfs/5.pdf", user_root) == (
            user_root,
            "pdfs/5.pdf",
        )