fix(security): authenticate shutdown endpoints with a per-session token

The /shutdown endpoints on both the backend (port 52123) and sync
microservice (port 52124) were unauthenticated, allowing any local
process to send a POST request and terminate PictoPy without user
interaction.

Fix:
- Generate a cryptographically random 256-bit token (secrets.token_hex)
  on every backend startup and write it to a temporary file
  (pictopy_shutdown.token in the OS temp directory).
- Both shutdown endpoints now require an X-Shutdown-Token header whose
  value is compared against the session token using hmac.compare_digest
  to prevent timing-based attacks. Requests with a missing or incorrect
  token receive 403 Forbidden.
- The sync microservice reads the same token file written by the backend,
  so both services share one token without additional coordination.
- The Tauri frontend (Windows path) is updated to read the token file at
  shutdown time and attach it as an X-Shutdown-Token header, preserving
  the existing Windows close behaviour.

Closes #1241

Author: Dotify71

backend/app/config/settings.py

@@ -1,5 +1,7 @@
 import os
 import sys
+import secrets
+import tempfile
 
 from platformdirs import user_data_dir
 
@@ -35,3 +37,17 @@
     DATABASE_PATH = os.path.join(user_data_dir("PictoPy"), "database", "PictoPy.db")
 THUMBNAIL_IMAGES_PATH = os.path.join(user_data_dir("PictoPy"), "thumbnails")
 IMAGES_PATH = "./images"
+
+# Generate a fresh cryptographic token on every backend startup.
+# This token is written to a temporary file so that only the local Tauri
+# frontend — which reads the same file — can authenticate shutdown requests.
+# Any other process on the machine will not know the token and will be
+# rejected with 403 Forbidden.
+SHUTDOWN_TOKEN: str = secrets.token_hex(32)
+SHUTDOWN_TOKEN_FILE: str = os.path.join(tempfile.gettempdir(), "pictopy_shutdown.token")
+
+# Write with owner-only permissions (0o600) so other local users on
+# multi-user systems cannot read the token and trigger a shutdown.
+_fd = os.open(SHUTDOWN_TOKEN_FILE, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+with os.fdopen(_fd, "w") as _f:
+    _f.write(SHUTDOWN_TOKEN)

backend/app/routes/shutdown.py

@@ -1,9 +1,11 @@
 import asyncio
+import hmac
 import os
 import platform
 import signal
-from fastapi import APIRouter
+from fastapi import APIRouter, Header, HTTPException
 from pydantic import BaseModel
+from app.config.settings import SHUTDOWN_TOKEN
 from app.logging.setup_logging import get_logger
 
 logger = get_logger(__name__)
@@ -37,16 +39,23 @@ async def _delayed_shutdown(delay: float = 0.5):
 
 
 @router.post("/shutdown", response_model=ShutdownResponse)
-async def shutdown():
+async def shutdown(x_shutdown_token: str = Header(...)):
     """
     Gracefully shutdown the PictoPy backend.
 
-    This endpoint schedules backend server termination after response is sent.
-    The frontend is responsible for shutting down the sync service separately.
+    This endpoint requires the ``X-Shutdown-Token`` header to match the token
+    generated at startup.  The token is shared with the Tauri frontend via a
+    temporary file, so only the PictoPy application itself can trigger this
+    endpoint — arbitrary local processes are rejected with 403 Forbidden.
 
     Returns:
         ShutdownResponse with status and message
     """
+    # Use constant-time comparison to prevent timing-based token guessing
+    if not hmac.compare_digest(x_shutdown_token, SHUTDOWN_TOKEN):
+        logger.warning("Shutdown attempt rejected: invalid token")
+        raise HTTPException(status_code=403, detail="Forbidden")
+
     logger.info("Shutdown request received for PictoPy backend")
 
     # Define callback to handle potential exceptions in the background task

frontend/src-tauri/src/main.rs

@@ -61,11 +61,41 @@ fn kill_process(process: &sysinfo::Process) {
 #[cfg(windows)]
 pub fn kill_process(_process: &sysinfo::Process) -> Result<(), String> {
     use reqwest::blocking::Client;
+    use reqwest::header::{HeaderMap, HeaderName, HeaderValue};
+    use std::str::FromStr;
+
+    // Read the per-session shutdown token written by the backend at startup.
+    // This guarantees that only the PictoPy frontend — which runs alongside
+    // the backend — can authenticate the shutdown request.
+    let token_path = std::env::temp_dir().join("pictopy_shutdown.token");
+    let token = match std::fs::read_to_string(&token_path) {
+        Ok(t) => {
+            let trimmed = t.trim().to_string();
+            if trimmed.is_empty() {
+                eprintln!("[PictoPy] Warning: shutdown token file is empty — shutdown request will be rejected by the backend.");
+            }
+            trimmed
+        }
+        Err(e) => {
+            eprintln!("[PictoPy] Warning: could not read shutdown token file ({token_path:?}): {e} — shutdown request will be rejected by the backend.");
+            String::new()
+        }
+    };
+
+    let mut headers = HeaderMap::new();
+    if !token.is_empty() {
+        if let (Ok(name), Ok(value)) = (
+            HeaderName::from_str("x-shutdown-token"),
+            HeaderValue::from_str(&token),
+        ) {
+            headers.insert(name, value);
+        }
+    }
 
     let client = Client::builder().build().map_err(|e| e.to_string())?;
 
     for (name, url, _) in &ENDPOINTS {
-        match client.post(*url).send() {
+        match client.post(*url).headers(headers.clone()).send() {
             Ok(resp) => {
                 let status = resp.status();
 

sync-microservice/app/config/settings.py

@@ -1,5 +1,10 @@
-from platformdirs import user_data_dir
 import os
+import secrets
+import tempfile
+import time as _time
+import warnings
+
+from platformdirs import user_data_dir
 
 # Model Exports Path
 MODEL_EXPORTS_PATH = "app/models/ONNX_Exports"
@@ -28,3 +33,35 @@
     DATABASE_PATH = os.path.join(user_data_dir("PictoPy"), "database", "PictoPy.db")
 THUMBNAIL_IMAGES_PATH = "./images/thumbnails"
 IMAGES_PATH = "./images"
+
+# The backend writes a fresh cryptographic token to this temp file on every
+# startup.  The sync microservice reads the same file so both services share
+# a single token without any additional coordination.
+SHUTDOWN_TOKEN_FILE: str = os.path.join(tempfile.gettempdir(), "pictopy_shutdown.token")
+
+# Retry for up to 5 seconds to handle the race where the sync microservice
+# starts before the backend has had a chance to write the token file.
+_deadline = _time.monotonic() + 5.0
+SHUTDOWN_TOKEN: str = ""
+while _time.monotonic() < _deadline:
+    try:
+        with open(SHUTDOWN_TOKEN_FILE) as _f:
+            _token = _f.read().strip()
+        if _token:
+            SHUTDOWN_TOKEN = _token
+            break
+    except FileNotFoundError:
+        pass
+    _time.sleep(0.1)
+
+if not SHUTDOWN_TOKEN:
+    # Backend token unavailable after timeout — generate a fallback so the
+    # service can still start, but log a clear warning so the issue is visible.
+    SHUTDOWN_TOKEN = secrets.token_hex(32)
+    warnings.warn(
+        "pictopy_shutdown.token not found after 5 s; using an independent "
+        "shutdown token. The sync /shutdown endpoint may reject requests from "
+        "the Tauri frontend. Ensure the backend starts before the sync service.",
+        RuntimeWarning,
+        stacklevel=1,
+    )

sync-microservice/app/routes/shutdown.py

@@ -1,9 +1,11 @@
 import asyncio
+import hmac
 import os
 import platform
 import signal
-from fastapi import APIRouter
+from fastapi import APIRouter, Header, HTTPException
 from pydantic import BaseModel
+from app.config.settings import SHUTDOWN_TOKEN
 from app.utils.watcher import watcher_util_stop_folder_watcher
 from app.logging.setup_logging import get_sync_logger
 
@@ -38,18 +40,29 @@ async def _delayed_shutdown(delay: float = 0.1):
 
 
 @router.post("/shutdown", response_model=ShutdownResponse)
-async def shutdown():
+async def shutdown(x_shutdown_token: str = Header(...)):
     """
     Gracefully shutdown the sync microservice.
 
+    This endpoint requires the ``X-Shutdown-Token`` header to match the token
+    generated by the backend at startup.  The token is shared between services
+    via a temporary file, so only the PictoPy application itself can trigger
+    shutdown — arbitrary local processes are rejected with 403 Forbidden.
+
     This endpoint:
-    1. Stops the folder watcher
-    2. Schedules server termination after response is sent
-    3. Returns confirmation to the caller
+    1. Validates the shutdown token
+    2. Stops the folder watcher
+    3. Schedules server termination after response is sent
+    4. Returns confirmation to the caller
 
     Returns:
         ShutdownResponse with status and message
     """
+    # Use constant-time comparison to prevent timing-based token guessing
+    if not hmac.compare_digest(x_shutdown_token, SHUTDOWN_TOKEN):
+        logger.warning("Shutdown attempt rejected: invalid token")
+        raise HTTPException(status_code=403, detail="Forbidden")
+
     logger.info("Shutdown request received for sync microservice")
 
     try: