feat(files): POSIX paths, elevation, recursive chmod, access hints and docs

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

server/api/remote_path_validation.py

@@ -0,0 +1,33 @@
+"""Validation helpers for remote absolute paths (SSH file operations)."""
+
+from __future__ import annotations
+
+from server.utils.posix_paths import (
+    PosixPathError,
+    normalize_remote_abs_path,
+    normalize_remote_dest,
+    remote_join,
+)
+
+# Backward-compatible alias used by API layers
+RemotePathError = PosixPathError
+
+__all__ = [
+    "RemotePathError",
+    "normalize_remote_abs_path",
+    "normalize_remote_dest",
+    "remote_join",
+    "assert_clipboard_transfer_safe",
+]
+
+
+def assert_clipboard_transfer_safe(sources: list[str], dest_dir: str) -> tuple[list[str], str]:
+    """Return normalized sources and dest_dir; raise RemotePathError if unsafe."""
+    dest = normalize_remote_abs_path(dest_dir)
+    normalized: list[str] = []
+    for raw in sources:
+        src = normalize_remote_abs_path(raw)
+        if dest == src or dest.startswith(src + "/"):
+            raise RemotePathError(f"目标目录不能是源路径自身或其子目录: {src}")
+        normalized.append(src)
+    return normalized, dest