Align /api/validate-path with validate_workspace_path (PR #22)

- POST /api/validate-path now uses the same realpath + marker checks as
  set-workspace; returns canonical path and structured errors on failure.
- README documents WORKSPACE_PATH as trusted-operator tilde expansion only.
- Config page shows server error text when validation fails.
- Docstrings + symlink-test CI note; TOCTOU comment after realpath.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: bradjin8

README.md

@@ -122,6 +122,8 @@ The application automatically detects your Cursor workspace storage location:
 
 To override, set the `WORKSPACE_PATH` environment variable or use the Configuration page in the web UI.
 
+Paths submitted through **`POST /api/set-workspace`** (and **`POST /api/validate-path`**) are validated the same way: canonical resolution (`realpath`), directory checks, and Cursor workspace markers (`state.vscdb` under immediate subdirectories). The **`WORKSPACE_PATH`** environment variable is only tilde-expanded — it is a **trusted-operator** escape hatch for automation and known-good paths, not a substitute for those API checks when untrusted input matters.
+
 Cursor CLI agent sessions are read from `~/.cursor/chats/` (the default path used by the `cursor agent` CLI). Override with the `CLI_CHATS_PATH` environment variable.
 
 ## Project Structure

api/config_api.py

@@ -12,7 +12,6 @@
 
 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
 
@@ -51,23 +50,30 @@ def detect_environment():
 
 @bp.route("/api/validate-path", methods=["POST"])
 def validate_path():
+    """Same path rules as POST /api/set-workspace: realpath, markers (issue #15)."""
     try:
         body = request.get_json(silent=True) or {}
-        workspace_path = body.get("path", "")
-        expanded = expand_tilde_path(workspace_path)
-
-        if not os.path.isdir(expanded):
-            return jsonify({"valid": False, "error": "Path does not exist"})
+        raw = body.get("path", "")
+        try:
+            canonical = validate_workspace_path(raw)
+        except WorkspacePathError as e:
+            return jsonify({"valid": False, "error": str(e), "workspaceCount": 0})
 
         workspace_count = 0
-        for name in os.listdir(expanded):
-            full = os.path.join(expanded, name)
+        for name in os.listdir(canonical):
+            full = os.path.join(canonical, name)
             if os.path.isdir(full):
                 db = os.path.join(full, "state.vscdb")
                 if os.path.isfile(db):
                     workspace_count += 1
 
-        return jsonify({"valid": workspace_count > 0, "workspaceCount": workspace_count})
+        return jsonify(
+            {
+                "valid": workspace_count > 0,
+                "workspaceCount": workspace_count,
+                "path": canonical,
+            }
+        )
 
     except Exception as e:
         print(f"Validation error: {e}")

templates/config.html

@@ -96,7 +96,7 @@ <h1>Configuration</h1>
       setTimeout(() => { window.location.href = '/'; }, 1000);
     } else {
       statusEl.className = 'alert alert-danger';
-      statusEl.textContent = 'No workspaces found in the specified location';
+      statusEl.textContent = data.error || 'No workspaces found in the specified location';
       statusEl.style.display = 'block';
     }
   } catch (e) {

tests/test_workspace_path_validation.py

@@ -114,6 +114,7 @@ def test_traversal_into_non_workspace_is_rejected(self):
             validate_workspace_path(escape)
 
     # ─── Symlink-escape class ──────────────────────────────────────
+    # POSIX-only; CI runs tests on ubuntu-latest so these still run in CI.
 
     @unittest.skipIf(sys.platform == "win32", "POSIX symlinks only")
     def test_symlink_to_non_workspace_is_rejected(self):
@@ -196,6 +197,24 @@ def test_dict_with_valid_path_returns_200_with_canonical(self):
         self.assertTrue(body["success"])
         self.assertEqual(body["path"], os.path.realpath(storage))
 
+    def test_validate_path_returns_canonical_and_count(self):
+        storage = _make_cursor_workspace_dir(self.tmp)
+        resp = self.client.post("/api/validate-path", json={"path": storage})
+        self.assertEqual(resp.status_code, 200)
+        data = resp.get_json()
+        self.assertTrue(data["valid"])
+        self.assertGreaterEqual(data["workspaceCount"], 1)
+        self.assertEqual(data["path"], os.path.realpath(storage))
+
+    def test_validate_path_invalid_returns_error(self):
+        plain = os.path.join(self.tmp, "no-markers")
+        os.makedirs(plain)
+        resp = self.client.post("/api/validate-path", json={"path": plain})
+        self.assertEqual(resp.status_code, 200)
+        data = resp.get_json()
+        self.assertFalse(data["valid"])
+        self.assertIn("error", data)
+
 
 if __name__ == "__main__":
     unittest.main()

utils/path_validation.py

@@ -1,4 +1,4 @@
-"""Validation for workspace paths submitted via /api/set-workspace.
+"""Validation for workspace paths submitted via /api/set-workspace and /api/validate-path.
 
 Lives outside ``api/`` so the unit tests can import it without pulling
 Flask into scope (the existing test suite intentionally avoids Flask —
@@ -30,9 +30,10 @@ class WorkspacePathError(ValueError):
 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
+    Same heuristic as POST /api/validate-path (counts workspaces). Nested
+    layouts beyond one level are out of scope per issue #15. 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:
@@ -50,7 +51,9 @@ def _has_cursor_workspace_markers(directory: str) -> bool:
 
 
 def validate_workspace_path(raw_path: str) -> str:
-    """Validate a /api/set-workspace input and return the canonical real path.
+    """Validate a workspace path input and return the canonical real path.
+
+    Used by POST /api/set-workspace and POST /api/validate-path (issue #15).
 
     Raises :class:`WorkspacePathError` if the path:
       - is empty / not a string,
@@ -69,6 +72,8 @@ def validate_workspace_path(raw_path: str) -> str:
     # realpath() collapses `..` AND resolves symlinks. Both classes of escape
     # become equivalent to whatever is actually on disk.
     real = os.path.realpath(expanded)
+    # Classic TOCTOU: the tree could change before listdir below; low practical
+    # risk for this single-user local tool (issue #15 review).
 
     if not os.path.exists(real):
         raise WorkspacePathError("path does not exist")

utils/workspace_path.py

@@ -58,7 +58,12 @@ def get_default_workspace_path() -> str:
 
 
 def resolve_workspace_path() -> str:
-    """Return the effective workspace path (override > env var > default)."""
+    """Return the effective workspace path (override > env var > default).
+
+    Override comes from POST /api/set-workspace (validated). ``WORKSPACE_PATH``
+    is only tilde-expanded — trusted-operator escape hatch, not the same checks
+    as the API (issue #15).
+    """
     if _workspace_path_override:
         return expand_tilde_path(_workspace_path_override)
     env_path = os.environ.get("WORKSPACE_PATH", "").strip()