Phase 12: file browser (0.12.0)

Add a full host filesystem browser reachable from the sidebar (/files):
breadcrumb navigation, browse-root chips, show-hidden toggle, and a table
with size/permissions/mtime. Text files open in a Monaco editor (language by
extension); binary/oversized files fall back to download. Admins can create
folders/files, rename, delete (recursive for dirs), upload, and save edits;
download is available to all users. Every mutation is audit-logged.

Backend: new services/file_service.py reuses device_service's sandbox helpers
(confined to ALLOWED_BROWSE_ROOTS, mapped via HOST_ROOT_PREFIX) and rejects
path traversal and deleting a browse root. routers/files.py exposes
/api/files/{list,read,download,write,mkdir,touch,rename,upload,DELETE}
(reads: any user; mutations: admin). device_service.browse entries gained
mtime + symlink (non-breaking).

Deployment: ALLOWED_BROWSE_ROOTS + HOST_ROOT_PREFIX are now env-wired in
docker-compose.yml and .env.example, with a commented /:/host_root mount to
browse/manage the real host filesystem.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

backend/services/device_service.py

@@ -138,6 +138,8 @@ def browse(path: str = "/", show_hidden: bool = False) -> dict:
                     "type": "dir" if is_dir else "file",
                     "size": st.st_size if not is_dir else None,
                     "permissions": oct(st.st_mode & 0o777),
+                    "mtime": st.st_mtime,
+                    "symlink": os.path.islink(full_real),
                 }
             )
         except OSError:

backend/services/file_service.py

@@ -0,0 +1,188 @@
+"""Sandboxed host filesystem operations for the web file browser.
+
+All paths are *logical* host paths (what the user sees, e.g. ``/opt/foo``).
+They are validated against ``ALLOWED_BROWSE_ROOTS`` and then mapped into the
+container's view via ``HOST_ROOT_PREFIX`` before any I/O. Directory listing is
+provided by :func:`device_service.browse`; this module adds the read/write,
+upload/download and management operations needed for a full browser.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+
+from services.device_service import BrowseError, _is_allowed, _real_root
+
+# Largest file we will load into the in-browser text editor.
+MAX_EDIT_BYTES = 2 * 1024 * 1024  # 2 MiB
+
+
+def _safe_real(path: str) -> str:
+    """Validate a logical path against the sandbox and return its real path."""
+    path = os.path.normpath(path or "/")
+    if not path.startswith("/"):
+        raise BrowseError("Path must be absolute")
+    if not _is_allowed(path):
+        raise BrowseError("Path is outside the allowed browse roots")
+    return _real_root(path)
+
+
+def _child(path: str, name: str) -> str:
+    """Return the logical path of ``name`` directly inside ``path``.
+
+    ``name`` must be a single path component (no separators, no traversal).
+    """
+    if not name or name in (".", "..") or "/" in name or "\\" in name:
+        raise BrowseError("Invalid name")
+    base = "" if path == "/" else path.rstrip("/")
+    return f"{base}/{name}"
+
+
+def _looks_binary(chunk: bytes) -> bool:
+    return b"\x00" in chunk
+
+
+# --------------------------------------------------------------------------- #
+# Read / write text
+# --------------------------------------------------------------------------- #
+
+
+def read_file(path: str) -> dict:
+    real = _safe_real(path)
+    if not os.path.isfile(real):
+        raise BrowseError(f"Not a file: {path}")
+    size = os.path.getsize(real)
+    if size > MAX_EDIT_BYTES:
+        return {
+            "path": path,
+            "content": None,
+            "size": size,
+            "binary": False,
+            "too_large": True,
+        }
+    try:
+        with open(real, "rb") as fh:
+            raw = fh.read()
+    except PermissionError as exc:
+        raise BrowseError(f"Permission denied: {path}") from exc
+
+    if _looks_binary(raw[:8192]):
+        return {"path": path, "content": None, "size": size, "binary": True, "too_large": False}
+    try:
+        content = raw.decode("utf-8")
+    except UnicodeDecodeError:
+        return {"path": path, "content": None, "size": size, "binary": True, "too_large": False}
+    return {"path": path, "content": content, "size": size, "binary": False, "too_large": False}
+
+
+def write_file(path: str, content: str) -> dict:
+    real = _safe_real(path)
+    if os.path.isdir(real):
+        raise BrowseError(f"Is a directory: {path}")
+    parent = os.path.dirname(real)
+    if not os.path.isdir(parent):
+        raise BrowseError("Parent directory does not exist")
+    try:
+        with open(real, "w", encoding="utf-8") as fh:
+            fh.write(content)
+    except PermissionError as exc:
+        raise BrowseError(f"Permission denied: {path}") from exc
+    return {"path": path, "size": os.path.getsize(real)}
+
+
+# --------------------------------------------------------------------------- #
+# Management
+# --------------------------------------------------------------------------- #
+
+
+def create_dir(path: str, name: str) -> dict:
+    child = _child(path, name)
+    real = _safe_real(child)
+    if os.path.exists(real):
+        raise BrowseError(f"Already exists: {name}")
+    try:
+        os.mkdir(real)
+    except PermissionError as exc:
+        raise BrowseError(f"Permission denied: {path}") from exc
+    return {"path": child}
+
+
+def create_file(path: str, name: str) -> dict:
+    child = _child(path, name)
+    real = _safe_real(child)
+    if os.path.exists(real):
+        raise BrowseError(f"Already exists: {name}")
+    try:
+        with open(real, "x", encoding="utf-8"):
+            pass
+    except PermissionError as exc:
+        raise BrowseError(f"Permission denied: {path}") from exc
+    return {"path": child}
+
+
+def rename(path: str, new_name: str) -> dict:
+    real = _safe_real(path)
+    if not os.path.lexists(real):
+        raise BrowseError(f"No such path: {path}")
+    parent = os.path.dirname(path) or "/"
+    dest = _child(parent, new_name)
+    dest_real = _safe_real(dest)
+    if os.path.lexists(dest_real):
+        raise BrowseError(f"Already exists: {new_name}")
+    try:
+        os.rename(real, dest_real)
+    except PermissionError as exc:
+        raise BrowseError(f"Permission denied: {path}") from exc
+    return {"path": dest}
+
+
+def delete(path: str, recursive: bool = False) -> dict:
+    real = _safe_real(path)
+    norm = os.path.normpath(path)
+    if norm == "/" or norm in {os.path.normpath(r) for r in _root_paths()}:
+        raise BrowseError("Refusing to delete a browse root")
+    if not os.path.lexists(real):
+        raise BrowseError(f"No such path: {path}")
+    try:
+        if os.path.isdir(real) and not os.path.islink(real):
+            if recursive:
+                shutil.rmtree(real)
+            else:
+                os.rmdir(real)  # fails if non-empty
+        else:
+            os.remove(real)
+    except OSError as exc:
+        raise BrowseError(f"Could not delete {path}: {exc.strerror or exc}") from exc
+    return {"path": path}
+
+
+def _root_paths() -> list[str]:
+    from config import settings
+
+    return settings.ALLOWED_BROWSE_ROOTS
+
+
+# --------------------------------------------------------------------------- #
+# Download / upload
+# --------------------------------------------------------------------------- #
+
+
+def resolve_download(path: str) -> tuple[str, str]:
+    """Return (real_path, filename) for a file download, or raise BrowseError."""
+    real = _safe_real(path)
+    if not os.path.isfile(real):
+        raise BrowseError(f"Not a file: {path}")
+    return real, os.path.basename(path)
+
+
+def upload_target(dir_path: str, filename: str, overwrite: bool = False) -> str:
+    """Validate an upload destination and return the real path to write to."""
+    real_dir = _safe_real(dir_path)
+    if not os.path.isdir(real_dir):
+        raise BrowseError(f"Not a directory: {dir_path}")
+    name = os.path.basename(filename or "")
+    child = _child(dir_path, name)
+    real = _safe_real(child)
+    if os.path.exists(real) and not overwrite:
+        raise BrowseError(f"Already exists: {name}")
+    return real