menzeljonas/stackpilot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Phase 12: file browser (0.12.0)

Browse Source 
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>
This commit is contained in:
menzelj
2026-06-08 10:33:38 +00:00
co-authored by Claude Opus 4.8
parent e69c1fa065
commit e3313fb4ac
15 changed files with 1004 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
backend/agent_app.py
+1 -1
View File
@@ -40,7 +40,7 @@ from services import backup_service, compose_service
logger = logging.getLogger("stackpilot.agent")
AGENT_VERSION = "0.11.1"
AGENT_VERSION = "0.12.0"
# --------------------------------------------------------------------------- #
backend/main.py
+3 -1
View File
@@ -20,6 +20,7 @@ from routers import (
backups,
destinations,
editor,
files,
images,
networks,
ports,
@@ -54,7 +55,7 @@ async def lifespan(app: FastAPI):
schedule_task.cancel()
app = FastAPI(title="StackPilot", version="0.11.1", lifespan=lifespan)
app = FastAPI(title="StackPilot", version="0.12.0", lifespan=lifespan)
app.add_middleware(
CORSMiddleware,
@@ -78,6 +79,7 @@ app.include_router(stacks.router)
app.include_router(system.router)
app.include_router(volumes.router)
app.include_router(editor.router)
app.include_router(files.router)
app.include_router(images.router)
app.include_router(ports.router)
app.include_router(templates.router)
backend/routers/files.py
+194
View File
@@ -0,0 +1,194 @@
"""Full host filesystem browser: list, read, edit, manage, up/download.
Listing and reads require an authenticated user; every mutating operation
(write, mkdir, rename, delete, upload) requires admin and is audit-logged.
All paths are sandboxed by :mod:`services.file_service`.
"""
from __future__ import annotations
import os
import tempfile
from fastapi import (
APIRouter,
Depends,
File,
Form,
HTTPException,
Query,
Request,
UploadFile,
)
from fastapi.responses import FileResponse
from pydantic import BaseModel
from sqlmodel import Session
from auth import get_current_user, require_admin
from database import get_session
from models.user import User
from services import audit_service, device_service, file_service
router = APIRouter(prefix="/api/files", tags=["files"])
def _ip(request: Request) -> str:
return request.client.host if request.client else "unknown"
def _guard(fn, *args, **kwargs):
try:
return fn(*args, **kwargs)
except file_service.BrowseError as exc:
raise HTTPException(status_code=400, detail=str(exc)) from exc
# --------------------------------------------------------------------------- #
# Read-only
# --------------------------------------------------------------------------- #
@router.get("/list")
def list_dir(
path: str = Query("/"),
show_hidden: bool = Query(False),
_user: User = Depends(get_current_user),
) -> dict:
return _guard(device_service.browse, path, show_hidden)
@router.get("/read")
def read_file(
path: str = Query(...),
_user: User = Depends(get_current_user),
) -> dict:
return _guard(file_service.read_file, path)
@router.get("/download")
def download(
path: str = Query(...),
_user: User = Depends(get_current_user),
):
real, filename = _guard(file_service.resolve_download, path)
return FileResponse(real, filename=filename, media_type="application/octet-stream")
# --------------------------------------------------------------------------- #
# Mutating (admin only)
# --------------------------------------------------------------------------- #
class WriteBody(BaseModel):
path: str
content: str
class NameBody(BaseModel):
path: str
name: str
class RenameBody(BaseModel):
path: str
new_name: str
@router.put("/write")
def write_file(
body: WriteBody,
request: Request,
session: Session = Depends(get_session),
user: User = Depends(require_admin),
) -> dict:
result = _guard(file_service.write_file, body.path, body.content)
audit_service.record(
session, user=user.username, action="file.write", target=body.path, ip=_ip(request)
)
return result
@router.post("/mkdir")
def mkdir(
body: NameBody,
request: Request,
session: Session = Depends(get_session),
user: User = Depends(require_admin),
) -> dict:
result = _guard(file_service.create_dir, body.path, body.name)
audit_service.record(
session, user=user.username, action="file.mkdir", target=result["path"], ip=_ip(request)
)
return result
@router.post("/touch")
def touch(
body: NameBody,
request: Request,
session: Session = Depends(get_session),
user: User = Depends(require_admin),
) -> dict:
result = _guard(file_service.create_file, body.path, body.name)
audit_service.record(
session, user=user.username, action="file.create", target=result["path"], ip=_ip(request)
)
return result
@router.post("/rename")
def rename(
body: RenameBody,
request: Request,
session: Session = Depends(get_session),
user: User = Depends(require_admin),
) -> dict:
result = _guard(file_service.rename, body.path, body.new_name)
audit_service.record(
session, user=user.username, action="file.rename",
target=body.path, detail=f"-> {result['path']}", ip=_ip(request),
)
return result
@router.delete("")
def delete(
request: Request,
path: str = Query(...),
recursive: bool = Query(False),
session: Session = Depends(get_session),
user: User = Depends(require_admin),
) -> dict:
result = _guard(file_service.delete, path, recursive)
audit_service.record(
session, user=user.username, action="file.delete", target=path,
detail="recursive" if recursive else None, ip=_ip(request),
)
return result
@router.post("/upload")
async def upload(
request: Request,
path: str = Form(...),
overwrite: bool = Form(False),
file: UploadFile = File(...),
session: Session = Depends(get_session),
user: User = Depends(require_admin),
) -> dict:
real = _guard(file_service.upload_target, path, file.filename or "", overwrite)
# Stream to a temp file first, then move into place atomically.
tmp = tempfile.NamedTemporaryFile(delete=False, dir=os.path.dirname(real))
try:
while chunk := await file.read(1024 * 1024):
tmp.write(chunk)
tmp.close()
os.replace(tmp.name, real)
except OSError as exc:
if os.path.exists(tmp.name):
os.unlink(tmp.name)
raise HTTPException(status_code=400, detail=f"Upload failed: {exc}") from exc
audit_service.record(
session, user=user.username, action="file.upload",
target=path, detail=file.filename, ip=_ip(request),
)
return {"ok": True, "name": file.filename}
backend/services/device_service.py
+2
View File
@@ -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
+188
View File
@@ -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