fix(api): stop canonical path matching at the project boundary

_canonical_file_path followed escaping symlinks with os.scandir before the
post-canonicalization containment check rejected the request: on a
case-sensitive filesystem a wrong-cased request like 'LINK/secret.md' passes
the pre-check (the path does not exist, so resolve() never follows the real
'link' symlink), and segment matching then descended through 'link' and
scanned the outside directory — an information touch beyond the project
boundary even though the request was ultimately rejected.

Re-check the boundary at every traversal step: before scanning the current
directory, its fully-resolved path must still be contained in the resolved
project home; bail with None the moment resolution escapes. The
post-canonicalization checks remain as defense in depth, and symlinks whose
targets stay inside the project keep canonicalizing as before.

Regression tests spy on os.scandir to prove the outside directory is never
scanned (meaningful on case-insensitive macOS too, where the pre-check
already rejects the request), and exercise the boundary bail directly so it
is covered on every filesystem.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

src/basic_memory/api/v2/routers/knowledge_router.py

@@ -260,11 +260,23 @@ def _canonical_file_path(home: pathlib.Path, segments: list[str]) -> str | None:
     Outcome: each segment is matched against real directory entries — exact name first
         (so distinct case-variant files on case-sensitive filesystems stay distinct),
         then a unique case-insensitive match. Returns None when any segment cannot be
-        matched to exactly one entry, including missing files.
+        matched to exactly one entry, including missing files. Traversal stops at the
+        project boundary: a directory whose resolved path escapes the project home is
+        never scanned.
     """
+    resolved_home = home.resolve()
     current = home
     canonical_segments: list[str] = []
     for segment in segments:
+        # Trigger: a previously matched segment may be a symlink whose target lies
+        #     outside the project root (e.g. wrong-cased 'LINK' matched the on-disk
+        #     'link' -> /tmp/outside on a case-sensitive filesystem).
+        # Why: os.scandir follows symlinked directories, so continuing would read
+        #     directory contents outside the project boundary even though the
+        #     post-canonicalization containment check rejects the request later.
+        # Outcome: bail before scanning the moment resolution escapes the home.
+        if not current.resolve().is_relative_to(resolved_home):
+            return None
         try:
             with os.scandir(current) as entries_iter:
                 entries = [entry.name for entry in entries_iter]

tests/api/v2/test_knowledge_router.py

@@ -1,12 +1,14 @@
 """Tests for V2 knowledge graph API routes (ID-based endpoints)."""
 
+import os
 from datetime import datetime, timezone
 from pathlib import Path
 import uuid
 
 import pytest
 from httpx import AsyncClient
 
+from basic_memory.api.v2.routers.knowledge_router import _canonical_file_path
 from basic_memory.ignore_utils import get_bmignore_path
 from basic_memory.models import Entity as EntityModel, Project
 from basic_memory.repository.entity_repository import EntityRepository
@@ -1045,9 +1047,9 @@ async def test_sync_file_rejects_symlink_escape(
     boundary check: the path exists, so resolve() follows the symlink and detects the
     escape. The wrong-cased request ('LINK/secret.md') is the regression case — on a
     case-sensitive filesystem that path does not exist, the pre-check resolves it
-    lexically and passes, and only canonicalization rewrites it to the real 'link'
-    segment; the post-canonicalization containment check must reject it. On
-    case-insensitive filesystems the pre-check catches both. Either way: 400.
+    lexically and passes; canonicalization then matches the real 'link' segment but
+    stops at the project boundary and reports the path as not found (404). On
+    case-insensitive filesystems the pre-check catches both with 400.
     """
     project_path = Path(test_project.path)
     outside_dir = project_path.parent / "sync-file-outside"
@@ -1057,18 +1059,98 @@ async def test_sync_file_rejects_symlink_escape(
     )
     (project_path / "link").symlink_to(outside_dir, target_is_directory=True)
 
-    for requested in ("link/secret.md", "LINK/secret.md"):
-        response = await client.post(
-            f"{v2_project_url}/knowledge/sync-file",
-            json={"file_path": requested},
-        )
-        assert response.status_code == 400, requested
-        assert "project boundaries" in response.json()["detail"]
+    response = await client.post(
+        f"{v2_project_url}/knowledge/sync-file",
+        json={"file_path": "link/secret.md"},
+    )
+    assert response.status_code == 400
+    assert "project boundaries" in response.json()["detail"]
+
+    # 400 (pre-check, case-insensitive FS) or 404 (canonicalization stops at the
+    # boundary, case-sensitive FS) — either way the escape is rejected.
+    response = await client.post(
+        f"{v2_project_url}/knowledge/sync-file",
+        json={"file_path": "LINK/secret.md"},
+    )
+    assert response.status_code in (400, 404)
 
     # Nothing outside the project root was indexed
     assert await entity_repository.find_all() == []
 
 
+@pytest.mark.asyncio
+async def test_sync_file_symlink_escape_never_scans_outside_directory(
+    client: AsyncClient,
+    v2_project_url,
+    test_project: Project,
+    entity_repository,
+    monkeypatch: pytest.MonkeyPatch,
+):
+    """Canonicalization never scans directories outside the project root.
+
+    Rejecting the request is not enough: before this fix, the wrong-cased request
+    ('LINK/secret.md') passed the pre-check on a case-sensitive filesystem, and
+    canonicalization followed the escaping 'link' symlink with os.scandir before the
+    post-canonicalization containment check fired — an information touch outside the
+    boundary. We spy on os.scandir and assert the outside directory is never scanned.
+    The spy is what makes this test meaningful on case-insensitive macOS too, where
+    the request is already rejected by the pre-check: the assertion proves no layer
+    scanned past the boundary either way.
+    """
+    project_path = Path(test_project.path)
+    outside_dir = (project_path.parent / "sync-file-outside-scan").resolve()
+    outside_dir.mkdir(parents=True, exist_ok=True)
+    (outside_dir / "secret.md").write_text(
+        "# Outside\n\nMust never be scanned.\n", encoding="utf-8"
+    )
+    (project_path / "link").symlink_to(outside_dir, target_is_directory=True)
+
+    real_scandir = os.scandir
+    scanned: list[Path] = []
+
+    def recording_scandir(path=".", *args, **kwargs):
+        # Record the resolved path so a scandir on the symlinked 'link' directory
+        # shows up as the outside directory it actually reads.
+        scanned.append(Path(path).resolve())
+        return real_scandir(path, *args, **kwargs)
+
+    monkeypatch.setattr(os, "scandir", recording_scandir)
+
+    response = await client.post(
+        f"{v2_project_url}/knowledge/sync-file",
+        json={"file_path": "LINK/secret.md"},
+    )
+    assert response.status_code in (400, 404)
+    assert outside_dir not in scanned
+
+    assert await entity_repository.find_all() == []
+
+
+def test_canonical_file_path_stops_at_project_boundary(tmp_path: Path):
+    """_canonical_file_path bails before descending past the resolved project home.
+
+    Exercised directly (not via the endpoint) so the boundary bail is covered on
+    case-insensitive filesystems too, where the endpoint pre-check rejects the
+    request before canonicalization runs.
+    """
+    home = tmp_path / "project"
+    home.mkdir()
+    outside_dir = tmp_path / "outside"
+    outside_dir.mkdir()
+    (outside_dir / "secret.md").write_text("# Outside\n", encoding="utf-8")
+    (home / "link").symlink_to(outside_dir, target_is_directory=True)
+
+    assert _canonical_file_path(home, ["link", "secret.md"]) is None
+
+    # Symlinks that stay inside the project keep canonicalizing as before.
+    real_dir = home / "real"
+    real_dir.mkdir()
+    (real_dir / "inside.md").write_text("# Inside\n", encoding="utf-8")
+    (home / "alias").symlink_to(real_dir, target_is_directory=True)
+
+    assert _canonical_file_path(home, ["alias", "inside.md"]) == "alias/inside.md"
+
+
 @pytest.mark.asyncio
 async def test_sync_file_symlink_inside_project_still_indexes(
     client: AsyncClient, v2_project_url, test_project: Project