Studio: expose Windows drive roots in the folder browser (#7082)

* Studio: expose Windows drive roots in the folder browser

The model-selection folder browser bounds navigation to the roots returned
by _build_browse_allowlist(), which exposed Linux removable-media mounts via
linux_run_media_mount_roots() but had no Windows analog. As a result a user
on C: could not browse to D:/E: to pick a model directory.

Add windows_drive_roots(), a Windows-only companion to
linux_run_media_mount_roots() that lists readable logical drive roots, and
wire it into both browse-allowlist builders and their suggestion chips so
other drives are both navigable and offered as quick-picks. The helper is a
no-op on Linux/macOS, so existing platforms are unaffected.

Closes #6368

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: cover the Windows drive-root browse wiring with an integration test

Add an allowlist integration test mirroring the Linux side's
test_legacy_browse_allowlist_includes_linux_run_media_mounts: it extracts
_build_browse_allowlist from routes/models.py, stubs external_media so
windows_drive_roots() yields a fake drive root, and asserts that root becomes
browsable through the built allowlist. Proves the wiring, not just the helper.

* Studio: skip inactive drives via GetLogicalDrives before probing

Resolve active logical drives from GetLogicalDrives() before probing each
letter with os.path.isdir. Probing a drive letter mapped to a disconnected
network share can otherwise block the async backend for tens of seconds per
letter. The call degrades gracefully (falls back to probing all letters) when
ctypes/windll is unavailable, so behavior is unchanged on Linux/macOS. Tests
override the bitmask source to stay deterministic on real Windows hosts.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: allow browsing descendants of a drive-root allowlist entry

routes/models.py _is_path_inside_allowlist() checked descendants with
startswith(root_real + os.sep). A drive root ("D:\") already ends in a
separator, so the prefix became "D:\\" and a child like "D:\models" was
rejected with 403 after the browser opened the drive root. Only append a
separator when the root does not already end in one. folder_browser.py already
uses commonpath and was unaffected. Adds a regression test covering the
separator-terminated-root descendant case.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: enforce the system-directory denylist during folder browsing

Exposing whole Windows drive roots (and any legacy-registered filesystem root)
widened the browse allowlist above system directories, but the browse
resolvers only re-applied the credential/config denylist, not the
_denied_path_prefixes() system-dir denylist that scan-folder registration
enforces. That let browse-folders enumerate C:\Windows, C:\Program Files,
/etc and /proc.

- Add is_denied_system_path() to both storage modules and enforce it in both
  browse resolvers (legacy routes/models.py and hub folder_browser.py), on each
  resolved child and on the final target, keeping the /run/media carve-out.
- Rework the legacy _is_path_inside_allowlist to use splitdrive + commonpath so
  a Windows drive root authorizes its descendants while a bare POSIX / does not,
  and to compare case-insensitively like the hub browser.
- Reject the filesystem root in the legacy add_scan_folder, matching the hub.
- Hide denied system dirs from browse listings and suggestion chips.
- Add tests/test_browse_denylist.py and update the external-media path tests.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: make browse-denylist tests OS-portable

The browse-time denylist tests used real /etc and tmp_path locations; on macOS
tmp lives under the (legitimately denied) /private/var and /etc resolves to
/private/etc, so three tests failed there. Pin the platform / use a tmp-based
denied prefix so they assert the same behavior on Linux, macOS and Windows.

* Studio: apply the bare POSIX-root guard to the hub folder browser too

The _is_path_inside_allowlist guard that stops a legacy-registered '/' scan
folder from authorizing every absolute path lived only in the legacy browser.
The hub browser used commonpath without it, so a stale '/' row let it descend
into /var, /root, /home -- which the system-directory denylist (/proc /sys /dev
/etc /boot /run) does not cover, while the legacy browser blocked them. Mirror
the legacy guard so both browsers treat '/' identically.

Also resolve each directory entry before the denylist check in both listing
loops, so a symlink or junction pointing into a denied dir is hidden instead of
rendered as a row that 403s on descent. Adds legacy-vs-hub parity tests.

* Studio: bound Windows drive probing so a disconnected mapping can't stall the browser

GetLogicalDrives includes mapped network drives, so a disconnected but still
mapped drive (e.g. Z: -> \\nas\share) stays set in the bitmask and reaches
os.path.isdir, which can block for tens of seconds while Windows tries to
reconnect. Because windows_drive_roots() runs synchronously while building both
folder-browser responses, one stale mapping stalled every browse request.

Probe each surviving drive in a daemon thread bounded by a short timeout and
skip it if it does not answer in time, so a hung mapping is dropped instead of
blocking the caller. Connected drives (local or network) still respond well
within the timeout, so drive discovery is unchanged. Corrects the
GetLogicalDrives docstring, which claimed the bitmask alone prevented the stall.

* Studio: probe drive/media roots once per browse request, not twice

Both folder browsers called windows_drive_roots() (and
linux_run_media_mount_roots()) twice per browse request: once to seed the
allowlist in _build_browse_allowlist() and again to build the suggestion chips.
With the bounded drive probe, a disconnected mapped network drive then paid the
timeout twice per folder click. Probe both once in the request handler and pass
the results into _build_browse_allowlist(), reusing them for the chips, in both
the legacy and hub browsers. Adds a test asserting the roots are reused, not
re-probed.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: run the legacy browse endpoint in the threadpool, fix its stale test

Two follow-ups from review of the drive-probe changes:

- browse_folders was 'async def' but does only blocking filesystem I/O (the
  timeout-bounded drive probe, iterdir, realpath). On the event loop a
  disconnected mapped drive waiting out its probe timeout stalled every other
  request. Declare it sync 'def' so FastAPI runs it in the threadpool, matching
  the hub browse endpoint. No await was used in the body.

- test_browse_folders_hides_sensitive_dirs monkeypatched _build_browse_allowlist
  with a zero-arg lambda; the once-per-request refactor now calls it with
  (media_roots, drive_roots), so the lambda raised TypeError. Accept and ignore
  the args.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: probe Windows drive roots concurrently so multiple dead mappings don't stack timeouts

windows_drive_roots() probed each candidate serially, so N disconnected-but-mapped network drives each paid the full per-drive timeout in turn (e.g. four stale mappings added ~8s to every folder-browser request). Collect the candidate roots first, then probe them all at once under a single overall deadline, so the added delay stays at ~one timeout regardless of how many drives are disconnected. _readable_dir_within stays as a thin single-path wrapper for its existing callers/tests.

* Studio: tighten comments in the folder-browser drive-root changes

Condense the comments and docstrings added by the Windows drive-root and
system-directory denylist work to be shorter and clearer while keeping the
security and correctness rationale intact. Comment and docstring text only;
no code changes.

* Studio: iterate the input, not the results dict, when collecting readable drive probes

_readable_dirs_within returned {path for path, ok in results.items()...}, but a probe thread that exceeded the join deadline is still alive and can insert its key into results during that iteration, raising 'dictionary changed size during iteration' -- reachable exactly in the disconnected-mapped-drive case the probe exists for. Iterate the fixed input list and read results.get(path) (an atomic read) instead.

* Studio: keep the browse-route containment tests denylist-inert so they pass on macOS

test_browse_folders_route.py exercises allowlist containment and the file-vs-directory guard, not the system-directory denylist. On macOS pytest tmp_path resolves under /private/var, a denied prefix, so _resolve_browse_target 403s the fixture dirs before the containment logic runs (4 failures). Add an autouse fixture that makes is_denied_system_path inert in this file; the denylist keeps its own coverage in test_browse_denylist.py.

* Studio: keep the hub browse tests denylist-inert so they pass on macOS

* Studio: register a UNC share root; only reject local filesystem roots

* Studio: reject device drive roots and browse a registered UNC share root

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: treat device-namespace volume GUID roots as local filesystem roots

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: danielhanchen <danielhanchen@gmail.com>

studio/backend/utils/paths/external_media.py

@@ -8,6 +8,10 @@ from __future__ import annotations
 import getpass
 import os
 import platform
+import string
+import threading
+import time
+from collections.abc import Iterable
 from pathlib import Path
 
 from utils.paths.sensitive import (
@@ -16,6 +20,33 @@ from utils.paths.sensitive import (
 )
 
 
+def is_local_filesystem_root(path: str, *, _pathmod = os.path) -> bool:
+    """True for a bare local filesystem root -- POSIX ``/``, a drive root ``C:\\``,
+    or a device-namespace volume root like ``\\\\?\\C:\\`` or
+    ``\\\\?\\Volume{GUID}\\`` -- which sit above denied system dirs, but NOT a UNC
+    share root (``\\\\server\\share`` or its ``\\\\?\\UNC\\...`` form), which has
+    none under it and was registerable before this guard. ``splitdrive`` is empty
+    on POSIX servers, so this reduces to the plain ``dirname == self`` test there.
+    ``_pathmod`` lets tests drive ``ntpath`` semantics on a POSIX CI.
+    """
+    # Resolve the Windows device / extended-length namespace, where \\?\C:\,
+    # \\.\C:\ and \\?\Volume{GUID}\ are all bare LOCAL volume roots (rejected)
+    # while only \\?\UNC\server\share is a UNC share (handled like \\server\share).
+    if path[:4].lower() in ("\\\\?\\", "\\\\.\\"):
+        rest = path[4:]
+        if rest[:4].lower() == "unc\\":
+            path = "\\\\" + rest[4:]
+        else:
+            # A device volume root is just the volume specifier (C:, Volume{GUID})
+            # with no further component; a deeper path is an ordinary folder.
+            core = rest.rstrip("\\/")
+            return "\\" not in core and "/" not in core
+    if _pathmod.dirname(path) != path:
+        return False
+    drive, _ = _pathmod.splitdrive(path)
+    return drive[:2] not in ("\\\\", "//")
+
+
 def _is_linux_media_mount_path(path: str, media_root: Path | str) -> bool:
     normalized = os.path.normpath(os.path.realpath(os.path.expanduser(path)))
     root = os.path.normpath(os.path.realpath(os.path.expanduser(str(media_root))))
@@ -98,3 +129,101 @@ def linux_run_media_mount_roots(
             seen.add(key)
             roots.append(resolved)
     return roots
+
+
+def _active_windows_drive_bitmask() -> int:
+    """Active-logical-drive bitmask from ``GetLogicalDrives`` (bit 0 = ``A:``), or ``0`` when unavailable.
+
+    A fast non-blocking call that lets :func:`windows_drive_roots` skip the
+    ``os.path.isdir`` probe on unmapped letters. A disconnected network mapping
+    stays set here, so it does not guard the reconnect stall on its own;
+    :func:`windows_drive_roots` bounds each surviving probe too. Returns ``0``
+    (probe every letter) when ctypes/``windll`` is missing.
+    """
+    try:
+        import ctypes
+        return int(ctypes.windll.kernel32.GetLogicalDrives())
+    except Exception:  # noqa: BLE001 -- best-effort; fall back to probing all letters
+        return 0
+
+
+# A disconnected mapped drive stays set in the GetLogicalDrives bitmask, so
+# ``os.path.isdir`` on it can block for tens of seconds. Bound each drive probe
+# so one stale mapping cannot stall a whole folder-browser request.
+_DRIVE_PROBE_TIMEOUT_S = 2.0
+
+
+def _readable_dirs_within(paths: Iterable[str], timeout: float) -> set[str]:
+    """Which of *paths* are readable directories, probed concurrently under one overall *timeout* (seconds).
+
+    Each path is checked (``os.path.isdir`` + ``os.access(R_OK)``) in its own
+    daemon thread and the call waits at most *timeout* total, not per path, so N
+    stalled network drives add ~timeout instead of N*timeout. A path not
+    answering ``True`` by the deadline is treated as unreadable. The daemon
+    threads are never joined past the deadline, so a stuck OS call cannot delay
+    interpreter exit or block the caller (``os.path.isdir`` releases the GIL).
+    """
+    paths = list(paths)  # fixed input we can iterate twice; one probe per path
+    results: dict[str, bool] = {}
+
+    def _probe(path: str) -> None:
+        try:
+            results[path] = os.path.isdir(path) and os.access(path, os.R_OK)
+        except OSError:
+            results[path] = False
+
+    threads: list[threading.Thread] = []
+    for path in paths:
+        thread = threading.Thread(target = _probe, args = (path,), daemon = True)
+        thread.start()
+        threads.append(thread)
+
+    deadline = time.monotonic() + timeout
+    for thread in threads:
+        thread.join(max(0.0, deadline - time.monotonic()))
+
+    # Iterate the fixed input, not results.items(): a probe that timed out is
+    # still alive and may insert its key here, which would raise "dictionary
+    # changed size during iteration". results.get() is an atomic read.
+    return {path for path in paths if results.get(path)}
+
+
+def _readable_dir_within(path: str, timeout: float) -> bool:
+    """``os.path.isdir(path) and os.access(path, R_OK)``, bounded by *timeout* seconds; single-path wrapper over :func:`_readable_dirs_within`."""
+    return path in _readable_dirs_within((path,), timeout)
+
+
+def windows_drive_roots(drive_letters: Iterable[str] = string.ascii_uppercase) -> list[Path]:
+    """Readable logical drive roots (``C:\\``, ``D:\\`` ...) for the folder browser; the Windows analog of :func:`linux_run_media_mount_roots`.
+
+    Without it the allowlist and chips only reach the home drive, so a user
+    cannot navigate from ``C:`` to ``D:``/``E:``. ``GetLogicalDrives`` drops
+    unmapped letters; the rest are probed concurrently under a single timeout
+    and kept only if readable in time. A disconnected mapped drive stays active
+    in the bitmask and its ``os.path.isdir`` can hang for tens of seconds, so
+    parallel probing bounds the added delay at ~one timeout rather than one per
+    drive. Returns ``[]`` off Windows.
+    """
+    if platform.system() != "Windows":
+        return []
+
+    active_mask = _active_windows_drive_bitmask()
+    candidates: list[str] = []
+    seen: set[str] = set()
+    for letter in drive_letters:
+        letter = letter.strip().rstrip(":").upper()
+        if len(letter) != 1 or letter not in string.ascii_uppercase:
+            continue
+        if active_mask and not active_mask & (1 << (ord(letter) - ord("A"))):
+            continue
+        root_text = f"{letter}:\\"
+        key = os.path.normcase(root_text)
+        if key in seen:
+            continue
+        seen.add(key)
+        candidates.append(root_text)
+
+    # Bounded concurrent probe: an active bitmask bit can still be a
+    # disconnected mapping whose os.path.isdir blocks, so probe all at once.
+    readable = _readable_dirs_within(candidates, _DRIVE_PROBE_TIMEOUT_S)
+    return [Path(root_text) for root_text in candidates if root_text in readable]