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.

33.0 KB
Raw Blame
# allow: no-sut-import — security tests for the document-library
# deletion cascade; drives the REAL LibraryService / DocumentDeletionService
# / PDFStorageManager / CascadeHelper code against an in-memory library DB
# whose DB-stored path columns point at canary files under tmp_path.
"""Security tripwire tests for DB-stored-path -> unlink in the library
deletion cascade.

Surfaces verified on this branch (security/test-file-write-risk-battery):

(1) Document file deletion cascade — every unlink is guarded today:

* ``src/local_deep_research/research_library/services/library_service.py``
  lines 1041-1052 (``LibraryService.delete_document``): resolves the
  document's own ``file_path`` or, for a document without one, the
  ``DownloadTracker.file_path`` of a tracker that identifies it, through
  ``get_absolute_path_from_settings(...)``
  -> ``_resolve_within_root`` -> ``PathValidator.validate_safe_path``
  (werkzeug ``safe_join``: absolute / ``..`` / encoded / unicode
  traversal all rejected) + a leaf ``is_symlink()`` refusal, and only
  then ``.unlink()``.
* ``src/local_deep_research/research_library/deletion/services/document_deletion.py``
  lines 239-266 (``DocumentDeletionService._delete_document_locked``,
  the service behind the routed DELETE handler in
  ``deletion/routes/delete_routes.py:80``): same validated resolution,
  then ``CascadeHelper.delete_filesystem_file`` with
  ``allowed_root=<per-user library root>``. The twin sites at ~484
  (``delete_blob_only``) and ~737 (unlink-only path) share the guard.
* ``src/local_deep_research/research_library/services/pdf_storage_manager.py``
  lines 538-542 (``PDFStorageManager.delete_pdf``): validates
  ``Document.file_path`` via ``_get_safe_file_path(...,
  allow_legacy_fallback=False)`` -> ``_safe_path_in_root`` ->
  ``PathValidator`` + leaf-symlink refusal, and fails closed without a
  username.
* ``src/local_deep_research/research_library/deletion/utils/cascade_helper.py``
  lines 176-226 (``delete_filesystem_file``): unconditional leaf-symlink
  refusal + ``_resolved_containment_ok`` against ``allowed_root``.
  Lines 229-353 (``delete_faiss_index_files``): containment on the
  ``RAGIndex.index_path``-derived ``.faiss``/``.pkl``/``.idmap.json``
  family + per-file symlink refusals; all production callers
  (``collection_deletion.py:267,387``, ``rag_routes.py:2446``) pass
  ``allowed_root=<cache>/rag_indices``.

(2) Stale-research cleanup in ``research_routes.py``: VERIFIED NOT TO
EXIST as a distinct surface. ``grep -n "unlink" research_routes.py``
finds exactly two sites — line 1500 (``DELETE /api/delete/<id>``) and
line 1580 (``POST /api/clear_history`` loop) — both already covered by
the sibling battery ``tests/security/test_report_path_deletion.py``.
The ~1045-1088 range is research-*creation* code with no unlink, and
``web/queue/lifecycle_cleanup.py`` contains no file deletion. This
battery therefore does not duplicate the sibling's coverage.

The DB columns themselves remain plain unvalidated ``Text``
(``DownloadTracker.file_path``, ``Document.file_path``,
``RAGIndex.index_path``) — poisonable via DB restore / direct SQL — so
these tests plant hostile values directly in the columns and assert the
SECURE delete-side behaviour: canaries outside the caller's library root
must SURVIVE. They are GREEN regression tripwires today; if a refactor
ever swaps the validated resolution for a raw ``Path(...).unlink()``
they turn RED. Positive controls confirm legitimate in-root files still
delete, guarding against over-blocking fixes.

Run with: .venv/bin/python -m pytest tests/security/test_document_path_deletion.py -v --no-header --timeout=120
"""

import hashlib
import uuid
from contextlib import contextmanager
from pathlib import Path
from unittest.mock import patch

import pytest
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

from tests.test_utils import add_src_to_path

add_src_to_path()

from local_deep_research.database.models import Base  # noqa: E402
from local_deep_research.database.models.download_tracker import (  # noqa: E402
    DownloadTracker,
)
from local_deep_research.database.models.library import (  # noqa: E402
    Document,
    DocumentStatus,
    SourceType,
)
from local_deep_research.research_library.deletion.services.document_deletion import (  # noqa: E402
    DocumentDeletionService,
)
from local_deep_research.research_library.deletion.utils.cascade_helper import (  # noqa: E402
    CascadeHelper,
)
from local_deep_research.research_library.services.library_service import (  # noqa: E402
    LibraryService,
)
from local_deep_research.research_library.services.pdf_storage_manager import (  # noqa: E402
    PDFStorageManager,
)
from local_deep_research.research_library.utils import get_url_hash  # noqa: E402

_TEST_USER = "path-canary-user"

# get_absolute_path_from_settings looks the settings manager up at call
# time (``from ...utilities.db_utils import get_settings_manager`` inside
# the function body), so patching the SOURCE module covers every caller.
_SETTINGS_MGR = "local_deep_research.utilities.db_utils.get_settings_manager"

# Modules that import get_user_db_session at module load — the DB/session
# plumbing mock targets for the services under test. LibraryService's
# post-commit purge delegates to DocumentDeletionService, so its tests
# patch both.
_LS_SESSION = (
    "local_deep_research.research_library.services.library_service"
    ".get_user_db_session"
)
_DD_SESSION = (
    "local_deep_research.research_library.deletion.services"
    ".document_deletion.get_user_db_session"
)


class _StubSettingsManager:
    """Minimal settings manager: per-user library root under tmp_path."""

    def __init__(self, storage_base: Path):
        self._storage_base = str(storage_base)

    def get_setting(self, key, default=None):
        if key == "research_library.storage_path":
            return self._storage_base
        if key == "research_library.shared_library":
            return False
        return default


@contextmanager
def _settings_root(tmp_path, monkeypatch):
    """Point ``research_library.storage_path`` at ``<tmp>/app_data/storage``.

    The resulting per-user library root (``apply_user_subdir`` joins the
    username) is ``<tmp>/app_data/storage/<_TEST_USER>``.

    Also pins ``LDR_DATA_DIR`` under ``tmp_path``. ``get_absolute_path_
    from_settings`` calls ``settings.get_setting("research_library.
    storage_path", str(get_library_directory()))`` -- the default is a
    normal function argument, so Python evaluates
    ``str(get_library_directory())`` (which ``mkdir``s
    ``<data_dir>/library``) *before* ``get_setting`` even runs, regardless
    of whether the stub below ignores that default. Without this,
    "default" is the real ``platformdirs.user_data_dir`` on the machine
    running the suite. Pinning ``LDR_DATA_DIR`` keeps that unconditional
    side effect inside ``tmp_path``.
    """
    monkeypatch.setenv("LDR_DATA_DIR", str(tmp_path / "app_data"))
    base = tmp_path / "app_data" / "storage"
    per_user_root = base / _TEST_USER
    per_user_root.mkdir(parents=True, exist_ok=True)
    with patch(_SETTINGS_MGR, return_value=_StubSettingsManager(base)):
        yield base, per_user_root


@contextmanager
def _patched_user_session(targets, session):
    """Replace ``get_user_db_session`` in each target module namespace.

    The replacement yields a fresh context manager per call, so services
    that open several sessions (delete + post-commit purge) all operate
    on the same real in-memory session.
    """

    @contextmanager
    def _factory(username=None):
        yield session

    patchers = [patch(t, new=_factory) for t in targets]
    for p in patchers:
        p.start()
    try:
        yield
    finally:
        for p in reversed(patchers):
            p.stop()


def _seed_library_db():
    """In-memory SQLite session with the library models loaded."""
    engine = create_engine("sqlite:///:memory:")
    Base.metadata.create_all(engine)
    session = sessionmaker(bind=engine)()
    return session, engine


def _make_document(session, *, file_path=None, original_url=None):
    """Commit one filesystem-mode Document and return it."""
    st = SourceType(
        id=str(uuid.uuid4()),
        name="research_download",
        display_name="Research Download",
        description="x",
    )
    session.add(st)
    session.commit()
    doc = Document(
        id=str(uuid.uuid4()),
        source_type_id=st.id,
        document_hash=hashlib.sha256(b"placeholder").hexdigest(),
        file_size=0,
        file_type="pdf",
        status=DocumentStatus.COMPLETED,
        title="canary doc",
        storage_mode="filesystem",
        file_path=file_path,
        original_url=original_url,
    )
    session.add(doc)
    session.commit()
    return doc


def _make_tracker(session, doc, file_path):
    """Commit one DownloadTracker row whose file_path is the payload.

    The tracker carries the document's content hash, as a download's
    tracker does, so it identifies ``doc``: ``delete_document`` takes the
    path of a tracker that identifies a document without a path of its own,
    and never the path of another document's tracker.

    ``first_resource_id`` is nullable=False but SQLite FK enforcement is
    off by default in a fresh SQLAlchemy engine, so a synthetic id
    commits cleanly without seeding a ResearchResource row.
    """
    tracker = DownloadTracker(
        url=doc.original_url,
        url_hash=get_url_hash(doc.original_url),
        first_resource_id=1,
        file_path=file_path,
        file_hash=doc.document_hash,
        is_downloaded=True,
    )
    session.add(tracker)
    session.commit()
    return tracker


def _relative_escape(root: Path, canary: Path) -> str:
    """A ``..``-laden relative path from ``root`` to the canary."""
    root_parts = root.resolve().parts
    canary_parts = canary.resolve().parts
    common = 0
    for a, b in zip(root_parts, canary_parts):
        if a != b:
            break
        common += 1
    ups = [".."] * (len(root_parts) - common)
    downs = list(canary_parts[common:])
    return "/".join(ups + downs)


def _files_outside_root(tmp_path: Path, root: Path) -> list[str]:
    """Every file or symlink under ``tmp_path`` that is not inside ``root``."""
    return sorted(
        str(p.relative_to(tmp_path))
        for p in tmp_path.rglob("*")
        if (p.is_file() or p.is_symlink()) and root not in p.parents
    )


# ---------------------------------------------------------------------------
# LibraryService.delete_document — DownloadTracker.file_path -> unlink
# (library_service.py:1041-1052)
# ---------------------------------------------------------------------------


class TestLibraryServiceDeleteDocumentTrackerFile:
    """The tracker-file unlink in ``LibraryService.delete_document`` must
    never reach outside the caller's per-user library root."""

    def _run_delete(self, session, document_id):
        with _patched_user_session([_LS_SESSION, _DD_SESSION], session):
            return LibraryService(_TEST_USER).delete_document(document_id)

    def test_absolute_tracker_path_outside_root_is_preserved(
        self, tmp_path, monkeypatch
    ):
        with _settings_root(tmp_path, monkeypatch) as (_base, per_user_root):
            outside = tmp_path / "outside_storage"
            outside.mkdir()
            canary = outside / "canary.txt"
            canary.write_text("DO NOT DELETE")

            session, engine = _seed_library_db()
            try:
                doc = _make_document(
                    session, original_url="https://example.com/abs.pdf"
                )
                _make_tracker(session, doc, str(canary))
                deleted = self._run_delete(session, doc.id)
            finally:
                session.close()
                engine.dispose()

        assert deleted is True
        assert canary.exists(), (
            "LibraryService.delete_document unlinked an absolute "
            "DownloadTracker.file_path outside the library root — no path "
            "validation present"
        )
        assert canary.read_text() == "DO NOT DELETE"

    def test_traversal_tracker_path_is_preserved(self, tmp_path, monkeypatch):
        with _settings_root(tmp_path, monkeypatch) as (_base, per_user_root):
            outside = tmp_path / "outside_sibling"
            outside.mkdir()
            canary = outside / "victim.txt"
            canary.write_text("DO NOT DELETE")
            traversal = _relative_escape(per_user_root, canary)
            assert traversal.startswith(".."), "payload must traverse"

            session, engine = _seed_library_db()
            try:
                doc = _make_document(
                    session, original_url="https://example.com/trav.pdf"
                )
                _make_tracker(session, doc, traversal)
                deleted = self._run_delete(session, doc.id)
            finally:
                session.close()
                engine.dispose()

        assert deleted is True
        assert canary.exists(), (
            "LibraryService.delete_document followed a ``..``-laden "
            "DownloadTracker.file_path outside the library root — no "
            "containment check present"
        )
        assert canary.read_text() == "DO NOT DELETE"

    def test_symlink_tracker_path_is_refused(self, tmp_path, monkeypatch):
        with _settings_root(tmp_path, monkeypatch) as (_base, per_user_root):
            outside = tmp_path / "outside_target"
            outside.mkdir()
            canary = outside / "symlink_target.txt"
            canary.write_text("DO NOT DELETE")
            link = per_user_root / "evil_link"
            try:
                link.symlink_to(canary)
            except OSError:
                pytest.skip("Cannot create symlinks in this environment")
            assert link.is_symlink()

            session, engine = _seed_library_db()
            try:
                doc = _make_document(
                    session, original_url="https://example.com/link.pdf"
                )
                _make_tracker(session, doc, "evil_link")
                deleted = self._run_delete(session, doc.id)
            finally:
                session.close()
                engine.dispose()

        assert deleted is True
        assert canary.exists(), (
            "LibraryService.delete_document dereferenced a symlinked "
            "DownloadTracker.file_path — no link-target containment "
            "present"
        )
        assert canary.read_text() == "DO NOT DELETE"
        assert link.is_symlink() or link.exists(), (
            "LibraryService.delete_document removed a symlink planted in "
            "the library root — no leaf-symlink refusal present"
        )

    def test_legitimate_tracker_file_is_deleted(self, tmp_path, monkeypatch):
        """POSITIVE CONTROL: a real file inside the per-user root is
        still unlinked by delete_document."""
        with _settings_root(tmp_path, monkeypatch) as (_base, per_user_root):
            (per_user_root / "pdfs").mkdir(exist_ok=True)
            legit = per_user_root / "pdfs" / "legit.pdf"
            legit.write_bytes(b"%PDF-1.4 legit")

            session, engine = _seed_library_db()
            try:
                doc = _make_document(
                    session, original_url="https://example.com/legit.pdf"
                )
                _make_tracker(session, doc, "pdfs/legit.pdf")
                deleted = self._run_delete(session, doc.id)
            finally:
                session.close()
                engine.dispose()

        assert deleted is True
        assert not legit.exists(), (
            "POSITIVE CONTROL FAILED: a legitimate in-root tracker file "
            "was not deleted. If a containment fix was just added, it is "
            "overly restrictive."
        )


# ---------------------------------------------------------------------------
# LibraryService.delete_document — Document.file_path -> unlink
# The document's OWN path is the primary unlink input; the tracker path
# above is only borrowed for a document that has none.
# ---------------------------------------------------------------------------


class TestLibraryServiceDeleteDocumentOwnFile:
    """The unlink of ``Document.file_path`` in ``LibraryService.
    delete_document`` must never reach outside the caller's per-user
    library root.

    The tracker cases above use pathless documents, so they only exercise
    the path ``delete_document`` borrows from a tracker. These cases plant
    the same hostile values in the document's own ``file_path``.
    """

    def _run_delete(self, session, document_id):
        with _patched_user_session([_LS_SESSION, _DD_SESSION], session):
            return LibraryService(_TEST_USER).delete_document(document_id)

    @pytest.mark.parametrize("kind", ["absolute", "traversal", "symlink"])
    def test_hostile_document_file_path_is_preserved(
        self, tmp_path, monkeypatch, kind
    ):
        with _settings_root(tmp_path, monkeypatch) as (_base, per_user_root):
            outside = tmp_path / f"outside_own_{kind}"
            outside.mkdir()
            canary = outside / "canary.txt"
            canary.write_text("DO NOT DELETE")
            link = None
            if kind == "absolute":
                payload = str(canary)
            elif kind == "traversal":
                payload = _relative_escape(per_user_root, canary)
                assert payload.startswith(".."), "payload must traverse"
            else:
                link = per_user_root / "evil_own_link"
                try:
                    link.symlink_to(canary)
                except OSError:
                    pytest.skip("Cannot create symlinks in this environment")
                assert link.is_symlink()
                payload = "evil_own_link"
            outside_before = _files_outside_root(tmp_path, per_user_root)

            session, engine = _seed_library_db()
            try:
                doc = _make_document(session, file_path=payload)
                deleted = self._run_delete(session, doc.id)
            finally:
                session.close()
                engine.dispose()

        assert deleted is True
        assert canary.exists(), (
            "LibraryService.delete_document unlinked the target of a "
            f"hostile ({kind}) Document.file_path outside the library "
            "root — no containment check on the document's own path"
        )
        assert canary.read_text() == "DO NOT DELETE"
        outside_after = _files_outside_root(tmp_path, per_user_root)
        assert outside_after == outside_before, (
            "LibraryService.delete_document removed a file outside the "
            f"library root through a hostile ({kind}) Document.file_path"
        )
        if link is not None:
            assert link.is_symlink() or link.exists(), (
                "LibraryService.delete_document removed a symlink planted in "
                "the library root through Document.file_path — no "
                "leaf-symlink refusal present"
            )

    def test_legitimate_document_file_is_deleted(self, tmp_path, monkeypatch):
        """POSITIVE CONTROL: a real file inside the per-user root named by
        ``Document.file_path`` is still unlinked by delete_document."""
        with _settings_root(tmp_path, monkeypatch) as (_base, per_user_root):
            (per_user_root / "pdfs").mkdir(exist_ok=True)
            legit = per_user_root / "pdfs" / "legit_own.pdf"
            legit.write_bytes(b"%PDF-1.4 legit")

            session, engine = _seed_library_db()
            try:
                doc = _make_document(session, file_path="pdfs/legit_own.pdf")
                deleted = self._run_delete(session, doc.id)
            finally:
                session.close()
                engine.dispose()

        assert deleted is True
        assert not legit.exists(), (
            "POSITIVE CONTROL FAILED: a legitimate in-root file named by "
            "Document.file_path was not deleted. If a containment fix was "
            "just added, it is overly restrictive."
        )


# ---------------------------------------------------------------------------
# DocumentDeletionService — Document.file_path -> unlink
# (document_deletion.py:239-266; routed via delete_routes.py:80)
# ---------------------------------------------------------------------------


class TestDocumentDeletionServiceDocumentFile:
    """The routed document-delete service must keep the
    ``Document.file_path`` unlink inside the per-user library root."""

    def _run_delete(self, session, document_id):
        with _patched_user_session([_DD_SESSION], session):
            return DocumentDeletionService(_TEST_USER).delete_document(
                document_id
            )

    def test_absolute_document_file_path_outside_root_is_preserved(
        self, tmp_path, monkeypatch
    ):
        with _settings_root(tmp_path, monkeypatch) as (_base, per_user_root):
            outside = tmp_path / "dd_outside"
            outside.mkdir()
            canary = outside / "canary.txt"
            canary.write_text("DO NOT DELETE")

            session, engine = _seed_library_db()
            try:
                doc = _make_document(session, file_path=str(canary))
                result = self._run_delete(session, doc.id)
            finally:
                session.close()
                engine.dispose()

        assert result.get("deleted") is True
        assert result.get("file_deleted") is False
        assert canary.exists(), (
            "DocumentDeletionService unlinked an absolute "
            "Document.file_path outside the library root — no path "
            "validation present"
        )
        assert canary.read_text() == "DO NOT DELETE"

    def test_symlink_document_file_path_is_refused(self, tmp_path, monkeypatch):
        with _settings_root(tmp_path, monkeypatch) as (_base, per_user_root):
            outside = tmp_path / "dd_symlink_target"
            outside.mkdir()
            canary = outside / "target.txt"
            canary.write_text("DO NOT DELETE")
            link = per_user_root / "evil_doc_link"
            try:
                link.symlink_to(canary)
            except OSError:
                pytest.skip("Cannot create symlinks in this environment")
            assert link.is_symlink()

            session, engine = _seed_library_db()
            try:
                doc = _make_document(session, file_path="evil_doc_link")
                result = self._run_delete(session, doc.id)
            finally:
                session.close()
                engine.dispose()

        assert result.get("deleted") is True
        assert result.get("file_deleted") is False
        assert canary.exists(), (
            "DocumentDeletionService dereferenced a symlinked "
            "Document.file_path — no link-target containment present"
        )
        assert link.is_symlink() or link.exists(), (
            "DocumentDeletionService removed a symlink planted in the "
            "library root — no leaf-symlink refusal present"
        )

    def test_legitimate_document_file_is_deleted(self, tmp_path, monkeypatch):
        """POSITIVE CONTROL: a real in-root file is unlinked by the
        routed deletion service."""
        with _settings_root(tmp_path, monkeypatch) as (_base, per_user_root):
            (per_user_root / "pdfs").mkdir(exist_ok=True)
            legit = per_user_root / "pdfs" / "legit_doc.pdf"
            legit.write_bytes(b"%PDF-1.4 legit")

            session, engine = _seed_library_db()
            try:
                doc = _make_document(session, file_path="pdfs/legit_doc.pdf")
                result = self._run_delete(session, doc.id)
            finally:
                session.close()
                engine.dispose()

        assert result.get("deleted") is True, result
        assert result.get("file_deleted") is True, result
        assert not legit.exists(), (
            "POSITIVE CONTROL FAILED: a legitimate in-root document file "
            "was not deleted by DocumentDeletionService. If a containment "
            "fix was just added, it is overly restrictive."
        )


# ---------------------------------------------------------------------------
# PDFStorageManager.delete_pdf — Document.file_path -> unlink
# (pdf_storage_manager.py:538-542)
# ---------------------------------------------------------------------------


class TestPdfStorageManagerDeletePdf:
    """``delete_pdf`` must keep the unlink inside the manager's own
    library root (constructor-supplied, mirroring the real per-user
    root)."""

    @pytest.fixture
    def psm_case(self, tmp_path):
        """(manager, session) — real manager rooted under tmp_path plus
        an in-memory library DB."""
        library_root = tmp_path / "library"
        (library_root / "pdfs").mkdir(parents=True)
        manager = PDFStorageManager(
            library_root=library_root,
            storage_mode="filesystem",
            username=_TEST_USER,
        )
        session, engine = _seed_library_db()
        try:
            yield manager, session
        finally:
            session.close()
            engine.dispose()

    def test_absolute_file_path_outside_root_is_preserved(
        self, tmp_path, psm_case
    ):
        manager, session = psm_case
        outside = tmp_path / "psm_outside"
        outside.mkdir()
        canary = outside / "canary.txt"
        canary.write_text("DO NOT DELETE")
        doc = _make_document(session, file_path=str(canary))

        ok = manager.delete_pdf(doc, session)

        assert ok is True
        assert canary.exists(), (
            "PDFStorageManager.delete_pdf unlinked an absolute "
            "Document.file_path outside the library root — no path "
            "validation present"
        )

    def test_traversal_file_path_outside_root_is_preserved(
        self, tmp_path, psm_case
    ):
        manager, session = psm_case
        outside = tmp_path / "psm_outside_sibling"
        outside.mkdir()
        canary = outside / "victim.txt"
        canary.write_text("DO NOT DELETE")
        traversal = _relative_escape(manager.library_root, canary)
        assert traversal.startswith(".."), "payload must traverse"
        doc = _make_document(session, file_path=traversal)

        ok = manager.delete_pdf(doc, session)

        assert ok is True
        assert canary.exists(), (
            "PDFStorageManager.delete_pdf followed a ``..``-laden "
            "Document.file_path outside the library root — no containment "
            "check present"
        )

    def test_legitimate_pdf_inside_root_is_deleted(self, tmp_path, psm_case):
        """POSITIVE CONTROL: an in-root pdfs/... file is unlinked."""
        manager, session = psm_case
        legit = manager.library_root / "pdfs" / "legit.pdf"
        legit.write_bytes(b"%PDF-1.4 legit")
        doc = _make_document(session, file_path="pdfs/legit.pdf")

        ok = manager.delete_pdf(doc, session)

        assert ok is True
        assert not legit.exists(), (
            "POSITIVE CONTROL FAILED: a legitimate in-root PDF was not "
            "deleted by delete_pdf. If a containment fix was just added, "
            "it is overly restrictive."
        )


# ---------------------------------------------------------------------------
# CascadeHelper.delete_filesystem_file (cascade_helper.py:176-226)
# ---------------------------------------------------------------------------


class TestCascadeHelperFilesystemFileUnlink:
    """The narrowest unlink primitive — used directly by
    DocumentDeletionService with ``allowed_root=<per-user root>``."""

    def test_absolute_path_outside_allowed_root_is_refused(self, tmp_path):
        root = tmp_path / "allowed_root"
        root.mkdir()
        outside = tmp_path / "fs_outside"
        outside.mkdir()
        canary = outside / "canary.txt"
        canary.write_text("DO NOT DELETE")

        deleted = CascadeHelper.delete_filesystem_file(
            str(canary), allowed_root=root
        )

        assert deleted is False
        assert canary.exists(), (
            "CascadeHelper.delete_filesystem_file unlinked an absolute "
            "path outside allowed_root — containment check missing"
        )

    def test_traversal_path_outside_allowed_root_is_refused(self, tmp_path):
        root = tmp_path / "allowed_root"
        (root / "sub").mkdir(parents=True)
        outside = tmp_path / "fs_outside_sibling"
        outside.mkdir()
        canary = outside / "victim.txt"
        canary.write_text("DO NOT DELETE")
        traversal = (
            root / "sub" / ".." / ".." / "fs_outside_sibling" / "victim.txt"
        )
        assert traversal.exists(), "traversal payload must be stat-able"
        assert traversal.resolve() == canary.resolve()

        deleted = CascadeHelper.delete_filesystem_file(
            str(traversal), allowed_root=root
        )

        assert deleted is False
        assert canary.exists(), (
            "CascadeHelper.delete_filesystem_file followed a ``..``-laden "
            "path outside allowed_root — containment check missing"
        )

    def test_legitimate_file_inside_allowed_root_is_deleted(self, tmp_path):
        """POSITIVE CONTROL: an in-root file is unlinked."""
        root = tmp_path / "allowed_root"
        root.mkdir()
        legit = root / "doc.pdf"
        legit.write_bytes(b"%PDF-1.4 legit")

        deleted = CascadeHelper.delete_filesystem_file(
            str(legit), allowed_root=root
        )

        assert deleted is True
        assert not legit.exists(), (
            "POSITIVE CONTROL FAILED: delete_filesystem_file refused a "
            "legitimate in-root file — containment is overly restrictive."
        )


# ---------------------------------------------------------------------------
# CascadeHelper.delete_faiss_index_files (cascade_helper.py:229-353)
# RAGIndex.index_path is a plain Text column — the poisonable DB input.
# ---------------------------------------------------------------------------


def _make_index_family(base_dir: Path, name: str = "index"):
    """Create a real .faiss/.pkl/.idmap.json family under ``base_dir``."""
    base_dir.mkdir(parents=True, exist_ok=True)
    stem = base_dir / name
    files = {
        "faiss": stem.with_suffix(".faiss"),
        "pkl": stem.with_suffix(".pkl"),
        "idmap": stem.with_suffix(".idmap.json"),
    }
    for f in files.values():
        f.write_bytes(b"payload")
    return str(stem), files


class TestCascadeHelperFaissIndexFamilyUnlink:
    """The FAISS family unlink must stay inside the rag_indices root the
    production callers pass (collection_deletion.py:267,387;
    rag_routes.py:2446)."""

    def test_absolute_index_path_outside_rag_root_is_refused(self, tmp_path):
        rag_root = tmp_path / "cache" / "rag_indices"
        rag_root.mkdir(parents=True)
        outside_dir = tmp_path / "outside_rag"
        stem, files = _make_index_family(outside_dir)

        deleted = CascadeHelper.delete_faiss_index_files(
            stem, allowed_root=rag_root
        )

        assert deleted is False
        for label, f in files.items():
            assert f.exists(), (
                f"CascadeHelper.delete_faiss_index_files unlinked the "
                f"{label} canary outside rag_indices/ — containment check "
                "missing"
            )

    def test_symlinked_index_family_files_are_refused(self, tmp_path):
        rag_root = tmp_path / "cache" / "rag_indices"
        coll_dir = rag_root / "coll"
        coll_dir.mkdir(parents=True)
        outside_dir = tmp_path / "outside_rag_links"
        outside_dir.mkdir()
        canaries = {}
        links = {}
        for ext in ("faiss", "pkl", "idmap.json"):
            canary = outside_dir / f"target.{ext}"
            canary.write_bytes(b"DO NOT DELETE")
            link = coll_dir / f"index.{ext}"
            try:
                link.symlink_to(canary)
            except OSError:
                pytest.skip("Cannot create symlinks in this environment")
            canaries[ext] = canary
            links[ext] = link

        deleted = CascadeHelper.delete_faiss_index_files(
            str(coll_dir / "index"), allowed_root=rag_root
        )

        assert deleted is False
        for ext, canary in canaries.items():
            assert canary.exists(), (
                f"delete_faiss_index_files dereferenced the .{ext} "
                "symlink to an outside canary — leaf-symlink refusal "
                "missing"
            )
            assert links[ext].is_symlink(), (
                f"delete_faiss_index_files removed the .{ext} symlink "
                "itself — leaf-symlink refusal missing"
            )

    def test_legitimate_index_family_inside_rag_root_is_deleted(self, tmp_path):
        """POSITIVE CONTROL: a real in-root index family is unlinked."""
        rag_root = tmp_path / "cache" / "rag_indices"
        stem, files = _make_index_family(rag_root / "coll")

        deleted = CascadeHelper.delete_faiss_index_files(
            stem, allowed_root=rag_root
        )

        assert deleted is True
        for label, f in files.items():
            assert not f.exists(), (
                f"POSITIVE CONTROL FAILED: the legitimate in-root "
                f"{label} file was not deleted. If a containment fix was "
                "just added, it is overly restrictive."
            )