~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.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
"""
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",
)