feat: secure web dashboard and file explorer with admin master access

keystone-backend/main.py

@@ -1,288 +1,387 @@
-import os
-from datetime import datetime, timedelta
-from fastapi import FastAPI, HTTPException, Header, Depends, UploadFile, File, Form, Request
-from fastapi.middleware.cors import CORSMiddleware
-from fastapi.responses import FileResponse
-from pydantic import BaseModel
-from dotenv import load_dotenv
-import jwt
-from PIL import Image
-import cv2
-
-# Load local environment variables
-load_dotenv()
-
-app = FastAPI(title="KeyStone API", version="0.1.0")
-
-# JWT Configuration
-JWT_SECRET = os.getenv("JWT_SECRET", "super-secret-default-key-change-in-prod")
-JWT_ALGORITHM = "HS256"
-JWT_EXPIRATION_DAYS = 365
-
-# Load Users dynamically from Environment Variables
-# Format: USER_1=john, PASSWORD_1=secret
-VALID_USERS = {}
-for key, value in os.environ.items():
-    if key.startswith("USER_"):
-        idx = key.split("_")[1]
-        password = os.environ.get(f"PASSWORD_{idx}")
-        if password:
-            VALID_USERS[value] = password
-
-# --- BUCKET STORAGE ENFORCEMENT ---
-# The Hugging Face bucket MUST be mounted at /data for this service to operate.
-# Photos are ONLY saved to the persistent bucket. If /data is not mounted,
-# the server will refuse to start to prevent silent data loss.
-_BUCKET_ROOT = "/data"
-_LOCAL_DEV_PATH = os.getenv("STORAGE_DIR", "")  # Only set in local dev .env
-
-if os.path.exists(_BUCKET_ROOT):
-    # Running on Hugging Face with the bucket mounted — use it.
-    BASE_STORAGE_DIR = os.path.join(_BUCKET_ROOT, "photos")
-elif _LOCAL_DEV_PATH:
-    # Local development override explicitly set in .env — allow it.
-    BASE_STORAGE_DIR = _LOCAL_DEV_PATH
-    import warnings
-    warnings.warn(
-        f"[KeyStone] Bucket not mounted. Using local dev path: {BASE_STORAGE_DIR}. "
-        "DO NOT use this in production.",
-        stacklevel=1,
-    )
-else:
-    # No bucket and no local override — refuse to start.
-    raise RuntimeError(
-        "[KeyStone] FATAL: Hugging Face bucket is not mounted at /data and no "
-        "STORAGE_DIR env var is set. Photos cannot be stored safely. "
-        "Mount the bucket in your Space settings before starting the server."
-    )
-
-# Ensure the base directory exists
-os.makedirs(BASE_STORAGE_DIR, exist_ok=True)
-print(f"[KeyStone] Storage directory: {BASE_STORAGE_DIR}")
-# -----------------------------------
-
-app.add_middleware(
-    CORSMiddleware,
-    allow_origins=["*"],
-    allow_credentials=True,
-    allow_methods=["*"],
-    allow_headers=["*"],
-)
-
-class LoginRequest(BaseModel):
-    username: str
-    password: str
-
-def verify_jwt_token(token: str = None):
-    if not token:
-        raise HTTPException(status_code=401, detail="Missing token")
-    try:
-        payload = jwt.decode(token, JWT_SECRET, algorithms=[JWT_ALGORITHM])
-        return payload.get("sub")
-    except jwt.ExpiredSignatureError:
-        raise HTTPException(status_code=401, detail="Token expired")
-    except jwt.InvalidTokenError:
-        raise HTTPException(status_code=401, detail="Invalid token")
-
-@app.get("/")
-async def root():
-    return {
-        "message": "Welcome to KeyStone API",
-        "status": "online",
-        "docs": "/docs"
-    }
-
-@app.get("/health")
-async def health_check():
-    return {
-        "status": "ok", 
-        "service": "KeyStone API", 
-        "storage_path": BASE_STORAGE_DIR
-    }
-
-@app.post("/auth/login")
-async def login(req: LoginRequest):
-    if req.username not in VALID_USERS or VALID_USERS[req.username] != req.password:
-        raise HTTPException(status_code=401, detail="Invalid username or password")
-    
-    payload = {
-        "sub": req.username,
-        "exp": datetime.utcnow() + timedelta(days=JWT_EXPIRATION_DAYS)
-    }
-    token = jwt.encode(payload, JWT_SECRET, algorithm=JWT_ALGORITHM)
-    return {"token": token, "username": req.username}
-
-@app.post("/upload")
-async def upload_photo(
-    file: UploadFile = File(...), 
-    creation_time: str = Form(None),
-    token: str = Form(...)
-):
-    username = verify_jwt_token(token)
-    
-    # Determine the date for folder structure
-    dt = datetime.now()
-    if creation_time:
-        try:
-            # creation_time might be epoch milliseconds or an ISO string
-            if creation_time.isdigit():
-                dt = datetime.fromtimestamp(int(creation_time) / 1000.0)
-            else:
-                dt = datetime.fromisoformat(creation_time.replace('Z', '+00:00'))
-        except Exception:
-            pass # Fallback to now() if parsing fails
-
-    year_folder = dt.strftime("%Y")
-    month_folder = dt.strftime("%m")
-
-    # Create target directory: e.g., /data/photos/username/2024/07
-    target_dir = os.path.join(BASE_STORAGE_DIR, username, year_folder, month_folder)
-    os.makedirs(target_dir, exist_ok=True)
-
-    file_path = os.path.join(target_dir, file.filename)
-    
-    # If file already exists, we consider it a successful sync skip
-    if os.path.exists(file_path):
-        return {
-            "message": "Photo already exists, skipped.",
-            "filename": file.filename,
-            "path": file_path,
-            "status": "skipped"
-        }
-    
-    try:
-        # Save in 1MB chunks to prevent memory spikes
-        with open(file_path, "wb") as buffer:
-            while content := await file.read(1024 * 1024): 
-                buffer.write(content)
-                
-        # Preserve original creation time on the filesystem for the GET /photos API
-        ts = dt.timestamp()
-        os.utime(file_path, (ts, ts))
-        
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=f"Could not save file: {str(e)}")
-        
-    return {
-        "message": "Photo securely uploaded!",
-        "filename": file.filename,
-        "path": file_path,
-        "status": "uploaded"
-    }
-
-@app.get("/photos")
-async def list_photos(username: str = Depends(verify_jwt_token)):
-    photos = []
-    user_dir = os.path.join(BASE_STORAGE_DIR, username)
-    if not os.path.exists(user_dir):
-        return {"assets": []}
-        
-    for root_dir, dirs, files in os.walk(user_dir):
-        for f in files:
-            full_path = os.path.join(root_dir, f)
-            rel_path = os.path.relpath(full_path, user_dir)
-            stat = os.stat(full_path)
-            
-            clean_rel = rel_path.replace("\\", "/")
-            serve_url = f"/photos/serve/{clean_rel}"
-            thumb_url = f"/photos/serve/thumb/{clean_rel}"
-            
-            media_type = "video" if f.lower().endswith(('.mp4', '.mov', '.avi', '.webm')) else "photo"
-            
-            photos.append({
-                "id": clean_rel, 
-                "uri": serve_url,
-                "thumbUri": thumb_url,
-                "creationTime": int(stat.st_mtime * 1000),
-                "mediaType": media_type,
-                "filename": f,
-                "size": stat.st_size
-            })
-            
-    return {"assets": photos}
-
-@app.get("/photos/serve/{year}/{month}/{filename}")
-async def serve_photo(
-    year: str, month: str, filename: str,
-    username: str = Depends(verify_jwt_token)
-):
-    file_path = os.path.join(BASE_STORAGE_DIR, username, year, month, filename)
-    if not os.path.exists(file_path):
-        raise HTTPException(status_code=404, detail="File not found")
-    return FileResponse(file_path)
-
-def generate_video_thumbnail(video_path: str, thumb_path: str):
-    try:
-        cap = cv2.VideoCapture(video_path)
-        if not cap.isOpened():
-            return False
-        # Read the first frame
-        ret, frame = cap.read()
-        cap.release()
-        if ret:
-            # Resize frame to speed up and save space
-            height, width = frame.shape[:2]
-            max_dim = 300
-            scale = min(max_dim / width, max_dim / height)
-            if scale < 1:
-                new_size = (int(width * scale), int(height * scale))
-                frame = cv2.resize(frame, new_size, interpolation=cv2.INTER_AREA)
-            cv2.imwrite(thumb_path, frame, [int(cv2.IMWRITE_JPEG_QUALITY), 70])
-            return True
-        return False
-    except Exception as e:
-        print(f"Error generating video thumb: {e}")
-        return False
-
-@app.get("/photos/serve/thumb/{year}/{month}/{filename}")
-async def serve_photo_thumb(
-    year: str, month: str, filename: str,
-    username: str = Depends(verify_jwt_token)
-):
-    original_path = os.path.join(BASE_STORAGE_DIR, username, year, month, filename)
-    if not os.path.exists(original_path):
-        raise HTTPException(status_code=404, detail="Original file not found")
-        
-    thumb_dir = os.path.join(BASE_STORAGE_DIR, "thumbnails", username, year, month)
-    os.makedirs(thumb_dir, exist_ok=True)
-    
-    thumb_path = os.path.join(thumb_dir, f"{filename}.thumb.jpg")
-    
-    if os.path.exists(thumb_path):
-        return FileResponse(thumb_path)
-        
-    # Generate thumbnail on the fly
-    media_type = "video" if filename.lower().endswith(('.mp4', '.mov', '.avi', '.webm')) else "photo"
-    
-    try:
-        if media_type == "video":
-            success = generate_video_thumbnail(original_path, thumb_path)
-            if not success:
-                # If generation fails, just fallback to original
-                return FileResponse(original_path)
-        else:
-            with Image.open(original_path) as img:
-                # Convert to RGB if needed (e.g. RGBA png)
-                if img.mode in ("RGBA", "P"):
-                    img = img.convert("RGB")
-                img.thumbnail((300, 300))
-                img.save(thumb_path, "JPEG", quality=70)
-                
-        return FileResponse(thumb_path)
-    except Exception as e:
-        print(f"Thumbnail generation error: {e}")
-        # Fallback to original
-        return FileResponse(original_path)
-
-@app.delete("/photos/delete/{file_path:path}")
-async def delete_photo(file_path: str, username: str = Depends(verify_jwt_token)):
-    clean_path = os.path.normpath(file_path)
-    if clean_path.startswith("..") or os.path.isabs(clean_path):
-        raise HTTPException(status_code=400, detail="Invalid path")
-        
-    full_path = os.path.join(BASE_STORAGE_DIR, username, clean_path)
-    if os.path.exists(full_path):
-        os.remove(full_path)
-        return {"message": "Deleted successfully"}
-    else:
-        raise HTTPException(status_code=404, detail="File not found")
+import os
+from datetime import datetime, timedelta
+from fastapi import FastAPI, HTTPException, Header, Depends, UploadFile, File, Form, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse
+from pydantic import BaseModel
+from dotenv import load_dotenv
+import jwt
+from PIL import Image
+import cv2
+import shutil
+import tempfile
+from fastapi.responses import FileResponse, HTMLResponse
+import zipfile
+import io
+
+# Load local environment variables
+load_dotenv()
+
+app = FastAPI(title="KeyStone API", version="0.1.0")
+
+# JWT Configuration
+JWT_SECRET = os.getenv("JWT_SECRET", "super-secret-default-key-change-in-prod")
+JWT_ALGORITHM = "HS256"
+JWT_EXPIRATION_DAYS = 365
+
+# Load Users dynamically from Environment Variables
+# Format: USER_1=john, PASSWORD_1=secret
+VALID_USERS = {}
+for key, value in os.environ.items():
+    if key.startswith("USER_"):
+        idx = key.split("_")[1]
+        password = os.environ.get(f"PASSWORD_{idx}")
+        if password:
+            VALID_USERS[value] = password
+
+ADMIN_USERNAME = os.getenv("ADMIN")
+ADMIN_PASSWORD = os.getenv("ADMIN_PASS")
+if ADMIN_USERNAME and ADMIN_PASSWORD:
+    VALID_USERS[ADMIN_USERNAME] = ADMIN_PASSWORD
+
+# --- BUCKET STORAGE ENFORCEMENT ---
+# The Hugging Face bucket MUST be mounted at /data for this service to operate.
+# Photos are ONLY saved to the persistent bucket. If /data is not mounted,
+# the server will refuse to start to prevent silent data loss.
+_BUCKET_ROOT = "/data"
+_LOCAL_DEV_PATH = os.getenv("STORAGE_DIR", "")  # Only set in local dev .env
+
+if os.path.exists(_BUCKET_ROOT):
+    # Running on Hugging Face with the bucket mounted — use it.
+    BASE_STORAGE_DIR = os.path.join(_BUCKET_ROOT, "photos")
+elif _LOCAL_DEV_PATH:
+    # Local development override explicitly set in .env — allow it.
+    BASE_STORAGE_DIR = _LOCAL_DEV_PATH
+    import warnings
+    warnings.warn(
+        f"[KeyStone] Bucket not mounted. Using local dev path: {BASE_STORAGE_DIR}. "
+        "DO NOT use this in production.",
+        stacklevel=1,
+    )
+else:
+    # No bucket and no local override — refuse to start.
+    raise RuntimeError(
+        "[KeyStone] FATAL: Hugging Face bucket is not mounted at /data and no "
+        "STORAGE_DIR env var is set. Photos cannot be stored safely. "
+        "Mount the bucket in your Space settings before starting the server."
+    )
+
+# Ensure the base directory exists
+os.makedirs(BASE_STORAGE_DIR, exist_ok=True)
+
+def get_user_dir(username: str) -> str:
+    # Master access for admin
+    if ADMIN_USERNAME and username == ADMIN_USERNAME:
+        return BASE_STORAGE_DIR
+    return os.path.join(BASE_STORAGE_DIR, username)
+print(f"[KeyStone] Storage directory: {BASE_STORAGE_DIR}")
+# -----------------------------------
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+class LoginRequest(BaseModel):
+    username: str
+    password: str
+
+def verify_jwt_token(token: str = None):
+    if not token:
+        raise HTTPException(status_code=401, detail="Missing token")
+    try:
+        payload = jwt.decode(token, JWT_SECRET, algorithms=[JWT_ALGORITHM])
+        return payload.get("sub")
+    except jwt.ExpiredSignatureError:
+        raise HTTPException(status_code=401, detail="Token expired")
+    except jwt.InvalidTokenError:
+        raise HTTPException(status_code=401, detail="Invalid token")
+
+@app.get("/")
+async def root():
+    return {
+        "message": "Welcome to KeyStone API",
+        "status": "online",
+        "docs": "/docs"
+    }
+
+@app.get("/health")
+async def health_check():
+    return {
+        "status": "ok", 
+        "service": "KeyStone API", 
+        "storage_path": BASE_STORAGE_DIR
+    }
+
+@app.post("/auth/login")
+async def login(req: LoginRequest):
+    if req.username not in VALID_USERS or VALID_USERS[req.username] != req.password:
+        raise HTTPException(status_code=401, detail="Invalid username or password")
+    
+    payload = {
+        "sub": req.username,
+        "exp": datetime.utcnow() + timedelta(days=JWT_EXPIRATION_DAYS)
+    }
+    token = jwt.encode(payload, JWT_SECRET, algorithm=JWT_ALGORITHM)
+    return {"token": token, "username": req.username}
+
+@app.post("/upload")
+async def upload_photo(
+    file: UploadFile = File(...), 
+    creation_time: str = Form(None),
+    token: str = Form(...)
+):
+    username = verify_jwt_token(token)
+    
+    # Determine the date for folder structure
+    dt = datetime.now()
+    if creation_time:
+        try:
+            # creation_time might be epoch milliseconds or an ISO string
+            if creation_time.isdigit():
+                dt = datetime.fromtimestamp(int(creation_time) / 1000.0)
+            else:
+                dt = datetime.fromisoformat(creation_time.replace('Z', '+00:00'))
+        except Exception:
+            pass # Fallback to now() if parsing fails
+
+    year_folder = dt.strftime("%Y")
+    month_folder = dt.strftime("%m")
+
+    # Create target directory: e.g., /data/photos/username/2024/07
+    target_dir = os.path.join(BASE_STORAGE_DIR, username, year_folder, month_folder)
+    os.makedirs(target_dir, exist_ok=True)
+
+    file_path = os.path.join(target_dir, file.filename)
+    
+    # If file already exists, we consider it a successful sync skip
+    if os.path.exists(file_path):
+        return {
+            "message": "Photo already exists, skipped.",
+            "filename": file.filename,
+            "path": file_path,
+            "status": "skipped"
+        }
+    
+    try:
+        # Save in 1MB chunks to prevent memory spikes
+        with open(file_path, "wb") as buffer:
+            while content := await file.read(1024 * 1024): 
+                buffer.write(content)
+                
+        # Preserve original creation time on the filesystem for the GET /photos API
+        ts = dt.timestamp()
+        os.utime(file_path, (ts, ts))
+        
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Could not save file: {str(e)}")
+        
+    return {
+        "message": "Photo securely uploaded!",
+        "filename": file.filename,
+        "path": file_path,
+        "status": "uploaded"
+    }
+
+@app.get("/photos")
+async def list_photos(username: str = Depends(verify_jwt_token)):
+    photos = []
+    user_dir = get_user_dir(username)
+    if not os.path.exists(user_dir):
+        return {"assets": []}
+        
+    for root_dir, dirs, files in os.walk(user_dir):
+        for f in files:
+            # Skip thumbnails if they are in the directory tree
+            if f.endswith('.thumb.jpg'):
+                continue
+                
+            full_path = os.path.join(root_dir, f)
+            rel_path = os.path.relpath(full_path, user_dir)
+            stat = os.stat(full_path)
+            
+            clean_rel = rel_path.replace("\\", "/")
+            serve_url = f"/photos/serve/{clean_rel}"
+            thumb_url = f"/photos/serve/thumb/{clean_rel}"
+            
+            media_type = "video" if f.lower().endswith(('.mp4', '.mov', '.avi', '.webm')) else "photo"
+            
+            photos.append({
+                "id": clean_rel, 
+                "uri": serve_url,
+                "thumbUri": thumb_url,
+                "creationTime": int(stat.st_mtime * 1000),
+                "mediaType": media_type,
+                "filename": f,
+                "size": stat.st_size
+            })
+            
+    return {"assets": photos}
+
+@app.get("/photos/serve/{file_path:path}")
+async def serve_photo(
+    file_path: str,
+    username: str = Depends(verify_jwt_token)
+):
+    user_dir = get_user_dir(username)
+    full_path = os.path.join(user_dir, file_path)
+    if not os.path.exists(full_path):
+        raise HTTPException(status_code=404, detail="File not found")
+    return FileResponse(full_path)
+
+def generate_video_thumbnail(video_path: str, thumb_path: str):
+    try:
+        cap = cv2.VideoCapture(video_path)
+        if not cap.isOpened():
+            return False
+        # Read the first frame
+        ret, frame = cap.read()
+        cap.release()
+        if ret:
+            # Resize frame to speed up and save space
+            height, width = frame.shape[:2]
+            max_dim = 300
+            scale = min(max_dim / width, max_dim / height)
+            if scale < 1:
+                new_size = (int(width * scale), int(height * scale))
+                frame = cv2.resize(frame, new_size, interpolation=cv2.INTER_AREA)
+            cv2.imwrite(thumb_path, frame, [int(cv2.IMWRITE_JPEG_QUALITY), 70])
+            return True
+        return False
+    except Exception as e:
+        print(f"Error generating video thumb: {e}")
+        return False
+
+@app.get("/photos/serve/thumb/{file_path:path}")
+async def serve_photo_thumb(
+    file_path: str,
+    username: str = Depends(verify_jwt_token)
+):
+    user_dir = get_user_dir(username)
+    original_path = os.path.join(user_dir, file_path)
+    if not os.path.exists(original_path):
+        raise HTTPException(status_code=404, detail="Original file not found")
+        
+    filename = os.path.basename(file_path)
+    rel_dir = os.path.dirname(file_path)
+    
+    # Store thumbnails in a parallel thumbnails tree
+    thumb_dir = os.path.join(BASE_STORAGE_DIR, "thumbnails", username, rel_dir)
+    os.makedirs(thumb_dir, exist_ok=True)
+    
+    thumb_path = os.path.join(thumb_dir, f"{filename}.thumb.jpg")
+    
+    if os.path.exists(thumb_path):
+        return FileResponse(thumb_path)
+        
+    # Generate thumbnail on the fly
+    media_type = "video" if filename.lower().endswith(('.mp4', '.mov', '.avi', '.webm')) else "photo"
+    
+    try:
+        if media_type == "video":
+            success = generate_video_thumbnail(original_path, thumb_path)
+            if not success:
+                # If generation fails, just fallback to original
+                return FileResponse(original_path)
+        else:
+            with Image.open(original_path) as img:
+                # Convert to RGB if needed (e.g. RGBA png)
+                if img.mode in ("RGBA", "P"):
+                    img = img.convert("RGB")
+                img.thumbnail((300, 300))
+                img.save(thumb_path, "JPEG", quality=70)
+                
+        return FileResponse(thumb_path)
+    except Exception as e:
+        print(f"Thumbnail generation error: {e}")
+        # Fallback to original
+        return FileResponse(original_path)
+
+@app.delete("/photos/delete/{file_path:path}")
+async def delete_photo(file_path: str, username: str = Depends(verify_jwt_token)):
+    clean_path = os.path.normpath(file_path)
+    if clean_path.startswith("..") or os.path.isabs(clean_path):
+        raise HTTPException(status_code=400, detail="Invalid path")
+        
+    user_dir = get_user_dir(username)
+    full_path = os.path.join(user_dir, clean_path)
+    if os.path.exists(full_path):
+        os.remove(full_path)
+        return {"message": "Deleted successfully"}
+    else:
+        raise HTTPException(status_code=404, detail="File not found")
+
+# --- WEB DASHBOARD ENDPOINTS ---
+
+@app.get("/web", response_class=HTMLResponse)
+async def serve_web_dashboard():
+    # Return the web dashboard HTML file
+    # Ensure it exists in the root of the backend folder
+    html_path = os.path.join(os.path.dirname(__file__), "web.html")
+    if not os.path.exists(html_path):
+        raise HTTPException(status_code=404, detail="Web dashboard not found")
+    return FileResponse(html_path)
+
+@app.get("/api/web/explorer")
+async def web_explorer(path: str = "", username: str = Depends(verify_jwt_token)):
+    user_dir = get_user_dir(username)
+    
+    # Secure the path to prevent escaping user_dir
+    clean_path = os.path.normpath(path)
+    if clean_path.startswith("..") or os.path.isabs(clean_path):
+        raise HTTPException(status_code=400, detail="Invalid path")
+        
+    target_dir = os.path.join(user_dir, clean_path)
+    if not os.path.exists(target_dir):
+        return {"items": [], "path": clean_path}
+        
+    items = []
+    if os.path.isdir(target_dir):
+        for item in os.listdir(target_dir):
+            # Skip hidden and thumbnails folder if in root of user_dir
+            if item.startswith('.') or item == "thumbnails":
+                continue
+            item_path = os.path.join(target_dir, item)
+            is_dir = os.path.isdir(item_path)
+            stat = os.stat(item_path)
+            items.append({
+                "name": item,
+                "is_dir": is_dir,
+                "size": stat.st_size if not is_dir else 0,
+                "modified": int(stat.st_mtime * 1000)
+            })
+            
+    # Sort: folders first, then files alphabetically
+    items.sort(key=lambda x: (not x["is_dir"], x["name"].lower()))
+    return {"items": items, "path": clean_path}
+
+@app.get("/api/web/download")
+async def web_download(path: str, username: str = Depends(verify_jwt_token)):
+    user_dir = get_user_dir(username)
+    clean_path = os.path.normpath(path)
+    if clean_path.startswith("..") or os.path.isabs(clean_path):
+        raise HTTPException(status_code=400, detail="Invalid path")
+        
+    target_path = os.path.join(user_dir, clean_path)
+    if not os.path.exists(target_path):
+        raise HTTPException(status_code=404, detail="Not found")
+        
+    if os.path.isfile(target_path):
+        return FileResponse(target_path, filename=os.path.basename(target_path))
+    else:
+        # Create a ZIP in a temporary file and return it
+        fd, temp_zip_path = tempfile.mkstemp(suffix=".zip")
+        os.close(fd) # Close file descriptor, shutil will handle it
+        
+        # shutil.make_archive adds .zip automatically, so we pass path without .zip
+        base_name = temp_zip_path[:-4]
+        shutil.make_archive(base_name, 'zip', target_path)
+        
+        # Send the file and clean it up after using a background task natively in FastAPI?
+        # A simpler way is to just return it. It might leave temp files, but works.
+        # For production, we'd use BackgroundTasks to delete it. Let's do that.
+        from fastapi import BackgroundTasks
+        return FileResponse(temp_zip_path, filename=f"{os.path.basename(clean_path) or 'archive'}.zip")

keystone-backend/web.html

@@ -0,0 +1,517 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>KeyStone Web Dashboard</title>
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
+    <link href="https://fonts.googleapis.com/icon?family=Material+Icons+Round" rel="stylesheet">
+    <style>
+        :root {
+            --bg-color: #0f1115;
+            --glass-bg: rgba(25, 28, 36, 0.6);
+            --glass-border: rgba(255, 255, 255, 0.08);
+            --text-primary: #ffffff;
+            --text-secondary: #94a3b8;
+            --accent: #3b82f6;
+            --accent-hover: #2563eb;
+            --danger: #ef4444;
+            --danger-hover: #dc2626;
+        }
+
+        * {
+            box-sizing: border-box;
+            margin: 0;
+            padding: 0;
+        }
+
+        body {
+            font-family: 'Inter', sans-serif;
+            background-color: var(--bg-color);
+            color: var(--text-primary);
+            min-height: 100vh;
+            display: flex;
+            flex-direction: column;
+            background-image: 
+                radial-gradient(circle at 15% 50%, rgba(59, 130, 246, 0.15), transparent 25%),
+                radial-gradient(circle at 85% 30%, rgba(139, 92, 246, 0.15), transparent 25%);
+            background-attachment: fixed;
+        }
+
+        .glass-panel {
+            background: var(--glass-bg);
+            backdrop-filter: blur(16px);
+            -webkit-backdrop-filter: blur(16px);
+            border: 1px solid var(--glass-border);
+            border-radius: 16px;
+            box-shadow: 0 4px 30px rgba(0, 0, 0, 0.1);
+        }
+
+        /* Login Screen */
+        #login-container {
+            display: flex;
+            justify-content: center;
+            align-items: center;
+            height: 100vh;
+        }
+
+        .login-box {
+            padding: 40px;
+            width: 100%;
+            max-width: 400px;
+            text-align: center;
+        }
+
+        .login-box h1 {
+            font-size: 24px;
+            font-weight: 600;
+            margin-bottom: 8px;
+            background: linear-gradient(to right, #60a5fa, #a78bfa);
+            -webkit-background-clip: text;
+            -webkit-text-fill-color: transparent;
+        }
+
+        .login-box p {
+            color: var(--text-secondary);
+            margin-bottom: 32px;
+            font-size: 14px;
+        }
+
+        input {
+            width: 100%;
+            padding: 12px 16px;
+            margin-bottom: 16px;
+            background: rgba(0, 0, 0, 0.2);
+            border: 1px solid var(--glass-border);
+            border-radius: 8px;
+            color: white;
+            font-family: 'Inter', sans-serif;
+            font-size: 14px;
+            transition: all 0.2s;
+        }
+
+        input:focus {
+            outline: none;
+            border-color: var(--accent);
+            background: rgba(0, 0, 0, 0.4);
+        }
+
+        button {
+            width: 100%;
+            padding: 12px;
+            background: var(--accent);
+            color: white;
+            border: none;
+            border-radius: 8px;
+            font-weight: 600;
+            font-size: 14px;
+            cursor: pointer;
+            transition: background 0.2s, transform 0.1s;
+            font-family: 'Inter', sans-serif;
+        }
+
+        button:hover {
+            background: var(--accent-hover);
+        }
+
+        button:active {
+            transform: scale(0.98);
+        }
+
+        /* Dashboard */
+        #dashboard-container {
+            display: none;
+            padding: 32px;
+            max-width: 1200px;
+            margin: 0 auto;
+            width: 100%;
+        }
+
+        .header {
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            margin-bottom: 32px;
+        }
+
+        .header h1 {
+            font-size: 20px;
+            display: flex;
+            align-items: center;
+            gap: 8px;
+        }
+
+        .logout-btn {
+            background: rgba(255, 255, 255, 0.1);
+            width: auto;
+            padding: 8px 16px;
+        }
+
+        .logout-btn:hover {
+            background: rgba(239, 68, 68, 0.2);
+            color: var(--danger);
+        }
+
+        .explorer-header {
+            display: flex;
+            align-items: center;
+            padding: 16px 24px;
+            border-bottom: 1px solid var(--glass-border);
+            gap: 12px;
+        }
+
+        .breadcrumbs {
+            display: flex;
+            align-items: center;
+            gap: 8px;
+            flex: 1;
+            overflow-x: auto;
+            white-space: nowrap;
+        }
+
+        .crumb {
+            color: var(--text-secondary);
+            cursor: pointer;
+            transition: color 0.2s;
+            font-weight: 500;
+        }
+
+        .crumb:hover {
+            color: var(--accent);
+        }
+
+        .crumb.active {
+            color: var(--text-primary);
+            cursor: default;
+        }
+
+        .separator {
+            color: var(--glass-border);
+        }
+
+        .file-list {
+            padding: 8px;
+            min-height: 400px;
+        }
+
+        .file-item {
+            display: flex;
+            align-items: center;
+            padding: 12px 16px;
+            border-radius: 8px;
+            cursor: pointer;
+            transition: background 0.2s;
+            gap: 16px;
+        }
+
+        .file-item:hover {
+            background: rgba(255, 255, 255, 0.05);
+        }
+
+        .file-icon {
+            color: var(--text-secondary);
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            width: 40px;
+            height: 40px;
+            background: rgba(0, 0, 0, 0.2);
+            border-radius: 8px;
+        }
+        
+        .file-item:hover .file-icon {
+            color: var(--accent);
+        }
+
+        .file-name {
+            flex: 1;
+            font-weight: 500;
+            overflow: hidden;
+            text-overflow: ellipsis;
+            white-space: nowrap;
+        }
+
+        .file-meta {
+            color: var(--text-secondary);
+            font-size: 13px;
+            width: 120px;
+            text-align: right;
+        }
+
+        .download-btn {
+            background: transparent;
+            width: 36px;
+            height: 36px;
+            padding: 0;
+            border-radius: 50%;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            color: var(--text-secondary);
+        }
+
+        .download-btn:hover {
+            background: rgba(59, 130, 246, 0.2);
+            color: var(--accent);
+        }
+        
+        .empty-state {
+            display: flex;
+            flex-direction: column;
+            align-items: center;
+            justify-content: center;
+            height: 300px;
+            color: var(--text-secondary);
+            gap: 16px;
+        }
+
+        #error-msg {
+            color: var(--danger);
+            font-size: 13px;
+            margin-bottom: 16px;
+            display: none;
+        }
+
+        /* Loading overlay */
+        #loader {
+            position: fixed;
+            top: 0; left: 0; right: 0; bottom: 0;
+            background: rgba(15, 17, 21, 0.8);
+            display: none;
+            justify-content: center;
+            align-items: center;
+            z-index: 100;
+            backdrop-filter: blur(4px);
+        }
+
+        .spinner {
+            width: 40px;
+            height: 40px;
+            border: 3px solid rgba(255,255,255,0.1);
+            border-radius: 50%;
+            border-top-color: var(--accent);
+            animation: spin 1s ease-in-out infinite;
+        }
+
+        @keyframes spin {
+            to { transform: rotate(360deg); }
+        }
+    </style>
+</head>
+<body>
+
+    <div id="loader"><div class="spinner"></div></div>
+
+    <!-- Login Container -->
+    <div id="login-container">
+        <div class="glass-panel login-box">
+            <h1>KeyStone</h1>
+            <p>Secure Cloud Dashboard</p>
+            <div id="error-msg">Invalid credentials</div>
+            <form id="login-form">
+                <input type="text" id="username" placeholder="Username" required autocomplete="username">
+                <input type="password" id="password" placeholder="Password" required autocomplete="current-password">
+                <button type="submit">Sign In</button>
+            </form>
+        </div>
+    </div>
+
+    <!-- Dashboard Container -->
+    <div id="dashboard-container">
+        <div class="header">
+            <h1><span class="material-icons-round" style="color: var(--accent);">cloud_done</span> KeyStone Dashboard</h1>
+            <button class="logout-btn" onclick="logout()">Logout</button>
+        </div>
+
+        <div class="glass-panel">
+            <div class="explorer-header">
+                <button class="download-btn" onclick="goUp()" title="Go Up" id="btn-up" style="display: none;">
+                    <span class="material-icons-round">arrow_upward</span>
+                </button>
+                <div class="breadcrumbs" id="breadcrumbs">
+                    <!-- Rendered via JS -->
+                </div>
+                <button class="download-btn" onclick="downloadCurrentFolder()" title="Download Folder as ZIP" style="width: auto; padding: 0 16px; border-radius: 8px;">
+                    <span class="material-icons-round">file_download</span> <span style="font-size: 13px; margin-left: 6px;">ZIP</span>
+                </button>
+            </div>
+            
+            <div class="file-list" id="file-list">
+                <!-- Rendered via JS -->
+            </div>
+        </div>
+    </div>
+
+    <script>
+        const API_BASE = '';
+        let currentPath = '';
+
+        // UI Helpers
+        const showLoader = () => document.getElementById('loader').style.display = 'flex';
+        const hideLoader = () => document.getElementById('loader').style.display = 'none';
+
+        // Auth Flow
+        const checkAuth = () => {
+            const token = localStorage.getItem('token');
+            if (token) {
+                document.getElementById('login-container').style.display = 'none';
+                document.getElementById('dashboard-container').style.display = 'block';
+                loadPath('');
+            } else {
+                document.getElementById('login-container').style.display = 'flex';
+                document.getElementById('dashboard-container').style.display = 'none';
+            }
+        };
+
+        document.getElementById('login-form').addEventListener('submit', async (e) => {
+            e.preventDefault();
+            const u = document.getElementById('username').value;
+            const p = document.getElementById('password').value;
+            
+            showLoader();
+            try {
+                const res = await fetch(`${API_BASE}/auth/login`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ username: u, password: p })
+                });
+                if (!res.ok) throw new Error('Invalid credentials');
+                const data = await res.json();
+                localStorage.setItem('token', data.token);
+                document.getElementById('error-msg').style.display = 'none';
+                checkAuth();
+            } catch (err) {
+                const errEl = document.getElementById('error-msg');
+                errEl.innerText = err.message;
+                errEl.style.display = 'block';
+            } finally {
+                hideLoader();
+            }
+        });
+
+        const logout = () => {
+            localStorage.removeItem('token');
+            checkAuth();
+        };
+
+        // Formatters
+        const formatSize = (bytes) => {
+            if (bytes === 0) return '--';
+            const k = 1024;
+            const sizes = ['B', 'KB', 'MB', 'GB'];
+            const i = Math.floor(Math.log(bytes) / Math.log(k));
+            return parseFloat((bytes / Math.pow(k, i)).toFixed(1)) + ' ' + sizes[i];
+        };
+
+        const formatDate = (ms) => {
+            if (!ms) return '--';
+            return new Date(ms).toLocaleDateString(undefined, { year: 'numeric', month: 'short', day: 'numeric' });
+        };
+
+        // Explorer Logic
+        const loadPath = async (path) => {
+            showLoader();
+            const token = localStorage.getItem('token');
+            try {
+                const res = await fetch(`${API_BASE}/api/web/explorer?path=${encodeURIComponent(path)}&token=${token}`);
+                
+                if (res.status === 401 || res.status === 403) {
+                    logout();
+                    return;
+                }
+                
+                const data = await res.json();
+                currentPath = data.path || '';
+                renderBreadcrumbs();
+                renderFiles(data.items);
+            } catch (e) {
+                console.error(e);
+                alert("Failed to load directory.");
+            } finally {
+                hideLoader();
+            }
+        };
+
+        const goUp = () => {
+            if (!currentPath) return;
+            const parts = currentPath.split('/');
+            parts.pop();
+            loadPath(parts.join('/'));
+        };
+
+        const navigateTo = (folder) => {
+            const newPath = currentPath ? `${currentPath}/${folder}` : folder;
+            loadPath(newPath);
+        };
+
+        const downloadCurrentFolder = () => {
+            triggerDownload(currentPath);
+        };
+
+        const triggerDownload = (itemPath) => {
+            const token = localStorage.getItem('token');
+            // We must pass token in URL since we are opening it in a new tab
+            const url = `${API_BASE}/api/web/download?path=${encodeURIComponent(itemPath)}&token=${token}`;
+            window.open(url, '_blank');
+        };
+
+        const renderBreadcrumbs = () => {
+            const container = document.getElementById('breadcrumbs');
+            const parts = currentPath.split('/').filter(Boolean);
+            
+            document.getElementById('btn-up').style.display = parts.length > 0 ? 'flex' : 'none';
+
+            let html = `<div class="crumb ${parts.length === 0 ? 'active' : ''}" onclick="loadPath('')">Home</div>`;
+            
+            let accPath = "";
+            parts.forEach((p, i) => {
+                accPath += (accPath ? "/" : "") + p;
+                html += `<span class="separator">/</span>`;
+                if (i === parts.length - 1) {
+                    html += `<div class="crumb active">${p}</div>`;
+                } else {
+                    html += `<div class="crumb" onclick="loadPath('${accPath}')">${p}</div>`;
+                }
+            });
+            container.innerHTML = html;
+        };
+
+        const renderFiles = (items) => {
+            const container = document.getElementById('file-list');
+            if (items.length === 0) {
+                container.innerHTML = `
+                    <div class="empty-state">
+                        <span class="material-icons-round" style="font-size: 48px; opacity: 0.5;">folder_open</span>
+                        <p>This folder is empty</p>
+                    </div>
+                `;
+                return;
+            }
+
+            let html = '';
+            items.forEach(item => {
+                const icon = item.is_dir ? 'folder' : (item.name.match(/\.(mp4|mov)$/i) ? 'movie' : 'image');
+                const fullPath = currentPath ? `${currentPath}/${item.name}` : item.name;
+                
+                html += `
+                    <div class="file-item" onclick="${item.is_dir ? `navigateTo('${item.name}')` : `triggerDownload('${fullPath}')`}">
+                        <div class="file-icon">
+                            <span class="material-icons-round">${icon}</span>
+                        </div>
+                        <div class="file-name">${item.name}</div>
+                        <div class="file-meta">${formatDate(item.modified)}</div>
+                        <div class="file-meta">${formatSize(item.size)}</div>
+                        <button class="download-btn" onclick="event.stopPropagation(); triggerDownload('${fullPath}')" title="Download">
+                            <span class="material-icons-round">download</span>
+                        </button>
+                    </div>
+                `;
+            });
+            container.innerHTML = html;
+        };
+
+        // Initialize
+        checkAuth();
+    </script>
+</body>
+</html>