fix: validate /api/set-workspace path — reject traversal, symlink escape, non-existent (closes #15)

POST /api/set-workspace accepted any string in body.path, ran tilde
expansion, and stored it in a module-global override consumed by every
subsequent file lookup. Anyone reaching the endpoint (including a
hostile JS payload — see XSS issue #11) could repoint the app at /etc,
/, ~/.ssh, or any other directory; the dashboard would then serve files
from there as if they were Cursor chat data. Symlink-based escape
(e.g. /tmp/cursor-link → /) bypassed any naive startswith-style check.

New utils/path_validation.py with validate_workspace_path(raw):

- Expands ~/.
- os.path.realpath() — collapses `..` AND resolves symlinks in one
  step. Both classes of escape become equivalent to the canonical real
  path on disk; downstream marker check then operates on the truth.
- Rejects with WorkspacePathError if the path doesn't exist, isn't a
  directory, or contains no immediate subdirectory with a state.vscdb
  marker (the same heuristic /api/validate-path already uses).
- Returns the canonical real path so the override is stored in
  canonical form, not whatever the caller sent.

api/config_api.py:set_workspace now calls the validator and returns
400 { error: "<reason>" } on rejection (was silently 200), and stores
the canonical path on success: 200 { success: true, path: "<canonical>" }.

Lives outside api/ so the test suite can import without Flask in scope
(tests/test_cli_args.py convention).

Tests: tests/test_workspace_path_validation.py — 11 cases covering:
  - happy path with marker file present
  - canonical path returned (`..` collapsed)
  - empty / whitespace / non-string rejected
  - non-existent / file-not-directory rejected
  - directory without Cursor markers rejected
  - traversal lands outside workspace → rejected on markers
  - symlink → / rejected on markers (POSIX-only)
  - symlink → real workspace canonicalised + accepted (POSIX-only)

Full suite: 148/148 OK (was 137; +11 new). Live HTTP smoke against the
running app verified all 9 documented behaviours (200 with canonical
path on accept; 400 with the documented reason on each reject).

Author: timon0305

api/config_api.py

@@ -13,6 +13,7 @@
 from flask import Blueprint, jsonify, request
 
 from utils.path_helpers import expand_tilde_path
+from utils.path_validation import WorkspacePathError, validate_workspace_path
 from utils.workspace_path import set_workspace_path_override
 
 bp = Blueprint("config_api", __name__)
@@ -75,14 +76,21 @@ def validate_path():
 
 @bp.route("/api/set-workspace", methods=["POST"])
 def set_workspace():
+    body = request.get_json(silent=True) or {}
+    raw = body.get("path", "")
+    # Validate the supplied path BEFORE storing the override (issue #15).
+    # validate_workspace_path collapses `..` traversal AND resolves symlinks
+    # via realpath, then enforces that the canonical target is an existing
+    # directory containing Cursor workspace markers. Returns the canonical
+    # path so we store that, not whatever the caller sent.
     try:
-        body = request.get_json(silent=True) or {}
-        path = body.get("path", "")
-        expanded = expand_tilde_path(path)
-        set_workspace_path_override(expanded)
-        return jsonify({"success": True})
-    except Exception:
-        return jsonify({"error": "Failed to set workspace path"}), 500
+        canonical = validate_workspace_path(raw)
+    except WorkspacePathError as e:
+        return jsonify({"error": str(e)}), 400
+    except Exception:  # noqa: BLE001 — only here as a fallback
+        return jsonify({"error": "Failed to validate workspace path"}), 500
+    set_workspace_path_override(canonical)
+    return jsonify({"success": True, "path": canonical})
 
 
 @bp.route("/api/get-username")

tests/test_workspace_path_validation.py

@@ -0,0 +1,133 @@
+"""
+Regression tests for issue #15 — /api/set-workspace path validation.
+
+Exercises validate_workspace_path() directly. Imports from utils/ to avoid
+pulling Flask into scope (tests/test_cli_args.py convention).
+
+Run:
+    python -m unittest tests.test_workspace_path_validation -v
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+import tempfile
+import unittest
+
+REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, REPO_ROOT)
+
+from utils.path_validation import WorkspacePathError, validate_workspace_path
+
+
+def _make_cursor_workspace_dir(parent: str, name: str = "real-storage") -> str:
+    """Create a directory that looks like a Cursor workspaceStorage dir.
+
+    Layout:
+      <parent>/<name>/
+        ws-001/state.vscdb     ← marker file the validator looks for
+    """
+    storage = os.path.join(parent, name)
+    ws = os.path.join(storage, "ws-001")
+    os.makedirs(ws)
+    with open(os.path.join(ws, "state.vscdb"), "wb") as f:
+        f.write(b"")
+    return storage
+
+
+class TestValidateWorkspacePath(unittest.TestCase):
+
+    def setUp(self):
+        self.tmp = tempfile.mkdtemp(prefix="cursor-validate-test-")
+        self.addCleanup(shutil.rmtree, self.tmp, ignore_errors=True)
+
+    # ─── Happy path ────────────────────────────────────────────────
+
+    def test_accepts_directory_with_cursor_marker(self):
+        storage = _make_cursor_workspace_dir(self.tmp)
+        result = validate_workspace_path(storage)
+        self.assertEqual(result, os.path.realpath(storage))
+
+    def test_returns_canonical_path_collapsing_dotdot(self):
+        # /tmp/<x>/real-storage/../real-storage  → /tmp/<x>/real-storage
+        storage = _make_cursor_workspace_dir(self.tmp)
+        traversal_input = os.path.join(storage, "..", os.path.basename(storage))
+        result = validate_workspace_path(traversal_input)
+        self.assertEqual(result, os.path.realpath(storage))
+        self.assertNotIn("..", result)
+
+    # ─── Hard rejects ──────────────────────────────────────────────
+
+    def test_rejects_empty_string(self):
+        with self.assertRaises(WorkspacePathError) as ctx:
+            validate_workspace_path("")
+        self.assertIn("required", str(ctx.exception))
+
+    def test_rejects_whitespace_only(self):
+        with self.assertRaises(WorkspacePathError):
+            validate_workspace_path("   \t  ")
+
+    def test_rejects_non_string(self):
+        with self.assertRaises(WorkspacePathError):
+            validate_workspace_path(None)  # type: ignore[arg-type]
+
+    def test_rejects_non_existent_path(self):
+        bogus = os.path.join(self.tmp, "does-not-exist", "anywhere")
+        with self.assertRaises(WorkspacePathError) as ctx:
+            validate_workspace_path(bogus)
+        self.assertIn("does not exist", str(ctx.exception))
+
+    def test_rejects_file_not_directory(self):
+        f = os.path.join(self.tmp, "regular-file")
+        with open(f, "w") as h:
+            h.write("not a directory")
+        with self.assertRaises(WorkspacePathError) as ctx:
+            validate_workspace_path(f)
+        self.assertIn("not a directory", str(ctx.exception))
+
+    def test_rejects_directory_without_cursor_markers(self):
+        # Existing directory but no state.vscdb anywhere — common case for
+        # a user pointing at /tmp, /etc, /, ~/.ssh, etc.
+        plain = os.path.join(self.tmp, "plain-dir")
+        os.makedirs(os.path.join(plain, "subdir"))
+        with self.assertRaises(WorkspacePathError) as ctx:
+            validate_workspace_path(plain)
+        self.assertIn("Cursor workspaceStorage", str(ctx.exception))
+
+    # ─── Path-traversal class ──────────────────────────────────────
+
+    def test_traversal_into_non_workspace_is_rejected(self):
+        # /tmp/<x>/real-storage/../../  → /tmp/  → no Cursor markers → reject
+        storage = _make_cursor_workspace_dir(self.tmp)
+        escape = os.path.join(storage, "..", "..")
+        with self.assertRaises(WorkspacePathError):
+            validate_workspace_path(escape)
+
+    # ─── Symlink-escape class ──────────────────────────────────────
+
+    @unittest.skipIf(sys.platform == "win32", "POSIX symlinks only")
+    def test_symlink_to_non_workspace_is_rejected(self):
+        # A symlink that points to / (no Cursor markers) is rejected because
+        # realpath() resolves to the real target before the marker check.
+        link = os.path.join(self.tmp, "evil-link")
+        os.symlink("/", link)
+        with self.assertRaises(WorkspacePathError) as ctx:
+            validate_workspace_path(link)
+        self.assertIn("Cursor workspaceStorage", str(ctx.exception))
+
+    @unittest.skipIf(sys.platform == "win32", "POSIX symlinks only")
+    def test_symlink_to_real_workspace_is_canonicalised_and_accepted(self):
+        # Symlink → real Cursor storage. Accepted, but the canonical path
+        # returned is the realpath (the storage dir), NOT the symlink path.
+        storage = _make_cursor_workspace_dir(self.tmp)
+        link = os.path.join(self.tmp, "good-link")
+        os.symlink(storage, link)
+        result = validate_workspace_path(link)
+        self.assertEqual(result, os.path.realpath(storage))
+        self.assertNotEqual(result, link)
+
+
+if __name__ == "__main__":
+    unittest.main()

utils/path_validation.py

@@ -0,0 +1,83 @@
+"""Validation for workspace paths submitted via /api/set-workspace.
+
+Lives outside ``api/`` so the unit tests can import it without pulling
+Flask into scope (the existing test suite intentionally avoids Flask —
+see ``tests/test_cli_args.py`` for the convention).
+
+The validation collapses path traversal *and* resolves symlinks via
+``os.path.realpath()`` in a single step. Both ``/foo/../bar`` and a
+symlink that points outside the intended tree become whatever the
+canonical real path is on disk; downstream checks then operate on
+that canonical value, not on whatever the caller sent.
+"""
+
+from __future__ import annotations
+
+import os
+
+from .path_helpers import expand_tilde_path
+
+
+class WorkspacePathError(ValueError):
+    """Raised when a /api/set-workspace path fails validation.
+
+    Carries a single ``reason`` string suitable for a 400 response body.
+    Distinct exception type so the API handler can map it to a 400 while
+    letting unexpected exceptions surface as 500.
+    """
+
+
+def _has_cursor_workspace_markers(directory: str) -> bool:
+    """Return True iff at least one immediate subdirectory contains state.vscdb.
+
+    Same heuristic /api/validate-path already uses to recognise a Cursor
+    workspaceStorage directory. Used here as the final accept gate so that
+    a symlink whose realpath happens to leave the user's own data area
+    (e.g. /tmp, /etc) is rejected — those locations have no state.vscdb.
+    """
+    try:
+        names = os.listdir(directory)
+    except OSError:
+        return False
+    for name in names:
+        full = os.path.join(directory, name)
+        try:
+            if os.path.isdir(full) and os.path.isfile(os.path.join(full, "state.vscdb")):
+                return True
+        except OSError:
+            continue
+    return False
+
+
+def validate_workspace_path(raw_path: str) -> str:
+    """Validate a /api/set-workspace input and return the canonical real path.
+
+    Raises :class:`WorkspacePathError` if the path:
+      - is empty / not a string,
+      - does not exist after symlink + ``..`` resolution,
+      - is not a directory,
+      - contains no Cursor workspace markers (no immediate subdir with state.vscdb).
+
+    On success, returns the canonical absolute real path. The caller should
+    store that, not the raw input, so subsequent reads resolve through the
+    same canonical value.
+    """
+    if not isinstance(raw_path, str) or not raw_path.strip():
+        raise WorkspacePathError("path is required")
+
+    expanded = expand_tilde_path(raw_path)
+    # realpath() collapses `..` AND resolves symlinks. Both classes of escape
+    # become equivalent to whatever is actually on disk.
+    real = os.path.realpath(expanded)
+
+    if not os.path.exists(real):
+        raise WorkspacePathError("path does not exist")
+    if not os.path.isdir(real):
+        raise WorkspacePathError("path is not a directory")
+    if not _has_cursor_workspace_markers(real):
+        raise WorkspacePathError(
+            "path does not look like a Cursor workspaceStorage directory "
+            "(no immediate subdirectory contains state.vscdb)"
+        )
+
+    return real