From 58eec1ce0fa6bbf0b235534f8f0f80754c4059dc Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Thu, 25 Jun 2026 19:55:51 +0530
Subject: [PATCH 01/44] deps: add platform-specific dependencies for OS service
 management

Add libc (unix) for effective-uid check in the service elevation guard,
and windows-service for native Service Control Manager integration.
---
 Cargo.lock              | 19 +++++++++++++++++++
 apps/backend/Cargo.toml |  8 ++++++++
 2 files changed, 27 insertions(+)

diff --git a/Cargo.lock b/Cargo.lock
index ac72d5f2..08729ca6 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -808,6 +808,7 @@ dependencies = [
  "http-body-util",
  "image",
  "json-patch",
+ "libc",
  "mime_guess",
  "object_store",
  "prost",
@@ -846,6 +847,7 @@ dependencies = [
  "utoipa",
  "utoipa-scalar",
  "uuid",
+ "windows-service",
  "wiremock",
  "zstd",
 ]
@@ -5475,6 +5477,12 @@ version = "2.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "998767ef88740d1f5b0682a9c53c24431453923962269c2db68ee43788c5a40d"
 
+[[package]]
+name = "widestring"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72069c3113ab32ab29e5584db3c6ec55d416895e60715417b5b883a357c3e471"
+
 [[package]]
 name = "winapi"
 version = "0.3.9"
@@ -5567,6 +5575,17 @@ dependencies = [
  "windows-link",
 ]
 
+[[package]]
+name = "windows-service"
+version = "0.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d24d6bcc7f734a4091ecf8d7a64c5f7d7066f45585c1861eba06449909609c8a"
+dependencies = [
+ "bitflags",
+ "widestring",
+ "windows-sys 0.52.0",
+]
+
 [[package]]
 name = "windows-strings"
 version = "0.5.1"
diff --git a/apps/backend/Cargo.toml b/apps/backend/Cargo.toml
index 137c47a0..a25c2f99 100644
--- a/apps/backend/Cargo.toml
+++ b/apps/backend/Cargo.toml
@@ -77,6 +77,14 @@ tar = "0.4"
 croner = "3"
 tantivy = "0.26"
 
+# Unix: effective-uid check for the `service` elevation guard.
+[target.'cfg(unix)'.dependencies]
+libc = "0.2"
+
+# Windows: native Service Control Manager integration for `vcms service`.
+[target.'cfg(windows)'.dependencies]
+windows-service = "0.7"
+
 [build-dependencies]
 tonic-build = "0.14"
 tonic-prost-build = "0.14"

From 8366b60b49e6051ccbed8983067efdb5866f08a0 Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Thu, 25 Jun 2026 19:56:03 +0530
Subject: [PATCH 02/44] refactor(grpc): add shutdown future parameter for
 graceful drain

Accept an injected shutdown future in start_grpc_server and
spawn_grpc_server, switching from serve() to serve_with_shutdown().
This enables the server bootstrap to be shared between the foreground
serve command and OS service runners that provide their own shutdown
trigger (e.g. Windows SCM stop control).
---
 apps/backend/src/grpc/server.rs | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/apps/backend/src/grpc/server.rs b/apps/backend/src/grpc/server.rs
index 87a26ba7..88ff63bb 100644
--- a/apps/backend/src/grpc/server.rs
+++ b/apps/backend/src/grpc/server.rs
@@ -26,6 +26,7 @@ pub async fn start_grpc_server(
     config: Arc<Config>,
     storage_registry: Arc<StorageRegistry>,
     grpc_addr: SocketAddr,
+    shutdown: impl Future<Output = ()> + Send + 'static,
 ) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
     let collection_svc = CollectionServiceImpl::new(services.collection.clone(), repository.clone());
     let entry_svc = EntryServiceImpl::new(services.entry.clone(), repository.clone());
@@ -90,7 +91,7 @@ pub async fn start_grpc_server(
         .add_service(file_svc)
         .add_service(site_svc)
         .add_service(webhook_svc)
-        .serve(grpc_addr)
+        .serve_with_shutdown(grpc_addr, shutdown)
         .await?;
 
     Ok(())
@@ -102,6 +103,7 @@ pub fn spawn_grpc_server(
     config: Arc<Config>,
     storage_registry: Arc<StorageRegistry>,
     grpc_addr: SocketAddr,
+    shutdown: Pin<Box<dyn Future<Output = ()> + Send>>,
 ) -> GrpcServerFuture {
     Box::pin(start_grpc_server(
         services,
@@ -109,5 +111,6 @@ pub fn spawn_grpc_server(
         config,
         storage_registry,
         grpc_addr,
+        shutdown,
     ))
 }

From 12cc20c3f42b7c9cd00ab6509c32273cfb8ad6c2 Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Thu, 25 Jun 2026 19:56:17 +0530
Subject: [PATCH 03/44] refactor: extract server bootstrap into reusable server
 module

Move the full startup sequence (home dir, secrets, config, migrations,
REST + gRPC servers, search indexer, backup scheduler) from main.rs
into a new server module with a run() function that accepts an injected
shutdown future. This allows both the foreground serve command and OS
service runners (systemd, launchd, Windows SCM) to share the exact
same bootstrap path.

Also loads .env from /.env in addition to cwd, so installed
services and mcp stdio (which run from an arbitrary cwd) pick up
persisted secrets. The home .env is second-wins so real env vars and
the cwd file keep precedence.
---
 apps/backend/src/lib.rs    |   2 +
 apps/backend/src/main.rs   | 260 +++-----------------------------
 apps/backend/src/server.rs | 299 +++++++++++++++++++++++++++++++++++++
 3 files changed, 321 insertions(+), 240 deletions(-)
 create mode 100644 apps/backend/src/server.rs

diff --git a/apps/backend/src/lib.rs b/apps/backend/src/lib.rs
index c795463d..cbce407a 100644
--- a/apps/backend/src/lib.rs
+++ b/apps/backend/src/lib.rs
@@ -8,6 +8,8 @@ pub mod graphql;
 pub mod mcp;
 pub mod paths;
 pub mod secrets;
+pub mod server;
+pub mod service;
 pub mod signed_upload;
 pub mod test_helpers;
 pub mod tracing;
diff --git a/apps/backend/src/main.rs b/apps/backend/src/main.rs
index 653c364d..5d9998e8 100644
--- a/apps/backend/src/main.rs
+++ b/apps/backend/src/main.rs
@@ -2,21 +2,31 @@ use clap::Parser;
 use cms::cli::{AdminAction, BackupAction, Cli, Command, ConfigAction, McpTransport};
 use cms::config::{self, Config};
 use cms::database::{connect_db_without_migrations, init_db_with_config};
-use cms::grpc::server::spawn_grpc_server;
 use cms::middleware::auth::Actor;
 use cms::repository::Repository;
-use cms::router::create_router;
 use cms::services::Services;
-use cms::storage::{self, STORAGE_KIND_FILESYSTEM, STORAGE_KIND_S3, StorageRegistry};
 
 use std::error::Error;
-use std::net::SocketAddr;
 use std::sync::Arc;
-use tracing::{debug, info, warn};
+use tracing::{debug, info};
 
 #[tokio::main]
 async fn main() {
+    // Load env from the cwd `.env` (dev) first, then `$VCMS_HOME/.env` (installed
+    // services + `mcp stdio`, which run from an arbitrary cwd). dotenvy is
+    // first-wins, so real env vars and the cwd file keep precedence over the home
+    // file. VCMS_HOME must be a real env var — resolved here before the home `.env`
+    // loads — never set inside that file (chicken-and-egg).
     dotenvy::dotenv().ok();
+    let home_env = cms::paths::home().join(".env");
+    match dotenvy::from_path(&home_env) {
+        Ok(()) => {}
+        Err(e) if e.not_found() => {} // missing file is fine
+        Err(e) => {
+            eprintln!("Error: cannot load {}: {e}", home_env.display());
+            std::process::exit(1);
+        }
+    }
 
     let cli = Cli::parse();
 
@@ -31,10 +41,11 @@ async fn main() {
             import_as_new,
             yes,
         }) => run_restore(file, scope, site, *import_as_new, *yes, &cli).await,
+        Some(Command::Service { action }) => cms::service::run_service(action, &cli).await,
         Some(Command::Mcp {
             transport: McpTransport::Stdio,
         }) => run_mcp_stdio(&cli).await,
-        Some(Command::Serve) | None => run_serve(&cli).await,
+        Some(Command::Serve) | None => cms::server::run(&cli, cms::server::shutdown_signal()).await,
     };
 
     if let Err(e) = result {
@@ -43,128 +54,6 @@ async fn main() {
     }
 }
 
-async fn run_serve(cli: &Cli) -> Result<(), Box<dyn Error>> {
-    cms::paths::ensure()?;
-    cms::secrets::ensure()?;
-    let config = Config::load(cli)?;
-
-    let _guard = cms::tracing::init_tracing(&config);
-
-    if let Err(e) = config.validate_security() {
-        return Err(format!("Invalid production security configuration: {e}").into());
-    }
-
-    let pool = init_db_with_config(&config).await?;
-
-    let repository = Repository::new(&pool);
-
-    seed_admin(&repository).await;
-
-    let storage_registry = initialize_storage(&config);
-    // Build these once and share them: the REST router and the gRPC server use the
-    // same `Services` so the single-writer search index is opened only once.
-    let repository_arc = Arc::new(repository.clone());
-    let config_arc = Arc::new(config.clone());
-    let services = Services::new(repository_arc.clone(), &pool, &config);
-
-    let backup_destination = cms::services::backup::build_backup_destination(&config)
-        .map_err(|e| format!("Failed to initialize backup destination: {e}"))?;
-    let backup_service = Arc::new(cms::services::backup::BackupService::new(
-        pool.clone(),
-        storage_registry.clone(),
-        backup_destination,
-        &config,
-    ));
-
-    let app = create_router(
-        repository.clone(),
-        config.clone(),
-        storage_registry.clone(),
-        services.clone(),
-        backup_service.clone(),
-    );
-
-    // Reconcile backups/restore jobs left mid-flight by a previous process: any
-    // running/pending row at startup is orphaned (backups only run in-process).
-    match cms::services::backup::meta::fail_orphaned(&pool, &cms::services::backup::now_iso()).await {
-        Ok(n) if n > 0 => info!("Reconciled {n} interrupted backup job(s) to failed"),
-        Ok(_) => {}
-        Err(e) => tracing::error!("Failed to reconcile interrupted backups: {e}"),
-    }
-
-    if config.backup_enabled {
-        let scheduler_service = backup_service.clone();
-        tokio::spawn(async move {
-            cms::services::backup::scheduler::run(scheduler_service).await;
-        });
-        info!("Backup scheduler started");
-    }
-
-    // The search indexer is the single writer/consumer: it rebuilds the index when
-    // empty (first run / wiped), then drains the cross-process queue forever.
-    if let (Some(search), Some(queue)) = (services.search.clone(), services.search_queue.clone()) {
-        let repo = repository_arc.clone();
-        tokio::spawn(async move {
-            if search.is_empty() {
-                info!("Search index is empty; building from database...");
-                match search.rebuild_all(&repo).await {
-                    Ok(n) => info!("Search index built: {} entries", n),
-                    Err(e) => tracing::error!("Search index build failed: {}", e),
-                }
-            }
-            cms::services::search::indexer::run(search, queue, repo).await;
-        });
-    }
-
-    let addr: SocketAddr = config.bind_address.parse().expect("Invalid BIND_ADDRESS");
-    info!("Dashboard UI available at http://{}/dashboard", addr);
-    info!("REST API server running on http://{}", addr);
-    info!("GraphQL endpoint at http://{}/api/graphql", addr);
-    if config.mcp_enabled {
-        info!("MCP HTTP endpoint at http://{}/mcp", addr);
-    }
-
-    let grpc_addr: SocketAddr = config.grpc_bind_address.parse().expect("Invalid GRPC_BIND_ADDRESS");
-    info!("gRPC server running on {}", grpc_addr);
-
-    let rest_handle = tokio::spawn(async move {
-        let listener = tokio::net::TcpListener::bind(addr)
-            .await
-            .expect("Failed to bind address");
-
-        axum::serve(
-            listener,
-            app.into_make_service_with_connect_info::<std::net::SocketAddr>(),
-        )
-        .with_graceful_shutdown(shutdown_signal())
-        .await
-        .expect("Server error");
-    });
-
-    let grpc_handle = tokio::spawn(spawn_grpc_server(
-        services.clone(),
-        repository_arc.clone(),
-        config_arc.clone(),
-        storage_registry.clone(),
-        grpc_addr,
-    ));
-
-    tokio::select! {
-        result = rest_handle => {
-            if let Err(e) = result {
-                tracing::error!("REST server error: {}", e);
-            }
-        }
-        result = grpc_handle => {
-            if let Err(e) = result {
-                tracing::error!("gRPC server error: {}", e);
-            }
-        }
-    }
-
-    Ok(())
-}
-
 async fn run_mcp_stdio(cli: &Cli) -> Result<(), Box<dyn Error>> {
     // Read-only: never create the home dir, database, or secrets file here. The
     // persisted secrets written by `vcms serve` are what make this process verify
@@ -209,7 +98,7 @@ async fn run_mcp_stdio(cli: &Cli) -> Result<(), Box<dyn Error>> {
         Actor::User(_) => return Err("MCP stdio requires a CMS site access token".into()),
     }
 
-    let storage_registry = initialize_storage(&config);
+    let storage_registry = cms::server::initialize_storage(&config);
     let repository = Arc::new(repository);
     let config = Arc::new(config);
     // Read-only search: stdio can run alongside the server without contending for
@@ -225,51 +114,6 @@ async fn run_mcp_stdio(cli: &Cli) -> Result<(), Box<dyn Error>> {
     result
 }
 
-fn initialize_storage(config: &Config) -> Arc<StorageRegistry> {
-    let mut storage_registry = StorageRegistry::new();
-
-    // Use an explicit filesystem path if set; otherwise default to ~/.vcms/storage
-    // so uploads work out of the box — unless S3 is configured and takes over.
-    let fs_path = match (&config.storage_fs_path, config.has_s3()) {
-        (Some(path), _) => Some(path.clone()),
-        (None, false) => Some(cms::paths::storage_dir().to_string_lossy().into_owned()),
-        (None, true) => None,
-    };
-
-    if let Some(fs_path) = fs_path {
-        match storage::FileSystemStorage::new(&fs_path) {
-            Ok(fs) => {
-                storage_registry.register(STORAGE_KIND_FILESYSTEM, Arc::new(fs));
-                info!("Filesystem storage initialized at {}", fs_path);
-            }
-            Err(error) => warn!("Failed to initialize filesystem storage: {}", error),
-        }
-    }
-
-    if config.has_s3() {
-        match storage::S3Storage::new(
-            config.s3_access_key_id.as_deref().unwrap(),
-            config.s3_secret_access_key.as_deref().unwrap(),
-            config.s3_bucket.as_deref().unwrap(),
-            config.s3_region.as_deref().unwrap_or("us-east-1"),
-            config.s3_endpoint.as_deref(),
-            config.s3_public_url.as_deref(),
-        ) {
-            Ok(s3) => {
-                storage_registry.register(STORAGE_KIND_S3, Arc::new(s3));
-                info!("S3 storage initialized");
-            }
-            Err(error) => warn!("Failed to initialize S3 storage: {}", error),
-        }
-    }
-
-    if storage_registry.get(STORAGE_KIND_FILESYSTEM).is_none() && storage_registry.get(STORAGE_KIND_S3).is_none() {
-        warn!("No storage providers configured. Set STORAGE_FS_PATH or S3_* env vars.");
-    }
-
-    Arc::new(storage_registry)
-}
-
 fn run_config(action: &ConfigAction, cli: &Cli) -> Result<(), Box<dyn Error>> {
     match action {
         ConfigAction::Init { force, path } => {
@@ -337,7 +181,7 @@ async fn run_backup(action: &BackupAction, cli: &Cli) -> Result<(), Box<dyn Erro
     cms::secrets::ensure()?;
     let config = Config::load(cli)?;
     let pool = init_db_with_config(&config).await?;
-    let storage_registry = initialize_storage(&config);
+    let storage_registry = cms::server::initialize_storage(&config);
     let destination = build_backup_destination(&config)?;
     let service = BackupService::new(pool.clone(), storage_registry, destination, &config);
 
@@ -423,7 +267,7 @@ async fn run_restore(
     cms::secrets::ensure()?;
     let config = Config::load(cli)?;
     let pool = init_db_with_config(&config).await?;
-    let storage_registry = initialize_storage(&config);
+    let storage_registry = cms::server::initialize_storage(&config);
     let destination = build_backup_destination(&config)?;
     let service = BackupService::new(pool.clone(), storage_registry, destination, &config);
 
@@ -469,67 +313,3 @@ fn parse_scope(scope: &str, site: Option<&str>) -> Result<cms::services::backup:
         other => Err(format!("unknown scope '{other}' (use instance|site)").into()),
     }
 }
-
-/// Email identity of the default admin account. Login is by email, so the seed
-/// gate keys on this (non-unique display name "admin" would be the wrong column).
-const ADMIN_EMAIL: &str = "admin@cms.local";
-
-async fn seed_admin(repository: &Repository) {
-    debug!("Checking if admin user needs to be seeded");
-    if !repository.user.exists(ADMIN_EMAIL).await.unwrap_or(false) {
-        info!("Seeding default admin user");
-        let id = uuid::Uuid::now_v7().to_string();
-        let password_hash = bcrypt::hash("admin", bcrypt::DEFAULT_COST).expect("Failed to hash password");
-        repository
-            .user
-            .create(&id, "admin", ADMIN_EMAIL, &password_hash)
-            .await
-            .expect("Failed to seed admin user");
-        repository
-            .user
-            .set_instance_role(&id, Some("instance_owner"))
-            .await
-            .expect("Failed to assign instance owner");
-        repository
-            .user
-            .update_password(&id, &password_hash, true)
-            .await
-            .expect("Failed to require password change");
-
-        warn!("Seeded default admin user (admin@cms.local / admin) — CHANGE THE PASSWORD IMMEDIATELY!");
-        eprintln!(
-            "\n\
-             ============================ SECURITY WARNING ============================\n\
-             A default admin account was created:  email 'admin@cms.local'  password 'admin'\n\
-             Sign in with the email and password. Anyone who can reach this server can log\n\
-             in until you change it. Run:\n\
-             \n    vcms admin reset-password --email admin@cms.local --password <new-strong-password>\n\n\
-             or change it from the dashboard now. Do NOT expose this server until done.\n\
-             =========================================================================\n"
-        );
-    } else {
-        debug!("Admin user already exists, skipping seeding");
-    }
-}
-
-async fn shutdown_signal() {
-    let ctrl_c = async {
-        tokio::signal::ctrl_c().await.expect("failed to install Ctrl+C handler");
-    };
-
-    #[cfg(unix)]
-    let terminate = async {
-        tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate())
-            .expect("failed to install signal handler")
-            .recv()
-            .await;
-    };
-
-    #[cfg(not(unix))]
-    let terminate = std::future::pending::<()>();
-
-    tokio::select! {
-        _ = ctrl_c => info!("Received Ctrl+C, shutting down..."),
-        _ = terminate => info!("Received SIGTERM, shutting down..."),
-    }
-}
diff --git a/apps/backend/src/server.rs b/apps/backend/src/server.rs
new file mode 100644
index 00000000..cc63cea3
--- /dev/null
+++ b/apps/backend/src/server.rs
@@ -0,0 +1,299 @@
+//! Server bootstrap shared by `vcms serve` and the platform service runners.
+//!
+//! The full startup sequence (home dir, secrets, config, migrations, REST + gRPC)
+//! lives here rather than in `main.rs` so that the Windows Service Control Manager
+//! entry point — which lives in the library — can host the exact same server. The
+//! caller injects a *shutdown future*; whatever resolves it (Ctrl+C / SIGTERM on a
+//! normal run, an SCM stop control on Windows) triggers one graceful drain of both
+//! the REST and gRPC servers.
+
+use std::error::Error;
+use std::future::Future;
+use std::net::SocketAddr;
+use std::sync::Arc;
+
+use tracing::{debug, info, warn};
+
+use crate::cli::Cli;
+use crate::config::Config;
+use crate::database::init_db_with_config;
+use crate::grpc::server::spawn_grpc_server;
+use crate::repository::Repository;
+use crate::router::create_router;
+use crate::services::Services;
+use crate::storage::{self, STORAGE_KIND_FILESYSTEM, STORAGE_KIND_S3, StorageRegistry};
+
+/// Email identity of the default admin account. Login is by email, so the seed
+/// gate keys on this (non-unique display name "admin" would be the wrong column).
+const ADMIN_EMAIL: &str = "admin@cms.local";
+
+/// Boot the full server and run until `shutdown` resolves.
+///
+/// Shared by the foreground `serve` command and the OS service runners. The
+/// `shutdown` future is the single trigger that gracefully drains both the REST
+/// and gRPC listeners.
+pub async fn run(cli: &Cli, shutdown: impl Future<Output = ()> + Send + 'static) -> Result<(), Box<dyn Error>> {
+    crate::paths::ensure()?;
+    crate::secrets::ensure()?;
+    let config = Config::load(cli)?;
+
+    let _guard = crate::tracing::init_tracing(&config);
+
+    if let Err(e) = config.validate_security() {
+        return Err(format!("Invalid production security configuration: {e}").into());
+    }
+
+    let pool = init_db_with_config(&config).await?;
+
+    let repository = Repository::new(&pool);
+
+    seed_admin(&repository).await;
+
+    let storage_registry = initialize_storage(&config);
+    // Build these once and share them: the REST router and the gRPC server use the
+    // same `Services` so the single-writer search index is opened only once.
+    let repository_arc = Arc::new(repository.clone());
+    let config_arc = Arc::new(config.clone());
+    let services = Services::new(repository_arc.clone(), &pool, &config);
+
+    let backup_destination = crate::services::backup::build_backup_destination(&config)
+        .map_err(|e| format!("Failed to initialize backup destination: {e}"))?;
+    let backup_service = Arc::new(crate::services::backup::BackupService::new(
+        pool.clone(),
+        storage_registry.clone(),
+        backup_destination,
+        &config,
+    ));
+
+    let app = create_router(
+        repository.clone(),
+        config.clone(),
+        storage_registry.clone(),
+        services.clone(),
+        backup_service.clone(),
+    );
+
+    // Reconcile backups/restore jobs left mid-flight by a previous process: any
+    // running/pending row at startup is orphaned (backups only run in-process).
+    match crate::services::backup::meta::fail_orphaned(&pool, &crate::services::backup::now_iso()).await {
+        Ok(n) if n > 0 => info!("Reconciled {n} interrupted backup job(s) to failed"),
+        Ok(_) => {}
+        Err(e) => tracing::error!("Failed to reconcile interrupted backups: {e}"),
+    }
+
+    if config.backup_enabled {
+        let scheduler_service = backup_service.clone();
+        tokio::spawn(async move {
+            crate::services::backup::scheduler::run(scheduler_service).await;
+        });
+        info!("Backup scheduler started");
+    }
+
+    // The search indexer is the single writer/consumer: it rebuilds the index when
+    // empty (first run / wiped), then drains the cross-process queue forever.
+    if let (Some(search), Some(queue)) = (services.search.clone(), services.search_queue.clone()) {
+        let repo = repository_arc.clone();
+        tokio::spawn(async move {
+            if search.is_empty() {
+                info!("Search index is empty; building from database...");
+                match search.rebuild_all(&repo).await {
+                    Ok(n) => info!("Search index built: {} entries", n),
+                    Err(e) => tracing::error!("Search index build failed: {}", e),
+                }
+            }
+            crate::services::search::indexer::run(search, queue, repo).await;
+        });
+    }
+
+    let addr: SocketAddr = config
+        .bind_address
+        .parse()
+        .map_err(|e| format!("Invalid BIND_ADDRESS '{}': {e}", config.bind_address))?;
+    info!("Dashboard UI available at http://{}/dashboard", addr);
+    info!("REST API server running on http://{}", addr);
+    info!("GraphQL endpoint at http://{}/api/graphql", addr);
+    if config.mcp_enabled {
+        info!("MCP HTTP endpoint at http://{}/mcp", addr);
+    }
+
+    let grpc_addr: SocketAddr = config
+        .grpc_bind_address
+        .parse()
+        .map_err(|e| format!("Invalid GRPC_BIND_ADDRESS '{}': {e}", config.grpc_bind_address))?;
+    info!("gRPC server running on {}", grpc_addr);
+
+    // One shutdown signal fans out to both listeners via a watch channel: the
+    // injected `shutdown` future flips it, and both servers drain on the change.
+    let (shutdown_tx, shutdown_rx) = tokio::sync::watch::channel(false);
+    let shutdown_tx2 = shutdown_tx.clone();
+    tokio::spawn(async move {
+        shutdown.await;
+        let _ = shutdown_tx.send(true);
+    });
+
+    let rest_rx = shutdown_rx.clone();
+    let rest_handle = tokio::spawn(async move {
+        let listener = tokio::net::TcpListener::bind(addr).await.map_err(|e| {
+            tracing::error!("Failed to bind REST address {addr}: {e}");
+            e
+        })?;
+
+        axum::serve(
+            listener,
+            app.into_make_service_with_connect_info::<std::net::SocketAddr>(),
+        )
+        .with_graceful_shutdown(wait_for_shutdown(rest_rx))
+        .await
+        .map_err(|e| {
+            tracing::error!("REST server error: {e}");
+            e
+        })
+    });
+
+    let grpc_handle = tokio::spawn(spawn_grpc_server(
+        services.clone(),
+        repository_arc.clone(),
+        config_arc.clone(),
+        storage_registry.clone(),
+        grpc_addr,
+        Box::pin(wait_for_shutdown(shutdown_rx)),
+    ));
+
+    tokio::select! {
+        result = rest_handle => {
+            let _ = shutdown_tx2.send(true);
+            match result {
+                Ok(Ok(())) => {}
+                Ok(Err(e)) => return Err(e.into()),
+                Err(e) => return Err(e.into()),
+            }
+        }
+        result = grpc_handle => {
+            let _ = shutdown_tx2.send(true);
+            match result {
+                Ok(Ok(())) => {}
+                // gRPC's error is `Box<dyn Error + Send + Sync>`; format it so the
+                // conversion to this fn's `Box<dyn Error>` is unambiguous.
+                Ok(Err(e)) => return Err(format!("gRPC server error: {e}").into()),
+                Err(e) => return Err(format!("gRPC server task panicked: {e}").into()),
+            }
+        }
+    }
+
+    Ok(())
+}
+
+/// Resolve once the watch channel reports a shutdown was requested.
+async fn wait_for_shutdown(mut rx: tokio::sync::watch::Receiver<bool>) {
+    if *rx.borrow_and_update() {
+        return;
+    }
+    let _ = rx.changed().await;
+}
+
+/// Wait for a Ctrl+C or (on unix) SIGTERM — the foreground `serve` shutdown trigger.
+pub async fn shutdown_signal() {
+    let ctrl_c = async {
+        tokio::signal::ctrl_c().await.expect("failed to install Ctrl+C handler");
+    };
+
+    #[cfg(unix)]
+    let terminate = async {
+        tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate())
+            .expect("failed to install signal handler")
+            .recv()
+            .await;
+    };
+
+    #[cfg(not(unix))]
+    let terminate = std::future::pending::<()>();
+
+    tokio::select! {
+        _ = ctrl_c => info!("Received Ctrl+C, shutting down..."),
+        _ = terminate => info!("Received SIGTERM, shutting down..."),
+    }
+}
+
+/// Register the configured storage backends (filesystem and/or S3).
+pub fn initialize_storage(config: &Config) -> Arc<StorageRegistry> {
+    let mut storage_registry = StorageRegistry::new();
+
+    // Use an explicit filesystem path if set; otherwise default to ~/.vcms/storage
+    // so uploads work out of the box — unless S3 is configured and takes over.
+    let fs_path = match (&config.storage_fs_path, config.has_s3()) {
+        (Some(path), _) => Some(path.clone()),
+        (None, false) => Some(crate::paths::storage_dir().to_string_lossy().into_owned()),
+        (None, true) => None,
+    };
+
+    if let Some(fs_path) = fs_path {
+        match storage::FileSystemStorage::new(&fs_path) {
+            Ok(fs) => {
+                storage_registry.register(STORAGE_KIND_FILESYSTEM, Arc::new(fs));
+                info!("Filesystem storage initialized at {}", fs_path);
+            }
+            Err(error) => warn!("Failed to initialize filesystem storage: {}", error),
+        }
+    }
+
+    if config.has_s3() {
+        match storage::S3Storage::new(
+            config.s3_access_key_id.as_deref().unwrap(),
+            config.s3_secret_access_key.as_deref().unwrap(),
+            config.s3_bucket.as_deref().unwrap(),
+            config.s3_region.as_deref().unwrap_or("us-east-1"),
+            config.s3_endpoint.as_deref(),
+            config.s3_public_url.as_deref(),
+        ) {
+            Ok(s3) => {
+                storage_registry.register(STORAGE_KIND_S3, Arc::new(s3));
+                info!("S3 storage initialized");
+            }
+            Err(error) => warn!("Failed to initialize S3 storage: {}", error),
+        }
+    }
+
+    if storage_registry.get(STORAGE_KIND_FILESYSTEM).is_none() && storage_registry.get(STORAGE_KIND_S3).is_none() {
+        warn!("No storage providers configured. Set STORAGE_FS_PATH or S3_* env vars.");
+    }
+
+    Arc::new(storage_registry)
+}
+
+async fn seed_admin(repository: &Repository) {
+    debug!("Checking if admin user needs to be seeded");
+    if !repository.user.exists(ADMIN_EMAIL).await.unwrap_or(false) {
+        info!("Seeding default admin user");
+        let id = uuid::Uuid::now_v7().to_string();
+        let password_hash = bcrypt::hash("admin", bcrypt::DEFAULT_COST).expect("Failed to hash password");
+        repository
+            .user
+            .create(&id, "admin", ADMIN_EMAIL, &password_hash)
+            .await
+            .expect("Failed to seed admin user");
+        repository
+            .user
+            .set_instance_role(&id, Some("instance_owner"))
+            .await
+            .expect("Failed to assign instance owner");
+        repository
+            .user
+            .update_password(&id, &password_hash, true)
+            .await
+            .expect("Failed to require password change");
+
+        warn!("Seeded default admin user (admin@cms.local / admin) — CHANGE THE PASSWORD IMMEDIATELY!");
+        eprintln!(
+            "\n\
+             ============================ SECURITY WARNING ============================\n\
+             A default admin account was created:  email 'admin@cms.local'  password 'admin'\n\
+             Sign in with the email and password. Anyone who can reach this server can log\n\
+             in until you change it. Run:\n\
+             \n    vcms admin reset-password --email admin@cms.local --password <new-strong-password>\n\n\
+             or change it from the dashboard now. Do NOT expose this server until done.\n\
+             =========================================================================\n"
+        );
+    } else {
+        debug!("Admin user already exists, skipping seeding");
+    }
+}

From 6c79f6bd1cdc72eb4f8700c3a803db95934fb44e Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Thu, 25 Jun 2026 19:56:34 +0530
Subject: [PATCH 04/44] feat: add cross-platform OS service management

Add 'vcms service' subcommand with install, uninstall, status, start,
and stop actions for managing the server as a native OS background
service:

- Linux: systemd unit (install/enable/start via systemctl)
- macOS: launchd LaunchDaemon (bootstrap/kickstart via launchctl)
- Windows: Service Control Manager via windows-service crate
  (auto-start, LocalSystem, ACL-hardened ProgramData home)

Shared logic (unit file rendering, username validation, home directory
resolution, secure .env creation) lives in service/mod.rs so it
compiles and tests on every platform. Platform-specific side effects
are behind cfg-gated submodules.

Security: the service refuses to run as root on unix; Windows uses
LocalSystem. The .env file is created with mode 0600, symlink
attacks are rejected, and Windows ACLs are locked to SYSTEM +
Administrators only.
---
 apps/backend/src/cli.rs             |  80 +++++++
 apps/backend/src/service/linux.rs   | 125 +++++++++++
 apps/backend/src/service/macos.rs   | 123 +++++++++++
 apps/backend/src/service/mod.rs     | 309 ++++++++++++++++++++++++++++
 apps/backend/src/service/windows.rs | 264 ++++++++++++++++++++++++
 5 files changed, 901 insertions(+)
 create mode 100644 apps/backend/src/service/linux.rs
 create mode 100644 apps/backend/src/service/macos.rs
 create mode 100644 apps/backend/src/service/mod.rs
 create mode 100644 apps/backend/src/service/windows.rs

diff --git a/apps/backend/src/cli.rs b/apps/backend/src/cli.rs
index 5a0eff60..b8f7b8f2 100644
--- a/apps/backend/src/cli.rs
+++ b/apps/backend/src/cli.rs
@@ -69,6 +69,11 @@ pub enum Command {
         #[command(subcommand)]
         action: BackupAction,
     },
+    /// Manage the OS background service (systemd / launchd / Windows SCM).
+    Service {
+        #[command(subcommand)]
+        action: ServiceAction,
+    },
     /// Restore a backup artifact (runs offline; destructive — replaces data in scope).
     Restore {
         /// Path to the backup artifact (`.cmsbak`).
@@ -114,6 +119,37 @@ pub enum BackupAction {
     List,
 }
 
+#[derive(Subcommand, Debug)]
+pub enum ServiceAction {
+    /// Install the service, enable it at boot, and start it now (requires root/admin).
+    ///
+    /// The service runs `vcms serve` as the chosen OS account; runtime files live
+    /// under that account's `$VCMS_HOME` (default `~/.vcms`).
+    Install {
+        /// OS account the service runs as.
+        ///
+        /// Defaults to the real invoking user (`$SUDO_USER` when run via sudo). The
+        /// service never runs as root. Ignored on Windows (runs as LocalSystem).
+        #[arg(long, value_name = "NAME")]
+        user: Option<String>,
+    },
+    /// Stop, disable, and remove the service (requires root/admin).
+    Uninstall,
+    /// Show whether the service is installed, enabled at boot, and running.
+    Status,
+    /// Start the installed service.
+    Start,
+    /// Stop the running service.
+    Stop,
+    /// Internal entry point invoked by the Windows Service Control Manager.
+    ///
+    /// Not for direct use — the SCM launches this to host the server inside a
+    /// Windows service. Hidden from `--help`.
+    #[cfg(windows)]
+    #[command(hide = true)]
+    Run,
+}
+
 #[derive(Subcommand, Debug)]
 pub enum McpTransport {
     /// Run MCP over stdin/stdout.
@@ -163,4 +199,48 @@ mod tests {
             })
         ));
     }
+
+    #[test]
+    fn parses_service_install_with_user() {
+        use super::ServiceAction;
+        let cli =
+            Cli::try_parse_from(["vcms", "service", "install", "--user", "deploy"]).expect("command should parse");
+        match cli.command {
+            Some(Command::Service {
+                action: ServiceAction::Install { user },
+            }) => assert_eq!(user.as_deref(), Some("deploy")),
+            other => panic!("unexpected command: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn parses_service_lifecycle_subcommands() {
+        use super::ServiceAction;
+        for (args, ok) in [
+            (
+                ["service", "status"],
+                matches!(parse_action(&["service", "status"]), ServiceAction::Status),
+            ),
+            (
+                ["service", "start"],
+                matches!(parse_action(&["service", "start"]), ServiceAction::Start),
+            ),
+            (
+                ["service", "stop"],
+                matches!(parse_action(&["service", "stop"]), ServiceAction::Stop),
+            ),
+        ] {
+            assert!(ok, "{args:?} did not parse to the expected ServiceAction");
+        }
+    }
+
+    #[cfg(test)]
+    fn parse_action(args: &[&str]) -> super::ServiceAction {
+        let mut full = vec!["vcms"];
+        full.extend_from_slice(args);
+        match Cli::try_parse_from(full).expect("parse").command {
+            Some(Command::Service { action }) => action,
+            other => panic!("unexpected: {other:?}"),
+        }
+    }
 }
diff --git a/apps/backend/src/service/linux.rs b/apps/backend/src/service/linux.rs
new file mode 100644
index 00000000..eb2dabd3
--- /dev/null
+++ b/apps/backend/src/service/linux.rs
@@ -0,0 +1,125 @@
+//! systemd integration for `vcms service` on Linux.
+
+use std::path::Path;
+use std::process::Command;
+
+use super::{InstallOptions, SERVICE_NAME, require_root, resolve_run_user, systemd_unit, user_home};
+use crate::cli::{Cli, ServiceAction};
+
+/// Where the generated unit file is written.
+const UNIT_PATH: &str = "/etc/systemd/system/vcms.service";
+
+pub fn dispatch(action: &ServiceAction, _cli: &Cli) -> Result<(), Box<dyn std::error::Error>> {
+    match action {
+        ServiceAction::Install { user } => install(user.as_deref()),
+        ServiceAction::Uninstall => uninstall(),
+        ServiceAction::Status => status(),
+        ServiceAction::Start => start(),
+        ServiceAction::Stop => stop(),
+    }
+}
+
+fn install(user: Option<&str>) -> Result<(), Box<dyn std::error::Error>> {
+    require_root("install")?;
+    if !Path::new("/run/systemd/system").exists() {
+        return Err("systemd was not detected (no /run/systemd/system). Only systemd-based \
+                    Linux distributions are supported by `vcms service`."
+            .into());
+    }
+
+    let user = resolve_run_user(user)?;
+    let vcms_home = user_home(&user)?.join(".vcms");
+    let exe_path = std::env::current_exe()?;
+    let opts = InstallOptions {
+        user: user.clone(),
+        exe_path,
+        vcms_home,
+    };
+
+    prepare_home(&opts)?;
+
+    std::fs::write(UNIT_PATH, systemd_unit(&opts))?;
+    println!("Wrote {UNIT_PATH}");
+
+    run(Command::new("systemctl").arg("daemon-reload"))?;
+    run(Command::new("systemctl").args(["enable", "--now", SERVICE_NAME]))?;
+
+    println!("Service '{SERVICE_NAME}' installed, enabled at boot, and started (running as {user}).");
+    println!("Secrets (Postgres/S3 only) go in {}", opts.env_file().display());
+    println!("Check it with:  vcms service status");
+    Ok(())
+}
+
+fn uninstall() -> Result<(), Box<dyn std::error::Error>> {
+    require_root("uninstall")?;
+    // Best-effort: the service may already be stopped/disabled.
+    let _ = run(Command::new("systemctl").args(["disable", "--now", SERVICE_NAME]));
+    if Path::new(UNIT_PATH).exists() {
+        std::fs::remove_file(UNIT_PATH)?;
+        println!("Removed {UNIT_PATH}");
+    }
+    run(Command::new("systemctl").arg("daemon-reload"))?;
+    println!("Service '{SERVICE_NAME}' uninstalled. Your data under ~/.vcms was left intact.");
+    Ok(())
+}
+
+fn start() -> Result<(), Box<dyn std::error::Error>> {
+    require_root("start")?;
+    run(Command::new("systemctl").args(["start", SERVICE_NAME]))?;
+    println!("Service '{SERVICE_NAME}' started.");
+    Ok(())
+}
+
+fn stop() -> Result<(), Box<dyn std::error::Error>> {
+    require_root("stop")?;
+    run(Command::new("systemctl").args(["stop", SERVICE_NAME]))?;
+    println!("Service '{SERVICE_NAME}' stopped.");
+    Ok(())
+}
+
+fn status() -> Result<(), Box<dyn std::error::Error>> {
+    let enabled = output_trim(Command::new("systemctl").args(["is-enabled", SERVICE_NAME]));
+    let active = output_trim(Command::new("systemctl").args(["is-active", SERVICE_NAME]));
+    println!("Service: {SERVICE_NAME}");
+    println!("  enabled at boot: {}", enabled.as_deref().unwrap_or("unknown"));
+    println!("  running:         {}", active.as_deref().unwrap_or("unknown"));
+    // Detailed view (best-effort; ignored if the unit is absent).
+    let _ = Command::new("systemctl")
+        .args(["status", SERVICE_NAME, "--no-pager"])
+        .status();
+    Ok(())
+}
+
+/// Create the run-as user's `~/.vcms` + optional `.env` (0600) and hand ownership
+/// to that account so the daemon can read and write its home.
+fn prepare_home(opts: &InstallOptions) -> Result<(), Box<dyn std::error::Error>> {
+    super::reject_symlink(&opts.vcms_home)?;
+    std::fs::create_dir_all(&opts.vcms_home)?;
+    let env_file = opts.env_file();
+    super::create_secure_env_file(&env_file)?;
+    set_mode_600(&env_file)?;
+    run(Command::new("chown")
+        .arg("-R")
+        .arg(format!("{}:", opts.user))
+        .arg(&opts.vcms_home))?;
+    Ok(())
+}
+
+fn set_mode_600(path: &Path) -> std::io::Result<()> {
+    use std::os::unix::fs::PermissionsExt;
+    std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o600))
+}
+
+fn run(cmd: &mut Command) -> Result<(), Box<dyn std::error::Error>> {
+    let status = cmd.status()?;
+    if !status.success() {
+        return Err(format!("command {cmd:?} failed with {status}").into());
+    }
+    Ok(())
+}
+
+fn output_trim(cmd: &mut Command) -> Option<String> {
+    let out = cmd.output().ok()?;
+    let s = String::from_utf8_lossy(&out.stdout).trim().to_string();
+    if s.is_empty() { None } else { Some(s) }
+}
diff --git a/apps/backend/src/service/macos.rs b/apps/backend/src/service/macos.rs
new file mode 100644
index 00000000..0b1ba80c
--- /dev/null
+++ b/apps/backend/src/service/macos.rs
@@ -0,0 +1,123 @@
+//! launchd integration for `vcms service` on macOS (system LaunchDaemon).
+
+use std::path::Path;
+use std::process::Command;
+
+use super::{InstallOptions, LAUNCHD_LABEL, launchd_plist, require_root, resolve_run_user, user_home};
+use crate::cli::{Cli, ServiceAction};
+
+/// Where the generated LaunchDaemon plist is written.
+const PLIST_PATH: &str = "/Library/LaunchDaemons/local.vcms.plist";
+
+/// Modern launchctl service target (`system/<label>`).
+fn target() -> String {
+    format!("system/{LAUNCHD_LABEL}")
+}
+
+pub fn dispatch(action: &ServiceAction, _cli: &Cli) -> Result<(), Box<dyn std::error::Error>> {
+    match action {
+        ServiceAction::Install { user } => install(user.as_deref()),
+        ServiceAction::Uninstall => uninstall(),
+        ServiceAction::Status => status(),
+        ServiceAction::Start => start(),
+        ServiceAction::Stop => stop(),
+    }
+}
+
+fn install(user: Option<&str>) -> Result<(), Box<dyn std::error::Error>> {
+    require_root("install")?;
+    let user = resolve_run_user(user)?;
+    let vcms_home = user_home(&user)?.join(".vcms");
+    let exe_path = std::env::current_exe()?;
+    let opts = InstallOptions {
+        user: user.clone(),
+        exe_path,
+        vcms_home,
+    };
+
+    prepare_home(&opts)?;
+
+    std::fs::write(PLIST_PATH, launchd_plist(&opts))?;
+    // launchd refuses daemons whose plist is not root-owned / group- or world-writable.
+    set_mode_644(Path::new(PLIST_PATH))?;
+    run(Command::new("chown").arg("root:wheel").arg(PLIST_PATH))?;
+    println!("Wrote {PLIST_PATH}");
+
+    // bootstrap loads the job; enable persists it across reboots; kickstart starts now.
+    run(Command::new("launchctl").args(["bootstrap", "system", PLIST_PATH]))?;
+    let _ = run(Command::new("launchctl").args(["enable", &target()]));
+    run(Command::new("launchctl").args(["kickstart", "-k", &target()]))?;
+
+    println!("Service '{LAUNCHD_LABEL}' installed, enabled at boot, and started (running as {user}).");
+    println!("Secrets (Postgres/S3 only) go in {}", opts.env_file().display());
+    println!("Check it with:  vcms service status");
+    Ok(())
+}
+
+fn uninstall() -> Result<(), Box<dyn std::error::Error>> {
+    require_root("uninstall")?;
+    // Best-effort: the job may already be unloaded.
+    let _ = run(Command::new("launchctl").args(["bootout", &target()]));
+    if Path::new(PLIST_PATH).exists() {
+        std::fs::remove_file(PLIST_PATH)?;
+        println!("Removed {PLIST_PATH}");
+    }
+    println!("Service '{LAUNCHD_LABEL}' uninstalled. Your data under ~/.vcms was left intact.");
+    Ok(())
+}
+
+fn start() -> Result<(), Box<dyn std::error::Error>> {
+    require_root("start")?;
+    run(Command::new("launchctl").args(["kickstart", &target()]))?;
+    println!("Service '{LAUNCHD_LABEL}' started.");
+    Ok(())
+}
+
+fn stop() -> Result<(), Box<dyn std::error::Error>> {
+    require_root("stop")?;
+    run(Command::new("launchctl").args(["kill", "SIGTERM", &target()]))?;
+    println!("Service '{LAUNCHD_LABEL}' stop signal sent.");
+    Ok(())
+}
+
+fn status() -> Result<(), Box<dyn std::error::Error>> {
+    println!("Service: {LAUNCHD_LABEL}");
+    // `launchctl print` prints state, last exit status, and PID when running.
+    let printed = Command::new("launchctl").args(["print", &target()]).status();
+    if !matches!(printed, Ok(s) if s.success()) {
+        println!("  (not loaded — run `vcms service install`)");
+    }
+    Ok(())
+}
+
+/// Create the run-as user's `~/.vcms` + optional `.env` (0600), owned by that user.
+fn prepare_home(opts: &InstallOptions) -> Result<(), Box<dyn std::error::Error>> {
+    super::reject_symlink(&opts.vcms_home)?;
+    std::fs::create_dir_all(&opts.vcms_home)?;
+    let env_file = opts.env_file();
+    super::create_secure_env_file(&env_file)?;
+    set_mode_600(&env_file)?;
+    run(Command::new("chown")
+        .arg("-R")
+        .arg(format!("{}:", opts.user))
+        .arg(&opts.vcms_home))?;
+    Ok(())
+}
+
+fn set_mode_600(path: &Path) -> std::io::Result<()> {
+    use std::os::unix::fs::PermissionsExt;
+    std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o600))
+}
+
+fn set_mode_644(path: &Path) -> std::io::Result<()> {
+    use std::os::unix::fs::PermissionsExt;
+    std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o644))
+}
+
+fn run(cmd: &mut Command) -> Result<(), Box<dyn std::error::Error>> {
+    let status = cmd.status()?;
+    if !status.success() {
+        return Err(format!("command {cmd:?} failed with {status}").into());
+    }
+    Ok(())
+}
diff --git a/apps/backend/src/service/mod.rs b/apps/backend/src/service/mod.rs
new file mode 100644
index 00000000..142b7079
--- /dev/null
+++ b/apps/backend/src/service/mod.rs
@@ -0,0 +1,309 @@
+//! `vcms service` — install and manage the server as a native OS background
+//! service (systemd on Linux, launchd on macOS, the Service Control Manager on
+//! Windows).
+//!
+//! The pure definition builders ([`systemd_unit`], [`launchd_plist`]) and the
+//! shared helpers live here so they compile and unit-test on every platform; the
+//! side-effecting bits (writing unit files, shelling out to the service manager,
+//! talking to the SCM) live in the per-OS submodules behind `#[cfg]`.
+
+use crate::cli::{Cli, ServiceAction};
+use std::path::PathBuf;
+
+#[cfg(target_os = "linux")]
+mod linux;
+#[cfg(target_os = "macos")]
+mod macos;
+#[cfg(windows)]
+mod windows;
+
+/// Service name registered with systemd / the Windows SCM.
+pub const SERVICE_NAME: &str = "vcms";
+/// Human-readable service description.
+pub const SERVICE_DISPLAY_NAME: &str = "vcms headless CMS";
+/// launchd job label (reverse-DNS-ish, kept short and unambiguous).
+pub const LAUNCHD_LABEL: &str = "local.vcms";
+
+/// Contents written to a freshly-created `<VCMS_HOME>/.env`. Empty of real values
+/// so the SQLite default + auto-generated `secrets.toml` work with zero edits; the
+/// commented keys show Postgres/MySQL/S3 users where their secrets go.
+pub(crate) const ENV_TEMPLATE: &str = "\
+# Environment for the vcms service (loaded from $VCMS_HOME/.env, mode 0600).
+# The default SQLite database and auto-generated secrets need nothing here.
+# Uncomment and set these only for Postgres/MySQL or S3 storage:
+#
+# DATABASE_URL=postgres://user:password@localhost/vcms
+# S3_ACCESS_KEY_ID=...
+# S3_SECRET_ACCESS_KEY=...
+# S3_BUCKET=...
+";
+
+/// Resolved inputs for writing a service definition.
+#[derive(Debug, Clone)]
+pub struct InstallOptions {
+    /// OS account the service runs as (unix only; Windows uses LocalSystem).
+    pub user: String,
+    /// Absolute path to the `vcms` binary, used as the program to launch.
+    pub exe_path: PathBuf,
+    /// The account's CMS home directory (becomes `VCMS_HOME`).
+    pub vcms_home: PathBuf,
+}
+
+impl InstallOptions {
+    /// `<vcms_home>/.env` — the optional, 0600 env file the service loads.
+    pub fn env_file(&self) -> PathBuf {
+        self.vcms_home.join(".env")
+    }
+}
+
+/// Render the systemd unit file for the resolved install options.
+///
+/// `EnvironmentFile=-` makes the `.env` optional (a missing/empty file is a no-op).
+pub fn systemd_unit(opts: &InstallOptions) -> String {
+    let exe = opts.exe_path.to_string_lossy();
+    let home = opts.vcms_home.to_string_lossy();
+    // systemd paths are always `/`-separated; build the env-file path explicitly so
+    // the rendered unit is host-independent (don't use `PathBuf::join`, which would
+    // emit a `\` when this runs on a non-unix host, e.g. in tests).
+    let env_file = format!("{home}/.env");
+    format!(
+        "[Unit]\n\
+         Description={SERVICE_DISPLAY_NAME}\n\
+         After=network-online.target\n\
+         Wants=network-online.target\n\
+         \n\
+         [Service]\n\
+         Type=simple\n\
+         User={user}\n\
+         Environment=VCMS_HOME={home}\n\
+         EnvironmentFile=-{env_file}\n\
+         ExecStart={exe} serve\n\
+         Restart=always\n\
+         RestartSec=5\n\
+         \n\
+         [Install]\n\
+         WantedBy=multi-user.target\n",
+        user = opts.user,
+    )
+}
+
+/// Render the launchd LaunchDaemon plist for the resolved install options.
+pub fn launchd_plist(opts: &InstallOptions) -> String {
+    let exe = xml_escape(&opts.exe_path.to_string_lossy());
+    let home = xml_escape(&opts.vcms_home.to_string_lossy());
+    let user = xml_escape(&opts.user);
+    format!(
+        "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n\
+         <!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\">\n\
+         <plist version=\"1.0\">\n\
+         <dict>\n\
+         \x20 <key>Label</key>\n\
+         \x20 <string>{LAUNCHD_LABEL}</string>\n\
+         \x20 <key>ProgramArguments</key>\n\
+         \x20 <array>\n\
+         \x20   <string>{exe}</string>\n\
+         \x20   <string>serve</string>\n\
+         \x20 </array>\n\
+         \x20 <key>UserName</key>\n\
+         \x20 <string>{user}</string>\n\
+         \x20 <key>EnvironmentVariables</key>\n\
+         \x20 <dict>\n\
+         \x20   <key>VCMS_HOME</key>\n\
+         \x20   <string>{home}</string>\n\
+         \x20 </dict>\n\
+         \x20 <key>RunAtLoad</key>\n\
+         \x20 <true/>\n\
+         \x20 <key>KeepAlive</key>\n\
+         \x20 <true/>\n\
+         </dict>\n\
+         </plist>\n",
+    )
+}
+
+/// Minimal XML escaping for plist string values.
+fn xml_escape(s: &str) -> String {
+    s.replace('&', "&amp;").replace('<', "&lt;").replace('>', "&gt;")
+}
+
+/// Validate that a username is safe to interpolate into a shell command / unit
+/// file: POSIX-portable account names only. Guards the `echo ~name` home lookup.
+pub fn validate_username(name: &str) -> Result<(), String> {
+    if name.is_empty() || name.len() > 32 {
+        return Err(format!("invalid username '{name}': must be 1-32 characters"));
+    }
+    let mut chars = name.chars();
+    let first = chars.next().unwrap();
+    if !(first.is_ascii_lowercase() || first == '_') {
+        return Err(format!(
+            "invalid username '{name}': must start with a lowercase letter or '_'"
+        ));
+    }
+    if !name
+        .chars()
+        .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '_' || c == '-')
+    {
+        return Err(format!("invalid username '{name}': only [a-z0-9_-] allowed"));
+    }
+    Ok(())
+}
+
+/// Dispatch a `vcms service <action>` invocation to the platform implementation.
+pub async fn run_service(action: &ServiceAction, cli: &Cli) -> Result<(), Box<dyn std::error::Error>> {
+    // Exactly one of these `let` bindings is active per target, so `result` is the
+    // single tail expression (no per-cfg `return`, which clippy flags as needless).
+    #[cfg(target_os = "linux")]
+    let result = linux::dispatch(action, cli);
+    #[cfg(target_os = "macos")]
+    let result = macos::dispatch(action, cli);
+    #[cfg(windows)]
+    let result = windows::dispatch(action, cli);
+    #[cfg(not(any(target_os = "linux", target_os = "macos", windows)))]
+    let result = {
+        let _ = (action, cli);
+        Err::<(), Box<dyn std::error::Error>>("`vcms service` is only supported on Linux, macOS, and Windows".into())
+    };
+
+    result
+}
+
+// ----- unix-shared helpers (compiled only on Linux + macOS) -----
+
+/// Reject a path that is a symlink, **without following it** (`lstat`), so a
+/// pre-planted symlink can't redirect a root-owned write. A dangling symlink (target
+/// missing) is still caught — unlike `Path::exists()`, which follows the link and
+/// reports `false`. A genuinely absent path is fine (returns `Ok`).
+#[cfg(unix)]
+pub(crate) fn reject_symlink(path: &std::path::Path) -> Result<(), Box<dyn std::error::Error>> {
+    match std::fs::symlink_metadata(path) {
+        Ok(meta) if meta.file_type().is_symlink() => Err(format!("refusing symlink at {}", path.display()).into()),
+        Ok(_) => Ok(()),
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),
+        Err(e) => Err(e.into()),
+    }
+}
+
+/// Atomically create `<VCMS_HOME>/.env` (mode 0600) with the env template, refusing
+/// to follow a symlink. `create_new` (`O_EXCL | O_CREAT`) fails rather than follows if
+/// the path already exists or is a symlink; an already-present regular file is left
+/// as-is (we only re-check it isn't a symlink).
+#[cfg(unix)]
+pub(crate) fn create_secure_env_file(path: &std::path::Path) -> Result<(), Box<dyn std::error::Error>> {
+    use std::io::Write;
+    use std::os::unix::fs::OpenOptionsExt;
+
+    reject_symlink(path)?;
+    match std::fs::OpenOptions::new()
+        .write(true)
+        .create_new(true)
+        .mode(0o600)
+        .open(path)
+    {
+        Ok(mut file) => file.write_all(ENV_TEMPLATE.as_bytes())?,
+        Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => reject_symlink(path)?,
+        Err(e) => return Err(e.into()),
+    }
+    Ok(())
+}
+
+/// Error if the current process is not running as root (euid 0).
+#[cfg(unix)]
+pub(crate) fn require_root(verb: &str) -> Result<(), Box<dyn std::error::Error>> {
+    // SAFETY: `geteuid` is always safe — it only reads the calling process's id.
+    let euid = unsafe { libc::geteuid() };
+    if euid != 0 {
+        return Err(format!("`vcms service {verb}` requires root (try: sudo vcms service {verb})").into());
+    }
+    Ok(())
+}
+
+/// Resolve the account the service should run as: explicit `--user`, else the real
+/// user behind sudo (`$SUDO_USER`), else the current login — never root.
+#[cfg(unix)]
+pub(crate) fn resolve_run_user(explicit: Option<&str>) -> Result<String, Box<dyn std::error::Error>> {
+    if let Some(user) = explicit {
+        validate_username(user)?;
+        if user == "root" {
+            return Err(
+                "refusing to run the service as root; pass --user <name> with an existing non-root account".into(),
+            );
+        }
+        return Ok(user.to_string());
+    }
+    if let Ok(sudo_user) = std::env::var("SUDO_USER") {
+        if !sudo_user.is_empty() && sudo_user != "root" {
+            validate_username(&sudo_user)?;
+            return Ok(sudo_user);
+        }
+    }
+    let current = std::env::var("USER").unwrap_or_default();
+    if current.is_empty() || current == "root" {
+        return Err("could not determine a non-root account to run the service as; \
+                    pass --user <name> with an existing non-root account"
+            .into());
+    }
+    validate_username(&current)?;
+    Ok(current)
+}
+
+/// Resolve a user's home directory via shell tilde expansion. The username must be
+/// pre-validated by [`validate_username`] (no shell metacharacters).
+#[cfg(unix)]
+pub(crate) fn user_home(user: &str) -> Result<PathBuf, Box<dyn std::error::Error>> {
+    validate_username(user)?;
+    let output = std::process::Command::new("sh")
+        .arg("-c")
+        .arg(format!("echo ~{user}"))
+        .output()?;
+    let home = String::from_utf8_lossy(&output.stdout).trim().to_string();
+    if home.is_empty() || home.starts_with('~') {
+        return Err(format!("could not resolve home directory for user '{user}'").into());
+    }
+    Ok(PathBuf::from(home))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::path::PathBuf;
+
+    fn sample() -> InstallOptions {
+        InstallOptions {
+            user: "deploy".into(),
+            exe_path: PathBuf::from("/usr/local/bin/vcms"),
+            vcms_home: PathBuf::from("/home/deploy/.vcms"),
+        }
+    }
+
+    #[test]
+    fn systemd_unit_contains_key_directives() {
+        let unit = systemd_unit(&sample());
+        assert!(unit.contains("ExecStart=/usr/local/bin/vcms serve"));
+        assert!(unit.contains("User=deploy"));
+        assert!(unit.contains("Environment=VCMS_HOME=/home/deploy/.vcms"));
+        assert!(unit.contains("EnvironmentFile=-/home/deploy/.vcms/.env"));
+        assert!(unit.contains("Restart=always"));
+        assert!(unit.contains("WantedBy=multi-user.target"));
+    }
+
+    #[test]
+    fn launchd_plist_contains_program_and_user() {
+        let plist = launchd_plist(&sample());
+        assert!(plist.contains("<string>local.vcms</string>"));
+        assert!(plist.contains("<string>/usr/local/bin/vcms</string>"));
+        assert!(plist.contains("<string>serve</string>"));
+        assert!(plist.contains("<string>deploy</string>"));
+        assert!(plist.contains("<key>VCMS_HOME</key>"));
+        assert!(plist.contains("<string>/home/deploy/.vcms</string>"));
+    }
+
+    #[test]
+    fn username_validation_rejects_injection() {
+        assert!(validate_username("deploy").is_ok());
+        assert!(validate_username("_svc-1").is_ok());
+        assert!(validate_username("root").is_ok());
+        assert!(validate_username("a; rm -rf /").is_err());
+        assert!(validate_username("Bob").is_err());
+        assert!(validate_username("").is_err());
+        assert!(validate_username("1user").is_err());
+    }
+}
diff --git a/apps/backend/src/service/windows.rs b/apps/backend/src/service/windows.rs
new file mode 100644
index 00000000..8a316464
--- /dev/null
+++ b/apps/backend/src/service/windows.rs
@@ -0,0 +1,264 @@
+//! Windows Service Control Manager integration for `vcms service`.
+//!
+//! `install`/`uninstall`/`status`/`start`/`stop` drive the SCM via the
+//! `windows-service` crate. `Run` is the hidden entry point the SCM launches
+//! (registered with `launch_arguments = ["service", "run"]`): it hands the thread
+//! to the SCM dispatcher, hosts the shared server on a fresh tokio runtime, and
+//! translates a Stop/Shutdown control into the server's graceful-shutdown signal.
+
+use std::ffi::OsString;
+use std::sync::Arc;
+use std::time::Duration;
+
+use windows_service::service::{
+    ServiceAccess, ServiceControl, ServiceControlAccept, ServiceErrorControl, ServiceExitCode, ServiceInfo,
+    ServiceStartType, ServiceState, ServiceStatus, ServiceType,
+};
+use windows_service::service_control_handler::{self, ServiceControlHandlerResult};
+use windows_service::service_manager::{ServiceManager, ServiceManagerAccess};
+use windows_service::{define_windows_service, service_dispatcher};
+
+use super::{ENV_TEMPLATE, SERVICE_DISPLAY_NAME, SERVICE_NAME};
+use crate::cli::{Cli, ServiceAction};
+
+/// Fixed home for the LocalSystem service (Windows convention is ProgramData).
+const WINDOWS_SERVICE_HOME: &str = r"C:\ProgramData\vcms";
+
+pub fn dispatch(action: &ServiceAction, _cli: &Cli) -> Result<(), Box<dyn std::error::Error>> {
+    match action {
+        ServiceAction::Install { user } => {
+            if user.as_deref().is_some_and(|u| !u.is_empty()) {
+                return Err(
+                    "custom user accounts are not supported on Windows; the service runs as LocalSystem".into(),
+                );
+            }
+            install()
+        }
+        ServiceAction::Uninstall => uninstall(),
+        ServiceAction::Status => status(),
+        ServiceAction::Start => start(),
+        ServiceAction::Stop => stop(),
+        ServiceAction::Run => run_dispatcher(),
+    }
+}
+
+fn install() -> Result<(), Box<dyn std::error::Error>> {
+    let manager = ServiceManager::local_computer(
+        None::<&str>,
+        ServiceManagerAccess::CONNECT | ServiceManagerAccess::CREATE_SERVICE,
+    )
+    .map_err(elevation_hint)?;
+
+    let exe_path = std::env::current_exe()?;
+    let info = ServiceInfo {
+        name: OsString::from(SERVICE_NAME),
+        display_name: OsString::from(SERVICE_DISPLAY_NAME),
+        service_type: ServiceType::OWN_PROCESS,
+        start_type: ServiceStartType::AutoStart,
+        error_control: ServiceErrorControl::Normal,
+        executable_path: exe_path,
+        launch_arguments: vec![OsString::from("service"), OsString::from("run")],
+        dependencies: vec![],
+        account_name: None, // LocalSystem
+        account_password: None,
+    };
+
+    let access = ServiceAccess::CHANGE_CONFIG | ServiceAccess::START;
+    let service = match manager.create_service(&info, access) {
+        Ok(service) => service,
+        // Already installed: update config and reuse it (idempotent install).
+        Err(_) => {
+            let service = manager.open_service(SERVICE_NAME, access).map_err(elevation_hint)?;
+            service.change_config(&info).map_err(elevation_hint)?;
+            println!("Service '{SERVICE_NAME}' already existed; configuration updated.");
+            service
+        }
+    };
+    let _ = service.set_description(SERVICE_DISPLAY_NAME);
+
+    prepare_home()?;
+
+    let already_running = service
+        .query_status()
+        .map(|s| s.current_state == windows_service::service::ServiceState::Running)
+        .unwrap_or(false);
+    if !already_running {
+        service.start::<&str>(&[])?;
+    }
+    println!("Service '{SERVICE_NAME}' installed (auto-start, LocalSystem) and started.");
+    println!("Home + secrets (.env): {WINDOWS_SERVICE_HOME}");
+    println!("Check it with:  vcms service status");
+    Ok(())
+}
+
+fn uninstall() -> Result<(), Box<dyn std::error::Error>> {
+    let service = open_service(ServiceAccess::STOP | ServiceAccess::DELETE | ServiceAccess::QUERY_STATUS)?;
+    let _ = service.stop(); // best-effort; may already be stopped
+    service.delete()?;
+    println!("Service '{SERVICE_NAME}' uninstalled. Your data under {WINDOWS_SERVICE_HOME} was left intact.");
+    Ok(())
+}
+
+fn start() -> Result<(), Box<dyn std::error::Error>> {
+    let service = open_service(ServiceAccess::START)?;
+    service.start::<&str>(&[])?;
+    println!("Service '{SERVICE_NAME}' started.");
+    Ok(())
+}
+
+fn stop() -> Result<(), Box<dyn std::error::Error>> {
+    let service = open_service(ServiceAccess::STOP)?;
+    service.stop()?;
+    println!("Service '{SERVICE_NAME}' stop requested.");
+    Ok(())
+}
+
+fn status() -> Result<(), Box<dyn std::error::Error>> {
+    let service = open_service(ServiceAccess::QUERY_STATUS)?;
+    let status = service.query_status()?;
+    println!("Service: {SERVICE_NAME}");
+    println!("  state: {:?}", status.current_state);
+    Ok(())
+}
+
+fn open_service(access: ServiceAccess) -> Result<windows_service::service::Service, Box<dyn std::error::Error>> {
+    let manager =
+        ServiceManager::local_computer(None::<&str>, ServiceManagerAccess::CONNECT).map_err(elevation_hint)?;
+    manager.open_service(SERVICE_NAME, access).map_err(|e| -> Box<dyn std::error::Error> {
+        format!("could not open service '{SERVICE_NAME}' ({e}). Is it installed, and is this terminal running as Administrator?").into()
+    })
+}
+
+fn elevation_hint(e: windows_service::Error) -> Box<dyn std::error::Error> {
+    format!("{e}. This action requires Administrator — run your terminal as Administrator.").into()
+}
+
+/// Create the service home + optional `.env` under ProgramData, locked to
+/// SYSTEM and Administrators only.
+fn prepare_home() -> Result<(), Box<dyn std::error::Error>> {
+    let home = std::path::PathBuf::from(WINDOWS_SERVICE_HOME);
+    std::fs::create_dir_all(&home)?;
+    let env_file = home.join(".env");
+    if !env_file.exists() {
+        std::fs::write(&env_file, ENV_TEMPLATE)?;
+    }
+    // Harden after the tree exists; `/T` covers `home` and the `.env` we just wrote.
+    harden_acl(&home)?;
+    Ok(())
+}
+
+/// Lock a directory tree to LocalSystem + Administrators (Full), dropping inherited
+/// ACEs so the `.env` (which may hold `DATABASE_URL`/S3 secrets) is not world-readable.
+///
+/// Shells out to `icacls` — same "use the native tool" pattern as the unix `chown`
+/// path — rather than hand-rolling Win32 security FFI. Well-known SIDs are used so it
+/// works regardless of the OS display language (`S-1-5-18` = LocalSystem,
+/// `S-1-5-32-544` = Administrators).
+fn harden_acl(path: &std::path::Path) -> Result<(), Box<dyn std::error::Error>> {
+    let status = std::process::Command::new("icacls")
+        .arg(path)
+        .arg("/inheritance:r")
+        // Drop explicit broad ACEs a pre-existing dir may carry (`/inheritance:r` only
+        // removes *inherited* ones): Everyone, Users, Authenticated Users.
+        .args(["/remove:g", "*S-1-1-0", "*S-1-5-32-545", "*S-1-5-11"])
+        .args(["/grant:r", "*S-1-5-18:(OI)(CI)F"])
+        .args(["/grant:r", "*S-1-5-32-544:(OI)(CI)F"])
+        .arg("/T")
+        .status()?;
+    if !status.success() {
+        return Err(format!("icacls failed to harden {} ({status})", path.display()).into());
+    }
+    Ok(())
+}
+
+// ----- SCM-hosted run path -----
+
+define_windows_service!(ffi_service_main, service_main);
+
+/// Entry point for `vcms service run`: hand the thread to the SCM dispatcher.
+fn run_dispatcher() -> Result<(), Box<dyn std::error::Error>> {
+    // Pin the service to the ProgramData home so it doesn't fall back to the
+    // LocalSystem profile. Set before any thread/runtime reads the environment.
+    if std::env::var_os(crate::paths::CMS_HOME_ENV).is_none() {
+        // SAFETY: called once at process start, before tokio/threads spin up.
+        unsafe {
+            std::env::set_var(crate::paths::CMS_HOME_ENV, WINDOWS_SERVICE_HOME);
+        }
+    }
+    service_dispatcher::start(SERVICE_NAME, ffi_service_main)?;
+    Ok(())
+}
+
+fn service_main(_arguments: Vec<OsString>) {
+    if let Err(e) = run_service_session() {
+        eprintln!("vcms service error: {e}");
+    }
+}
+
+fn run_service_session() -> Result<(), Box<dyn std::error::Error>> {
+    use std::sync::Mutex;
+    use tokio::sync::Notify;
+
+    // A Stop/Shutdown control fires this; the server's injected shutdown future
+    // awaits it. `notify_one` stores a permit, so an early stop is not lost.
+    let notify = Arc::new(Notify::new());
+    let handler_notify = notify.clone();
+
+    // The handle is created by register() but needed inside the handler closure to
+    // publish StopPending. Store it behind Mutex so the closure can grab it.
+    let status_handle_cell: Arc<Mutex<Option<service_control_handler::ServiceStatusHandle>>> =
+        Arc::new(Mutex::new(None));
+    let handle_cell = status_handle_cell.clone();
+
+    let status_handle = service_control_handler::register(SERVICE_NAME, move |control| match control {
+        ServiceControl::Stop | ServiceControl::Shutdown => {
+            if let Ok(guard) = handle_cell.lock()
+                && let Some(h) = guard.as_ref()
+            {
+                let _ = h.set_service_status(ServiceStatus {
+                    service_type: ServiceType::OWN_PROCESS,
+                    current_state: ServiceState::StopPending,
+                    controls_accepted: ServiceControlAccept::empty(),
+                    exit_code: ServiceExitCode::Win32(0),
+                    checkpoint: 1,
+                    wait_hint: Duration::from_secs(30),
+                    process_id: None,
+                });
+            }
+            handler_notify.notify_one();
+            ServiceControlHandlerResult::NoError
+        }
+        ServiceControl::Interrogate => ServiceControlHandlerResult::NoError,
+        _ => ServiceControlHandlerResult::NotImplemented,
+    })?;
+    *status_handle_cell.lock().map_err(|e| format!("{e}"))? = Some(status_handle);
+
+    let running = ServiceStatus {
+        service_type: ServiceType::OWN_PROCESS,
+        current_state: ServiceState::Running,
+        controls_accepted: ServiceControlAccept::STOP | ServiceControlAccept::SHUTDOWN,
+        exit_code: ServiceExitCode::Win32(0),
+        checkpoint: 0,
+        wait_hint: Duration::default(),
+        process_id: None,
+    };
+    status_handle.set_service_status(running.clone())?;
+
+    // This thread is owned by the SCM dispatcher (not a tokio worker), so building
+    // a fresh runtime here is safe — no nested-runtime panic.
+    let runtime = tokio::runtime::Builder::new_multi_thread().enable_all().build()?;
+    let shutdown = async move { notify.notified().await };
+    let result = runtime.block_on(crate::server::run(&Cli::default(), shutdown));
+
+    let stopped = ServiceStatus {
+        current_state: ServiceState::Stopped,
+        exit_code: if result.is_ok() {
+            ServiceExitCode::Win32(0)
+        } else {
+            ServiceExitCode::Win32(1)
+        },
+        ..running
+    };
+    status_handle.set_service_status(stopped)?;
+    result
+}

From 9888fbecc05698bc28a625756de96961fdf1782d Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Tue, 30 Jun 2026 20:30:00 +0530
Subject: [PATCH 05/44] refactor(paths): support platform-conventional split
 layout with single-dir fallback

Introduce a dual-layout directory system: split (default) uses the
platform's per-type directories via the \directories\ crate, while
single mode (VCMS_HOME set or legacy ~/.vcms exists) keeps everything
under one root. This aligns with OS conventions (XDG on Linux,
Library dirs on macOS, AppData on Windows) while preserving backward
compatibility for existing installs.
---
 apps/backend/src/config.rs  |  21 ++--
 apps/backend/src/paths.rs   | 224 +++++++++++++++++++++++++++---------
 apps/backend/src/secrets.rs |   2 +-
 apps/backend/src/server.rs  |   4 +-
 4 files changed, 184 insertions(+), 67 deletions(-)

diff --git a/apps/backend/src/config.rs b/apps/backend/src/config.rs
index 60df4d41..3fca3f2a 100644
--- a/apps/backend/src/config.rs
+++ b/apps/backend/src/config.rs
@@ -185,8 +185,8 @@ impl Config {
     pub fn load(cli: &Cli) -> Result<Self, Box<figment::Error>> {
         let mut figment = Figment::new();
 
-        // Lowest-precedence secret layer: persisted HMAC secret from
-        // `~/.vcms/secrets.toml`. Read-only here (generation happens in
+        // Lowest-precedence secret layer: persisted HMAC secret from the config dir's
+        // `secrets.toml`. Read-only here (generation happens in
         // `secrets::ensure()` during serve/admin). Best-effort: a missing or
         // unreadable file just leaves the built-in defaults in play. Env vars
         // and CLI flags still override these.
@@ -357,11 +357,10 @@ impl RawConfig {
         // `secrets::ensure()` and `mcp stdio` guards on its presence, so this only
         // fires on a genuinely uninitialized instance.
         let hmac_secret = self.hmac_secret.ok_or_else(|| {
-            Box::new(figment::Error::from(
-                "No HMAC secret resolved; run `vcms serve` once to generate ~/.vcms/secrets.toml, \
-                 or set HMAC_SECRET"
-                    .to_string(),
-            ))
+            Box::new(figment::Error::from(format!(
+                "No HMAC secret resolved; run `vcms serve` once to generate {}, or set HMAC_SECRET",
+                paths::secrets_file().display(),
+            )))
         })?;
 
         let log = self.log.unwrap_or_default();
@@ -441,8 +440,8 @@ pub fn config_search_paths() -> Vec<PathBuf> {
     paths
 }
 
-/// The user-config location for the config file: `~/.vcms/config.toml`
-/// (or `$VCMS_HOME/config.toml`).
+/// The user-config location for the config file: the platform config dir
+/// (`config.toml`), or `$VCMS_HOME/config.toml` in single-dir mode.
 pub fn user_config_path() -> Option<PathBuf> {
     Some(paths::config_file())
 }
@@ -498,7 +497,7 @@ pub fn default_config_toml() -> String {
          # --- Backups ---\n\
          # Run the scheduled-backup poller and allow on-demand backups.\n\
          backup_enabled = true\n\
-         # Destination for backup artifacts: \"filesystem\" (default, under ~/.vcms/backups)\n\
+         # Destination for backup artifacts: \"filesystem\" (default, the data dir's backups/)\n\
          # or \"s3\". S3 credentials are secrets — set them via env (see below).\n\
          backup_destination = \"filesystem\"\n\
          # backup_local_path = \"./backups\"\n\
@@ -515,7 +514,7 @@ pub fn default_config_toml() -> String {
          # Build a local inverted index so entry search is ranked + tokenized.\n\
          # When false, search falls back to a basic SQL LIKE match.\n\
          search_enabled = true\n\
-         # search_index_path = \"./search\"   # defaults to ~/.vcms/search\n\n\
+         # search_index_path = \"./search\"   # defaults to the cache dir's search/\n\n\
          # --- MCP ---\n\
          mcp_enabled = true\n\
          mcp_allowed_hosts = [{hosts}]\n\
diff --git a/apps/backend/src/paths.rs b/apps/backend/src/paths.rs
index 2466a24a..5a213d83 100644
--- a/apps/backend/src/paths.rs
+++ b/apps/backend/src/paths.rs
@@ -1,116 +1,201 @@
-//! Resolution of the CMS home directory and the runtime files within it.
+//! Resolution of where the CMS keeps its runtime files.
 //!
-//! Everything the running instance owns lives under a single root so a fresh
-//! install "just works" regardless of the current working directory:
+//! There are two layouts:
 //!
-//! ```text
-//! ~/.vcms/
-//!   config.toml     # non-secret configuration
-//!   secrets.toml    # auto-generated HMAC + backup encryption secrets (0600)
-//!   vcms.db         # default SQLite database (+ -wal / -shm)
-//!   logs/           # rolling logs when log output = "file"
-//!   storage/        # default filesystem storage for uploads
-//! ```
+//! * **Split** (the default for an interactive install) — files land in the
+//!   platform-conventional per-type directories via the `directories` crate:
+//!   config/secrets in the config dir, the database/uploads/backups in the data dir,
+//!   the (rebuildable) search index in the cache dir, and logs in the state dir.
+//!   On Linux this is XDG (`~/.config/vcms`, `~/.local/share/vcms`, `~/.cache/vcms`,
+//!   `~/.local/state/vcms`); on macOS `~/Library/Application Support/vcms` (+ Caches);
+//!   on Windows `%APPDATA%`/`%LOCALAPPDATA%` under `vcms`.
 //!
-//! The root is `$VCMS_HOME` when set, otherwise `~/.vcms` resolved cross-platform
-//! via the `directories` crate. This mirrors the convention used by tools like
-//! `CARGO_HOME` / `PGDATA`: one predictable, overridable home.
+//! * **Single** — everything nests under one root. Chosen when `$VCMS_HOME` is set
+//!   (the OS-service installer pins it to a system dir like `/var/lib/vcms` or
+//!   `C:\ProgramData\vcms`), or when a legacy `~/.vcms` already holds data (so an
+//!   existing install keeps working untouched).
 
 use std::path::PathBuf;
 
-/// Environment variable that overrides the home directory location.
+/// Environment variable that forces the single-directory layout at a chosen root.
 pub const CMS_HOME_ENV: &str = "VCMS_HOME";
 
-/// The CMS home directory root.
-///
-/// `$VCMS_HOME` wins if set and non-empty. Otherwise `~/.vcms`. As a last resort
-/// (no detectable home directory) falls back to `.vcms` in the current dir.
-pub fn home() -> PathBuf {
+/// Where each class of file lives. Resolved fresh on each call (cheap) so tests and
+/// the service can change `$VCMS_HOME` without a process restart.
+enum Layout {
+    /// One root holding everything (`$VCMS_HOME`, a legacy `~/.vcms`, or a `.vcms`
+    /// fallback when no platform dirs are detectable).
+    Single(PathBuf),
+    /// Per-type platform directories.
+    Split {
+        config: PathBuf,
+        data: PathBuf,
+        cache: PathBuf,
+        state: PathBuf,
+    },
+}
+
+impl Layout {
+    fn config(&self) -> PathBuf {
+        match self {
+            Layout::Single(root) => root.clone(),
+            Layout::Split { config, .. } => config.clone(),
+        }
+    }
+
+    fn data(&self) -> PathBuf {
+        match self {
+            Layout::Single(root) => root.clone(),
+            Layout::Split { data, .. } => data.clone(),
+        }
+    }
+
+    fn cache(&self) -> PathBuf {
+        match self {
+            Layout::Single(root) => root.clone(),
+            Layout::Split { cache, .. } => cache.clone(),
+        }
+    }
+
+    fn state(&self) -> PathBuf {
+        match self {
+            Layout::Single(root) => root.clone(),
+            Layout::Split { state, .. } => state.clone(),
+        }
+    }
+}
+
+/// Resolve the active layout: `$VCMS_HOME` → legacy `~/.vcms` → platform split.
+fn layout() -> Layout {
     if let Some(value) = std::env::var_os(CMS_HOME_ENV)
         && !value.is_empty()
     {
-        return PathBuf::from(value);
+        return Layout::Single(PathBuf::from(value));
     }
 
-    directories::BaseDirs::new()
-        .map(|dirs| dirs.home_dir().join(".vcms"))
-        .unwrap_or_else(|| PathBuf::from(".vcms"))
+    if let Some(base) = directories::BaseDirs::new() {
+        // Back-compat: a pre-existing single `~/.vcms` keeps owning everything so an
+        // upgrade never strands a user's database or secrets.
+        let legacy = base.home_dir().join(".vcms");
+        if legacy.is_dir() {
+            return Layout::Single(legacy);
+        }
+    }
+
+    match directories::ProjectDirs::from("", "", "vcms") {
+        Some(dirs) => split_from(&dirs),
+        // No detectable platform dirs (rare): fall back to a local blob.
+        None => Layout::Single(PathBuf::from(".vcms")),
+    }
 }
 
-/// `~/.vcms/config.toml` — the user-level config file.
+/// Map `ProjectDirs` onto our four directory classes. Logs use the state dir where
+/// the platform has one (Linux), else the local data dir (macOS/Windows).
+fn split_from(dirs: &directories::ProjectDirs) -> Layout {
+    Layout::Split {
+        config: dirs.config_dir().to_path_buf(),
+        data: dirs.data_dir().to_path_buf(),
+        cache: dirs.cache_dir().to_path_buf(),
+        state: dirs.state_dir().unwrap_or_else(|| dirs.data_local_dir()).to_path_buf(),
+    }
+}
+
+/// `config.toml` — the non-secret config file (config dir).
 pub fn config_file() -> PathBuf {
-    home().join("config.toml")
+    layout().config().join("config.toml")
 }
 
-/// `~/.vcms/secrets.toml` — auto-generated secrets file.
+/// `secrets.toml` — auto-generated secrets file (config dir, 0600 on unix).
 pub fn secrets_file() -> PathBuf {
-    home().join("secrets.toml")
+    layout().config().join("secrets.toml")
 }
 
-/// `~/.vcms/vcms.db` — the default SQLite database file.
-pub fn default_db_path() -> PathBuf {
-    home().join("vcms.db")
+/// `.env` — optional environment file loaded at startup (config dir).
+pub fn env_file() -> PathBuf {
+    layout().config().join(".env")
 }
 
-/// `~/.vcms/logs` — directory for rolling log files.
-pub fn logs_dir() -> PathBuf {
-    home().join("logs")
+/// `vcms.db` — the default SQLite database file (data dir).
+pub fn default_db_path() -> PathBuf {
+    layout().data().join("vcms.db")
 }
 
-/// `~/.vcms/storage` — default filesystem storage directory for uploads.
+/// `storage/` — default filesystem storage directory for uploads (data dir).
 pub fn storage_dir() -> PathBuf {
-    home().join("storage")
+    layout().data().join("storage")
 }
 
-/// `~/.vcms/backups` — default local destination for backup artifacts.
+/// `backups/` — default local destination for backup artifacts (data dir).
 pub fn backups_dir() -> PathBuf {
-    home().join("backups")
+    layout().data().join("backups")
 }
 
-/// `~/.vcms/search` — default location for the Tantivy full-text search index.
+/// `search/` — default location for the derived Tantivy index (cache dir).
 pub fn search_dir() -> PathBuf {
-    home().join("search")
+    layout().cache().join("search")
+}
+
+/// `logs/` — directory for rolling log files (state dir).
+pub fn logs_dir() -> PathBuf {
+    layout().state().join("logs")
 }
 
-/// Build the default `DATABASE_URL` (`sqlite://<home>/vcms.db`).
+/// Build the default `DATABASE_URL` (`sqlite://<data>/vcms.db`).
 ///
 /// SQLite URLs use forward slashes, so backslashes are normalized for Windows.
 pub fn default_database_url() -> String {
     format!("sqlite://{}", default_db_path().to_string_lossy().replace('\\', "/"))
 }
 
-/// Create the home directory and its subdirectories (`logs/`, `storage/`).
-///
-/// Called by commands that own/initialize the instance (`serve`, `admin`).
-/// Read-only commands such as `mcp stdio` must not create anything.
+/// Create the directories the running instance writes to (config, data, storage,
+/// logs). Called by commands that own/initialize the instance (`serve`, `admin`);
+/// read-only commands such as `mcp stdio` must not create anything.
 pub fn ensure() -> std::io::Result<()> {
-    let root = home();
-    std::fs::create_dir_all(&root)?;
-    std::fs::create_dir_all(logs_dir())?;
-    std::fs::create_dir_all(storage_dir())?;
+    let layout = layout();
+    for dir in [
+        layout.config(),
+        layout.data(),
+        layout.state().join("logs"),
+        layout.data().join("storage"),
+    ] {
+        std::fs::create_dir_all(dir)?;
+    }
     Ok(())
 }
 
+/// Whether a file sits inside the home root in single-dir mode. Only meaningful for
+/// `$VCMS_HOME`/legacy installs; in split mode there is no single root.
+pub fn single_root() -> Option<PathBuf> {
+    match layout() {
+        Layout::Single(root) => Some(root),
+        Layout::Split { .. } => None,
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
     use crate::test_helpers::with_home;
+    use std::path::Path;
 
     #[test]
-    fn cms_home_env_overrides_root() {
+    fn vcms_home_forces_single_layout() {
         let dir = tempfile::tempdir().expect("temp dir");
         with_home(dir.path(), || {
-            assert_eq!(home(), dir.path());
+            assert_eq!(single_root().as_deref(), Some(dir.path()));
             assert_eq!(config_file(), dir.path().join("config.toml"));
             assert_eq!(secrets_file(), dir.path().join("secrets.toml"));
+            assert_eq!(env_file(), dir.path().join(".env"));
             assert_eq!(default_db_path(), dir.path().join("vcms.db"));
-            assert_eq!(logs_dir(), dir.path().join("logs"));
             assert_eq!(storage_dir(), dir.path().join("storage"));
+            assert_eq!(backups_dir(), dir.path().join("backups"));
+            assert_eq!(search_dir(), dir.path().join("search"));
+            assert_eq!(logs_dir(), dir.path().join("logs"));
         });
     }
 
     #[test]
-    fn ensure_creates_subdirectories() {
+    fn ensure_creates_subdirectories_in_single_mode() {
         let dir = tempfile::tempdir().expect("temp dir");
         let root = dir.path().join("home");
         with_home(&root, || {
@@ -130,4 +215,37 @@ mod tests {
             assert!(!url.contains('\\'));
         });
     }
+
+    #[test]
+    fn split_layout_separates_file_classes() {
+        // Drive the pure mapping directly so the assertion is platform-independent
+        // (real ProjectDirs vary by OS and ambient env).
+        let layout = Layout::Split {
+            config: PathBuf::from("/cfg"),
+            data: PathBuf::from("/dat"),
+            cache: PathBuf::from("/cch"),
+            state: PathBuf::from("/st"),
+        };
+        assert!(layout.config().join("config.toml").starts_with(Path::new("/cfg")));
+        assert!(layout.data().join("vcms.db").starts_with(Path::new("/dat")));
+        assert!(layout.cache().join("search").starts_with(Path::new("/cch")));
+        assert!(layout.state().join("logs").starts_with(Path::new("/st")));
+        // config / data / cache / state are genuinely distinct in split mode.
+        assert_ne!(layout.config(), layout.data());
+        assert_ne!(layout.data(), layout.cache());
+        assert_ne!(layout.cache(), layout.state());
+    }
+
+    #[test]
+    fn split_state_falls_back_to_local_data_when_absent() {
+        // When a platform lacks a state dir, logs must still resolve (we feed the
+        // local-data dir into `state`). Modeled here as state == data.
+        let layout = Layout::Split {
+            config: PathBuf::from("/cfg"),
+            data: PathBuf::from("/dat"),
+            cache: PathBuf::from("/cch"),
+            state: PathBuf::from("/dat"),
+        };
+        assert!(layout.state().join("logs").starts_with(Path::new("/dat")));
+    }
 }
diff --git a/apps/backend/src/secrets.rs b/apps/backend/src/secrets.rs
index e3800a3b..18e6e16d 100644
--- a/apps/backend/src/secrets.rs
+++ b/apps/backend/src/secrets.rs
@@ -1,4 +1,4 @@
-//! Persisted instance secrets (`~/.vcms/secrets.toml`).
+//! Persisted instance secrets (`secrets.toml` in the config dir).
 //!
 //! On first `serve`/`admin`, a random `HMAC_SECRET` value is
 //! generated and written to `secrets.toml` (perms `0600` on unix). Every later
diff --git a/apps/backend/src/server.rs b/apps/backend/src/server.rs
index cc63cea3..99c3504b 100644
--- a/apps/backend/src/server.rs
+++ b/apps/backend/src/server.rs
@@ -218,8 +218,8 @@ pub async fn shutdown_signal() {
 pub fn initialize_storage(config: &Config) -> Arc<StorageRegistry> {
     let mut storage_registry = StorageRegistry::new();
 
-    // Use an explicit filesystem path if set; otherwise default to ~/.vcms/storage
-    // so uploads work out of the box — unless S3 is configured and takes over.
+    // Use an explicit filesystem path if set; otherwise default to the data dir's
+    // storage/ so uploads work out of the box — unless S3 is configured and takes over.
     let fs_path = match (&config.storage_fs_path, config.has_s3()) {
         (Some(path), _) => Some(path.clone()),
         (None, false) => Some(crate::paths::storage_dir().to_string_lossy().into_owned()),

From eda22efb23fe3490c8e24ed1973ef5b134e87318 Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Tue, 30 Jun 2026 20:30:18 +0530
Subject: [PATCH 06/44] feat(service): pin OS service homes to system-owned
 directories

Replace per-user ~/.vcms with platform-specific system directories for
service installs: /var/lib/vcms (Linux), ~/Library/Application Support/vcms
(macOS), C:\ProgramData\vcms (Windows). Remove the user_home() helper
that resolved tilde expansion, since the daemon no longer nests under a
user's home. Update CLI help text to reflect the split layout.
---
 apps/backend/src/cli.rs           | 29 +++++++++++++++--------------
 apps/backend/src/service/linux.rs | 17 +++++++++++------
 apps/backend/src/service/macos.rs | 15 ++++++++++-----
 apps/backend/src/service/mod.rs   | 24 ++++--------------------
 4 files changed, 40 insertions(+), 45 deletions(-)

diff --git a/apps/backend/src/cli.rs b/apps/backend/src/cli.rs
index b8f7b8f2..ce41b2ba 100644
--- a/apps/backend/src/cli.rs
+++ b/apps/backend/src/cli.rs
@@ -9,18 +9,18 @@ use clap::{Parser, Subcommand};
     version,
     about = "Headless CMS server",
     long_about = "Headless CMS server.\n\n\
-        All runtime files live under one home directory ($VCMS_HOME, default ~/.vcms): \
-        config.toml, secrets.toml, the SQLite database, logs/, and storage/. \
-        `vcms serve` creates it on first run and generates secrets if absent.",
-    after_help = "DATA DIRECTORY ($VCMS_HOME, default ~/.vcms):\n  \
-        config.toml   non-secret config (written by `vcms config init`)\n  \
-        secrets.toml  auto-generated HMAC + backup secrets (0600 on unix)\n  \
-        vcms.db       default SQLite database (+ -wal / -shm)\n  \
-        logs/         rolling logs when [log] output = \"file\"\n  \
-        storage/      default filesystem storage for uploads\n\n\
+        Runtime files default to the platform's per-type directories (config, data, \
+        cache, state) via the `directories` crate. Set $VCMS_HOME to keep everything \
+        under one root instead (the `vcms service` installer pins it to a system dir). \
+        `vcms serve` creates what it needs on first run and generates secrets if absent.",
+    after_help = "DATA DIRECTORIES (defaults; set $VCMS_HOME for a single root):\n  \
+        config dir   config.toml, secrets.toml (0600 on unix), .env\n  \
+        data dir     vcms.db (+ -wal / -shm), storage/, backups/\n  \
+        cache dir    search/ (derived Tantivy index, rebuildable)\n  \
+        state dir    logs/ (when [log] output = \"file\")\n\n\
         KEY ENVIRONMENT (env overrides config; CLI flags override env):\n  \
-        VCMS_HOME     home directory                   [default: ~/.vcms]\n  \
-        DATABASE_URL  sqlite/postgres/mysql URL        [default: sqlite://~/.vcms/vcms.db]\n  \
+        VCMS_HOME     force single-root layout         [default: platform split dirs]\n  \
+        DATABASE_URL  sqlite/postgres/mysql URL        [default: sqlite://<data dir>/vcms.db]\n  \
         HMAC_SECRET   token-lookup HMAC key            [auto-generated to secrets.toml]"
 )]
 pub struct Cli {
@@ -33,7 +33,7 @@ pub struct Cli {
     pub bind: Option<String>,
 
     /// Database URL, e.g. sqlite:path / postgres://… (overrides config + env)
-    /// [default: sqlite://~/.vcms/vcms.db].
+    /// [default: sqlite://<data dir>/vcms.db].
     #[arg(long, global = true, value_name = "URL")]
     pub database_url: Option<String>,
 
@@ -123,8 +123,9 @@ pub enum BackupAction {
 pub enum ServiceAction {
     /// Install the service, enable it at boot, and start it now (requires root/admin).
     ///
-    /// The service runs `vcms serve` as the chosen OS account; runtime files live
-    /// under that account's `$VCMS_HOME` (default `~/.vcms`).
+    /// The service runs `vcms serve` as the chosen OS account; `VCMS_HOME` is pinned
+    /// to a system dir (Linux `/var/lib/vcms`, macOS `/Library/Application Support/vcms`,
+    /// Windows `C:\ProgramData\vcms`) so all runtime files live under one owned root.
     Install {
         /// OS account the service runs as.
         ///
diff --git a/apps/backend/src/service/linux.rs b/apps/backend/src/service/linux.rs
index eb2dabd3..67e3862a 100644
--- a/apps/backend/src/service/linux.rs
+++ b/apps/backend/src/service/linux.rs
@@ -1,14 +1,17 @@
 //! systemd integration for `vcms service` on Linux.
 
-use std::path::Path;
+use std::path::{Path, PathBuf};
 use std::process::Command;
 
-use super::{InstallOptions, SERVICE_NAME, require_root, resolve_run_user, systemd_unit, user_home};
+use super::{InstallOptions, SERVICE_NAME, require_root, resolve_run_user, systemd_unit};
 use crate::cli::{Cli, ServiceAction};
 
 /// Where the generated unit file is written.
 const UNIT_PATH: &str = "/etc/systemd/system/vcms.service";
 
+/// System data directory the daemon owns (FHS convention for service state).
+const SERVICE_HOME: &str = "/var/lib/vcms";
+
 pub fn dispatch(action: &ServiceAction, _cli: &Cli) -> Result<(), Box<dyn std::error::Error>> {
     match action {
         ServiceAction::Install { user } => install(user.as_deref()),
@@ -28,7 +31,9 @@ fn install(user: Option<&str>) -> Result<(), Box<dyn std::error::Error>> {
     }
 
     let user = resolve_run_user(user)?;
-    let vcms_home = user_home(&user)?.join(".vcms");
+    // The daemon stores everything under one system dir (VCMS_HOME single-layout),
+    // owned by the run-as account — not that account's per-user `~/.config` etc.
+    let vcms_home = PathBuf::from(SERVICE_HOME);
     let exe_path = std::env::current_exe()?;
     let opts = InstallOptions {
         user: user.clone(),
@@ -59,7 +64,7 @@ fn uninstall() -> Result<(), Box<dyn std::error::Error>> {
         println!("Removed {UNIT_PATH}");
     }
     run(Command::new("systemctl").arg("daemon-reload"))?;
-    println!("Service '{SERVICE_NAME}' uninstalled. Your data under ~/.vcms was left intact.");
+    println!("Service '{SERVICE_NAME}' uninstalled. Your data under {SERVICE_HOME} was left intact.");
     Ok(())
 }
 
@@ -90,8 +95,8 @@ fn status() -> Result<(), Box<dyn std::error::Error>> {
     Ok(())
 }
 
-/// Create the run-as user's `~/.vcms` + optional `.env` (0600) and hand ownership
-/// to that account so the daemon can read and write its home.
+/// Create the service home (`/var/lib/vcms`) + optional `.env` (0600) and hand
+/// ownership to the run-as account so the daemon can read and write it.
 fn prepare_home(opts: &InstallOptions) -> Result<(), Box<dyn std::error::Error>> {
     super::reject_symlink(&opts.vcms_home)?;
     std::fs::create_dir_all(&opts.vcms_home)?;
diff --git a/apps/backend/src/service/macos.rs b/apps/backend/src/service/macos.rs
index 0b1ba80c..00623d62 100644
--- a/apps/backend/src/service/macos.rs
+++ b/apps/backend/src/service/macos.rs
@@ -1,14 +1,17 @@
 //! launchd integration for `vcms service` on macOS (system LaunchDaemon).
 
-use std::path::Path;
+use std::path::{Path, PathBuf};
 use std::process::Command;
 
-use super::{InstallOptions, LAUNCHD_LABEL, launchd_plist, require_root, resolve_run_user, user_home};
+use super::{InstallOptions, LAUNCHD_LABEL, launchd_plist, require_root, resolve_run_user};
 use crate::cli::{Cli, ServiceAction};
 
 /// Where the generated LaunchDaemon plist is written.
 const PLIST_PATH: &str = "/Library/LaunchDaemons/local.vcms.plist";
 
+/// System data directory the daemon owns (macOS convention for shared app data).
+const SERVICE_HOME: &str = "/Library/Application Support/vcms";
+
 /// Modern launchctl service target (`system/<label>`).
 fn target() -> String {
     format!("system/{LAUNCHD_LABEL}")
@@ -27,7 +30,8 @@ pub fn dispatch(action: &ServiceAction, _cli: &Cli) -> Result<(), Box<dyn std::e
 fn install(user: Option<&str>) -> Result<(), Box<dyn std::error::Error>> {
     require_root("install")?;
     let user = resolve_run_user(user)?;
-    let vcms_home = user_home(&user)?.join(".vcms");
+    // One system dir (VCMS_HOME single-layout), owned by the run-as account.
+    let vcms_home = PathBuf::from(SERVICE_HOME);
     let exe_path = std::env::current_exe()?;
     let opts = InstallOptions {
         user: user.clone(),
@@ -62,7 +66,7 @@ fn uninstall() -> Result<(), Box<dyn std::error::Error>> {
         std::fs::remove_file(PLIST_PATH)?;
         println!("Removed {PLIST_PATH}");
     }
-    println!("Service '{LAUNCHD_LABEL}' uninstalled. Your data under ~/.vcms was left intact.");
+    println!("Service '{LAUNCHD_LABEL}' uninstalled. Your data under {SERVICE_HOME} was left intact.");
     Ok(())
 }
 
@@ -90,7 +94,8 @@ fn status() -> Result<(), Box<dyn std::error::Error>> {
     Ok(())
 }
 
-/// Create the run-as user's `~/.vcms` + optional `.env` (0600), owned by that user.
+/// Create the service home (`/Library/Application Support/vcms`) + optional `.env`
+/// (0600), owned by the run-as account.
 fn prepare_home(opts: &InstallOptions) -> Result<(), Box<dyn std::error::Error>> {
     super::reject_symlink(&opts.vcms_home)?;
     std::fs::create_dir_all(&opts.vcms_home)?;
diff --git a/apps/backend/src/service/mod.rs b/apps/backend/src/service/mod.rs
index 142b7079..40c12241 100644
--- a/apps/backend/src/service/mod.rs
+++ b/apps/backend/src/service/mod.rs
@@ -245,22 +245,6 @@ pub(crate) fn resolve_run_user(explicit: Option<&str>) -> Result<String, Box<dyn
     Ok(current)
 }
 
-/// Resolve a user's home directory via shell tilde expansion. The username must be
-/// pre-validated by [`validate_username`] (no shell metacharacters).
-#[cfg(unix)]
-pub(crate) fn user_home(user: &str) -> Result<PathBuf, Box<dyn std::error::Error>> {
-    validate_username(user)?;
-    let output = std::process::Command::new("sh")
-        .arg("-c")
-        .arg(format!("echo ~{user}"))
-        .output()?;
-    let home = String::from_utf8_lossy(&output.stdout).trim().to_string();
-    if home.is_empty() || home.starts_with('~') {
-        return Err(format!("could not resolve home directory for user '{user}'").into());
-    }
-    Ok(PathBuf::from(home))
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -270,7 +254,7 @@ mod tests {
         InstallOptions {
             user: "deploy".into(),
             exe_path: PathBuf::from("/usr/local/bin/vcms"),
-            vcms_home: PathBuf::from("/home/deploy/.vcms"),
+            vcms_home: PathBuf::from("/var/lib/vcms"),
         }
     }
 
@@ -279,8 +263,8 @@ mod tests {
         let unit = systemd_unit(&sample());
         assert!(unit.contains("ExecStart=/usr/local/bin/vcms serve"));
         assert!(unit.contains("User=deploy"));
-        assert!(unit.contains("Environment=VCMS_HOME=/home/deploy/.vcms"));
-        assert!(unit.contains("EnvironmentFile=-/home/deploy/.vcms/.env"));
+        assert!(unit.contains("Environment=VCMS_HOME=/var/lib/vcms"));
+        assert!(unit.contains("EnvironmentFile=-/var/lib/vcms/.env"));
         assert!(unit.contains("Restart=always"));
         assert!(unit.contains("WantedBy=multi-user.target"));
     }
@@ -293,7 +277,7 @@ mod tests {
         assert!(plist.contains("<string>serve</string>"));
         assert!(plist.contains("<string>deploy</string>"));
         assert!(plist.contains("<key>VCMS_HOME</key>"));
-        assert!(plist.contains("<string>/home/deploy/.vcms</string>"));
+        assert!(plist.contains("<string>/var/lib/vcms</string>"));
     }
 
     #[test]

From aaa373d3811efaf9142802db8142663c81b206bc Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Tue, 30 Jun 2026 20:30:37 +0530
Subject: [PATCH 07/44] refactor(mcp): rewrite stdio transport as thin HTTP
 proxy

Replace the in-process MCP stdio server (which opened the database,
secrets, and search index directly) with a stateless HTTP proxy that
forwards JSON-RPC between stdin/stdout and the running server's /mcp
endpoint. This means the stdio process needs no disk access and works
even when data belongs to a privileged service account.

- Remove CmsServer::new_stdio(), verify_stdio_token(), and stdio_token
- Rewrite transports/stdio.rs as a reqwest-based HTTP proxy
- Simplify run_mcp_stdio() to just read VCMS_MCP_TOKEN and VCMS_MCP_URL
- Replace init_stdio_tracing() with config-free init_proxy_tracing()
- Delete old mcp_stdio.rs tests, add proxy-focused tests
---
 apps/backend/src/main.rs                    |  87 ++----
 apps/backend/src/mcp/auth.rs                |   6 -
 apps/backend/src/mcp/server.rs              |  20 --
 apps/backend/src/mcp/transports/stdio.rs    | 277 ++++++++++++++++++-
 apps/backend/src/tracing.rs                 |  34 +--
 apps/backend/tests/mcp/main.rs              |   1 +
 apps/backend/tests/mcp/stdio_proxy_tests.rs | 168 ++++++++++++
 apps/backend/tests/mcp_stdio.rs             | 289 --------------------
 8 files changed, 464 insertions(+), 418 deletions(-)
 create mode 100644 apps/backend/tests/mcp/stdio_proxy_tests.rs
 delete mode 100644 apps/backend/tests/mcp_stdio.rs

diff --git a/apps/backend/src/main.rs b/apps/backend/src/main.rs
index 5d9998e8..28bf2e61 100644
--- a/apps/backend/src/main.rs
+++ b/apps/backend/src/main.rs
@@ -1,29 +1,26 @@
 use clap::Parser;
 use cms::cli::{AdminAction, BackupAction, Cli, Command, ConfigAction, McpTransport};
 use cms::config::{self, Config};
-use cms::database::{connect_db_without_migrations, init_db_with_config};
-use cms::middleware::auth::Actor;
+use cms::database::init_db_with_config;
 use cms::repository::Repository;
-use cms::services::Services;
 
 use std::error::Error;
-use std::sync::Arc;
-use tracing::{debug, info};
+use tracing::info;
 
 #[tokio::main]
 async fn main() {
     // Load env from the cwd `.env` (dev) first, then `$VCMS_HOME/.env` (installed
-    // services + `mcp stdio`, which run from an arbitrary cwd). dotenvy is
-    // first-wins, so real env vars and the cwd file keep precedence over the home
-    // file. VCMS_HOME must be a real env var — resolved here before the home `.env`
-    // loads — never set inside that file (chicken-and-egg).
+    // services run from an arbitrary cwd). dotenvy is first-wins, so real env vars and
+    // the cwd file keep precedence over the config-dir file. VCMS_HOME must be a real
+    // env var — resolved here before the `.env` loads — never set inside that file
+    // (chicken-and-egg).
     dotenvy::dotenv().ok();
-    let home_env = cms::paths::home().join(".env");
-    match dotenvy::from_path(&home_env) {
+    let env_file = cms::paths::env_file();
+    match dotenvy::from_path(&env_file) {
         Ok(()) => {}
         Err(e) if e.not_found() => {} // missing file is fine
         Err(e) => {
-            eprintln!("Error: cannot load {}: {e}", home_env.display());
+            eprintln!("Error: cannot load {}: {e}", env_file.display());
             std::process::exit(1);
         }
     }
@@ -44,7 +41,7 @@ async fn main() {
         Some(Command::Service { action }) => cms::service::run_service(action, &cli).await,
         Some(Command::Mcp {
             transport: McpTransport::Stdio,
-        }) => run_mcp_stdio(&cli).await,
+        }) => run_mcp_stdio().await,
         Some(Command::Serve) | None => cms::server::run(&cli, cms::server::shutdown_signal()).await,
     };
 
@@ -54,64 +51,24 @@ async fn main() {
     }
 }
 
-async fn run_mcp_stdio(cli: &Cli) -> Result<(), Box<dyn Error>> {
-    // Read-only: never create the home dir, database, or secrets file here. The
-    // persisted secrets written by `vcms serve` are what make this process verify
-    // the site token with the same HMAC secret the server signed it with.
-    if cms::secrets::load()?.is_none() && std::env::var("HMAC_SECRET").is_err() {
-        return Err("No instance secrets found. Run `vcms serve` once to initialize \
-                    ~/.vcms (or set HMAC_SECRET) before `vcms mcp stdio`."
-            .into());
-    }
-
-    let config = Config::load(cli)?;
-    cms::tracing::init_stdio_tracing(&config);
-
-    info!("Starting standalone MCP stdio process");
-    debug!(
-        database_backend = ?cms::database::backend::DatabaseBackend::from_url(&config.database_url),
-        "MCP stdio configuration loaded"
-    );
-
-    if let Err(error) = config.validate_security() {
-        return Err(format!("Invalid production security configuration: {error}").into());
-    }
+async fn run_mcp_stdio() -> Result<(), Box<dyn Error>> {
+    // A thin proxy to the running server's `/mcp` endpoint — it touches no disk
+    // (no home dir, database, secrets, or search index), so it works even when those
+    // belong to the privileged service account. It needs only a server URL and a
+    // `vcms_site_*` access token, forwarded as the bearer credential.
+    cms::tracing::init_proxy_tracing();
 
     let token = std::env::var("VCMS_MCP_TOKEN").map_err(|_| "VCMS_MCP_TOKEN is required for `vcms mcp stdio`")?;
-    if token.trim().is_empty() {
+    let token = token.trim().to_string();
+    if token.is_empty() {
         return Err("VCMS_MCP_TOKEN must not be empty".into());
     }
 
-    let pool = connect_db_without_migrations(&config).await?;
-    info!("Existing CMS database schema is compatible; no migrations were run");
-
-    let repository = Repository::new(&pool);
-    let actor = cms::mcp::auth::verify_stdio_token(&token, &repository, &config.hmac_secret)
-        .await
-        .map_err(|error| format!("MCP stdio authentication failed: {}", error.message))?;
-    match &actor {
-        Actor::ApiKey(api_key) => info!(
-            site_id = %api_key.site_id,
-            permission = %api_key.permission,
-            "MCP stdio site token authenticated"
-        ),
-        Actor::User(_) => return Err("MCP stdio requires a CMS site access token".into()),
-    }
+    let base = std::env::var("VCMS_MCP_URL").unwrap_or_else(|_| "http://127.0.0.1:3000".to_string());
+    let endpoint = format!("{}/mcp", base.trim_end_matches('/'));
 
-    let storage_registry = cms::server::initialize_storage(&config);
-    let repository = Arc::new(repository);
-    let config = Arc::new(config);
-    // Read-only search: stdio can run alongside the server without contending for
-    // the writer lock; its content writes enqueue for the server to index.
-    let services = Arc::new(Services::new_read_only(repository.clone(), &pool, &config));
-    let server = cms::mcp::server::CmsServer::new_stdio(services, repository, storage_registry, config, token);
-
-    let result = cms::mcp::transports::stdio::serve(server).await;
-    match &result {
-        Ok(()) => info!("Standalone MCP stdio process exited cleanly"),
-        Err(error) => tracing::error!(error = %error, "Standalone MCP stdio process exiting after failure"),
-    }
-    result
+    info!(%endpoint, "Starting MCP stdio proxy");
+    cms::mcp::transports::stdio::serve(endpoint, token).await
 }
 
 fn run_config(action: &ConfigAction, cli: &Cli) -> Result<(), Box<dyn Error>> {
diff --git a/apps/backend/src/mcp/auth.rs b/apps/backend/src/mcp/auth.rs
index 3e41e443..3a14ab71 100644
--- a/apps/backend/src/mcp/auth.rs
+++ b/apps/backend/src/mcp/auth.rs
@@ -63,12 +63,6 @@ pub fn resolve_actor(ctx: &RequestContext<RoleServer>) -> Result<Actor, ErrorDat
     Ok(actor)
 }
 
-pub async fn verify_stdio_token(token: &str, repository: &Repository, hmac_secret: &str) -> Result<Actor, ErrorData> {
-    verify_access_token(token, repository, hmac_secret)
-        .await
-        .map_err(|(_, Json(error))| mcp_error(ErrorCode::INVALID_REQUEST, error.message))
-}
-
 pub async fn authenticate_mcp_request(mut request: Request<Body>, next: Next) -> Response {
     let repository = match request.extensions().get::<Arc<Repository>>() {
         Some(repository) => repository.clone(),
diff --git a/apps/backend/src/mcp/server.rs b/apps/backend/src/mcp/server.rs
index 359f6106..6e3fd9af 100644
--- a/apps/backend/src/mcp/server.rs
+++ b/apps/backend/src/mcp/server.rs
@@ -28,7 +28,6 @@ pub struct CmsServer {
     pub storage_registry: Arc<StorageRegistry>,
     pub config: Arc<Config>,
     pub authorizer: Arc<AuthorizationService>,
-    stdio_token: Option<Arc<str>>,
 }
 
 #[tool_router]
@@ -46,22 +45,9 @@ impl CmsServer {
             storage_registry,
             config,
             authorizer,
-            stdio_token: None,
         }
     }
 
-    pub fn new_stdio(
-        services: Arc<Services>,
-        repository: Arc<Repository>,
-        storage_registry: Arc<StorageRegistry>,
-        config: Arc<Config>,
-        token: String,
-    ) -> Self {
-        let mut server = Self::new(services, repository, storage_registry, config);
-        server.stdio_token = Some(Arc::from(token));
-        server
-    }
-
     #[tool(description = "Get details of a specific site by ID")]
     async fn get_site(
         &self,
@@ -488,12 +474,6 @@ impl ServerHandler for CmsServer {
 
 impl CmsServer {
     async fn authenticate_context(&self, ctx: &mut RequestContext<RoleServer>) -> Result<Actor, McpError> {
-        if let Some(token) = &self.stdio_token {
-            let actor = crate::mcp::auth::verify_stdio_token(token, &self.repository, &self.config.hmac_secret).await?;
-            ctx.extensions.insert(actor.clone());
-            return Ok(actor);
-        }
-
         self.resolve_actor(ctx)
     }
 
diff --git a/apps/backend/src/mcp/transports/stdio.rs b/apps/backend/src/mcp/transports/stdio.rs
index 5cf831f5..9ced9474 100644
--- a/apps/backend/src/mcp/transports/stdio.rs
+++ b/apps/backend/src/mcp/transports/stdio.rs
@@ -1,19 +1,274 @@
-use rmcp::{ServiceExt, transport};
+//! `vcms mcp stdio` — a thin proxy between an MCP client's stdin/stdout and the
+//! running server's Streamable HTTP `/mcp` endpoint.
+//!
+//! The stdio process runs under the *invoking* user from an arbitrary cwd, while the
+//! server runs as the (often privileged) service account that owns the database,
+//! secrets, and search index. Rather than open those files directly — which fails
+//! when they belong to the service account — this proxy forwards JSON-RPC over HTTP
+//! and lets the server do all disk I/O. It needs only a URL and a `vcms_site_*`
+//! access token, which it injects as the `Authorization: Bearer` header.
+//!
+//! The server runs the HTTP transport in stateless, JSON-response mode (no SSE, no
+//! `Mcp-Session-Id`), so a flat per-message proxy is sufficient: read a
+//! newline-delimited JSON-RPC message from stdin, POST it, write the JSON reply back.
 
-use crate::mcp::server::CmsServer;
+use serde_json::Value;
+use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
 
-pub async fn serve(server: CmsServer) -> Result<(), Box<dyn std::error::Error>> {
-    tracing::info!("MCP stdio transport active");
-    let service = server.serve(transport::stdio()).await?;
+/// Run the proxy loop until stdin closes (EOF → clean exit).
+///
+/// `endpoint` is the fully-qualified MCP URL (e.g. `http://127.0.0.1:3000/mcp`) and
+/// `token` is the `vcms_site_*` access token forwarded as the bearer credential.
+pub async fn serve(endpoint: String, token: String) -> Result<(), Box<dyn std::error::Error>> {
+    let client = reqwest::Client::new();
+    let mut lines = BufReader::new(tokio::io::stdin()).lines();
+    let mut stdout = tokio::io::stdout();
 
-    match service.waiting().await {
-        Ok(reason) => {
-            tracing::info!(?reason, "MCP stdio transport stopped");
-            Ok(())
+    tracing::info!(%endpoint, "MCP stdio proxy active");
+
+    while let Some(line) = lines.next_line().await? {
+        let message = line.trim();
+        if message.is_empty() {
+            continue;
+        }
+        if let Some(response) = forward(&client, &endpoint, &token, message).await {
+            stdout.write_all(response.as_bytes()).await?;
+            stdout.write_all(b"\n").await?;
+            stdout.flush().await?;
+        }
+    }
+
+    tracing::info!("MCP stdio proxy stopped (stdin closed)");
+    Ok(())
+}
+
+/// Forward one JSON-RPC message to the server and return the line to write to stdout,
+/// or `None` when nothing should be written (a notification, which carries no `id`
+/// and expects no reply). On a transport failure for a request we synthesize a
+/// JSON-RPC error so the client sees a clean failure and the proxy keeps running.
+async fn forward(client: &reqwest::Client, endpoint: &str, token: &str, message: &str) -> Option<String> {
+    let parsed = serde_json::from_str::<Value>(message).ok();
+    // Requests and batches expect a response; a lone notification object (no `id`)
+    // does not. Unparseable input is forwarded so the server returns a proper
+    // JSON-RPC parse error.
+    let (needs_response, id) = match &parsed {
+        Some(Value::Object(obj)) => (obj.contains_key("id"), obj.get("id").cloned()),
+        Some(Value::Array(_)) => (true, None), // batch
+        _ => (true, None),                     // unparseable → let the server reject it
+    };
+
+    let result = client
+        .post(endpoint)
+        .header(reqwest::header::AUTHORIZATION, format!("Bearer {token}"))
+        .header(reqwest::header::CONTENT_TYPE, "application/json")
+        .header(reqwest::header::ACCEPT, "application/json, text/event-stream")
+        .body(message.to_string())
+        .send()
+        .await;
+
+    let response = match result {
+        Ok(response) => response,
+        Err(error) => {
+            return error_line(
+                needs_response,
+                &id,
+                format!("cannot reach vcms server at {endpoint}: {error}"),
+            );
         }
+    };
+
+    let status = response.status();
+    let content_type = response
+        .headers()
+        .get(reqwest::header::CONTENT_TYPE)
+        .and_then(|value| value.to_str().ok())
+        .unwrap_or_default()
+        .to_string();
+
+    let body = match response.text().await {
+        Ok(body) => body,
         Err(error) => {
-            tracing::error!(error = %error, "MCP stdio transport failed");
-            Err(error.into())
+            return error_line(
+                needs_response,
+                &id,
+                format!("reading vcms server response failed: {error}"),
+            );
         }
+    };
+
+    if !needs_response {
+        return None; // notification: server replies 202 with an empty body
+    }
+
+    // A non-2xx is an auth/host/transport failure (e.g. 401 for a bad token), not a
+    // JSON-RPC reply. Wrap it so the client sees a proper JSON-RPC error envelope.
+    if !status.is_success() {
+        let detail = http_error_detail(&body);
+        return error_line(needs_response, &id, format!("vcms server returned {status}: {detail}"));
+    }
+
+    // json-response mode returns `application/json`; defensively unwrap a single SSE
+    // frame if the server ever streams one back.
+    let payload = if content_type.contains("text/event-stream") {
+        extract_sse_data(&body).unwrap_or(body)
+    } else {
+        body
+    };
+    let payload = payload.trim();
+    if payload.is_empty() {
+        return error_line(
+            needs_response,
+            &id,
+            "vcms server returned an empty response".to_string(),
+        );
+    }
+
+    // Re-serialize compactly so the line carries no embedded newlines (MCP stdio
+    // framing is one message per line). Fall back to the raw payload if it isn't JSON.
+    Some(
+        serde_json::from_str::<Value>(payload)
+            .map(|value| value.to_string())
+            .unwrap_or_else(|_| payload.replace('\n', " ")),
+    )
+}
+
+/// Build a JSON-RPC error line for a failed request, or `None` for a notification
+/// (which has no `id` to respond to).
+fn error_line(needs_response: bool, id: &Option<Value>, message: String) -> Option<String> {
+    if !needs_response {
+        tracing::warn!(%message, "MCP notification forward failed");
+        return None;
+    }
+    let error = serde_json::json!({
+        "jsonrpc": "2.0",
+        "id": id.clone().unwrap_or(Value::Null),
+        "error": { "code": -32603, "message": message },
+    });
+    Some(error.to_string())
+}
+
+/// Concatenate the `data:` lines of an SSE payload into a single JSON string.
+fn extract_sse_data(body: &str) -> Option<String> {
+    let mut data = String::new();
+    for line in body.lines() {
+        if let Some(rest) = line.strip_prefix("data:") {
+            data.push_str(rest.trim_start());
+        }
+    }
+    (!data.is_empty()).then_some(data)
+}
+
+/// Pull a human-readable detail out of an error response body. The server's auth
+/// failures are `{"error": "..."}`; fall back to the raw trimmed body otherwise.
+fn http_error_detail(body: &str) -> String {
+    serde_json::from_str::<Value>(body)
+        .ok()
+        .and_then(|value| value.get("error").and_then(Value::as_str).map(str::to_string))
+        .unwrap_or_else(|| body.trim().to_string())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use axum::Router;
+    use axum::body::Bytes;
+    use axum::http::{HeaderMap, StatusCode};
+    use axum::routing::post;
+    use std::net::SocketAddr;
+
+    /// A stub `/mcp` that echoes the received Authorization/Accept headers back inside
+    /// a JSON-RPC result (for requests) and 202-accepts notifications.
+    async fn spawn_stub() -> SocketAddr {
+        let app = Router::new().route(
+            "/mcp",
+            post(|headers: HeaderMap, body: Bytes| async move {
+                let header = |name: &str| {
+                    headers
+                        .get(name)
+                        .and_then(|value| value.to_str().ok())
+                        .unwrap_or_default()
+                        .to_string()
+                };
+                let auth = header("authorization");
+                let accept = header("accept");
+                let parsed: Value = serde_json::from_slice(&body).unwrap_or(Value::Null);
+                let response_headers = [("content-type", "application/json")];
+                match parsed.get("id") {
+                    None => (StatusCode::ACCEPTED, response_headers, String::new()),
+                    Some(id) => {
+                        let reply = serde_json::json!({
+                            "jsonrpc": "2.0",
+                            "id": id,
+                            "result": { "auth": auth, "accept": accept },
+                        });
+                        (StatusCode::OK, response_headers, reply.to_string())
+                    }
+                }
+            }),
+        );
+        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let addr = listener.local_addr().unwrap();
+        tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
+        addr
+    }
+
+    #[tokio::test]
+    async fn forwards_bearer_and_relays_response() {
+        let addr = spawn_stub().await;
+        let endpoint = format!("http://{addr}/mcp");
+        let out = forward(
+            &reqwest::Client::new(),
+            &endpoint,
+            "vcms_site_test",
+            r#"{"jsonrpc":"2.0","id":1,"method":"tools/list"}"#,
+        )
+        .await
+        .expect("a request must produce a response line");
+        let value: Value = serde_json::from_str(&out).unwrap();
+        assert_eq!(value["id"], 1);
+        assert_eq!(value["result"]["auth"], "Bearer vcms_site_test");
+        assert!(value["result"]["accept"].as_str().unwrap().contains("application/json"));
+    }
+
+    #[tokio::test]
+    async fn notification_produces_no_output() {
+        let addr = spawn_stub().await;
+        let endpoint = format!("http://{addr}/mcp");
+        let out = forward(
+            &reqwest::Client::new(),
+            &endpoint,
+            "t",
+            r#"{"jsonrpc":"2.0","method":"notifications/initialized"}"#,
+        )
+        .await;
+        assert!(out.is_none());
+    }
+
+    #[tokio::test]
+    async fn unreachable_server_yields_jsonrpc_error_for_request() {
+        // Port 1 refuses immediately on all supported platforms.
+        let out = forward(
+            &reqwest::Client::new(),
+            "http://127.0.0.1:1/mcp",
+            "t",
+            r#"{"jsonrpc":"2.0","id":7,"method":"tools/list"}"#,
+        )
+        .await
+        .expect("a request must produce an error line");
+        let value: Value = serde_json::from_str(&out).unwrap();
+        assert_eq!(value["id"], 7);
+        assert_eq!(value["error"]["code"], -32603);
+    }
+
+    #[tokio::test]
+    async fn unreachable_server_swallows_notification() {
+        let out = forward(
+            &reqwest::Client::new(),
+            "http://127.0.0.1:1/mcp",
+            "t",
+            r#"{"jsonrpc":"2.0","method":"ping"}"#,
+        )
+        .await;
+        assert!(out.is_none());
     }
 }
diff --git a/apps/backend/src/tracing.rs b/apps/backend/src/tracing.rs
index d45d1477..7fa34a06 100644
--- a/apps/backend/src/tracing.rs
+++ b/apps/backend/src/tracing.rs
@@ -85,33 +85,13 @@ pub fn init_tracing(config: &crate::config::Config) -> Option<tracing_appender::
     }
 }
 
-pub fn init_stdio_tracing(config: &crate::config::Config) {
-    let env_filter = EnvFilter::new(&config.log_level);
-    let annotations = config.log_annotations;
-
-    if config.log_format == "json" {
-        let layer = fmt::layer()
-            .with_writer(std::io::stderr)
-            .with_target(true)
-            .with_file(annotations)
-            .with_line_number(annotations)
-            .json();
-        tracing_subscriber::registry().with(env_filter).with(layer).init();
-    } else {
-        let layer = fmt::layer()
-            .with_writer(std::io::stderr)
-            .with_target(true)
-            .with_file(annotations)
-            .with_line_number(annotations)
-            .pretty();
-        tracing_subscriber::registry().with(env_filter).with(layer).init();
-    }
-
-    tracing::info!(
-        log_output = "stderr",
-        log_format = %config.log_format,
-        "MCP stdio tracing initialized"
-    );
+/// Minimal stderr tracing for `vcms mcp stdio`, which is a thin proxy that loads no
+/// `Config` (it touches no disk). The filter comes straight from `RUST_LOG`, falling
+/// back to a quiet default. stdout is the MCP protocol channel, so logs go to stderr.
+pub fn init_proxy_tracing() {
+    let env_filter = EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new("vcms=info,cms=info"));
+    let layer = fmt::layer().with_writer(std::io::stderr).with_target(true);
+    tracing_subscriber::registry().with(env_filter).with(layer).init();
 }
 
 pub async fn trace_request(req: Request, next: Next) -> Response {
diff --git a/apps/backend/tests/mcp/main.rs b/apps/backend/tests/mcp/main.rs
index 9450c8d8..050aa844 100644
--- a/apps/backend/tests/mcp/main.rs
+++ b/apps/backend/tests/mcp/main.rs
@@ -8,4 +8,5 @@ mod protocol_tests;
 mod resource_tests;
 mod singleton_tests;
 mod site_tests;
+mod stdio_proxy_tests;
 mod webhook_tests;
diff --git a/apps/backend/tests/mcp/stdio_proxy_tests.rs b/apps/backend/tests/mcp/stdio_proxy_tests.rs
new file mode 100644
index 00000000..ff58ddaf
--- /dev/null
+++ b/apps/backend/tests/mcp/stdio_proxy_tests.rs
@@ -0,0 +1,168 @@
+//! End-to-end tests for `vcms mcp stdio` as a thin HTTP proxy.
+//!
+//! The real `vcms` binary is spawned in stdio mode and pointed at a live
+//! `TestServer`'s `/mcp` endpoint via `VCMS_MCP_URL` + `VCMS_MCP_TOKEN`. It touches
+//! no database or secrets of its own — everything is forwarded to the server.
+
+use std::process::Stdio;
+
+use serde_json::{Value, json};
+use tokio::io::{AsyncBufReadExt, AsyncReadExt, AsyncWriteExt, BufReader};
+use tokio::process::{Child, ChildStdin, ChildStdout, Command};
+
+use crate::common::{TestServer, fixtures};
+
+struct StdioClient {
+    child: Child,
+    stdin: ChildStdin,
+    stdout: BufReader<ChildStdout>,
+}
+
+impl StdioClient {
+    /// Spawn the proxy the way an MCP client does: it knows only the server URL and a
+    /// site token — no `DATABASE_URL`, `HMAC_SECRET`, or `VCMS_HOME`.
+    async fn start(url: &str, token: &str) -> Self {
+        let mut child = Command::new(env!("CARGO_BIN_EXE_vcms"))
+            .args(["mcp", "stdio"])
+            .env_remove("DATABASE_URL")
+            .env_remove("HMAC_SECRET")
+            .env_remove("VCMS_HOME")
+            .env("VCMS_MCP_URL", url)
+            .env("VCMS_MCP_TOKEN", token)
+            .env("RUST_LOG", "warn")
+            .stdin(Stdio::piped())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::piped())
+            .kill_on_drop(true)
+            .spawn()
+            .expect("spawn vcms mcp stdio");
+
+        let stdin = child.stdin.take().expect("child stdin");
+        let stdout = BufReader::new(child.stdout.take().expect("child stdout"));
+        Self { child, stdin, stdout }
+    }
+
+    async fn request(&mut self, id: u64, method: &str, params: Option<Value>) -> Value {
+        let mut request = json!({"jsonrpc": "2.0", "id": id, "method": method});
+        if let Some(params) = params {
+            request["params"] = params;
+        }
+        self.stdin
+            .write_all(format!("{request}\n").as_bytes())
+            .await
+            .expect("write MCP request");
+        self.stdin.flush().await.expect("flush MCP request");
+
+        let mut line = String::new();
+        self.stdout.read_line(&mut line).await.expect("read MCP response");
+        serde_json::from_str(&line).unwrap_or_else(|error| panic!("stdout was not pure MCP JSON: {line:?}: {error}"))
+    }
+
+    async fn notify(&mut self, method: &str) {
+        let request = json!({"jsonrpc": "2.0", "method": method});
+        self.stdin
+            .write_all(format!("{request}\n").as_bytes())
+            .await
+            .expect("write MCP notification");
+        self.stdin.flush().await.expect("flush MCP notification");
+    }
+
+    async fn close(mut self) -> std::process::ExitStatus {
+        drop(self.stdin);
+        let mut stderr = self.child.stderr.take().expect("child stderr");
+        let status = self.child.wait().await.expect("wait for stdio process");
+        let mut logs = String::new();
+        stderr.read_to_string(&mut logs).await.expect("read stderr logs");
+        status
+    }
+}
+
+async fn initialize(client: &mut StdioClient) -> Value {
+    let response = client
+        .request(
+            1,
+            "initialize",
+            Some(json!({
+                "protocolVersion": "2024-11-05",
+                "capabilities": {},
+                "clientInfo": {"name": "stdio-proxy-test", "version": "1.0"}
+            })),
+        )
+        .await;
+    client.notify("notifications/initialized").await;
+    response
+}
+
+#[tokio::test]
+async fn stdio_proxy_round_trips_tools_and_calls_through_the_server() {
+    let server = TestServer::start().await;
+    let (_site_id, token) = fixtures::create_site_and_token(&server, "write").await;
+
+    let mut client = StdioClient::start(&server.base_url, &token).await;
+    let init = initialize(&mut client).await;
+    assert_eq!(init["result"]["serverInfo"]["name"], "cms");
+
+    let tools = client.request(2, "tools/list", None).await;
+    assert!(
+        tools["result"]["tools"].as_array().is_some_and(|t| !t.is_empty()),
+        "tools/list should return the site's tools: {tools}"
+    );
+
+    let site = client
+        .request(3, "tools/call", Some(json!({"name": "get_site", "arguments": {}})))
+        .await;
+    assert_eq!(
+        site["result"]["isError"], false,
+        "get_site should succeed through the proxy: {site}"
+    );
+
+    assert!(client.close().await.success(), "proxy should exit cleanly on stdin EOF");
+}
+
+#[tokio::test]
+async fn stdio_proxy_enforces_token_permission() {
+    let server = TestServer::start().await;
+    // A read-only token: reads pass, writes are denied by the server.
+    let (_site_id, token) = fixtures::create_site_and_token(&server, "read").await;
+
+    let mut client = StdioClient::start(&server.base_url, &token).await;
+    initialize(&mut client).await;
+
+    let mutation = client
+        .request(
+            2,
+            "tools/call",
+            Some(json!({"name": "update_site", "arguments": {"name": "Forbidden"}})),
+        )
+        .await;
+    assert_eq!(
+        mutation["result"]["isError"], true,
+        "read token must not write: {mutation}"
+    );
+
+    assert!(client.close().await.success());
+}
+
+#[tokio::test]
+async fn stdio_proxy_wraps_bad_token_as_jsonrpc_error() {
+    let server = TestServer::start().await;
+
+    let mut client = StdioClient::start(&server.base_url, "vcms_site_definitely_invalid").await;
+    let response = client
+        .request(
+            1,
+            "initialize",
+            Some(json!({
+                "protocolVersion": "2024-11-05",
+                "capabilities": {},
+                "clientInfo": {"name": "bad", "version": "1.0"}
+            })),
+        )
+        .await;
+    assert!(
+        response.get("error").is_some(),
+        "an invalid token must surface as a JSON-RPC error: {response}"
+    );
+
+    assert!(client.close().await.success());
+}
diff --git a/apps/backend/tests/mcp_stdio.rs b/apps/backend/tests/mcp_stdio.rs
deleted file mode 100644
index d8d36456..00000000
--- a/apps/backend/tests/mcp_stdio.rs
+++ /dev/null
@@ -1,289 +0,0 @@
-use std::process::Stdio;
-
-use cms::config::Config;
-use cms::database::{init_db_with_config, pool::DbPool};
-use cms::models::access_token::AccessTokenPermission;
-use cms::repository::Repository;
-use cms::services::access_token::AccessTokenService;
-use serde_json::{Value, json};
-use tokio::io::{AsyncBufReadExt, AsyncReadExt, AsyncWriteExt, BufReader};
-use tokio::process::{Child, ChildStdin, ChildStdout, Command};
-
-struct StdioClient {
-    child: Child,
-    stdin: ChildStdin,
-    stdout: BufReader<ChildStdout>,
-}
-
-impl StdioClient {
-    async fn start(database_url: &str, hmac_secret: &str, token: &str) -> Self {
-        let mut child = Command::new(env!("CARGO_BIN_EXE_vcms"))
-            .args(["mcp", "stdio"])
-            .env("DATABASE_URL", database_url)
-            .env("HMAC_SECRET", hmac_secret)
-            .env("VCMS_MCP_TOKEN", token)
-            .env("DB_MIN_CONNECTIONS", "1")
-            .env("DB_MAX_CONNECTIONS", "2")
-            .env("RUST_LOG", "cms=debug,vcms=debug")
-            .env("LOG_FORMAT", "pretty")
-            .stdin(Stdio::piped())
-            .stdout(Stdio::piped())
-            .stderr(Stdio::piped())
-            .kill_on_drop(true)
-            .spawn()
-            .expect("spawn cms mcp stdio");
-
-        let stdin = child.stdin.take().expect("child stdin");
-        let stdout = BufReader::new(child.stdout.take().expect("child stdout"));
-        Self { child, stdin, stdout }
-    }
-
-    /// Start the stdio process the way a real MCP client does: it knows only
-    /// `VCMS_HOME` and `VCMS_MCP_TOKEN`. No `DATABASE_URL` / `HMAC_SECRET` in the
-    /// environment, and a working directory with no `.env` — so both the database
-    /// path and the HMAC secret must be resolved from `~/.vcms`.
-    async fn start_from_home(home: &std::path::Path, token: &str) -> Self {
-        let mut child = Command::new(env!("CARGO_BIN_EXE_vcms"))
-            .args(["mcp", "stdio"])
-            .env_remove("DATABASE_URL")
-            .env_remove("HMAC_SECRET")
-            .env("VCMS_HOME", home)
-            .env("VCMS_MCP_TOKEN", token)
-            .env("DB_MIN_CONNECTIONS", "1")
-            .env("DB_MAX_CONNECTIONS", "2")
-            .env("RUST_LOG", "cms=debug,vcms=debug")
-            .env("LOG_FORMAT", "pretty")
-            .current_dir(home)
-            .stdin(Stdio::piped())
-            .stdout(Stdio::piped())
-            .stderr(Stdio::piped())
-            .kill_on_drop(true)
-            .spawn()
-            .expect("spawn cms mcp stdio");
-
-        let stdin = child.stdin.take().expect("child stdin");
-        let stdout = BufReader::new(child.stdout.take().expect("child stdout"));
-        Self { child, stdin, stdout }
-    }
-
-    async fn request(&mut self, id: u64, method: &str, params: Option<Value>) -> Value {
-        let mut request = json!({
-            "jsonrpc": "2.0",
-            "id": id,
-            "method": method,
-        });
-        if let Some(params) = params {
-            request["params"] = params;
-        }
-        self.stdin
-            .write_all(format!("{}\n", request).as_bytes())
-            .await
-            .expect("write MCP request");
-        self.stdin.flush().await.expect("flush MCP request");
-
-        let mut line = String::new();
-        self.stdout.read_line(&mut line).await.expect("read MCP response");
-        serde_json::from_str(&line).unwrap_or_else(|error| panic!("stdout was not pure MCP JSON: {line:?}: {error}"))
-    }
-
-    async fn notify(&mut self, method: &str) {
-        let request = json!({"jsonrpc": "2.0", "method": method});
-        self.stdin
-            .write_all(format!("{}\n", request).as_bytes())
-            .await
-            .expect("write MCP notification");
-        self.stdin.flush().await.expect("flush MCP notification");
-    }
-
-    async fn close(mut self) -> (std::process::ExitStatus, String) {
-        drop(self.stdin);
-        let mut stderr = self.child.stderr.take().expect("child stderr");
-        let status = self.child.wait().await.expect("wait for stdio process");
-        let mut logs = String::new();
-        stderr.read_to_string(&mut logs).await.expect("read stderr logs");
-        (status, logs)
-    }
-}
-
-async fn setup_database(permission: AccessTokenPermission) -> (tempfile::TempDir, Config, String, String) {
-    let directory = tempfile::tempdir().expect("temp directory");
-    let database_path = directory.path().join("vcms.db");
-    let database_url = format!("sqlite://{}", database_path.to_string_lossy().replace('\\', "/"));
-    let hmac_secret = "stdio-test-hmac-secret".to_string();
-    let config = Config {
-        database_url,
-        hmac_secret: hmac_secret.clone(),
-        bcrypt_cost: 4,
-        db_max_connections: 2,
-        db_min_connections: 1,
-        db_acquire_timeout_secs: 5,
-        db_idle_timeout_secs: 60,
-        ..Config::default()
-    };
-    let pool = init_db_with_config(&config).await.expect("initialize database");
-    let repository = Repository::new(&pool);
-    let password_hash = bcrypt::hash("password", 4).expect("password hash");
-    repository
-        .user
-        .create("stdio-user", "stdio", "stdio@example.com", &password_hash)
-        .await
-        .expect("create user");
-    repository
-        .site
-        .create("stdio-site", "Stdio Site", "filesystem", "stdio-user")
-        .await
-        .expect("create site");
-    let token = AccessTokenService::new(repository.access_token.clone(), hmac_secret.clone(), 4)
-        .create_site_token("stdio-site", "stdio".to_string(), permission, Some("stdio-user"))
-        .await
-        .expect("create token");
-    drop(repository);
-    drop(pool);
-
-    (directory, config, token.id, token.token)
-}
-
-/// Provision a `~/.vcms`-style home: a `secrets.toml` and a database at the
-/// default location (`<home>/vcms.db`), with a site token signed by the persisted
-/// HMAC secret. Mirrors what `vcms serve` leaves behind on first run.
-async fn setup_home_instance(home: &std::path::Path) -> String {
-    let hmac_secret = "home-instance-hmac-secret".to_string();
-    std::fs::write(home.join("secrets.toml"), format!("hmac_secret = \"{hmac_secret}\"\n"))
-        .expect("write secrets.toml");
-
-    let database_path = home.join("vcms.db");
-    let database_url = format!("sqlite://{}", database_path.to_string_lossy().replace('\\', "/"));
-    let config = Config {
-        database_url,
-        hmac_secret: hmac_secret.clone(),
-        bcrypt_cost: 4,
-        db_max_connections: 2,
-        db_min_connections: 1,
-        db_acquire_timeout_secs: 5,
-        db_idle_timeout_secs: 60,
-        ..Config::default()
-    };
-    let pool = init_db_with_config(&config).await.expect("initialize database");
-    let repository = Repository::new(&pool);
-    let password_hash = bcrypt::hash("password", 4).expect("password hash");
-    repository
-        .user
-        .create("home-user", "home", "home@example.com", &password_hash)
-        .await
-        .expect("create user");
-    repository
-        .site
-        .create("home-site", "Home Site", "filesystem", "home-user")
-        .await
-        .expect("create site");
-    let token = AccessTokenService::new(repository.access_token.clone(), hmac_secret, 4)
-        .create_site_token(
-            "home-site",
-            "home".to_string(),
-            AccessTokenPermission::Write,
-            Some("home-user"),
-        )
-        .await
-        .expect("create token");
-    drop(repository);
-    drop(pool);
-
-    token.token
-}
-
-/// Proves the MCP-stdio fix: a cwd-less client process authenticates and serves
-/// using only `VCMS_HOME` + `VCMS_MCP_TOKEN`, with the database path and HMAC
-/// secret resolved from `~/.vcms` rather than a cwd `.env`.
-#[tokio::test]
-async fn stdio_resolves_database_and_secret_from_cms_home() {
-    let home = tempfile::tempdir().expect("temp home");
-    let token = setup_home_instance(home.path()).await;
-
-    let mut client = StdioClient::start_from_home(home.path(), &token).await;
-    initialize(&mut client).await;
-
-    let site = client
-        .request(2, "tools/call", Some(json!({"name": "get_site", "arguments": {}})))
-        .await;
-    assert_eq!(site["result"]["isError"], false, "stdio must authenticate from ~/.vcms");
-
-    let (status, logs) = client.close().await;
-    assert!(status.success(), "stdio process should exit cleanly; logs:\n{logs}");
-}
-
-async fn initialize(client: &mut StdioClient) {
-    let response = client
-        .request(
-            1,
-            "initialize",
-            Some(json!({
-                "protocolVersion": "2024-11-05",
-                "capabilities": {},
-                "clientInfo": {"name": "stdio-test", "version": "1.0"}
-            })),
-        )
-        .await;
-    assert_eq!(response["result"]["serverInfo"]["name"], "cms");
-    client.notify("notifications/initialized").await;
-}
-
-#[tokio::test]
-async fn stdio_serves_mcp_with_protocol_only_stdout_and_lifecycle_logs_on_stderr() {
-    let (_directory, config, _token_id, token) = setup_database(AccessTokenPermission::Write).await;
-    let mut client = StdioClient::start(&config.database_url, &config.hmac_secret, &token).await;
-    initialize(&mut client).await;
-
-    let tools = client.request(2, "tools/list", None).await;
-    assert!(
-        tools["result"]["tools"]
-            .as_array()
-            .is_some_and(|tools| !tools.is_empty())
-    );
-
-    let site = client
-        .request(3, "tools/call", Some(json!({"name": "get_site", "arguments": {}})))
-        .await;
-    assert_eq!(site["result"]["isError"], false);
-
-    let (status, logs) = client.close().await;
-    assert!(status.success());
-    assert!(logs.contains("Starting standalone MCP stdio process"));
-    assert!(logs.contains("no migrations were run"));
-    assert!(logs.contains("MCP stdio transport active"));
-    assert!(logs.contains("exited cleanly"));
-}
-
-#[tokio::test]
-async fn stdio_enforces_read_permission_and_revalidates_deleted_token() {
-    let (_directory, config, token_id, token) = setup_database(AccessTokenPermission::Read).await;
-    let mut client = StdioClient::start(&config.database_url, &config.hmac_secret, &token).await;
-    initialize(&mut client).await;
-
-    let mutation = client
-        .request(
-            2,
-            "tools/call",
-            Some(json!({
-                "name": "update_site",
-                "arguments": {"name": "Forbidden"}
-            })),
-        )
-        .await;
-    assert_eq!(mutation["result"]["isError"], true);
-
-    let pool = DbPool::from_existing_with_config(&config).await.expect("open database");
-    let repository = Repository::new(&pool);
-    repository
-        .access_token
-        .delete(&token_id, "stdio-site")
-        .await
-        .expect("delete token");
-    drop(repository);
-    drop(pool);
-
-    let rejected = client.request(3, "tools/list", None).await;
-    assert!(rejected.get("error").is_some(), "deleted token must be rejected");
-
-    let (status, _logs) = client.close().await;
-    assert!(status.success());
-}

From ffd3e2fc3efe4f4d06a6bbf6b772e7800040d44d Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Tue, 30 Jun 2026 20:30:51 +0530
Subject: [PATCH 08/44] docs: document split layout, MCP stdio proxy, and OS
 service management

Update all three documentation files to reflect:
- Split/single directory layout with platform-specific paths table
- MCP stdio as a thin HTTP proxy (VCMS_MCP_URL env var)
- vcms service install/uninstall/status/start/stop commands
- Updated environment variable defaults and descriptions
---
 AGENTS.md | 68 +++++++++++++++++++++++++++++++++-----------------
 CLAUDE.md | 74 ++++++++++++++++++++++++++++++++++---------------------
 README.md | 60 ++++++++++++++++++++++----------------------
 3 files changed, 122 insertions(+), 80 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index ab222c07..0b0d19e7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -75,12 +75,22 @@ vcms admin reset-password --email U --password P
 vcms backup create [--scope instance|site] [--site ID] [--out FILE] [--no-files] [--encrypt]
 vcms backup list                       # list recorded backups
 vcms restore --file PATH [--scope instance|site] [--site ID] [--import-as-new] --yes
+vcms service install [--user NAME]     # install/enable/start as an OS service (systemd/launchd/SCM)
+vcms service uninstall|status|start|stop
+vcms mcp stdio                         # thin HTTP proxy to a running server's /mcp (for MCP clients)
 ```
 
 `backup`/`restore` run offline (no HTTP server) against the configured database —
 the disaster-recovery path when the instance won't boot. `restore` is destructive
 and requires `--yes`.
 
+`mcp stdio` opens no database, secrets, or search index of its own: it forwards
+JSON-RPC between stdin/stdout and the server's `/mcp` Streamable-HTTP endpoint,
+reading only `VCMS_MCP_TOKEN` (bearer) and `VCMS_MCP_URL` (default
+`http://127.0.0.1:3000`). So it works even when the data is owned by the OS-service
+account. `vcms service install` pins `VCMS_HOME` to a system dir so the daemon stores
+everything under one owned root.
+
 Global flags (highest precedence): `--config <PATH>`, `--bind <ADDR>`, `--database-url <URL>`, `--log-level <LEVEL>`.
 
 The server auto-migrates the database on every startup; there is no separate migrate command.
@@ -93,29 +103,41 @@ Layers merge with precedence: **CLI flag > env var > config file > built-in defa
 Config file search order (first existing wins; missing is fine):
 1. `--config` flag / `VCMS_CONFIG` env
 2. `./vcms.toml` (current dir)
-3. `~/.vcms/config.toml` (CMS home; `$VCMS_HOME/config.toml` if set) — where `vcms config init` writes
+3. the platform config dir (`config.toml`; `$VCMS_HOME/config.toml` in single-dir mode) — where `vcms config init` writes
 4. `/etc/vcms/config.toml`
 
-## Data directory (CMS home)
+## Data directory
+
+Resolution lives in `apps/backend/src/paths.rs` and has two layouts:
+
+**Split (default, interactive installs)** — files land in the platform-conventional
+per-type directories via the `directories` crate (`ProjectDirs`):
+
+| File(s) | Dir | Linux | macOS | Windows |
+|---------|-----|-------|-------|---------|
+| `config.toml`, `secrets.toml`, `.env` | config | `~/.config/vcms` | `~/Library/Application Support/vcms` | `%APPDATA%\vcms\config` |
+| `vcms.db`, `storage/`, `backups/` | data | `~/.local/share/vcms` | `~/Library/Application Support/vcms` | `%APPDATA%\vcms\data` |
+| `search/` (derived, rebuildable) | cache | `~/.cache/vcms` | `~/Library/Caches/vcms` | `%LOCALAPPDATA%\vcms\cache` |
+| `logs/` | state | `~/.local/state/vcms` | `~/Library/Application Support/vcms` | `%LOCALAPPDATA%\vcms\data` |
+
+(`logs/` uses the state dir where the platform has one — Linux — else the local data dir.)
 
-All runtime files live under one home directory: `$VCMS_HOME` if set, else `~/.vcms`
-(same layout on Windows, macOS, Linux via the `directories` crate). `vcms serve`
-creates it on first run. Resolution lives in `apps/backend/src/paths.rs`.
+**Single** — everything nests under one root. Chosen when **`$VCMS_HOME` is set** (the
+`vcms service` installer pins it to a system dir: Linux `/var/lib/vcms`, macOS
+`/Library/Application Support/vcms`, Windows `C:\ProgramData\vcms`), or when a legacy
+**`~/.vcms`** already exists (so an existing install keeps working untouched):
 
 ```text
-~/.vcms/
-  config.toml     # non-secret config (vcms config init target)
-  secrets.toml    # auto-generated HMAC_SECRET + backup key (0600 on unix)
-  vcms.db          # default SQLite database (+ -wal / -shm)
-  logs/           # rolling logs when [log] output = "file"
-  storage/        # default filesystem storage for uploads
+$VCMS_HOME/                # or ~/.vcms (legacy)
+  config.toml secrets.toml .env
+  vcms.db (+ -wal / -shm)  logs/  storage/  backups/  search/
 ```
 
-Secrets: on first `serve`/`admin`, a random `HMAC_SECRET` is generated
-and persisted to `secrets.toml` (`apps/backend/src/secrets.rs`), then loaded by
-every process — including `vcms mcp stdio`, which is launched from an arbitrary cwd
-and so cannot rely on a cwd `.env`. Env vars still override the file. `mcp stdio`
-is read-only: it never creates the home dir, database, or secrets file.
+Secrets: on first `serve`/`admin`, a random `HMAC_SECRET` is generated and persisted to
+`secrets.toml` (`apps/backend/src/secrets.rs`), then loaded by the server processes.
+`vcms mcp stdio` does **not** load secrets, the database, or any data-dir file: it is a
+thin HTTP proxy to the running server's `/mcp` (see CLI), forwarding `VCMS_MCP_TOKEN` as
+the bearer; the server owns all disk I/O.
 
 Env-only secrets (never read from `config.toml` by convention, omitted from
 `config init`): `DATABASE_URL`, `HMAC_SECRET`, `S3_ACCESS_KEY_ID`,
@@ -153,8 +175,10 @@ Logging keys map to the `[log]` table: `RUST_LOG`→`log.level`, `LOG_OUTPUT`→
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `VCMS_CONFIG` | - | Explicit config file path (same as `--config`) |
-| `VCMS_HOME` | `~/.vcms` | CMS home directory (db, config, secrets, logs, storage) |
-| `DATABASE_URL` | `sqlite://~/.vcms/vcms.db` | Database URL: `sqlite:path`, `postgres://...`, `mysql://...` |
+| `VCMS_HOME` | - | If set, forces single-dir mode: db/config/secrets/logs/storage all nest under this root (else files use the platform split dirs) |
+| `VCMS_MCP_TOKEN` | - | `vcms_site_*` access token forwarded by `vcms mcp stdio` as the bearer credential (required for stdio) |
+| `VCMS_MCP_URL` | `http://127.0.0.1:3000` | Running server's base URL that `vcms mcp stdio` proxies to (`{url}/mcp`) |
+| `DATABASE_URL` | `sqlite://<data dir>/vcms.db` | Database URL: `sqlite:path`, `postgres://...`, `mysql://...` |
 | `HMAC_SECRET` | auto | HMAC key for token lookup (required; auto-generated to `secrets.toml`, env overrides) |
 | `BIND_ADDRESS` | `0.0.0.0:3000` | REST API listen address |
 | `GRPC_BIND_ADDRESS` | `0.0.0.0:50051` | gRPC server listen address |
@@ -167,7 +191,7 @@ Logging keys map to the `[log]` table: `RUST_LOG`→`log.level`, `LOG_OUTPUT`→
 | `S3_PUBLIC_URL` | - | Public URL for S3 assets |
 | `BACKUP_ENABLED` | `true` | Run the scheduled-backup poller / allow backups |
 | `BACKUP_DESTINATION` | `filesystem` | Backup destination: `filesystem` or `s3` |
-| `BACKUP_LOCAL_PATH` | `~/.vcms/backups` | Local backup dir (when destination is filesystem) |
+| `BACKUP_LOCAL_PATH` | `<data dir>/backups` | Local backup dir (when destination is filesystem) |
 | `BACKUP_ZSTD_LEVEL` | `12` | zstd compression level for backups |
 | `BACKUP_DEFAULT_RETENTION` | `7` | Default "keep last N" for new schedules |
 | `BACKUP_S3_BUCKET` / `_REGION` / `_ENDPOINT` / `_PUBLIC_URL` | - | S3 backup destination (non-secret parts) |
@@ -185,10 +209,10 @@ Logging keys map to the `[log]` table: `RUST_LOG`→`log.level`, `LOG_OUTPUT`→
 | `LOG_OUTPUT` | `stdout` | `stdout` or `file` (`[log] output`) |
 | `LOG_FORMAT` | `pretty` | `pretty` or `json` (`[log] format`) |
 | `LOG_ANNOTATIONS` | `false` | Include file + line numbers (`[log] annotations`) |
-| `LOG_DIR` | `~/.vcms/logs` | Log directory when `output = file` (`[log] dir`) |
+| `LOG_DIR` | `<state dir>/logs` | Log directory when `output = file` (`[log] dir`) |
 
-**Note**: `HMAC_SECRET` is auto-generated and persisted to
-`~/.vcms/secrets.toml` on first run. Set it explicitly via env to override.
+**Note**: `HMAC_SECRET` is auto-generated and persisted to the config dir's
+`secrets.toml` on first run. Set it explicitly via env to override.
 
 ## Proto Compilation
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 7fa991bf..111bd897 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -94,30 +94,44 @@ Layers merge with precedence: **CLI flag > env var > config file > built-in defa
 Config file search order (first existing wins; missing is fine):
 1. `--config` flag / `VCMS_CONFIG` env
 2. `./vcms.toml` (current dir)
-3. `~/.vcms/config.toml` (CMS home; `$VCMS_HOME/config.toml` if set) — where `vcms config init` writes
+3. the platform config dir (`config.toml`; `$VCMS_HOME/config.toml` in single-dir mode) — where `vcms config init` writes
 4. `/etc/vcms/config.toml`
 
-## Data directory (CMS home)
+## Data directory
 
-All runtime files live under one home directory: `$VCMS_HOME` if set, else `~/.vcms`
-(same layout on Windows, macOS, Linux via the `directories` crate). `vcms serve`
-creates it on first run. Resolution lives in `apps/backend/src/paths.rs`.
+Resolution lives in `apps/backend/src/paths.rs` and has two layouts:
+
+**Split (default, interactive installs)** — files land in the platform-conventional
+per-type directories via the `directories` crate (`ProjectDirs`):
+
+| File(s) | Dir | Linux | macOS | Windows |
+|---------|-----|-------|-------|---------|
+| `config.toml`, `secrets.toml`, `.env` | config | `~/.config/vcms` | `~/Library/Application Support/vcms` | `%APPDATA%\vcms\config` |
+| `vcms.db`, `storage/`, `backups/` | data | `~/.local/share/vcms` | `~/Library/Application Support/vcms` | `%APPDATA%\vcms\data` |
+| `search/` (derived, rebuildable) | cache | `~/.cache/vcms` | `~/Library/Caches/vcms` | `%LOCALAPPDATA%\vcms\cache` |
+| `logs/` | state | `~/.local/state/vcms` | `~/Library/Application Support/vcms` | `%LOCALAPPDATA%\vcms\data` |
+
+(`logs/` uses the state dir where the platform has one — Linux — else the local data dir.)
+
+**Single** — everything nests under one root. Chosen when **`$VCMS_HOME` is set** (the
+`vcms service` installer pins it to a system dir: Linux `/var/lib/vcms`, macOS
+`/Library/Application Support/vcms`, Windows `C:\ProgramData\vcms`), or when a legacy
+**`~/.vcms`** already exists (so an existing install keeps working untouched):
 
 ```text
-~/.vcms/
-  config.toml     # non-secret config (vcms config init target)
-  secrets.toml    # auto-generated HMAC_SECRET + backup key (0600 on unix)
-  vcms.db          # default SQLite database (+ -wal / -shm)
-  logs/           # rolling logs when [log] output = "file"
-  storage/        # default filesystem storage for uploads
-  search/         # Tantivy full-text search index (derived; rebuildable)
+$VCMS_HOME/                # or ~/.vcms (legacy)
+  config.toml secrets.toml .env
+  vcms.db (+ -wal / -shm)  logs/  storage/  backups/  search/
 ```
 
+`vcms serve`/`admin` create the dirs they need on first run; `vcms mcp stdio` creates
+nothing.
+
 Secrets: on first `serve`/`admin`, a random `HMAC_SECRET` is generated
 and persisted to `secrets.toml` (`apps/backend/src/secrets.rs`), then loaded by
-every process — including `vcms mcp stdio`, which is launched from an arbitrary cwd
-and so cannot rely on a cwd `.env`. Env vars still override the file. `mcp stdio`
-is read-only: it never creates the home dir, database, or secrets file.
+the server processes. `vcms mcp stdio` does **not** load secrets, the database, or
+any home-dir file: it is a thin HTTP proxy (see below) and the server it forwards to
+owns all of those.
 
 Env-only secrets (never read from `config.toml` by convention, omitted from
 `config init`): `DATABASE_URL`, `HMAC_SECRET`, `S3_ACCESS_KEY_ID`,
@@ -156,8 +170,10 @@ Logging keys map to the `[log]` table: `RUST_LOG`→`log.level`, `LOG_OUTPUT`→
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `VCMS_CONFIG` | - | Explicit config file path (same as `--config`) |
-| `VCMS_HOME` | `~/.vcms` | CMS home directory (db, config, secrets, logs, storage) |
-| `DATABASE_URL` | `sqlite://~/.vcms/vcms.db` | Database URL: `sqlite:path`, `postgres://...`, `mysql://...` |
+| `VCMS_HOME` | - | If set, forces single-dir mode: db/config/secrets/logs/storage all nest under this root (else files use the platform split dirs) |
+| `VCMS_MCP_TOKEN` | - | `vcms_site_*` access token forwarded by `vcms mcp stdio` as the bearer credential (required for stdio) |
+| `VCMS_MCP_URL` | `http://127.0.0.1:3000` | Running server's base URL that `vcms mcp stdio` proxies to (`{url}/mcp`) |
+| `DATABASE_URL` | `sqlite://<data dir>/vcms.db` | Database URL: `sqlite:path`, `postgres://...`, `mysql://...` |
 | `HMAC_SECRET` | auto | HMAC key for token lookup (required; auto-generated to `secrets.toml`, env overrides) |
 | `BIND_ADDRESS` | `0.0.0.0:3000` | REST API listen address |
 | `GRPC_BIND_ADDRESS` | `0.0.0.0:50051` | gRPC server listen address |
@@ -170,7 +186,7 @@ Logging keys map to the `[log]` table: `RUST_LOG`→`log.level`, `LOG_OUTPUT`→
 | `S3_PUBLIC_URL` | - | Public URL for S3 assets |
 | `BACKUP_ENABLED` | `true` | Run the scheduled-backup poller / allow backups |
 | `BACKUP_DESTINATION` | `filesystem` | Backup destination: `filesystem` or `s3` |
-| `BACKUP_LOCAL_PATH` | `~/.vcms/backups` | Local backup dir (when destination is filesystem) |
+| `BACKUP_LOCAL_PATH` | `<data dir>/backups` | Local backup dir (when destination is filesystem) |
 | `BACKUP_ZSTD_LEVEL` | `12` | zstd compression level for backups |
 | `BACKUP_DEFAULT_RETENTION` | `7` | Default "keep last N" for new schedules |
 | `BACKUP_S3_BUCKET` / `_REGION` / `_ENDPOINT` / `_PUBLIC_URL` | - | S3 backup destination (non-secret parts) |
@@ -178,7 +194,7 @@ Logging keys map to the `[log]` table: `RUST_LOG`→`log.level`, `LOG_OUTPUT`→
 | `BACKUP_S3_SECRET_ACCESS_KEY` | - | S3 backup secret key (secret, env-only) |
 | `BACKUP_ENCRYPTION_KEY` | auto | AES-256 backup key (hex); auto-generated to `secrets.toml` |
 | `SEARCH_ENABLED` | `true` | Build/use the Tantivy full-text index for entry search (else SQL `LIKE`) |
-| `SEARCH_INDEX_PATH` | `~/.vcms/search` | Directory for the Tantivy search index |
+| `SEARCH_INDEX_PATH` | `<cache dir>/search` | Directory for the Tantivy search index |
 | `MAX_UPLOAD_SIZE_MB` | `50` | Max upload size in MB |
 | `COOKIE_SECURE` | `false` | Require HTTPS cookies |
 | `DB_MAX_CONNECTIONS` | `10` | Max DB connections |
@@ -190,10 +206,10 @@ Logging keys map to the `[log]` table: `RUST_LOG`→`log.level`, `LOG_OUTPUT`→
 | `LOG_OUTPUT` | `stdout` | `stdout` or `file` (`[log] output`) |
 | `LOG_FORMAT` | `pretty` | `pretty` or `json` (`[log] format`) |
 | `LOG_ANNOTATIONS` | `false` | Include file + line numbers (`[log] annotations`) |
-| `LOG_DIR` | `~/.vcms/logs` | Log directory when `output = file` (`[log] dir`) |
+| `LOG_DIR` | `<state dir>/logs` | Log directory when `output = file` (`[log] dir`) |
 
-**Note**: `HMAC_SECRET` is auto-generated and persisted to
-`~/.vcms/secrets.toml` on first run. Set it explicitly via env to override.
+**Note**: `HMAC_SECRET` is auto-generated and persisted to the config dir's
+`secrets.toml` on first run. Set it explicitly via env to override.
 
 ## Proto Compilation
 
@@ -298,8 +314,9 @@ is **derived** and fully rebuildable.
   scalar text of `data`, English-stemmed, BM25-ranked). `fields_from` re-resolves the
   schema when opening an existing index read-only.
 - `mod.rs` — `SearchService`. **Reading** needs no lock: `open_read_only` (reader
-  only) lets *any* process search the index, including a separate `vcms mcp stdio`
-  running next to the server. **Writing** requires the directory lock: `open`
+  only) lets *any* auxiliary process search the index alongside the server (this is a
+  general capability; `vcms mcp stdio` itself no longer opens the index — it proxies
+  over HTTP). **Writing** requires the directory lock: `open`
   (reader + writer) is held only by the running server. `index_doc`/`delete_doc`
   stage uncommitted ops; `commit` flushes; `rebuild_all`/`rebuild_site` reindex from
   the DB by reusing `EntryRepository::list` (covers singletons too). Write/commit on
@@ -314,7 +331,8 @@ is **derived** and fully rebuildable.
 
 Wiring: `Services` holds `search: Option<Arc<SearchService>>` (reads) and
 `search_queue: Option<Arc<SearchQueue>>` (writes). `Services::new` opens the index
-read-write (server); `Services::new_read_only` opens it read-only (`vcms mcp stdio`).
+read-write (server); `Services::new_read_only` opens it read-only for an auxiliary
+process that searches without taking the writer lock.
 `EntryService`/`SingletonService` **enqueue** on write; `EntryService::list_entries`
 queries the index — so REST, GraphQL, gRPC, and MCP all get ranked search via the
 existing `search` param with **no handler changes**. Indexing is asynchronous
@@ -324,9 +342,9 @@ index builds on startup when empty, rebuilds after a restore, and exposes
 owner/operator reindex routes: `POST /api/dashboard/instance/search/reindex` and
 `POST /api/dashboard/sites/{site_id}/search/reindex`.
 
-This is the cross-process model: writes from `vcms mcp stdio` (or any process) land in
-the durable queue and the running server indexes them; if the server is down they
-drain on its next start. The remaining hard limit is *concurrent writers* — only one
+This is the cross-process model: writes from any process land in the durable queue
+and the running server indexes them; if the server is down they drain on its next
+start. The remaining hard limit is *concurrent writers* — only one
 process indexes at a time.
 
 ### No typo tolerance (deliberate) — and how to add it
diff --git a/README.md b/README.md
index 7919d30b..f4ee9ed8 100644
--- a/README.md
+++ b/README.md
@@ -89,51 +89,51 @@ password after your first login.*
 
 ### MCP over stdio
 
-Run a standalone MCP process for clients that launch local stdio servers:
+For clients that launch a local stdio MCP server, run `vcms mcp stdio`. It is a
+**thin proxy** to a running server's `/mcp` endpoint — it opens no database, secrets,
+or search index of its own. It forwards JSON-RPC between stdin/stdout and the server
+over HTTP, so it keeps working even when the data is owned by a system-service account
+that the client process can't read.
 
 ```bash
-VCMS_MCP_TOKEN=vcms_site_... vcms mcp stdio
+VCMS_MCP_TOKEN=vcms_site_... VCMS_MCP_URL=http://127.0.0.1:3000 vcms mcp stdio
 ```
 
-The command connects to an existing CMS database and never starts HTTP/gRPC
-listeners, seeds users, creates a SQLite database, or runs migrations. Run
-`vcms serve` first when the database schema needs initialization or migration.
-MCP protocol messages use stdout; structured process logs use stderr.
-
-Because the process is launched by the MCP client from an arbitrary working
-directory, it does **not** rely on a `.env` in the current directory. The
-database path and the `HMAC_SECRET` it needs to verify the token are
-read from the CMS home directory (`~/.vcms`, see [Data directory](#data-directory))
-that `vcms serve` initialized. The client only needs to supply `VCMS_MCP_TOKEN`
-(and `VCMS_HOME` if you moved the home directory):
+It needs only two env vars: `VCMS_MCP_TOKEN` (a `vcms_site_*` access token, forwarded
+as the `Authorization: Bearer` credential) and `VCMS_MCP_URL` (the running server's
+base URL, default `http://127.0.0.1:3000`; the proxy posts to `{url}/mcp`). A `vcms
+serve` instance must be running. MCP protocol messages use stdout; logs use stderr.
 
 ```jsonc
 // Example MCP client config
 {
   "command": "vcms",
   "args": ["mcp", "stdio"],
-  "env": { "VCMS_MCP_TOKEN": "vcms_site_..." }
+  "env": { "VCMS_MCP_TOKEN": "vcms_site_...", "VCMS_MCP_URL": "http://127.0.0.1:3000" }
 }
 ```
 
 ### Data directory
 
-All runtime files live under a single home directory so a fresh install works
-from any working directory. The location is `$VCMS_HOME` when set, otherwise
-`~/.vcms` (resolved cross-platform — same layout on Windows, macOS, and Linux):
-
-```text
-~/.vcms/
-  config.toml     # non-secret configuration (vcms config init writes here)
-  secrets.toml    # auto-generated HMAC_SECRET + backup key (0600 on unix)
-  vcms.db          # default SQLite database (+ -wal / -shm)
-  logs/           # rolling logs when [log] output = "file"
-  storage/        # default filesystem storage for uploads
-```
-
-`vcms serve` creates this directory on first run and generates `secrets.toml` if
-absent. Environment variables (`DATABASE_URL`, `HMAC_SECRET`,
-`STORAGE_FS_PATH`, S3 settings, …) still override these defaults.
+By default, runtime files go to the platform-conventional per-type directories
+(resolved cross-platform via the `directories` crate):
+
+| File(s) | Linux | macOS | Windows |
+|---------|-------|-------|---------|
+| `config.toml`, `secrets.toml`, `.env` | `~/.config/vcms` | `~/Library/Application Support/vcms` | `%APPDATA%\vcms\config` |
+| `vcms.db`, `storage/`, `backups/` | `~/.local/share/vcms` | `~/Library/Application Support/vcms` | `%APPDATA%\vcms\data` |
+| `search/` (rebuildable index) | `~/.cache/vcms` | `~/Library/Caches/vcms` | `%LOCALAPPDATA%\vcms\cache` |
+| `logs/` | `~/.local/state/vcms` | `~/Library/Application Support/vcms` | `%LOCALAPPDATA%\vcms\data` |
+
+Set **`$VCMS_HOME`** to keep everything under a single root instead (and an existing
+`~/.vcms` is honored automatically, so upgrades don't move your data). The `vcms
+service` installer uses this to pin the daemon to one system dir — `/var/lib/vcms`
+(Linux), `/Library/Application Support/vcms` (macOS), or `C:\ProgramData\vcms`
+(Windows).
+
+`vcms serve` creates what it needs on first run and generates `secrets.toml` if
+absent. Environment variables (`DATABASE_URL`, `HMAC_SECRET`, `STORAGE_FS_PATH`,
+S3 settings, …) still override these defaults.
 
 
 

From bb52640bd2ee8c9ead6220bf43d30ecd8108067c Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Wed, 1 Jul 2026 11:47:41 +0530
Subject: [PATCH 09/44] chore(deps): update dependencies

---
 Cargo.lock              | 294 +++++++++++++++++-----------------------
 apps/backend/Cargo.toml |   8 +-
 2 files changed, 132 insertions(+), 170 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 08729ca6..47b61b71 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -16,34 +16,34 @@ checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
 
 [[package]]
 name = "aead"
-version = "0.5.2"
+version = "0.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d122413f284cf2d62fb1b7db97e02edb8cda96d769b16e443a4f6195e35662b0"
+checksum = "1973cfbc1a2daf9cf550e74e1f088c28e7f7d8c1e1418fb6c9dc5184b7e84c99"
 dependencies = [
- "crypto-common 0.1.7",
- "generic-array",
+ "crypto-common 0.2.2",
+ "inout",
 ]
 
 [[package]]
 name = "aes"
-version = "0.8.4"
+version = "0.9.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b169f7a6d4742236a0a00c541b845991d0ac43e546831af1249753ab4c3aa3a0"
+checksum = "f1fc76eaeac4c9164506c466d4ffdd8ec9d0c5bf57ee97177c4d8eceb3a0e138"
 dependencies = [
- "cfg-if",
- "cipher 0.4.4",
- "cpufeatures 0.2.17",
+ "cipher",
+ "cpubits",
+ "cpufeatures 0.3.0",
 ]
 
 [[package]]
 name = "aes-gcm"
-version = "0.10.3"
+version = "0.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "831010a0f742e1209b3bcea8fab6a8e149051ba6099432c8cb2cc117dec3ead1"
+checksum = "fdf011db2e21ce0d575593d749db5554b47fed37aff429e4dc50bc91ac93a028"
 dependencies = [
  "aead",
  "aes",
- "cipher 0.4.4",
+ "cipher",
  "ctr",
  "ghash",
  "subtle",
@@ -143,9 +143,9 @@ dependencies = [
 
 [[package]]
 name = "anyhow"
-version = "1.0.102"
+version = "1.0.103"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"
+checksum = "2a4385e2e34eb35d6b3efe798b9eb88096925d87726c0798709bf56d9ed84af3"
 
 [[package]]
 name = "arbitrary"
@@ -155,9 +155,9 @@ checksum = "c3d036a3c4ab069c7b410a2ce876bd74808d2d0888a82667669f8e783a898bf1"
 
 [[package]]
 name = "arc-swap"
-version = "1.9.1"
+version = "1.9.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6a3a1fd6f75306b68087b831f025c712524bcb19aad54e557b1129cfa0a2b207"
+checksum = "c049c0be4daef0b145cb3555416b3b8ef5b7888a38aea1a3a155801fe7b0810b"
 dependencies = [
  "rustversion",
 ]
@@ -413,9 +413,9 @@ dependencies = [
 
 [[package]]
 name = "aws-lc-rs"
-version = "1.17.0"
+version = "1.17.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5ec2f1fc3ec205783a5da9a7e6c1509cc69dedf09a1949e412c1e18469326d00"
+checksum = "4342d8937fc7e5dd9b1c60292261c0670c882a2cd1719cfc11b1af41731e32ad"
 dependencies = [
  "aws-lc-sys",
  "zeroize",
@@ -423,14 +423,15 @@ dependencies = [
 
 [[package]]
 name = "aws-lc-sys"
-version = "0.41.0"
+version = "0.42.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1a2f9779ce85b93ab6170dd940ad0169b5766ff848247aff13bb788b832fe3f4"
+checksum = "6d9ceb1da931507a12f4fccea479dccd00da1943e1b4ae72d8e502d707361444"
 dependencies = [
  "cc",
  "cmake",
  "dunce",
  "fs_extra",
+ "pkg-config",
 ]
 
 [[package]]
@@ -583,7 +584,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "62ce3946557b35e71d1bbe07ec385073ce9eda05043f95de134eb578fcf1a298"
 dependencies = [
  "byteorder",
- "cipher 0.5.2",
+ "cipher",
 ]
 
 [[package]]
@@ -705,24 +706,15 @@ dependencies = [
  "windows-link",
 ]
 
-[[package]]
-name = "cipher"
-version = "0.4.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "773f3b9af64447d2ce9850330c473515014aa235e6a783b02db81ff39e4a3dad"
-dependencies = [
- "crypto-common 0.1.7",
- "inout 0.1.4",
-]
-
 [[package]]
 name = "cipher"
 version = "0.5.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e8cf2a2c93cd704877c0858356ed03480ff301ee950b43f1cbe4573b088bfa6c"
 dependencies = [
+ "block-buffer 0.12.1",
  "crypto-common 0.2.2",
- "inout 0.2.2",
+ "inout",
 ]
 
 [[package]]
@@ -814,7 +806,7 @@ dependencies = [
  "prost",
  "rand 0.10.1",
  "regex",
- "reqwest 0.13.4",
+ "reqwest",
  "rmcp",
  "rust-embed",
  "schemars",
@@ -944,6 +936,12 @@ version = "0.8.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
 
+[[package]]
+name = "cpubits"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "15b85f9c39137c3a891689859392b1bd49812121d0d61c9caf00d46ed5ce06ae"
+
 [[package]]
 name = "cpufeatures"
 version = "0.2.17"
@@ -977,6 +975,16 @@ version = "2.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "217698eaf96b4a3f0bc4f3662aaa55bdf913cd54d7204591faa790070c6d0853"
 
+[[package]]
+name = "crc-fast"
+version = "1.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e75b2483e97a5a7da73ac68a05b629f9c53cff58d8ed1c77866079e18b00dba5"
+dependencies = [
+ "digest 0.10.7",
+ "spin 0.10.0",
+]
+
 [[package]]
 name = "crc32fast"
 version = "1.5.0"
@@ -1048,12 +1056,11 @@ checksum = "460fbee9c2c2f33933d720630a6a0bac33ba7053db5344fac858d4b8952d77d5"
 
 [[package]]
 name = "crypto-common"
-version = "0.1.7"
+version = "0.1.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
+checksum = "1bfb12502f3fc46cca1bb51ac28df9d618d813cdc3d2f25b9fe775a34af26bb3"
 dependencies = [
  "generic-array",
- "rand_core 0.6.4",
  "typenum",
 ]
 
@@ -1063,16 +1070,18 @@ version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ce6e4c961d6cd6c9a86db418387425e8bdeaf05b3c8bc1411e6dca4c252f1453"
 dependencies = [
+ "getrandom 0.4.3",
  "hybrid-array",
+ "rand_core 0.10.1",
 ]
 
 [[package]]
 name = "ctr"
-version = "0.9.2"
+version = "0.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0369ee1ad671834580515889b80f2ea915f23b8be8d0daa4bbaf2ac5c7590835"
+checksum = "baaca1c4b237092596f64d571e9db6ce4109c4ef9742e27590f1709594461f21"
 dependencies = [
- "cipher 0.4.4",
+ "cipher",
 ]
 
 [[package]]
@@ -1244,7 +1253,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
 dependencies = [
  "block-buffer 0.10.4",
- "crypto-common 0.1.7",
+ "crypto-common 0.1.6",
 ]
 
 [[package]]
@@ -1503,7 +1512,7 @@ checksum = "5e139bc46ca777eb5efaf62df0ab8cc5fd400866427e56c68b22e414e53bd3be"
 dependencies = [
  "futures-core",
  "futures-sink",
- "spin",
+ "spin 0.9.8",
 ]
 
 [[package]]
@@ -1660,9 +1669,9 @@ dependencies = [
 
 [[package]]
 name = "generic-array"
-version = "0.14.7"
+version = "0.14.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"
+checksum = "4bb6743198531e02858aeaea5398fcc883e71851fcbcb5a2f773e2fb6cb1edf2"
 dependencies = [
  "typenum",
  "version_check",
@@ -1709,11 +1718,10 @@ dependencies = [
 
 [[package]]
 name = "ghash"
-version = "0.5.1"
+version = "0.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f0d8a4362ccb29cb0b265253fb0a2728f592895ee6854fd9bc13f2ffda266ff1"
+checksum = "2eecf2d5dc9b66b732b97707a0210906b1d30523eb773193ab777c0c84b3e8d5"
 dependencies = [
- "opaque-debug",
  "polyval",
 ]
 
@@ -1908,9 +1916,9 @@ checksum = "135b12329e5e3ce057a9f972339ea52bc954fe1e9358ef27f95e89716fbc5424"
 
 [[package]]
 name = "hybrid-array"
-version = "0.4.12"
+version = "0.4.13"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9155a582abd142abc056962c29e3ce5ff2ad5469f4246b537ed42c5deba857da"
+checksum = "818356c5132c1fede50f837ca96afbe78ff42413047f4abb886217845e1b6c8c"
 dependencies = [
  "typenum",
 ]
@@ -1947,7 +1955,6 @@ dependencies = [
  "hyper",
  "hyper-util",
  "rustls",
- "rustls-native-certs",
  "tokio",
  "tokio-rustls",
  "tower-service",
@@ -2178,15 +2185,6 @@ version = "0.1.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c8fae54786f62fb2918dcfae3d568594e50eb9b5c25bf04371af6fe7516452fb"
 
-[[package]]
-name = "inout"
-version = "0.1.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "879f10e63c20629ecabbb64a8010319738c66a5cd0c29b02d63d272b03751d01"
-dependencies = [
- "generic-array",
-]
-
 [[package]]
 name = "inout"
 version = "0.2.2"
@@ -2237,6 +2235,15 @@ dependencies = [
  "either",
 ]
 
+[[package]]
+name = "itertools"
+version = "0.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b4baf93f58d4425749ca49a51c50ebab072c5df6994d08fed93541c331481dc"
+dependencies = [
+ "either",
+]
+
 [[package]]
 name = "itoa"
 version = "1.0.18"
@@ -2470,16 +2477,6 @@ dependencies = [
  "cfg-if",
 ]
 
-[[package]]
-name = "md-5"
-version = "0.10.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d89e7ee0cfbedfc4da3340218492196241d89eefb6dab27de5df917a6d2e78cf"
-dependencies = [
- "cfg-if",
- "digest 0.10.7",
-]
-
 [[package]]
 name = "md-5"
 version = "0.11.0"
@@ -2580,7 +2577,7 @@ dependencies = [
  "httparse",
  "memchr",
  "mime",
- "spin",
+ "spin 0.9.8",
  "version_check",
 ]
 
@@ -2602,6 +2599,18 @@ version = "1.0.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "650eef8c711430f1a879fdd01d4745a7deea475becfb90269c06775983bbf086"
 
+[[package]]
+name = "nix"
+version = "0.31.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf20d2fde8ff38632c426f1165ed7436270b44f199fc55284c38276f9db47c3d"
+dependencies = [
+ "bitflags",
+ "cfg-if",
+ "cfg_aliases",
+ "libc",
+]
+
 [[package]]
 name = "no_std_io2"
 version = "0.9.4"
@@ -2728,14 +2737,16 @@ dependencies = [
 
 [[package]]
 name = "object_store"
-version = "0.13.2"
+version = "0.14.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "622acbc9100d3c10e2ee15804b0caa40e55c933d5aa53814cd520805b7958a49"
+checksum = "765784b4390c6bcf80316e5a22f4e3661b639c9d8c83246856643c27d8ce9dbe"
 dependencies = [
  "async-trait",
+ "aws-lc-rs",
  "base64",
  "bytes",
  "chrono",
+ "crc-fast",
  "form_urlencoded",
  "futures-channel",
  "futures-core",
@@ -2744,14 +2755,15 @@ dependencies = [
  "http-body-util",
  "humantime",
  "hyper",
- "itertools",
- "md-5 0.10.6",
+ "itertools 0.15.0",
+ "md-5",
+ "nix",
  "parking_lot",
  "percent-encoding",
  "quick-xml",
  "rand 0.10.1",
- "reqwest 0.12.28",
- "ring",
+ "reqwest",
+ "rustls-pki-types",
  "serde",
  "serde_json",
  "serde_urlencoded",
@@ -2762,6 +2774,7 @@ dependencies = [
  "walkdir",
  "wasm-bindgen-futures",
  "web-time",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -2782,12 +2795,6 @@ version = "0.1.13"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "269bca4c2591a28585d6bf10d9ed0332b7d76900a1b02bec41bdc3a2cdcda107"
 
-[[package]]
-name = "opaque-debug"
-version = "0.3.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c08d65885ee38876c4f86fa503fb49d7b507c2b62552df7c70b2fce627e06381"
-
 [[package]]
 name = "openssl-probe"
 version = "0.2.1"
@@ -3009,13 +3016,12 @@ dependencies = [
 
 [[package]]
 name = "polyval"
-version = "0.6.2"
+version = "0.7.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9d1fe60d06143b2430aa532c94cfe9e29783047f06c0d7fd359a9a51b729fa25"
+checksum = "7dfc63250416fea14f5749b90725916a6c903f599d51cb635aa7a52bfd03eede"
 dependencies = [
- "cfg-if",
- "cpufeatures 0.2.17",
- "opaque-debug",
+ "cpubits",
+ "cpufeatures 0.3.0",
  "universal-hash",
 ]
 
@@ -3120,7 +3126,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "03da047801ff44bb6a4d407d4860c05fd70bb81714e6b2f3812603d5b145b042"
 dependencies = [
  "heck",
- "itertools",
+ "itertools 0.14.0",
  "log",
  "multimap",
  "petgraph",
@@ -3141,7 +3147,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b570b25f7617e43d59005d0990ccb79e950a423952cea19671b7a876da390adf"
 dependencies = [
  "anyhow",
- "itertools",
+ "itertools 0.14.0",
  "proc-macro2",
  "quote",
  "syn",
@@ -3206,9 +3212,9 @@ checksum = "a993555f31e5a609f617c12db6250dedcac1b0a85076912c436e6fc9b2c8e6a3"
 
 [[package]]
 name = "quick-xml"
-version = "0.39.4"
+version = "0.40.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cdcc8dd4e2f670d309a5f0e83fe36dfdc05af317008fea29144da1a2ac858e5e"
+checksum = "2474bd2e5029e7ccb6abb2ba48cf2383a333851dedf495901544281590c7da7f"
 dependencies = [
  "memchr",
  "serde",
@@ -3322,15 +3328,6 @@ dependencies = [
  "rand_core 0.9.5",
 ]
 
-[[package]]
-name = "rand_core"
-version = "0.6.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c"
-dependencies = [
- "getrandom 0.2.17",
-]
-
 [[package]]
 name = "rand_core"
 version = "0.9.5"
@@ -3362,7 +3359,7 @@ dependencies = [
  "built",
  "cfg-if",
  "interpolate_name",
- "itertools",
+ "itertools 0.14.0",
  "libc",
  "libfuzzer-sys",
  "log",
@@ -3484,48 +3481,6 @@ version = "0.8.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
 
-[[package]]
-name = "reqwest"
-version = "0.12.28"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "eddd3ca559203180a307f12d114c268abf583f59b03cb906fd0b3ff8646c1147"
-dependencies = [
- "base64",
- "bytes",
- "futures-core",
- "futures-util",
- "h2",
- "http",
- "http-body",
- "http-body-util",
- "hyper",
- "hyper-rustls",
- "hyper-util",
- "js-sys",
- "log",
- "percent-encoding",
- "pin-project-lite",
- "quinn",
- "rustls",
- "rustls-native-certs",
- "rustls-pki-types",
- "serde",
- "serde_json",
- "serde_urlencoded",
- "sync_wrapper",
- "tokio",
- "tokio-rustls",
- "tokio-util",
- "tower",
- "tower-http 0.6.11",
- "tower-service",
- "url",
- "wasm-bindgen",
- "wasm-bindgen-futures",
- "wasm-streams",
- "web-sys",
-]
-
 [[package]]
 name = "reqwest"
 version = "0.13.4"
@@ -3561,12 +3516,14 @@ dependencies = [
  "sync_wrapper",
  "tokio",
  "tokio-rustls",
+ "tokio-util",
  "tower",
  "tower-http 0.6.11",
  "tower-service",
  "url",
  "wasm-bindgen",
  "wasm-bindgen-futures",
+ "wasm-streams",
  "web-sys",
 ]
 
@@ -3592,9 +3549,9 @@ dependencies = [
 
 [[package]]
 name = "rmcp"
-version = "1.8.0"
+version = "2.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1d1f571c72940a19d9532fe52dbea8bc9912bf1d766c2970bb824056b86f3f59"
+checksum = "d52d21e5b342699bc4de690e6104fc4e43255e4e8420ff0f2cbb963aac09da6f"
 dependencies = [
  "async-trait",
  "base64",
@@ -3623,9 +3580,9 @@ dependencies = [
 
 [[package]]
 name = "rmcp-macros"
-version = "1.8.0"
+version = "2.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1aad0035b69380782d78ea95b508327e6deaa2235909053e596eea8f27b5e1d5"
+checksum = "6c68cec74c5b3ac73ff46375ae49e161637bda80bba70f0d5db641583bb308ee"
 dependencies = [
  "darling 0.23.0",
  "proc-macro2",
@@ -3714,7 +3671,6 @@ checksum = "6b92b125634d9b795e7beca796cc790df15a7fb38323bf3196fda83292d06b1f"
 dependencies = [
  "aws-lc-rs",
  "once_cell",
- "ring",
  "rustls-pki-types",
  "rustls-webpki",
  "subtle",
@@ -3735,9 +3691,9 @@ dependencies = [
 
 [[package]]
 name = "rustls-pki-types"
-version = "1.14.1"
+version = "1.15.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "30a7197ae7eb376e574fe940d068c30fe0462554a3ddbe4eca7838e049c937a9"
+checksum = "764899a24af3980067ee14bc143654f297b22eaebfe3c7b6b211920a5a59b046"
 dependencies = [
  "web-time",
  "zeroize",
@@ -4112,6 +4068,12 @@ dependencies = [
  "lock_api",
 ]
 
+[[package]]
+name = "spin"
+version = "0.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d5fe4ccb98d9c292d56fec89a5e07da7fc4cf0dc11e156b41793132775d3e591"
+
 [[package]]
 name = "sqlx"
 version = "0.9.0"
@@ -4250,7 +4212,7 @@ dependencies = [
  "hmac",
  "itoa",
  "log",
- "md-5 0.11.0",
+ "md-5",
  "memchr",
  "rand 0.10.1",
  "serde",
@@ -4439,7 +4401,7 @@ dependencies = [
  "fnv",
  "fs4",
  "htmlescape",
- "itertools",
+ "itertools 0.14.0",
  "levenshtein_automata",
  "log",
  "lru",
@@ -4488,7 +4450,7 @@ checksum = "c57166f5bcfd478f370ab8445afb4678dce44801fa5ce5c451aaf8595583c5dc"
 dependencies = [
  "downcast-rs",
  "fastdivide",
- "itertools",
+ "itertools 0.14.0",
  "serde",
  "tantivy-bitpacker",
  "tantivy-common",
@@ -4540,7 +4502,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8a2cfc3ac5164cbadc28965ffb145a8f47582a60ae5897859ad8d4316596c606"
 dependencies = [
  "futures-util",
- "itertools",
+ "itertools 0.14.0",
  "tantivy-bitpacker",
  "tantivy-common",
  "tantivy-fst",
@@ -4621,9 +4583,9 @@ dependencies = [
 
 [[package]]
 name = "time"
-version = "0.3.51"
+version = "0.3.53"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "85c17d80feb7334b40c484e45ed1a5273dfd8bfda537c3be2e74a06a6686f327"
+checksum = "18dfaaeddcb932337b5e7866ee7d0ce9b76d2fd092997146f187ec09b4558a50"
 dependencies = [
  "deranged",
  "num-conv",
@@ -4641,9 +4603,9 @@ checksum = "9e1c906769ad99c88eaa54e728060edef082f8e358ff32030cb7c7d315e81109"
 
 [[package]]
 name = "time-macros"
-version = "0.2.30"
+version = "0.2.31"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dcef1a61bdb119096e153208ec5cbec23944ce8bca13be5c7f60c634f7403935"
+checksum = "c431b87111666e491a90baa837f914fb45cd5dc3c268591b0220ff5057f2085f"
 dependencies = [
  "num-conv",
  "time-core",
@@ -5213,12 +5175,12 @@ checksum = "7df058c713841ad818f1dc5d3fd88063241cc61f49f5fbea4b951e8cf5a8d71d"
 
 [[package]]
 name = "universal-hash"
-version = "0.5.1"
+version = "0.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fc1de2c688dc15305988b563c3854064043356019f97a4b46276fe734c4f07ea"
+checksum = "f4987bdc12753382e0bec4a65c50738ffaabc998b9cdd1f952fb5f39b0048a96"
 dependencies = [
- "crypto-common 0.1.7",
- "subtle",
+ "crypto-common 0.2.2",
+ "ctutils",
 ]
 
 [[package]]
@@ -5425,9 +5387,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-streams"
-version = "0.4.2"
+version = "0.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "15053d8d85c7eccdbefef60f06769760a563c7f0a9d6902a13d35c7800b0ad65"
+checksum = "9d1ec4f6517c9e11ae630e200b2b65d193279042e28edd4a2cda233e46670bbb"
 dependencies = [
  "futures-util",
  "js-sys",
@@ -5577,13 +5539,13 @@ dependencies = [
 
 [[package]]
 name = "windows-service"
-version = "0.7.0"
+version = "0.8.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d24d6bcc7f734a4091ecf8d7a64c5f7d7066f45585c1861eba06449909609c8a"
+checksum = "857224b3b211c6f3616921f081ee54721ee3ad2ace2fac6a6337e032f7b4dcf2"
 dependencies = [
  "bitflags",
  "widestring",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
diff --git a/apps/backend/Cargo.toml b/apps/backend/Cargo.toml
index a25c2f99..6e534537 100644
--- a/apps/backend/Cargo.toml
+++ b/apps/backend/Cargo.toml
@@ -38,7 +38,7 @@ utoipa = { version = "5", features = ["axum_extras"] }
 utoipa-scalar = { version = "0.3", features = ["axum"] }
 dotenvy = "0.15"
 image = { version = "0.25", default-features = false, features = ["png", "jpeg", "webp", "gif", "avif"] }
-object_store = { version = "0.13", features = ["aws"] }
+object_store = { version = "0.14", features = ["aws"] }
 bytes = "1"
 http = "1"
 regex = "1"
@@ -53,7 +53,7 @@ hmac = "0.13"
 hex = "0.4"
 cookie = "0.18"
 base64 = "0.22"
-aes-gcm = "0.10"
+aes-gcm = "0.11"
 rand = "0.10"
 dashmap = "6"
 url = "2"
@@ -65,7 +65,7 @@ tonic-prost = "0.14.5"
 tonic-reflection = "0.14"
 tonic-health = "0.14"
 http-body-util = "0.1.3"
-rmcp = { version = "1.6", features = ["server", "transport-io", "transport-streamable-http-server", "macros", "schemars"] }
+rmcp = { version = "2.0", features = ["server", "transport-io", "transport-streamable-http-server", "macros", "schemars"] }
 tokio-util = { version = "0.7", features = ["rt"] }
 schemars = "1"
 clap = { version = "4.6.1", features = ["derive", "env"] }
@@ -83,7 +83,7 @@ libc = "0.2"
 
 # Windows: native Service Control Manager integration for `vcms service`.
 [target.'cfg(windows)'.dependencies]
-windows-service = "0.7"
+windows-service = "0.8"
 
 [build-dependencies]
 tonic-build = "0.14"

From 7dc2c5347f7c3be00f2ed787a7feffdbdfd5e87e Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Wed, 1 Jul 2026 11:48:50 +0530
Subject: [PATCH 10/44] refactor(mcp): replace Content with ContentBlock and
 clean up imports to match rmcp 2.0

---
 apps/backend/src/mcp/auth.rs                  |  8 +++----
 apps/backend/src/mcp/resources/site_schema.rs | 21 ++++++-------------
 2 files changed, 10 insertions(+), 19 deletions(-)

diff --git a/apps/backend/src/mcp/auth.rs b/apps/backend/src/mcp/auth.rs
index 3a14ab71..7a4edb46 100644
--- a/apps/backend/src/mcp/auth.rs
+++ b/apps/backend/src/mcp/auth.rs
@@ -5,7 +5,7 @@ use axum::{
     middleware::Next,
     response::{IntoResponse, Response},
 };
-use rmcp::model::{CallToolResult, Content, ErrorCode, ErrorData};
+use rmcp::model::{CallToolResult, ContentBlock, ErrorCode, ErrorData};
 use rmcp::service::{RequestContext, RoleServer};
 use serde_json::json;
 
@@ -26,11 +26,11 @@ pub fn ok_result(data: &impl serde::Serialize) -> Result<CallToolResult, ErrorDa
             format!("Failed to serialize response: {}", e),
         )
     })?;
-    Ok(CallToolResult::success(vec![Content::text(json)]))
+    Ok(CallToolResult::success(vec![ContentBlock::text(json)]))
 }
 
 pub fn text_result(message: impl Into<String>) -> CallToolResult {
-    CallToolResult::success(vec![Content::text(message.into())])
+    CallToolResult::success(vec![ContentBlock::text(message.into())])
 }
 
 pub fn map_err(e: impl Into<crate::services::error::ServiceError>) -> ErrorData {
@@ -41,7 +41,7 @@ pub fn map_err(e: impl Into<crate::services::error::ServiceError>) -> ErrorData
 /// Use this for business logic errors that the LLM can act on (not found, validation, permission).
 pub fn tool_error(e: impl Into<crate::services::error::ServiceError>) -> CallToolResult {
     let error = e.into();
-    CallToolResult::error(vec![Content::text(error.error_message())])
+    CallToolResult::error(vec![ContentBlock::text(error.error_message())])
 }
 
 pub fn resolve_actor(ctx: &RequestContext<RoleServer>) -> Result<Actor, ErrorData> {
diff --git a/apps/backend/src/mcp/resources/site_schema.rs b/apps/backend/src/mcp/resources/site_schema.rs
index 34100cf2..893a3967 100644
--- a/apps/backend/src/mcp/resources/site_schema.rs
+++ b/apps/backend/src/mcp/resources/site_schema.rs
@@ -2,8 +2,7 @@ use std::sync::Arc;
 
 use chrono::Utc;
 use rmcp::ErrorData as McpError;
-use rmcp::model::RawResource;
-use rmcp::model::{Annotated, Annotations, ListResourcesResult, ReadResourceResult, Resource, ResourceContents};
+use rmcp::model::{Annotations, ListResourcesResult, ReadResourceResult, Resource, ResourceContents};
 
 use crate::middleware::auth::Actor;
 use crate::models::authorization::Action;
@@ -26,19 +25,11 @@ fn resource_uri(site_id: &str, path: &str) -> String {
 }
 
 fn make_resource(uri: &str, name: &str, title: &str, description: &str) -> Resource {
-    Annotated::new(
-        RawResource {
-            uri: uri.to_string(),
-            name: name.to_string(),
-            title: Some(title.to_string()),
-            description: Some(description.to_string()),
-            mime_type: Some("application/json".to_string()),
-            size: None,
-            icons: None,
-            meta: None,
-        },
-        Some(Annotations::for_resource(0.5, Utc::now())),
-    )
+    Resource::new(uri, name)
+        .with_title(title)
+        .with_description(description)
+        .with_mime_type("application/json")
+        .with_annotations(Annotations::for_resource(0.5, Utc::now()))
 }
 
 fn collection_to_schema_value(c: &Collection) -> serde_json::Value {

From 46e6bf53f65dd647b19340452fc33267077db404 Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Wed, 1 Jul 2026 11:49:03 +0530
Subject: [PATCH 11/44] refactor(crypto): update AES-GCM nonce and key handling
 for improved clarity

---
 apps/backend/src/services/backup/mod.rs | 14 +++++++++-----
 apps/backend/src/services/webhook.rs    | 16 ++++++++++------
 2 files changed, 19 insertions(+), 11 deletions(-)

diff --git a/apps/backend/src/services/backup/mod.rs b/apps/backend/src/services/backup/mod.rs
index 7f24e0bd..8b73ac43 100644
--- a/apps/backend/src/services/backup/mod.rs
+++ b/apps/backend/src/services/backup/mod.rs
@@ -589,12 +589,12 @@ impl BackupService {
         if encrypt {
             let key = self.encryption_key.ok_or(BackupError::MissingKey)?;
             out.push(FLAG_ENCRYPTED);
-            let cipher = Aes256Gcm::new(Key::<Aes256Gcm>::from_slice(&key));
+            let cipher = Aes256Gcm::new(&Key::<Aes256Gcm>::from(key));
             let mut nonce_bytes = [0u8; 12];
             rand::rng().fill_bytes(&mut nonce_bytes);
-            let nonce = Nonce::from_slice(&nonce_bytes);
+            let nonce = Nonce::from(nonce_bytes);
             let ciphertext = cipher
-                .encrypt(nonce, compressed.as_ref())
+                .encrypt(&nonce, compressed.as_ref())
                 .map_err(|e| BackupError::Crypto(e.to_string()))?;
             out.extend_from_slice(&nonce_bytes);
             out.extend_from_slice(&ciphertext);
@@ -619,9 +619,13 @@ impl BackupService {
                 return Err(BackupError::Invalid("truncated encrypted backup".into()));
             }
             let (nonce_bytes, ciphertext) = body.split_at(12);
-            let cipher = Aes256Gcm::new(Key::<Aes256Gcm>::from_slice(&key));
+            let cipher = Aes256Gcm::new(&Key::<Aes256Gcm>::from(key));
+            let nonce_arr: [u8; 12] = nonce_bytes
+                .try_into()
+                .map_err(|_| BackupError::Invalid("truncated encrypted backup".into()))?;
+            let nonce = Nonce::from(nonce_arr);
             cipher
-                .decrypt(Nonce::from_slice(nonce_bytes), ciphertext)
+                .decrypt(&nonce, ciphertext)
                 .map_err(|_| BackupError::Crypto("decryption failed (wrong key?)".into()))?
         } else {
             body.to_vec()
diff --git a/apps/backend/src/services/webhook.rs b/apps/backend/src/services/webhook.rs
index fc30bf0f..7094a1fd 100644
--- a/apps/backend/src/services/webhook.rs
+++ b/apps/backend/src/services/webhook.rs
@@ -512,11 +512,11 @@ fn derive_encryption_key(secret: &str) -> [u8; 32] {
 /// `base64(nonce[12] || ciphertext||tag)`. A fresh random nonce is used per call.
 fn encrypt_headers(headers: &HashMap<String, String>, key: &[u8; 32]) -> String {
     let json = serde_json::to_string(headers).unwrap_or_default();
-    let cipher = Aes256Gcm::new(Key::<Aes256Gcm>::from_slice(key));
+    let cipher = Aes256Gcm::new(&Key::<Aes256Gcm>::from(*key));
     let mut nonce_bytes = [0u8; 12];
     rand::rng().fill_bytes(&mut nonce_bytes);
-    let nonce = Nonce::from_slice(&nonce_bytes);
-    match cipher.encrypt(nonce, json.as_bytes()) {
+    let nonce = Nonce::from(nonce_bytes);
+    match cipher.encrypt(&nonce, json.as_bytes()) {
         Ok(ciphertext) => {
             let mut out = Vec::with_capacity(nonce_bytes.len() + ciphertext.len());
             out.extend_from_slice(&nonce_bytes);
@@ -539,9 +539,13 @@ fn decrypt_headers(encrypted: &str, key: &[u8; 32]) -> HashMap<String, String> {
         return HashMap::new();
     }
     let (nonce_bytes, ciphertext) = raw.split_at(12);
-    let cipher = Aes256Gcm::new(Key::<Aes256Gcm>::from_slice(key));
-    let nonce = Nonce::from_slice(nonce_bytes);
-    match cipher.decrypt(nonce, ciphertext) {
+    let cipher = Aes256Gcm::new(&Key::<Aes256Gcm>::from(*key));
+    let nonce_arr: [u8; 12] = match nonce_bytes.try_into() {
+        Ok(n) => n,
+        Err(_) => return HashMap::new(),
+    };
+    let nonce = Nonce::from(nonce_arr);
+    match cipher.decrypt(&nonce, ciphertext) {
         Ok(plaintext) => match String::from_utf8(plaintext) {
             Ok(s) => serde_json::from_str(&s).unwrap_or_default(),
             Err(_) => HashMap::new(),

From 4c452fb91682b0bfd6eab44c4e6c20efbea15613 Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Wed, 1 Jul 2026 16:33:58 +0530
Subject: [PATCH 12/44] refactor(paths): extract system_home(), split layout
 resolution into pure function, add elevation preflight

- Add public system_home() as single source of truth for the OS service
  data directory (C:\ProgramData\vcms, /var/lib/vcms, etc.)
- Refactor layout() to gather filesystem/env inputs then delegate to a
  pure, testable resolve_layout() function with clear precedence:
   > system service home > legacy ~/.vcms > platform split
- Add preflight_system_home() that fails fast with an actionable hint
  when the active home is the system dir but the process lacks access
  (e.g. non-elevated CLI against ACL-locked ProgramData)
- Call preflight from ensure() so serve/admin/backup/restore surface
  the permission error early; read-only commands never trip it
- Add unit tests for the full resolve_layout() precedence chain
---
 apps/backend/src/paths.rs | 167 +++++++++++++++++++++++++++++++++-----
 1 file changed, 148 insertions(+), 19 deletions(-)

diff --git a/apps/backend/src/paths.rs b/apps/backend/src/paths.rs
index 5a213d83..02bb2af5 100644
--- a/apps/backend/src/paths.rs
+++ b/apps/backend/src/paths.rs
@@ -65,28 +65,73 @@ impl Layout {
     }
 }
 
-/// Resolve the active layout: `$VCMS_HOME` → legacy `~/.vcms` → platform split.
-fn layout() -> Layout {
-    if let Some(value) = std::env::var_os(CMS_HOME_ENV)
-        && !value.is_empty()
+/// The fixed system directory an installed OS service owns, per platform. This is the
+/// single source of truth for that path — the `service` submodules import it instead
+/// of re-declaring their own const. `None` on platforms without a service integration.
+pub fn system_home() -> Option<PathBuf> {
+    #[cfg(windows)]
     {
-        return Layout::Single(PathBuf::from(value));
+        Some(PathBuf::from(r"C:\ProgramData\vcms"))
     }
-
-    if let Some(base) = directories::BaseDirs::new() {
-        // Back-compat: a pre-existing single `~/.vcms` keeps owning everything so an
-        // upgrade never strands a user's database or secrets.
-        let legacy = base.home_dir().join(".vcms");
-        if legacy.is_dir() {
-            return Layout::Single(legacy);
-        }
+    #[cfg(target_os = "linux")]
+    {
+        Some(PathBuf::from("/var/lib/vcms"))
+    }
+    #[cfg(target_os = "macos")]
+    {
+        Some(PathBuf::from("/Library/Application Support/vcms"))
     }
+    #[cfg(not(any(windows, target_os = "linux", target_os = "macos")))]
+    {
+        None
+    }
+}
+
+/// Resolve the active layout: `$VCMS_HOME` → an existing system service home → legacy
+/// `~/.vcms` → platform split. Gathers the real filesystem/env inputs and defers the
+/// precedence decision to the pure [`resolve_layout`] (kept separate so it is testable
+/// without touching real system dirs).
+fn layout() -> Layout {
+    let env_home = std::env::var_os(CMS_HOME_ENV)
+        .filter(|v| !v.is_empty())
+        .map(PathBuf::from);
 
-    match directories::ProjectDirs::from("", "", "vcms") {
-        Some(dirs) => split_from(&dirs),
-        // No detectable platform dirs (rare): fall back to a local blob.
-        None => Layout::Single(PathBuf::from(".vcms")),
+    // A system home counts only when its dir already exists on disk: the OS-service
+    // installer creates it, and it survives uninstall (which leaves data behind). So a
+    // plain CLI invocation follows the service's data instead of forking to a second,
+    // per-user store. Absent (dev/eval boxes) → we fall through to the split layout.
+    let system = system_home().filter(|p| p.is_dir());
+
+    // Back-compat: a pre-existing single `~/.vcms` keeps owning everything so an upgrade
+    // never strands a user's database or secrets.
+    let legacy = directories::BaseDirs::new()
+        .map(|base| base.home_dir().join(".vcms"))
+        .filter(|p| p.is_dir());
+
+    let split = directories::ProjectDirs::from("", "", "vcms").map(|dirs| split_from(&dirs));
+
+    resolve_layout(env_home, system, legacy, split)
+}
+
+/// Pure precedence policy. Each `Option` is a candidate the caller has already vetted
+/// (env set & non-empty; system/legacy dirs confirmed to exist; split from `ProjectDirs`).
+/// Falls back to a local `.vcms` blob when no platform dirs are detectable (rare).
+fn resolve_layout(
+    env_home: Option<PathBuf>,
+    system_home: Option<PathBuf>,
+    legacy_home: Option<PathBuf>,
+    split: Option<Layout>,
+) -> Layout {
+    if let Some(root) = env_home {
+        return Layout::Single(root);
     }
+    if let Some(root) = system_home {
+        return Layout::Single(root);
+    }
+    if let Some(root) = legacy_home {
+        return Layout::Single(root);
+    }
+    split.unwrap_or_else(|| Layout::Single(PathBuf::from(".vcms")))
 }
 
 /// Map `ProjectDirs` onto our four directory classes. Logs use the state dir where
@@ -147,10 +192,38 @@ pub fn default_database_url() -> String {
     format!("sqlite://{}", default_db_path().to_string_lossy().replace('\\', "/"))
 }
 
+/// Fail fast when the active home is the system service home but this process can't
+/// access it (e.g. a non-elevated CLI against the ACL-locked `C:\ProgramData\vcms` or a
+/// root-owned `/var/lib/vcms`). Without this, a deep database/secrets read would blow up
+/// with an opaque IO error — and, worse, we must never silently fall back to a per-user
+/// store, which would recreate the very two-store split this resolution exists to kill.
+fn preflight_system_home() -> std::io::Result<()> {
+    let Layout::Single(root) = layout() else {
+        return Ok(());
+    };
+    if system_home().as_deref() != Some(root.as_path()) || !root.is_dir() {
+        return Ok(());
+    }
+    // A read probe: opening the db and secrets both need list+read on this dir.
+    match std::fs::read_dir(&root) {
+        Ok(_) => Ok(()),
+        Err(e) if e.kind() == std::io::ErrorKind::PermissionDenied => Err(std::io::Error::new(
+            std::io::ErrorKind::PermissionDenied,
+            format!(
+                "vcms data at {} requires Administrator/root; re-run in an elevated terminal.",
+                root.display()
+            ),
+        )),
+        Err(e) => Err(e),
+    }
+}
+
 /// Create the directories the running instance writes to (config, data, storage,
-/// logs). Called by commands that own/initialize the instance (`serve`, `admin`);
-/// read-only commands such as `mcp stdio` must not create anything.
+/// logs). Called by commands that own/initialize the instance (`serve`, `admin`,
+/// `backup`, `restore`); read-only commands such as `mcp stdio`, `config path/show`
+/// never call this and so never create anything or trip the preflight below.
 pub fn ensure() -> std::io::Result<()> {
+    preflight_system_home()?;
     let layout = layout();
     for dir in [
         layout.config(),
@@ -248,4 +321,60 @@ mod tests {
         };
         assert!(layout.state().join("logs").starts_with(Path::new("/dat")));
     }
+
+    fn split_sample() -> Option<Layout> {
+        Some(Layout::Split {
+            config: PathBuf::from("/c"),
+            data: PathBuf::from("/d"),
+            cache: PathBuf::from("/ch"),
+            state: PathBuf::from("/s"),
+        })
+    }
+
+    fn single_root_of(layout: Layout) -> Option<PathBuf> {
+        match layout {
+            Layout::Single(root) => Some(root),
+            Layout::Split { .. } => None,
+        }
+    }
+
+    #[test]
+    fn resolve_env_home_outranks_everything() {
+        let out = resolve_layout(
+            Some(PathBuf::from("/env")),
+            Some(PathBuf::from("/sys")),
+            Some(PathBuf::from("/legacy")),
+            split_sample(),
+        );
+        assert_eq!(single_root_of(out), Some(PathBuf::from("/env")));
+    }
+
+    #[test]
+    fn resolve_system_home_outranks_legacy_and_split() {
+        let out = resolve_layout(
+            None,
+            Some(PathBuf::from("/sys")),
+            Some(PathBuf::from("/legacy")),
+            split_sample(),
+        );
+        assert_eq!(single_root_of(out), Some(PathBuf::from("/sys")));
+    }
+
+    #[test]
+    fn resolve_legacy_home_when_no_env_or_system() {
+        let out = resolve_layout(None, None, Some(PathBuf::from("/legacy")), split_sample());
+        assert_eq!(single_root_of(out), Some(PathBuf::from("/legacy")));
+    }
+
+    #[test]
+    fn resolve_falls_through_to_split() {
+        let out = resolve_layout(None, None, None, split_sample());
+        assert!(matches!(out, Layout::Split { .. }));
+    }
+
+    #[test]
+    fn resolve_local_blob_when_nothing_detectable() {
+        let out = resolve_layout(None, None, None, None);
+        assert_eq!(single_root_of(out), Some(PathBuf::from(".vcms")));
+    }
 }

From 217ff3de99b71ae8f14c901cbe0b8aa5a877a954 Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Wed, 1 Jul 2026 16:34:11 +0530
Subject: [PATCH 13/44] fix(service/windows): harden install/uninstall
 lifecycle and use shared system_home()

- Replace hardcoded WINDOWS_SERVICE_HOME const with paths::system_home()
  so the CLI resolves to the same store as the running service
- Rewrite install() with clean-slate approach: stop + delete any lingering
  service record before creating fresh, avoiding the reuse trap after
  uninstall where Windows defers deletion and a stale record causes the
  new service to stay Stopped
- Wait for the service to reach Running before reporting success so
  crash-on-boot is no longer silently swallowed
- Add stop_and_wait(), wait_for_state(), wait_until_deleted() helpers
  with bounded SCM polling (30s timeout, 200ms interval)
- Handle ERROR_SERVICE_DOES_NOT_EXIST in uninstall() gracefully
- Report honestly when Windows defers deletion (handles still open)
---
 apps/backend/src/service/windows.rs | 147 +++++++++++++++++++++++-----
 1 file changed, 122 insertions(+), 25 deletions(-)

diff --git a/apps/backend/src/service/windows.rs b/apps/backend/src/service/windows.rs
index 8a316464..7a445836 100644
--- a/apps/backend/src/service/windows.rs
+++ b/apps/backend/src/service/windows.rs
@@ -8,10 +8,10 @@
 
 use std::ffi::OsString;
 use std::sync::Arc;
-use std::time::Duration;
+use std::time::{Duration, Instant};
 
 use windows_service::service::{
-    ServiceAccess, ServiceControl, ServiceControlAccept, ServiceErrorControl, ServiceExitCode, ServiceInfo,
+    Service, ServiceAccess, ServiceControl, ServiceControlAccept, ServiceErrorControl, ServiceExitCode, ServiceInfo,
     ServiceStartType, ServiceState, ServiceStatus, ServiceType,
 };
 use windows_service::service_control_handler::{self, ServiceControlHandlerResult};
@@ -22,7 +22,20 @@ use super::{ENV_TEMPLATE, SERVICE_DISPLAY_NAME, SERVICE_NAME};
 use crate::cli::{Cli, ServiceAction};
 
 /// Fixed home for the LocalSystem service (Windows convention is ProgramData).
-const WINDOWS_SERVICE_HOME: &str = r"C:\ProgramData\vcms";
+/// Defined once in `paths::system_home()` so a plain CLI invocation resolves to the
+/// same store; always `Some` on Windows.
+fn service_home() -> std::path::PathBuf {
+    crate::paths::system_home().expect("system_home is always set on Windows")
+}
+
+/// `ERROR_SERVICE_DOES_NOT_EXIST` — returned by `OpenServiceW` once the SCM has actually
+/// removed a record (deletion is deferred until every handle closes and the host exits).
+const ERROR_SERVICE_DOES_NOT_EXIST: i32 = 1060;
+
+/// Upper bound on any SCM state transition we wait for (stop, delete-finalize, start).
+const SCM_WAIT: Duration = Duration::from_secs(30);
+/// Poll interval while waiting on the SCM.
+const SCM_POLL: Duration = Duration::from_millis(200);
 
 pub fn dispatch(action: &ServiceAction, _cli: &Cli) -> Result<(), Box<dyn std::error::Error>> {
     match action {
@@ -63,42 +76,126 @@ fn install() -> Result<(), Box<dyn std::error::Error>> {
         account_password: None,
     };
 
-    let access = ServiceAccess::CHANGE_CONFIG | ServiceAccess::START;
-    let service = match manager.create_service(&info, access) {
-        Ok(service) => service,
-        // Already installed: update config and reuse it (idempotent install).
-        Err(_) => {
-            let service = manager.open_service(SERVICE_NAME, access).map_err(elevation_hint)?;
-            service.change_config(&info).map_err(elevation_hint)?;
-            println!("Service '{SERVICE_NAME}' already existed; configuration updated.");
-            service
+    // Start from a clean slate: tear down any lingering record first so we always
+    // `create_service` fresh. Reusing an existing entry is the reinstall trap — after an
+    // uninstall the old record can still be present (Windows defers deletion), and a
+    // reused/DELETE_PENDING service ends up Stopped instead of running the new config.
+    if let Ok(existing) = manager.open_service(
+        SERVICE_NAME,
+        ServiceAccess::STOP | ServiceAccess::DELETE | ServiceAccess::QUERY_STATUS,
+    ) {
+        stop_and_wait(&existing);
+        let _ = existing.delete(); // marks for deletion; finalizes once handles close
+        drop(existing); // close our handle so the SCM can finish removing the record
+        if !wait_until_deleted(&manager, SCM_WAIT) {
+            return Err("a previous 'vcms' service is still being removed by Windows; \
+                        wait a few seconds and re-run `vcms service install`"
+                .into());
         }
-    };
+    }
+
+    let access = ServiceAccess::CHANGE_CONFIG | ServiceAccess::START | ServiceAccess::QUERY_STATUS;
+    let service = manager.create_service(&info, access).map_err(elevation_hint)?;
     let _ = service.set_description(SERVICE_DISPLAY_NAME);
 
     prepare_home()?;
 
-    let already_running = service
-        .query_status()
-        .map(|s| s.current_state == windows_service::service::ServiceState::Running)
-        .unwrap_or(false);
-    if !already_running {
-        service.start::<&str>(&[])?;
+    service.start::<&str>(&[]).map_err(elevation_hint)?;
+    // Verify the service actually reached Running before claiming success — the old code
+    // printed "started" unconditionally, which is how a crash-on-boot slipped through.
+    if !wait_for_state(&service, ServiceState::Running, SCM_WAIT) {
+        return Err(format!(
+            "Service '{SERVICE_NAME}' was installed but did not reach Running. Check the logs under \
+             {}\\logs (read them from an elevated terminal). A common cause is another process already \
+             bound to the REST/gRPC ports.",
+            service_home().display()
+        )
+        .into());
     }
     println!("Service '{SERVICE_NAME}' installed (auto-start, LocalSystem) and started.");
-    println!("Home + secrets (.env): {WINDOWS_SERVICE_HOME}");
+    println!("Home + secrets (.env): {}", service_home().display());
     println!("Check it with:  vcms service status");
     Ok(())
 }
 
 fn uninstall() -> Result<(), Box<dyn std::error::Error>> {
-    let service = open_service(ServiceAccess::STOP | ServiceAccess::DELETE | ServiceAccess::QUERY_STATUS)?;
-    let _ = service.stop(); // best-effort; may already be stopped
+    let manager =
+        ServiceManager::local_computer(None::<&str>, ServiceManagerAccess::CONNECT).map_err(elevation_hint)?;
+    let service = match manager.open_service(
+        SERVICE_NAME,
+        ServiceAccess::STOP | ServiceAccess::DELETE | ServiceAccess::QUERY_STATUS,
+    ) {
+        Ok(service) => service,
+        Err(windows_service::Error::Winapi(e)) if e.raw_os_error() == Some(ERROR_SERVICE_DOES_NOT_EXIST) => {
+            println!("Service '{SERVICE_NAME}' is not installed.");
+            return Ok(());
+        }
+        Err(e) => return Err(elevation_hint(e)),
+    };
+
+    stop_and_wait(&service);
     service.delete()?;
-    println!("Service '{SERVICE_NAME}' uninstalled. Your data under {WINDOWS_SERVICE_HOME} was left intact.");
+    drop(service); // close our handle so the SCM can finalize removal
+
+    if wait_until_deleted(&manager, SCM_WAIT) {
+        println!(
+            "Service '{SERVICE_NAME}' uninstalled. Your data under {} was left intact.",
+            service_home().display()
+        );
+    } else {
+        // Deletion is queued but a handle elsewhere (e.g. an open Services.msc) is holding
+        // it; it will vanish once that closes. Report honestly instead of implying it's gone.
+        println!(
+            "Service '{SERVICE_NAME}' stop + delete requested; Windows will finish removing it once all \
+             handles close. Your data under {} was left intact.",
+            service_home().display()
+        );
+    }
     Ok(())
 }
 
+/// Request a stop and wait until the service reports `Stopped` (bounded). Tolerates a
+/// service that is already stopped or marked for deletion — both surface as `stop()`
+/// errors we intentionally ignore.
+fn stop_and_wait(service: &Service) {
+    let _ = service.stop();
+    wait_for_state(service, ServiceState::Stopped, SCM_WAIT);
+}
+
+/// Poll `query_status` until the service reaches `target` or the timeout elapses.
+/// Returns whether the target state was observed.
+fn wait_for_state(service: &Service, target: ServiceState, timeout: Duration) -> bool {
+    let deadline = Instant::now() + timeout;
+    loop {
+        if matches!(service.query_status(), Ok(status) if status.current_state == target) {
+            return true;
+        }
+        if Instant::now() >= deadline {
+            return false;
+        }
+        std::thread::sleep(SCM_POLL);
+    }
+}
+
+/// Poll until opening the service fails with `ERROR_SERVICE_DOES_NOT_EXIST` — i.e. the
+/// SCM has actually removed the record — or the timeout elapses. Each probe drops its
+/// handle immediately so it never itself keeps the record alive.
+fn wait_until_deleted(manager: &ServiceManager, timeout: Duration) -> bool {
+    let deadline = Instant::now() + timeout;
+    loop {
+        match manager.open_service(SERVICE_NAME, ServiceAccess::QUERY_STATUS) {
+            Err(windows_service::Error::Winapi(e)) if e.raw_os_error() == Some(ERROR_SERVICE_DOES_NOT_EXIST) => {
+                return true;
+            }
+            _ => {}
+        }
+        if Instant::now() >= deadline {
+            return false;
+        }
+        std::thread::sleep(SCM_POLL);
+    }
+}
+
 fn start() -> Result<(), Box<dyn std::error::Error>> {
     let service = open_service(ServiceAccess::START)?;
     service.start::<&str>(&[])?;
@@ -136,7 +233,7 @@ fn elevation_hint(e: windows_service::Error) -> Box<dyn std::error::Error> {
 /// Create the service home + optional `.env` under ProgramData, locked to
 /// SYSTEM and Administrators only.
 fn prepare_home() -> Result<(), Box<dyn std::error::Error>> {
-    let home = std::path::PathBuf::from(WINDOWS_SERVICE_HOME);
+    let home = service_home();
     std::fs::create_dir_all(&home)?;
     let env_file = home.join(".env");
     if !env_file.exists() {
@@ -182,7 +279,7 @@ fn run_dispatcher() -> Result<(), Box<dyn std::error::Error>> {
     if std::env::var_os(crate::paths::CMS_HOME_ENV).is_none() {
         // SAFETY: called once at process start, before tokio/threads spin up.
         unsafe {
-            std::env::set_var(crate::paths::CMS_HOME_ENV, WINDOWS_SERVICE_HOME);
+            std::env::set_var(crate::paths::CMS_HOME_ENV, service_home());
         }
     }
     service_dispatcher::start(SERVICE_NAME, ffi_service_main)?;

From 28a146a94d3f6b79628d190ccdc3c3f550d685aa Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Wed, 1 Jul 2026 16:34:23 +0530
Subject: [PATCH 14/44] refactor(service/linux): use shared
 paths::system_home() instead of local const

Replace SERVICE_HOME const with a service_home() function that delegates
to paths::system_home(), ensuring the CLI resolves to the same data
directory as the running service. No functional change on Linux.
---
 apps/backend/src/service/linux.rs | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/apps/backend/src/service/linux.rs b/apps/backend/src/service/linux.rs
index 67e3862a..bc63608b 100644
--- a/apps/backend/src/service/linux.rs
+++ b/apps/backend/src/service/linux.rs
@@ -9,8 +9,12 @@ use crate::cli::{Cli, ServiceAction};
 /// Where the generated unit file is written.
 const UNIT_PATH: &str = "/etc/systemd/system/vcms.service";
 
-/// System data directory the daemon owns (FHS convention for service state).
-const SERVICE_HOME: &str = "/var/lib/vcms";
+/// System data directory the daemon owns (FHS convention for service state). Defined
+/// once in `paths::system_home()` so a plain CLI invocation resolves to the same store;
+/// always `Some` on Linux.
+fn service_home() -> PathBuf {
+    crate::paths::system_home().expect("system_home is always set on Linux")
+}
 
 pub fn dispatch(action: &ServiceAction, _cli: &Cli) -> Result<(), Box<dyn std::error::Error>> {
     match action {
@@ -33,7 +37,7 @@ fn install(user: Option<&str>) -> Result<(), Box<dyn std::error::Error>> {
     let user = resolve_run_user(user)?;
     // The daemon stores everything under one system dir (VCMS_HOME single-layout),
     // owned by the run-as account — not that account's per-user `~/.config` etc.
-    let vcms_home = PathBuf::from(SERVICE_HOME);
+    let vcms_home = service_home();
     let exe_path = std::env::current_exe()?;
     let opts = InstallOptions {
         user: user.clone(),
@@ -64,7 +68,10 @@ fn uninstall() -> Result<(), Box<dyn std::error::Error>> {
         println!("Removed {UNIT_PATH}");
     }
     run(Command::new("systemctl").arg("daemon-reload"))?;
-    println!("Service '{SERVICE_NAME}' uninstalled. Your data under {SERVICE_HOME} was left intact.");
+    println!(
+        "Service '{SERVICE_NAME}' uninstalled. Your data under {} was left intact.",
+        service_home().display()
+    );
     Ok(())
 }
 

From e4a82f98eb0cfe666f2cd2055f2f4c5be80ac771 Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Wed, 1 Jul 2026 16:34:36 +0530
Subject: [PATCH 15/44] refactor(service/macos): use shared
 paths::system_home() instead of local const

Replace SERVICE_HOME const with a service_home() function that delegates
to paths::system_home(), ensuring the CLI resolves to the same data
directory as the running service. No functional change on macOS.
---
 apps/backend/src/service/macos.rs | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/apps/backend/src/service/macos.rs b/apps/backend/src/service/macos.rs
index 00623d62..a68e18a1 100644
--- a/apps/backend/src/service/macos.rs
+++ b/apps/backend/src/service/macos.rs
@@ -10,7 +10,11 @@ use crate::cli::{Cli, ServiceAction};
 const PLIST_PATH: &str = "/Library/LaunchDaemons/local.vcms.plist";
 
 /// System data directory the daemon owns (macOS convention for shared app data).
-const SERVICE_HOME: &str = "/Library/Application Support/vcms";
+/// Defined once in `paths::system_home()` so a plain CLI invocation resolves to the
+/// same store; always `Some` on macOS.
+fn service_home() -> PathBuf {
+    crate::paths::system_home().expect("system_home is always set on macOS")
+}
 
 /// Modern launchctl service target (`system/<label>`).
 fn target() -> String {
@@ -31,7 +35,7 @@ fn install(user: Option<&str>) -> Result<(), Box<dyn std::error::Error>> {
     require_root("install")?;
     let user = resolve_run_user(user)?;
     // One system dir (VCMS_HOME single-layout), owned by the run-as account.
-    let vcms_home = PathBuf::from(SERVICE_HOME);
+    let vcms_home = service_home();
     let exe_path = std::env::current_exe()?;
     let opts = InstallOptions {
         user: user.clone(),
@@ -66,7 +70,10 @@ fn uninstall() -> Result<(), Box<dyn std::error::Error>> {
         std::fs::remove_file(PLIST_PATH)?;
         println!("Removed {PLIST_PATH}");
     }
-    println!("Service '{LAUNCHD_LABEL}' uninstalled. Your data under {SERVICE_HOME} was left intact.");
+    println!(
+        "Service '{LAUNCHD_LABEL}' uninstalled. Your data under {} was left intact.",
+        service_home().display()
+    );
     Ok(())
 }
 

From c42891daef9d53f2b9e37c76c7cac405661db880 Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Wed, 1 Jul 2026 16:34:50 +0530
Subject: [PATCH 16/44] fix(main): tolerate PermissionDenied when loading .env
 from system home
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The home .env is optional; when it lives in the ACL-locked system service
home (e.g. C:\ProgramData\vcms), a non-elevated CLI legitimately cannot
read it — most notably vcms mcp stdio, a proxy that needs no home file.
Treat permission denied like absent and let the data-touching commands
hit paths::ensure()'s preflight, which reports the access problem with
an actionable hint.
---
 apps/backend/src/main.rs | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/apps/backend/src/main.rs b/apps/backend/src/main.rs
index 28bf2e61..1a877e68 100644
--- a/apps/backend/src/main.rs
+++ b/apps/backend/src/main.rs
@@ -19,6 +19,13 @@ async fn main() {
     match dotenvy::from_path(&env_file) {
         Ok(()) => {}
         Err(e) if e.not_found() => {} // missing file is fine
+        // The home `.env` is optional. When it lives in the system service home
+        // (`C:\ProgramData\vcms`, `/var/lib/vcms`) it's ACL-locked to SYSTEM/root, so a
+        // non-elevated CLI legitimately can't read it — most notably `vcms mcp stdio`,
+        // a proxy that needs no home file at all. Treat "permission denied" like
+        // "absent" and move on: the data-touching commands still hit `paths::ensure`'s
+        // elevate preflight, which reports the access problem with an actionable hint.
+        Err(dotenvy::Error::Io(io)) if io.kind() == std::io::ErrorKind::PermissionDenied => {}
         Err(e) => {
             eprintln!("Error: cannot load {}: {e}", env_file.display());
             std::process::exit(1);

From 7a12b03d952d03072b7254ca8b595ccb8f5e2c35 Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Wed, 1 Jul 2026 16:35:04 +0530
Subject: [PATCH 17/44] docs(AGENTS.md): clarify single-layout precedence and
 elevation requirement

Document the three-tier single-layout resolution (env > system service
home > legacy ~/.vcms) and the new behavior where data-touching commands
fail fast when the system home is ACL-locked and the process lacks
elevation.
---
 AGENTS.md | 22 +++++++++++++++++-----
 1 file changed, 17 insertions(+), 5 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 0b0d19e7..ca10f176 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -122,17 +122,29 @@ per-type directories via the `directories` crate (`ProjectDirs`):
 
 (`logs/` uses the state dir where the platform has one — Linux — else the local data dir.)
 
-**Single** — everything nests under one root. Chosen when **`$VCMS_HOME` is set** (the
-`vcms service` installer pins it to a system dir: Linux `/var/lib/vcms`, macOS
-`/Library/Application Support/vcms`, Windows `C:\ProgramData\vcms`), or when a legacy
-**`~/.vcms`** already exists (so an existing install keeps working untouched):
+**Single** — everything nests under one root. Chosen (in precedence order) when:
+1. **`$VCMS_HOME` is set** — forces the root explicitly.
+2. **the system service home dir exists** — Linux `/var/lib/vcms`, macOS
+   `/Library/Application Support/vcms`, Windows `C:\ProgramData\vcms`. The
+   `vcms service` installer creates it (and leaves it behind on uninstall), so a plain
+   `vcms serve`/`admin`/`backup` **follows the service's data instead of forking to a
+   per-user split store**. This path is defined once in `paths::system_home()` and
+   imported by the `service` submodules.
+3. **a legacy `~/.vcms` exists** — an existing install keeps working untouched.
+
+Otherwise (dev/eval boxes with no service) files use the platform split dirs.
 
 ```text
-$VCMS_HOME/                # or ~/.vcms (legacy)
+$VCMS_HOME/                # or system home, or ~/.vcms (legacy)
   config.toml secrets.toml .env
   vcms.db (+ -wal / -shm)  logs/  storage/  backups/  search/
 ```
 
+When the active home is the system service home (owned by SYSTEM/root), the
+data-touching commands (`serve`/`admin`/`backup`/`restore`) require elevation — a
+non-elevated invocation **fails fast** with an "Administrator/root" hint (in
+`paths::ensure`'s preflight) rather than silently forking to a second store.
+
 Secrets: on first `serve`/`admin`, a random `HMAC_SECRET` is generated and persisted to
 `secrets.toml` (`apps/backend/src/secrets.rs`), then loaded by the server processes.
 `vcms mcp stdio` does **not** load secrets, the database, or any data-dir file: it is a

From ff130036ac5d526eb775b8f73eb0238db261b86c Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Wed, 1 Jul 2026 16:35:16 +0530
Subject: [PATCH 18/44] docs(CLAUDE.md): clarify single-layout precedence and
 elevation requirement

Mirror the AGENTS.md updates: document the three-tier single-layout
resolution and the fast-fail behavior when the system home requires
elevation.
---
 CLAUDE.md | 22 ++++++++++++++++------
 1 file changed, 16 insertions(+), 6 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 111bd897..a8fb3a63 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -113,19 +113,29 @@ per-type directories via the `directories` crate (`ProjectDirs`):
 
 (`logs/` uses the state dir where the platform has one — Linux — else the local data dir.)
 
-**Single** — everything nests under one root. Chosen when **`$VCMS_HOME` is set** (the
-`vcms service` installer pins it to a system dir: Linux `/var/lib/vcms`, macOS
-`/Library/Application Support/vcms`, Windows `C:\ProgramData\vcms`), or when a legacy
-**`~/.vcms`** already exists (so an existing install keeps working untouched):
+**Single** — everything nests under one root. Chosen (in precedence order) when:
+1. **`$VCMS_HOME` is set** — forces the root explicitly.
+2. **the system service home dir exists** — Linux `/var/lib/vcms`, macOS
+   `/Library/Application Support/vcms`, Windows `C:\ProgramData\vcms`. The
+   `vcms service` installer creates it (and leaves it behind on uninstall), so a plain
+   `vcms serve`/`admin`/`backup` **follows the service's data instead of forking to a
+   per-user split store**. This path is defined once in `paths::system_home()` and
+   imported by the `service` submodules.
+3. **a legacy `~/.vcms` exists** — an existing install keeps working untouched.
+
+Otherwise (dev/eval boxes with no service) files use the platform split dirs.
 
 ```text
-$VCMS_HOME/                # or ~/.vcms (legacy)
+$VCMS_HOME/                # or system home, or ~/.vcms (legacy)
   config.toml secrets.toml .env
   vcms.db (+ -wal / -shm)  logs/  storage/  backups/  search/
 ```
 
 `vcms serve`/`admin` create the dirs they need on first run; `vcms mcp stdio` creates
-nothing.
+nothing. When the active home is the system service home (owned by SYSTEM/root), the
+data-touching commands (`serve`/`admin`/`backup`/`restore`) require elevation — a
+non-elevated invocation **fails fast** with an "Administrator/root" hint (in
+`paths::ensure`'s preflight) rather than silently forking to a second store.
 
 Secrets: on first `serve`/`admin`, a random `HMAC_SECRET` is generated
 and persisted to `secrets.toml` (`apps/backend/src/secrets.rs`), then loaded by

From bd9c4bbbcf79487432750c1bd7fb6987d701a3d9 Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Wed, 1 Jul 2026 16:35:28 +0530
Subject: [PATCH 19/44] docs(README): explain that CLI follows the service's
 data directory

Clarify that once the system service home exists, any CLI invocation
(even with the service stopped or uninstalled) targets the same store
rather than creating a per-user copy, and that elevated permissions are
required because the directory is owned by SYSTEM/root.
---
 README.md | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index f4ee9ed8..5bcb0c8e 100644
--- a/README.md
+++ b/README.md
@@ -126,10 +126,16 @@ By default, runtime files go to the platform-conventional per-type directories
 | `logs/` | `~/.local/state/vcms` | `~/Library/Application Support/vcms` | `%LOCALAPPDATA%\vcms\data` |
 
 Set **`$VCMS_HOME`** to keep everything under a single root instead (and an existing
-`~/.vcms` is honored automatically, so upgrades don't move your data). The `vcms
-service` installer uses this to pin the daemon to one system dir — `/var/lib/vcms`
-(Linux), `/Library/Application Support/vcms` (macOS), or `C:\ProgramData\vcms`
-(Windows).
+`~/.vcms` is honored automatically, so upgrades don't move your data).
+
+The `vcms service` installer stores the daemon's data under one system dir —
+`/var/lib/vcms` (Linux), `/Library/Application Support/vcms` (macOS), or
+`C:\ProgramData\vcms` (Windows). **Once that directory exists, the CLI uses it too**:
+a plain `vcms serve`/`admin`/`backup` — even after the service is stopped or
+uninstalled — targets the *same* store rather than a separate per-user copy, so you
+never end up with two sets of data. Because that directory is owned by SYSTEM/root,
+run those commands from an elevated (Administrator/`sudo`) terminal; a non-elevated
+run fails with a clear hint instead of silently creating a second store.
 
 `vcms serve` creates what it needs on first run and generates `secrets.toml` if
 absent. Environment variables (`DATABASE_URL`, `HMAC_SECRET`, `STORAGE_FS_PATH`,

From a447f13e95ad7f68d94622dd187c2b240570b946 Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Thu, 2 Jul 2026 19:40:04 +0530
Subject: [PATCH 20/44] chore(deps): add futures-util and infer; promote
 tokio-stream to main deps

---
 Cargo.lock              | 22 ++++++++++++++++++++++
 apps/backend/Cargo.toml |  4 +++-
 2 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/Cargo.lock b/Cargo.lock
index 47b61b71..5a6fd5c6 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -669,6 +669,17 @@ version = "0.4.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4f4c707c6a209cbe82d10abd08e1ea8995e9ea937d2550646e02798948992be0"
 
+[[package]]
+name = "cfb"
+version = "0.7.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d38f2da7a0a2c4ccf0065be06397cc26a81f4e528be095826eee9d4adbb8c60f"
+dependencies = [
+ "byteorder",
+ "fnv",
+ "uuid",
+]
+
 [[package]]
 name = "cfg-if"
 version = "1.0.4"
@@ -794,11 +805,13 @@ dependencies = [
  "dotenvy",
  "email_address",
  "figment",
+ "futures-util",
  "hex",
  "hmac",
  "http",
  "http-body-util",
  "image",
+ "infer",
  "json-patch",
  "libc",
  "mime_guess",
@@ -2179,6 +2192,15 @@ dependencies = [
  "serde_core",
 ]
 
+[[package]]
+name = "infer"
+version = "0.19.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a588916bfdfd92e71cacef98a63d9b1f0d74d6599980d11894290e7ddefffcf7"
+dependencies = [
+ "cfb",
+]
+
 [[package]]
 name = "inlinable_string"
 version = "0.1.15"
diff --git a/apps/backend/Cargo.toml b/apps/backend/Cargo.toml
index 6e534537..1dcbb4ef 100644
--- a/apps/backend/Cargo.toml
+++ b/apps/backend/Cargo.toml
@@ -40,6 +40,8 @@ dotenvy = "0.15"
 image = { version = "0.25", default-features = false, features = ["png", "jpeg", "webp", "gif", "avif"] }
 object_store = { version = "0.14", features = ["aws"] }
 bytes = "1"
+futures-util = "0.3"
+infer = "0.19"
 http = "1"
 regex = "1"
 json-patch = "4"
@@ -67,6 +69,7 @@ tonic-health = "0.14"
 http-body-util = "0.1.3"
 rmcp = { version = "2.0", features = ["server", "transport-io", "transport-streamable-http-server", "macros", "schemars"] }
 tokio-util = { version = "0.7", features = ["rt"] }
+tokio-stream = { version = "0.1", features = ["net"] }
 schemars = "1"
 clap = { version = "4.6.1", features = ["derive", "env"] }
 figment = { version = "0.10.19", features = ["toml", "env"] }
@@ -92,5 +95,4 @@ tonic-prost-build = "0.14"
 [dev-dependencies]
 tempfile = "3"
 tokio-test = "0.4"
-tokio-stream = { version = "0.1", features = ["net"] }
 wiremock = "0.6"

From bb2adcbcc6d1efcf39541053d3ff963c97bf98dc Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Thu, 2 Jul 2026 19:40:20 +0530
Subject: [PATCH 21/44] feat(upload): add magic bytes content sniffing for MIME
 validation

New utils::magic_bytes module compares declared MIME types against file
signatures using the infer crate. Types with reliable magic-byte
signatures (images, video, audio, PDF, archives, Office formats) are
checked; signature-less types (text, CSV, SVG) are skipped.

The module is not yet wired into the upload path (follow-up commit).
---
 apps/backend/src/utils/magic_bytes.rs | 142 ++++++++++++++++++++++++++
 apps/backend/src/utils/mod.rs         |   1 +
 2 files changed, 143 insertions(+)
 create mode 100644 apps/backend/src/utils/magic_bytes.rs

diff --git a/apps/backend/src/utils/magic_bytes.rs b/apps/backend/src/utils/magic_bytes.rs
new file mode 100644
index 00000000..ff7a74ee
--- /dev/null
+++ b/apps/backend/src/utils/magic_bytes.rs
@@ -0,0 +1,142 @@
+//! Content sniffing for uploads: compare the declared MIME type against the
+//! file's magic bytes so a payload can't claim to be something it isn't
+//! (e.g. an executable declared as `image/png`).
+//!
+//! Only types with reliable signatures are checked; signature-less formats
+//! (plain text, CSV, SVG, ...) and declared types we have no table entry for
+//! are skipped rather than rejected.
+
+/// How many leading bytes the sniffer needs. Callers should buffer up to this
+/// many bytes (or the whole body, if smaller) before checking.
+pub const SNIFF_LEN: usize = 8192;
+
+/// Result of a sniff check.
+#[derive(Debug, PartialEq, Eq)]
+pub enum Sniff {
+    /// Detected type is compatible with the declared type.
+    Match,
+    /// Detected type contradicts the declared type (detected type inside, if any).
+    Mismatch(Option<&'static str>),
+    /// Declared type has no reliable signature — nothing to verify.
+    Skip,
+}
+
+/// MIME types accepted as a detection result for each checkable declared type.
+/// Groups exist because containers overlap (mp4/quicktime brands, ogg family,
+/// webm-is-matroska, OOXML-is-zip, legacy Office CFB).
+fn accepted_detections(declared: &str) -> Option<&'static [&'static str]> {
+    const OOXML_OR_ZIP: &[&str] = &[
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+        "application/zip",
+    ];
+    const LEGACY_OFFICE: &[&str] = &[
+        "application/msword",
+        "application/vnd.ms-excel",
+        "application/vnd.ms-powerpoint",
+        "application/x-ole-storage",
+    ];
+    const OGG: &[&str] = &["application/ogg", "audio/ogg", "video/ogg"];
+    const MP4_FAMILY: &[&str] = &["video/mp4", "video/quicktime", "video/x-m4v"];
+    const MATROSKA: &[&str] = &["video/webm", "video/x-matroska", "audio/webm"];
+
+    Some(match declared {
+        "image/jpeg" | "image/jpg" => &["image/jpeg"],
+        "image/png" => &["image/png"],
+        "image/gif" => &["image/gif"],
+        "image/webp" => &["image/webp"],
+        "image/avif" => &["image/avif", "image/heif", "image/heic"],
+        "image/tiff" => &["image/tiff"],
+        "image/bmp" => &["image/bmp"],
+        "video/mp4" | "video/quicktime" => MP4_FAMILY,
+        "video/webm" | "audio/webm" => MATROSKA,
+        "video/ogg" | "audio/ogg" => OGG,
+        "video/x-msvideo" => &["video/x-msvideo"],
+        "audio/mpeg" => &["audio/mpeg", "audio/mp3"],
+        "audio/wav" => &["audio/wav", "audio/x-wav"],
+        "audio/aac" => &["audio/aac"],
+        "audio/flac" => &["audio/flac", "audio/x-flac"],
+        "application/pdf" => &["application/pdf"],
+        "application/msword" | "application/vnd.ms-excel" | "application/vnd.ms-powerpoint" => LEGACY_OFFICE,
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+        | "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+        | "application/vnd.openxmlformats-officedocument.presentationml.presentation"
+        | "application/zip" => OOXML_OR_ZIP,
+        "application/gzip" => &["application/gzip"],
+        "application/x-tar" => &["application/x-tar"],
+        "application/x-7z-compressed" => &["application/x-7z-compressed"],
+        "application/x-rar-compressed" => &["application/vnd.rar", "application/x-rar-compressed"],
+        // Signature-less or unknown declared types: nothing to verify.
+        _ => return None,
+    })
+}
+
+/// Check `prefix` (the first bytes of the payload, up to [`SNIFF_LEN`]) against
+/// the declared MIME type.
+pub fn check(declared_mime: &str, prefix: &[u8]) -> Sniff {
+    let Some(accepted) = accepted_detections(declared_mime) else {
+        return Sniff::Skip;
+    };
+
+    match infer::get(prefix) {
+        Some(kind) if accepted.contains(&kind.mime_type()) => Sniff::Match,
+        Some(kind) => Sniff::Mismatch(Some(kind.mime_type())),
+        None => Sniff::Mismatch(None),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn png_signature_matches() {
+        let png = [0x89, b'P', b'N', b'G', 0x0D, 0x0A, 0x1A, 0x0A, 0, 0, 0, 0];
+        assert_eq!(check("image/png", &png), Sniff::Match);
+    }
+
+    #[test]
+    fn jpeg_signature_matches() {
+        let jpeg = [0xFF, 0xD8, 0xFF, 0xE0, 0, 0, 0, 0];
+        assert_eq!(check("image/jpeg", &jpeg), Sniff::Match);
+    }
+
+    #[test]
+    fn pdf_signature_matches() {
+        assert_eq!(check("application/pdf", b"%PDF-1.7 rest of file"), Sniff::Match);
+    }
+
+    #[test]
+    fn text_declared_as_png_is_mismatch() {
+        assert_eq!(check("image/png", b"definitely not a png"), Sniff::Mismatch(None));
+    }
+
+    #[test]
+    fn png_declared_as_jpeg_is_mismatch() {
+        let png = [0x89, b'P', b'N', b'G', 0x0D, 0x0A, 0x1A, 0x0A, 0, 0, 0, 0];
+        assert_eq!(check("image/jpeg", &png), Sniff::Mismatch(Some("image/png")));
+    }
+
+    #[test]
+    fn signature_less_types_are_skipped() {
+        assert_eq!(check("text/plain", b"hello"), Sniff::Skip);
+        assert_eq!(check("text/csv", b"a,b,c"), Sniff::Skip);
+        assert_eq!(check("image/svg+xml", b"<svg/>"), Sniff::Skip);
+        assert_eq!(check("application/octet-stream", &[0, 1, 2]), Sniff::Skip);
+    }
+
+    #[test]
+    fn ooxml_zip_family_is_interchangeable() {
+        // Minimal ZIP local-file-header signature.
+        let zip = [b'P', b'K', 0x03, 0x04, 0, 0, 0, 0];
+        assert_eq!(
+            check(
+                "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+                &zip
+            ),
+            Sniff::Match
+        );
+        assert_eq!(check("application/zip", &zip), Sniff::Match);
+    }
+}
diff --git a/apps/backend/src/utils/mod.rs b/apps/backend/src/utils/mod.rs
index 7dffe145..8c8fd09a 100644
--- a/apps/backend/src/utils/mod.rs
+++ b/apps/backend/src/utils/mod.rs
@@ -1,2 +1,3 @@
 pub mod content_types;
 pub mod diff;
+pub mod magic_bytes;

From ebe21a3af64214b9c84b5456f11befad07c6d7cc Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Thu, 2 Jul 2026 19:40:30 +0530
Subject: [PATCH 22/44] feat(storage): add multipart streaming upload to
 StorageProvider

Extend the StorageProvider trait with start_multipart() that returns an
object_store::MultipartUpload. Implementations:

- FileSystemStorage: put_multipart on the local ObjectStore
- S3Storage: put_multipart on the S3 ObjectStore
- MockStorage: in-memory MockMultipartUpload for tests (parts
  accumulate in a Vec, published on complete, cleared on abort)
---
 apps/backend/src/storage/filesystem.rs |  8 ++++
 apps/backend/src/storage/mod.rs        | 53 +++++++++++++++++++++++++-
 apps/backend/src/storage/s3.rs         |  8 ++++
 3 files changed, 68 insertions(+), 1 deletion(-)

diff --git a/apps/backend/src/storage/filesystem.rs b/apps/backend/src/storage/filesystem.rs
index 088ed316..6094df41 100644
--- a/apps/backend/src/storage/filesystem.rs
+++ b/apps/backend/src/storage/filesystem.rs
@@ -81,6 +81,14 @@ impl StorageProvider for FileSystemStorage {
     fn url(&self, key: &str, file_id: &str) -> String {
         self.url(key, file_id)
     }
+
+    async fn start_multipart(
+        &self,
+        key: &str,
+    ) -> Result<Box<dyn object_store::MultipartUpload>, Box<dyn std::error::Error + Send + Sync>> {
+        let path = ObjectPath::from(key);
+        Ok(self.store.put_multipart(&path).await?)
+    }
 }
 
 #[cfg(test)]
diff --git a/apps/backend/src/storage/mod.rs b/apps/backend/src/storage/mod.rs
index ec225bff..95143ac1 100644
--- a/apps/backend/src/storage/mod.rs
+++ b/apps/backend/src/storage/mod.rs
@@ -78,11 +78,51 @@ pub trait StorageProvider: Send + Sync {
     async fn get(&self, key: &str) -> Result<Bytes, Box<dyn std::error::Error + Send + Sync>>;
     async fn delete(&self, key: &str) -> Result<(), Box<dyn std::error::Error + Send + Sync>>;
     fn url(&self, key: &str, file_id: &str) -> String;
+    /// Begin a streaming (multipart) upload to `key`. Drive it with
+    /// [`object_store::WriteMultipart`]; `abort()` cleans up partial state.
+    async fn start_multipart(
+        &self,
+        key: &str,
+    ) -> Result<Box<dyn object_store::MultipartUpload>, Box<dyn std::error::Error + Send + Sync>>;
 }
 
 #[derive(Default)]
 pub struct MockStorage {
-    pub files: std::sync::Mutex<std::collections::HashMap<String, Bytes>>,
+    pub files: Arc<std::sync::Mutex<std::collections::HashMap<String, Bytes>>>,
+}
+
+/// In-memory [`object_store::MultipartUpload`] so `MockStorage` supports the
+/// streaming path: parts accumulate in a buffer, `complete` publishes to the map.
+#[derive(Debug)]
+struct MockMultipartUpload {
+    files: Arc<std::sync::Mutex<std::collections::HashMap<String, Bytes>>>,
+    key: String,
+    buf: Vec<u8>,
+}
+
+#[async_trait]
+impl object_store::MultipartUpload for MockMultipartUpload {
+    fn put_part(&mut self, data: object_store::PutPayload) -> object_store::UploadPart {
+        for chunk in data.iter() {
+            self.buf.extend_from_slice(chunk);
+        }
+        Box::pin(futures_util::future::ready(Ok(())))
+    }
+
+    async fn complete(&mut self) -> object_store::Result<object_store::PutResult> {
+        let data = Bytes::from(std::mem::take(&mut self.buf));
+        self.files.lock().unwrap().insert(self.key.clone(), data);
+        Ok(object_store::PutResult {
+            e_tag: None,
+            version: None,
+            extensions: Default::default(),
+        })
+    }
+
+    async fn abort(&mut self) -> object_store::Result<()> {
+        self.buf.clear();
+        Ok(())
+    }
 }
 
 #[async_trait]
@@ -109,6 +149,17 @@ impl StorageProvider for MockStorage {
     fn url(&self, _key: &str, file_id: &str) -> String {
         format!("/mock/{}", file_id)
     }
+
+    async fn start_multipart(
+        &self,
+        key: &str,
+    ) -> Result<Box<dyn object_store::MultipartUpload>, Box<dyn std::error::Error + Send + Sync>> {
+        Ok(Box::new(MockMultipartUpload {
+            files: self.files.clone(),
+            key: key.to_string(),
+            buf: Vec::new(),
+        }))
+    }
 }
 
 #[cfg(test)]
diff --git a/apps/backend/src/storage/s3.rs b/apps/backend/src/storage/s3.rs
index cb066a12..cff1db56 100644
--- a/apps/backend/src/storage/s3.rs
+++ b/apps/backend/src/storage/s3.rs
@@ -95,4 +95,12 @@ impl StorageProvider for S3Storage {
     fn url(&self, key: &str, file_id: &str) -> String {
         self.url(key, file_id)
     }
+
+    async fn start_multipart(
+        &self,
+        key: &str,
+    ) -> Result<Box<dyn object_store::MultipartUpload>, Box<dyn std::error::Error + Send + Sync>> {
+        let path = ObjectPath::from(key);
+        Ok(self.store.put_multipart(&path).await?)
+    }
 }

From 53fa44e3b5dde129d51e8cf7991a5a9fa1ea4551 Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Thu, 2 Jul 2026 19:40:39 +0530
Subject: [PATCH 23/44] feat(repo): add set_thumbnail_meta, unique-violation
 guard, and last_used_at

- FileRepository: add set_thumbnail_meta() for attaching thumbnail
  dimensions and key after background generation
- FileRepository::create: InMemoryFileRepository now returns
  UniqueViolation on duplicate id (matches real DB PK constraint)
- AccessTokenLookupRow: add last_used_at field to find_by_prefix
  queries across sqlite, mysql, and postgres (needed by auth debounce)
---
 .../src/repository/mysql/access_token.rs      |  2 +-
 apps/backend/src/repository/mysql/file.rs     | 17 ++++++++++++++
 .../src/repository/postgres/access_token.rs   |  2 +-
 apps/backend/src/repository/postgres/file.rs  | 17 ++++++++++++++
 .../src/repository/sqlite/access_token.rs     |  2 +-
 apps/backend/src/repository/sqlite/file.rs    | 17 ++++++++++++++
 apps/backend/src/repository/traits.rs         | 23 +++++++++++++------
 apps/backend/src/test_helpers.rs              | 20 ++++++++++++++++
 8 files changed, 90 insertions(+), 10 deletions(-)

diff --git a/apps/backend/src/repository/mysql/access_token.rs b/apps/backend/src/repository/mysql/access_token.rs
index 6c2dc25f..5df706f0 100644
--- a/apps/backend/src/repository/mysql/access_token.rs
+++ b/apps/backend/src/repository/mysql/access_token.rs
@@ -71,7 +71,7 @@ impl AccessTokenRepository for MysqlAccessTokenRepository {
 
     async fn find_by_prefix(&self, prefix: &str) -> Result<Vec<AccessTokenLookupRow>, RepositoryError> {
         let rows = sqlx::query_as::<_, AccessTokenLookupRow>(
-            "SELECT id, site_id, token_hash, token_hmac, CAST(expires_at AS CHAR) AS expires_at, CAST(revoked_at AS CHAR) AS revoked_at, permission
+            "SELECT id, site_id, token_hash, token_hmac, CAST(expires_at AS CHAR) AS expires_at, CAST(revoked_at AS CHAR) AS revoked_at, permission, CAST(last_used_at AS CHAR) AS last_used_at
              FROM access_tokens WHERE token_prefix = ?",
         )
         .bind(prefix)
diff --git a/apps/backend/src/repository/mysql/file.rs b/apps/backend/src/repository/mysql/file.rs
index 4d1807dd..47caa3f5 100644
--- a/apps/backend/src/repository/mysql/file.rs
+++ b/apps/backend/src/repository/mysql/file.rs
@@ -329,4 +329,21 @@ impl FileRepository for MysqlFileRepository {
 
         Ok(provider.unwrap_or_else(|| "filesystem".into()))
     }
+
+    async fn set_thumbnail_meta(
+        &self,
+        id: &str,
+        thumbnail_key: &str,
+        width: Option<i32>,
+        height: Option<i32>,
+    ) -> Result<(), RepositoryError> {
+        sqlx::query("UPDATE files SET thumbnail_key = ?, width = ?, height = ? WHERE id = ?")
+            .bind(thumbnail_key)
+            .bind(width)
+            .bind(height)
+            .bind(id)
+            .execute(&self.pool)
+            .await?;
+        Ok(())
+    }
 }
diff --git a/apps/backend/src/repository/postgres/access_token.rs b/apps/backend/src/repository/postgres/access_token.rs
index 025dda33..72409a6a 100644
--- a/apps/backend/src/repository/postgres/access_token.rs
+++ b/apps/backend/src/repository/postgres/access_token.rs
@@ -71,7 +71,7 @@ impl AccessTokenRepository for PostgresAccessTokenRepository {
 
     async fn find_by_prefix(&self, prefix: &str) -> Result<Vec<AccessTokenLookupRow>, RepositoryError> {
         let rows = sqlx::query_as::<_, AccessTokenLookupRow>(
-            "SELECT id, site_id, token_hash, token_hmac, expires_at::text, revoked_at::text, permission
+            "SELECT id, site_id, token_hash, token_hmac, expires_at::text, revoked_at::text, permission, last_used_at::text
              FROM access_tokens WHERE token_prefix = $1",
         )
         .bind(prefix)
diff --git a/apps/backend/src/repository/postgres/file.rs b/apps/backend/src/repository/postgres/file.rs
index 3061b8b0..ecef75f5 100644
--- a/apps/backend/src/repository/postgres/file.rs
+++ b/apps/backend/src/repository/postgres/file.rs
@@ -344,4 +344,21 @@ impl FileRepository for PostgresFileRepository {
 
         Ok(provider.unwrap_or_else(|| "filesystem".into()))
     }
+
+    async fn set_thumbnail_meta(
+        &self,
+        id: &str,
+        thumbnail_key: &str,
+        width: Option<i32>,
+        height: Option<i32>,
+    ) -> Result<(), RepositoryError> {
+        sqlx::query("UPDATE files SET thumbnail_key = $1, width = $2, height = $3 WHERE id = $4")
+            .bind(thumbnail_key)
+            .bind(width)
+            .bind(height)
+            .bind(id)
+            .execute(&self.pool)
+            .await?;
+        Ok(())
+    }
 }
diff --git a/apps/backend/src/repository/sqlite/access_token.rs b/apps/backend/src/repository/sqlite/access_token.rs
index c169b5f5..5164c0e8 100644
--- a/apps/backend/src/repository/sqlite/access_token.rs
+++ b/apps/backend/src/repository/sqlite/access_token.rs
@@ -71,7 +71,7 @@ impl AccessTokenRepository for SqliteAccessTokenRepository {
 
     async fn find_by_prefix(&self, prefix: &str) -> Result<Vec<AccessTokenLookupRow>, RepositoryError> {
         let rows = sqlx::query_as::<_, AccessTokenLookupRow>(
-            "SELECT id, site_id, token_hash, token_hmac, expires_at, revoked_at, permission
+            "SELECT id, site_id, token_hash, token_hmac, expires_at, revoked_at, permission, last_used_at
              FROM access_tokens WHERE token_prefix = ?",
         )
         .bind(prefix)
diff --git a/apps/backend/src/repository/sqlite/file.rs b/apps/backend/src/repository/sqlite/file.rs
index c8a84704..542974ef 100644
--- a/apps/backend/src/repository/sqlite/file.rs
+++ b/apps/backend/src/repository/sqlite/file.rs
@@ -339,4 +339,21 @@ impl FileRepository for SqliteFileRepository {
 
         Ok(provider.unwrap_or_else(|| "filesystem".into()))
     }
+
+    async fn set_thumbnail_meta(
+        &self,
+        id: &str,
+        thumbnail_key: &str,
+        width: Option<i32>,
+        height: Option<i32>,
+    ) -> Result<(), RepositoryError> {
+        sqlx::query("UPDATE files SET thumbnail_key = ?, width = ?, height = ? WHERE id = ?")
+            .bind(thumbnail_key)
+            .bind(width)
+            .bind(height)
+            .bind(id)
+            .execute(&self.pool)
+            .await?;
+        Ok(())
+    }
 }
diff --git a/apps/backend/src/repository/traits.rs b/apps/backend/src/repository/traits.rs
index f0aa425f..7d9a6676 100644
--- a/apps/backend/src/repository/traits.rs
+++ b/apps/backend/src/repository/traits.rs
@@ -268,16 +268,25 @@ pub trait FileRepository: Send + Sync {
         site_id: &str,
     ) -> Result<Vec<FileReference>, RepositoryError>;
     async fn get_storage_provider(&self, site_id: &str) -> Result<String, RepositoryError>;
+    /// Attach thumbnail metadata generated after the upload response (background task).
+    async fn set_thumbnail_meta(
+        &self,
+        id: &str,
+        thumbnail_key: &str,
+        width: Option<i32>,
+        height: Option<i32>,
+    ) -> Result<(), RepositoryError>;
 }
 
 pub type AccessTokenLookupRow = (
-    String,
-    String,
-    String,
-    Option<String>,
-    Option<String>,
-    Option<String>,
-    String,
+    String,         // id
+    String,         // site_id
+    String,         // token_hash
+    Option<String>, // token_hmac
+    Option<String>, // expires_at
+    Option<String>, // revoked_at
+    String,         // permission
+    Option<String>, // last_used_at (for the touch debounce)
 );
 
 /// A new access token to persist (see [`AccessTokenRepository::create`]).
diff --git a/apps/backend/src/test_helpers.rs b/apps/backend/src/test_helpers.rs
index 983c3294..810b9b30 100644
--- a/apps/backend/src/test_helpers.rs
+++ b/apps/backend/src/test_helpers.rs
@@ -993,6 +993,9 @@ impl FileRepository for InMemoryFileRepository {
             created_by,
         } = file;
         let mut files = self.files.lock().unwrap();
+        if files.iter().any(|f| f.id == id) {
+            return Err(RepositoryError::UniqueViolation("files.id".into()));
+        }
         let file = File {
             id: id.to_string(),
             site_id: site_id.to_string(),
@@ -1100,6 +1103,22 @@ impl FileRepository for InMemoryFileRepository {
             .map(|f| f.storage_provider.clone())
             .unwrap_or_else(|| "filesystem".to_string()))
     }
+
+    async fn set_thumbnail_meta(
+        &self,
+        id: &str,
+        thumbnail_key: &str,
+        width: Option<i32>,
+        height: Option<i32>,
+    ) -> Result<(), RepositoryError> {
+        let mut files = self.files.lock().unwrap();
+        if let Some(file) = files.iter_mut().find(|f| f.id == id) {
+            file.thumbnail_key = Some(thumbnail_key.to_string());
+            file.width = width;
+            file.height = height;
+        }
+        Ok(())
+    }
 }
 
 #[derive(Clone)]
@@ -1183,6 +1202,7 @@ impl AccessTokenRepository for InMemoryAccessTokenRepository {
                     t.expires_at.clone(),
                     t.revoked_at.clone(),
                     t.permission.clone(),
+                    t.last_used_at.clone(),
                 )
             })
             .collect())

From 6f6e77749578659367f35ee7cf490f823ff1dff3 Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Thu, 2 Jul 2026 19:40:48 +0530
Subject: [PATCH 24/44] feat(upload): rewrite file service for constant-memory
 streaming

Replace the buffered upload path with upload_file_streaming() that
streams via object_store multipart in 5 MiB chunks with 2 parts
concurrency. Key improvements:

- Constant memory regardless of file size (no full-body buffer)
- Magic-byte sniffing on first SNIFF_LEN bytes while streaming
- Size cap enforced incrementally (abort on overflow)
- Pre-generated file ids are single-use via in-flight DashMap claim
- Thumbnails generated in a background task after DB record exists
- Orphan blob cleanup on DB insert failure
- New error variants: AlreadyExists (409), ReadError (400)
---
 apps/backend/src/services/error.rs |   2 +
 apps/backend/src/services/file.rs  | 470 +++++++++++++++++++++++------
 2 files changed, 375 insertions(+), 97 deletions(-)

diff --git a/apps/backend/src/services/error.rs b/apps/backend/src/services/error.rs
index 7c1c2064..fc7bddbb 100644
--- a/apps/backend/src/services/error.rs
+++ b/apps/backend/src/services/error.rs
@@ -106,6 +106,8 @@ impl ServiceError {
                 FileError::StorageError(_) => StatusCode::INTERNAL_SERVER_ERROR,
                 FileError::NoStorageConfigured => StatusCode::INTERNAL_SERVER_ERROR,
                 FileError::DatabaseError(_) => StatusCode::INTERNAL_SERVER_ERROR,
+                FileError::AlreadyExists => StatusCode::CONFLICT,
+                FileError::ReadError(_) => StatusCode::BAD_REQUEST,
             },
             ServiceError::Singleton(e) => match e {
                 SingletonError::NotFound | SingletonError::NotASingleton => StatusCode::NOT_FOUND,
diff --git a/apps/backend/src/services/file.rs b/apps/backend/src/services/file.rs
index eca303fd..e3ed38ac 100644
--- a/apps/backend/src/services/file.rs
+++ b/apps/backend/src/services/file.rs
@@ -2,7 +2,10 @@ use std::sync::Arc;
 
 use axum::{Json, http::StatusCode, response::IntoResponse};
 use bytes::Bytes;
+use dashmap::DashMap;
+use futures_util::{Stream, StreamExt};
 use image::{DynamicImage, ImageEncoder, ImageReader};
+use object_store::WriteMultipart;
 use serde_json::json;
 use thiserror::Error;
 use tracing::{debug, error, info, warn};
@@ -10,13 +13,25 @@ use uuid::Uuid;
 
 use crate::config::Config;
 use crate::models::file::{File, FileReference, FileWithUrl};
+use crate::repository::error::RepositoryError;
 use crate::repository::traits::{FileListResult, FileRepository, ListFilesParams, NewFile};
 use crate::storage::StorageProvider;
+use crate::utils::magic_bytes::{self, SNIFF_LEN, Sniff};
+
+/// Multipart part size for streaming uploads. S3 requires >= 5 MiB for every
+/// part but the last; with ~2 parts in flight, worst case is ~15 MiB of memory
+/// per upload regardless of file size.
+const MULTIPART_CHUNK_SIZE: usize = 5 * 1024 * 1024;
+/// Max multipart parts concurrently in flight per upload.
+const MULTIPART_MAX_CONCURRENCY: usize = 2;
 
 #[derive(Clone)]
 pub struct FileService {
     file_repo: Arc<dyn FileRepository>,
     config: Arc<Config>,
+    /// Pre-generated file ids currently being uploaded (signed-URL flow); makes
+    /// one-time-use race-free in-process. The `files` PK is the durable backstop.
+    in_flight: Arc<DashMap<String, ()>>,
 }
 
 /// Inputs for [`FileService::upload_file`].
@@ -30,6 +45,46 @@ pub struct UploadFileRequest<'a> {
     pub storage_provider: &'a str,
 }
 
+/// Inputs for [`FileService::upload_file_streaming`]. `file_id` is set by the
+/// signed-URL flow (the token pre-generates it, enforcing one-time use).
+pub struct StreamingUploadRequest<'a> {
+    pub site_id: &'a str,
+    pub file_id: Option<&'a str>,
+    pub filename: &'a str,
+    pub content_type: &'a str,
+    pub created_by: Option<&'a str>,
+    pub storage: Arc<dyn StorageProvider>,
+    pub storage_provider: &'a str,
+}
+
+/// RAII claim on an in-flight pre-generated file id; released on drop.
+struct InFlightClaim {
+    map: Arc<DashMap<String, ()>>,
+    key: String,
+}
+
+impl InFlightClaim {
+    fn acquire(map: &Arc<DashMap<String, ()>>, key: &str) -> Option<Self> {
+        use dashmap::mapref::entry::Entry;
+        match map.entry(key.to_string()) {
+            Entry::Occupied(_) => None,
+            Entry::Vacant(v) => {
+                v.insert(());
+                Some(Self {
+                    map: map.clone(),
+                    key: key.to_string(),
+                })
+            }
+        }
+    }
+}
+
+impl Drop for InFlightClaim {
+    fn drop(&mut self) {
+        self.map.remove(&self.key);
+    }
+}
+
 #[derive(Error, Debug)]
 pub enum FileError {
     #[error("Not found")]
@@ -55,6 +110,12 @@ pub enum FileError {
 
     #[error("Database error: {0}")]
     DatabaseError(String),
+
+    #[error("File already exists")]
+    AlreadyExists,
+
+    #[error("Failed to read upload body: {0}")]
+    ReadError(String),
 }
 
 impl FileError {
@@ -77,6 +138,14 @@ impl FileError {
             ),
             FileError::DatabaseError(msg) => (StatusCode::INTERNAL_SERVER_ERROR, Json(json!({"error": msg}))),
             FileError::InvalidContentType(msg) => (StatusCode::BAD_REQUEST, Json(json!({"error": msg}))),
+            FileError::AlreadyExists => (
+                StatusCode::CONFLICT,
+                Json(json!({"error": "File already exists (upload URL already used)"})),
+            ),
+            FileError::ReadError(msg) => (
+                StatusCode::BAD_REQUEST,
+                Json(json!({"error": format!("Failed to read upload body: {}", msg)})),
+            ),
         };
         (status, body).into_response()
     }
@@ -84,7 +153,11 @@ impl FileError {
 
 impl FileService {
     pub fn new(file_repo: Arc<dyn FileRepository>, config: Arc<Config>) -> Self {
-        Self { file_repo, config }
+        Self {
+            file_repo,
+            config,
+            in_flight: Arc::new(DashMap::new()),
+        }
     }
 
     pub async fn list_files(&self, params: ListFilesParams<'_>) -> Result<FileListResult, FileError> {
@@ -108,6 +181,8 @@ impl FileService {
             .map_err(|e| FileError::DatabaseError(e.to_string()))
     }
 
+    /// Buffered upload — thin wrapper over [`Self::upload_file_streaming`] for
+    /// callers that already hold the whole payload (gRPC, tests).
     pub async fn upload_file(&self, req: UploadFileRequest<'_>) -> Result<FileWithUrl, FileError> {
         let UploadFileRequest {
             site_id,
@@ -118,25 +193,50 @@ impl FileService {
             storage,
             storage_provider,
         } = req;
-        info!(
-            "Uploading file: site_id={}, content_type={}, size={} bytes",
+
+        let stream = futures_util::stream::iter(std::iter::once(Ok(data)));
+        self.upload_file_streaming(
+            StreamingUploadRequest {
+                site_id,
+                file_id: None,
+                filename,
+                content_type,
+                created_by,
+                storage,
+                storage_provider,
+            },
+            stream,
+        )
+        .await
+    }
+
+    /// Streaming upload: constant memory regardless of file size. Enforces the
+    /// content-type whitelist, magic-byte sniffing on the first bytes, and the
+    /// size cap while streaming; aborts the multipart upload on any failure so
+    /// no partial object is left behind. Thumbnails are generated in a
+    /// background task after the DB record exists.
+    pub async fn upload_file_streaming<S>(
+        &self,
+        req: StreamingUploadRequest<'_>,
+        mut stream: S,
+    ) -> Result<FileWithUrl, FileError>
+    where
+        S: Stream<Item = Result<Bytes, Box<dyn std::error::Error + Send + Sync>>> + Unpin + Send,
+    {
+        let StreamingUploadRequest {
             site_id,
+            file_id,
+            filename,
             content_type,
-            data.len()
-        );
+            created_by,
+            storage,
+            storage_provider,
+        } = req;
 
-        if data.len() as u64 > self.config.max_upload_size_bytes as u64 {
-            warn!(
-                "File too large: site_id={}, size={} bytes, max={} bytes",
-                site_id,
-                data.len(),
-                self.config.max_upload_size_bytes
-            );
-            return Err(FileError::FileTooLarge(format!(
-                "File too large. Maximum size is {}MB",
-                self.config.max_upload_size_bytes / (1024 * 1024)
-            )));
-        }
+        info!(
+            "Uploading file (streaming): site_id={}, content_type={}",
+            site_id, content_type
+        );
 
         if !crate::utils::content_types::is_allowed(content_type) {
             return Err(FileError::InvalidContentType(format!(
@@ -145,9 +245,29 @@ impl FileService {
             )));
         }
 
+        // One-time-use for pre-generated ids (signed URLs): claim the id
+        // in-process, then verify no record exists. The PK insert below is the
+        // durable backstop.
+        let _claim = match file_id {
+            Some(id) => {
+                let claim = InFlightClaim::acquire(&self.in_flight, id).ok_or(FileError::AlreadyExists)?;
+                let existing = self
+                    .file_repo
+                    .get_by_id_any(id)
+                    .await
+                    .map_err(|e| FileError::DatabaseError(e.to_string()))?;
+                if existing.is_some() {
+                    return Err(FileError::AlreadyExists);
+                }
+                Some(claim)
+            }
+            None => None,
+        };
+
+        let file_id = file_id
+            .map(str::to_string)
+            .unwrap_or_else(|| Uuid::now_v7().to_string());
         let original_name = filename.to_string();
-        let file_size = data.len() as i64;
-        let file_id = Uuid::now_v7().to_string();
         let ext = std::path::Path::new(filename)
             .extension()
             .and_then(|e| e.to_str())
@@ -157,87 +277,84 @@ impl FileService {
         } else {
             format!("{}.{}", &file_id[..8], ext)
         };
-
         let storage_key = format!("s_{}/f_{}/{}", site_id, file_id, generated_filename);
         let mime_type = content_type.to_string();
+        let max = self.config.max_upload_size_bytes;
+
+        let upload = storage.start_multipart(&storage_key).await.map_err(|e| {
+            error!("Failed to start multipart upload: key={}, error={}", storage_key, e);
+            FileError::StorageError(e.to_string())
+        })?;
+        let mut writer = WriteMultipart::new_with_chunk_size(upload, MULTIPART_CHUNK_SIZE);
+
+        let too_large =
+            || FileError::FileTooLarge(format!("File too large. Maximum size is {}MB", max / (1024 * 1024)));
+
+        // Hold back the first SNIFF_LEN bytes so nothing is written before the
+        // magic-byte check passes; afterwards chunks stream straight through.
+        let mut sniff_buf: Vec<u8> = Vec::new();
+        let mut sniffed = false;
+        let mut total: usize = 0;
+
+        loop {
+            let chunk = match stream.next().await {
+                Some(Ok(chunk)) => chunk,
+                Some(Err(e)) => {
+                    let _ = writer.abort().await;
+                    return Err(FileError::ReadError(e.to_string()));
+                }
+                None => break,
+            };
+
+            total += chunk.len();
+            if total > max {
+                let _ = writer.abort().await;
+                warn!("File too large: site_id={}, size>{} bytes, max={}", site_id, total, max);
+                return Err(too_large());
+            }
 
-        debug!(
-            "File metadata: id={}, storage_key={}, mime_type={}, size={}",
-            file_id, storage_key, mime_type, file_size
-        );
-
-        let mut width: Option<i32> = None;
-        let mut height: Option<i32> = None;
-        let mut thumbnail_data: Option<(Vec<u8>, String)> = None;
-        let mut thumbnail_key: Option<String> = None;
-
-        if mime_type.starts_with("image/") {
-            debug!("Processing image for thumbnail: mime_type={}", mime_type);
-            let data_clone = data.clone();
-            let file_id_owned = file_id.clone();
-            let site_id_owned = site_id.to_string();
-
-            let result = tokio::task::spawn_blocking(move || {
-                let mut w: Option<i32> = None;
-                let mut h: Option<i32> = None;
-                let mut tdata: Option<(Vec<u8>, String)> = None;
-                let mut tkey: Option<String> = None;
-
-                if let Ok(reader) = ImageReader::new(std::io::Cursor::new(&data_clone)).with_guessed_format()
-                    && let Ok(img) = reader.decode()
-                {
-                    w = Some(img.width() as i32);
-                    h = Some(img.height() as i32);
-
-                    if let Some((thumb_bytes, thumb_mime)) = generate_thumbnail(&img) {
-                        tkey = Some(format!(
-                            "s_{}/f_{}/thumb_{}.avif",
-                            site_id_owned,
-                            file_id_owned,
-                            &file_id_owned[..8]
-                        ));
-                        tdata = Some((thumb_bytes, thumb_mime));
+            if !sniffed {
+                sniff_buf.extend_from_slice(&chunk);
+                if sniff_buf.len() >= SNIFF_LEN {
+                    if let Sniff::Mismatch(detected) = magic_bytes::check(&mime_type, &sniff_buf) {
+                        let _ = writer.abort().await;
+                        return Err(content_mismatch(&mime_type, detected));
                     }
+                    sniffed = true;
+                    if let Err(e) = writer.wait_for_capacity(MULTIPART_MAX_CONCURRENCY).await {
+                        let _ = writer.abort().await;
+                        return Err(FileError::StorageError(e.to_string()));
+                    }
+                    writer.write(&sniff_buf);
+                    sniff_buf = Vec::new();
                 }
-
-                (w, h, tdata, tkey)
-            })
-            .await;
-
-            if let Ok((w, h, tdata, tkey)) = result {
-                width = w;
-                height = h;
-                thumbnail_data = tdata;
-                thumbnail_key = tkey;
-                debug!(
-                    "Generated thumbnail: width={:?}, height={:?}, key={:?}",
-                    width, height, thumbnail_key
-                );
             } else {
-                warn!("Failed to generate thumbnail for image: {}", mime_type);
+                if let Err(e) = writer.wait_for_capacity(MULTIPART_MAX_CONCURRENCY).await {
+                    let _ = writer.abort().await;
+                    return Err(FileError::StorageError(e.to_string()));
+                }
+                writer.write(&chunk);
             }
         }
 
-        debug!("Storing file to storage: key={}", storage_key);
-        match storage.put(&storage_key, data.clone(), &mime_type).await {
-            Ok(_) => debug!("File stored successfully: key={}", storage_key),
-            Err(e) => {
-                error!("Failed to store file: key={}, error={}", storage_key, e);
-                return Err(FileError::StorageError(e.to_string()));
+        // EOF before the sniff buffer filled: check whatever we have.
+        if !sniffed {
+            if let Sniff::Mismatch(detected) = magic_bytes::check(&mime_type, &sniff_buf) {
+                let _ = writer.abort().await;
+                return Err(content_mismatch(&mime_type, detected));
+            }
+            if !sniff_buf.is_empty() {
+                writer.write(&sniff_buf);
             }
         }
 
-        if let (Some((thumb_data, thumb_mime)), Some(thumb_key)) = (&thumbnail_data, &thumbnail_key) {
-            debug!("Storing thumbnail: key={}", thumb_key);
-            let _ = storage
-                .put(thumb_key, Bytes::from(thumb_data.clone()), thumb_mime)
-                .await;
+        if let Err(e) = writer.finish().await {
+            error!("Failed to finish multipart upload: key={}, error={}", storage_key, e);
+            return Err(FileError::StorageError(e.to_string()));
         }
+        debug!("File stored successfully: key={}, size={} bytes", storage_key, total);
 
-        let thumb_key_str = thumbnail_key.as_deref();
-
-        debug!("Creating file record in repository: id={}", file_id);
-        let file = self
+        let file = match self
             .file_repo
             .create(NewFile {
                 id: &file_id,
@@ -245,31 +362,95 @@ impl FileService {
                 filename: &generated_filename,
                 original_name: &original_name,
                 mime_type: &mime_type,
-                size: file_size,
+                size: total as i64,
                 storage_provider,
                 storage_key: &storage_key,
-                thumbnail_key: thumb_key_str,
-                width,
-                height,
+                thumbnail_key: None,
+                width: None,
+                height: None,
                 created_by,
             })
             .await
-            .map_err(|e| {
-                error!(
-                    "Failed to create file record in repository: id={}, error={}",
-                    file_id, e
-                );
-                FileError::DatabaseError(e.to_string())
-            })?;
+        {
+            Ok(file) => file,
+            Err(RepositoryError::UniqueViolation(_)) => {
+                // A concurrent upload with the same pre-generated id won the
+                // insert. Do NOT delete the blob — the winner shares the key.
+                warn!("Duplicate file id on insert (upload URL reused): id={}", file_id);
+                return Err(FileError::AlreadyExists);
+            }
+            Err(e) => {
+                error!("Failed to create file record: id={}, error={}", file_id, e);
+                // Orphan cleanup: the blob was written but has no DB record.
+                if let Err(del_err) = storage.delete(&storage_key).await {
+                    warn!(
+                        "Failed to clean up orphaned blob: key={}, error={}",
+                        storage_key, del_err
+                    );
+                }
+                return Err(FileError::DatabaseError(e.to_string()));
+            }
+        };
 
         info!(
             "File uploaded successfully: id={}, site_id={}, size={} bytes",
             file.id, site_id, file.size
         );
 
+        if mime_type.starts_with("image/") {
+            self.spawn_thumbnail_task(file.clone(), storage.clone());
+        }
+
         Ok(self.file_to_with_url(&file, &*storage))
     }
 
+    /// Generate thumbnail + dimensions off the upload critical path: read the
+    /// image back from storage, encode in a blocking task, update the record.
+    /// Failures are logged and leave the thumbnail fields NULL.
+    fn spawn_thumbnail_task(&self, file: File, storage: Arc<dyn StorageProvider>) {
+        let repo = self.file_repo.clone();
+        tokio::spawn(async move {
+            let data = match storage.get(&file.storage_key).await {
+                Ok(data) => data,
+                Err(e) => {
+                    warn!("Thumbnail task: failed to read {}: {}", file.storage_key, e);
+                    return;
+                }
+            };
+
+            let result = tokio::task::spawn_blocking(move || {
+                let reader = ImageReader::new(std::io::Cursor::new(&data))
+                    .with_guessed_format()
+                    .ok()?;
+                let img = reader.decode().ok()?;
+                let (w, h) = (img.width() as i32, img.height() as i32);
+                let thumb = generate_thumbnail(&img)?;
+                Some((w, h, thumb))
+            })
+            .await;
+
+            match result {
+                Ok(Some((width, height, (thumb_bytes, thumb_mime)))) => {
+                    let thumb_key = format!("s_{}/f_{}/thumb_{}.avif", file.site_id, file.id, &file.id[..8]);
+                    if let Err(e) = storage.put(&thumb_key, Bytes::from(thumb_bytes), &thumb_mime).await {
+                        warn!("Thumbnail task: failed to store {}: {}", thumb_key, e);
+                        return;
+                    }
+                    if let Err(e) = repo
+                        .set_thumbnail_meta(&file.id, &thumb_key, Some(width), Some(height))
+                        .await
+                    {
+                        warn!("Thumbnail task: failed to update record {}: {}", file.id, e);
+                    } else {
+                        debug!("Thumbnail generated: id={}, key={}", file.id, thumb_key);
+                    }
+                }
+                Ok(None) => debug!("Thumbnail task: {} not decodable as image", file.id),
+                Err(e) => warn!("Thumbnail task panicked for {}: {}", file.id, e),
+            }
+        });
+    }
+
     pub async fn soft_delete(&self, id: &str, site_id: &str) -> Result<u64, FileError> {
         info!("Soft deleting file");
 
@@ -498,6 +679,17 @@ impl FileService {
     }
 }
 
+/// 400 error for a declared/detected content-type contradiction.
+fn content_mismatch(declared: &str, detected: Option<&'static str>) -> FileError {
+    FileError::InvalidContentType(match detected {
+        Some(d) => format!(
+            "File content does not match declared type '{}' (detected '{}')",
+            declared, d
+        ),
+        None => format!("File content does not match declared type '{}'", declared),
+    })
+}
+
 fn generate_thumbnail(img: &DynamicImage) -> Option<(Vec<u8>, String)> {
     let thumb = img.resize(260, 260, image::imageops::FilterType::Lanczos3);
     let rgba = thumb.to_rgba8();
@@ -620,6 +812,90 @@ mod tests {
         assert!(matches!(result, Err(FileError::FileTooLarge(_))));
     }
 
+    #[tokio::test]
+    async fn test_upload_file_streams_to_storage_and_creates_record() {
+        let file_repo = test_file_repo();
+        let config = test_config();
+        let service = FileService::new(file_repo.clone(), config);
+
+        let storage = Arc::new(MockStorage::default());
+        let result = service
+            .upload_file(UploadFileRequest {
+                site_id: "site-123",
+                data: Bytes::from("hello world"),
+                filename: "notes.txt",
+                content_type: "text/plain",
+                created_by: None,
+                storage: storage.clone(),
+                storage_provider: "filesystem",
+            })
+            .await
+            .expect("upload should succeed");
+
+        assert_eq!(result.size, 11);
+        assert!(result.thumbnail_url.is_none());
+        let stored = storage.files.lock().unwrap();
+        assert_eq!(stored.get(&result.storage_key).unwrap().as_ref(), b"hello world");
+    }
+
+    #[tokio::test]
+    async fn test_upload_streaming_magic_byte_mismatch_rejected() {
+        let file_repo = test_file_repo();
+        let config = test_config();
+        let service = FileService::new(file_repo, config);
+
+        let storage = Arc::new(MockStorage::default());
+        let result = service
+            .upload_file(UploadFileRequest {
+                site_id: "site-123",
+                data: Bytes::from("definitely not a png"),
+                filename: "fake.png",
+                content_type: "image/png",
+                created_by: None,
+                storage: storage.clone(),
+                storage_provider: "filesystem",
+            })
+            .await;
+
+        assert!(matches!(result, Err(FileError::InvalidContentType(_))));
+        // Aborted upload must leave nothing behind.
+        assert!(storage.files.lock().unwrap().is_empty());
+    }
+
+    #[tokio::test]
+    async fn test_upload_streaming_pregenerated_id_single_use() {
+        let file_repo = test_file_repo();
+        let config = test_config();
+        let service = FileService::new(file_repo, config);
+        let storage = Arc::new(MockStorage::default());
+
+        let req = |storage: Arc<MockStorage>| StreamingUploadRequest {
+            site_id: "site-123",
+            file_id: Some("0197-fixed-id"),
+            filename: "a.txt",
+            content_type: "text/plain",
+            created_by: None,
+            storage,
+            storage_provider: "filesystem",
+        };
+
+        let first = service
+            .upload_file_streaming(
+                req(storage.clone()),
+                futures_util::stream::iter(std::iter::once(Ok(Bytes::from("one")))),
+            )
+            .await;
+        assert!(first.is_ok());
+
+        let second = service
+            .upload_file_streaming(
+                req(storage.clone()),
+                futures_util::stream::iter(std::iter::once(Ok(Bytes::from("two")))),
+            )
+            .await;
+        assert!(matches!(second, Err(FileError::AlreadyExists)));
+    }
+
     #[tokio::test]
     async fn test_soft_delete_success() {
         let file_repo = test_file_repo();

From 31a92ea87aa86f069de1e423da7b8fe56c8672ef Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Thu, 2 Jul 2026 19:40:56 +0530
Subject: [PATCH 25/44] feat(upload): add signed URL PUT endpoint with
 configurable expiry

New public endpoint PUT /api/v1/files/upload/{token} accepts raw file
bytes using the HMAC-signed token as credential (no session/API key).
The token is verified, single-use enforced, content-type validated
against the token, and size-checked via Content-Length before streaming.

Config changes:
- New upload_token_expiry_secs field (default 900s / 15min)
- SignedUploadToken::generate() refactored to delegate to
  generate_with_storage_provider() which now accepts expiry_secs

The multipart upload_file handler is also rewritten to stream the
multipart field body directly into storage via upload_file_streaming.
---
 apps/backend/src/config.rs                |  12 +-
 apps/backend/src/handlers/file_handler.rs | 185 +++++++++++++++-------
 apps/backend/src/router/files.rs          |  13 +-
 apps/backend/src/router/mod.rs            |   2 +
 apps/backend/src/router/openapi.rs        |   1 +
 apps/backend/src/signed_upload.rs         |  64 ++++----
 apps/backend/tests/common/server.rs       |   2 +
 7 files changed, 192 insertions(+), 87 deletions(-)

diff --git a/apps/backend/src/config.rs b/apps/backend/src/config.rs
index 3fca3f2a..3049728f 100644
--- a/apps/backend/src/config.rs
+++ b/apps/backend/src/config.rs
@@ -44,6 +44,8 @@ pub struct Config {
 
     // Upload limits
     pub max_upload_size_bytes: usize,
+    /// Lifetime of signed upload URLs (seconds).
+    pub upload_token_expiry_secs: i64,
 
     // Cookie security
     pub cookie_secure: bool,
@@ -129,6 +131,7 @@ struct RawConfig {
     backup_encryption_key: Option<String>,
 
     max_upload_size_mb: Option<usize>,
+    upload_token_expiry_secs: Option<i64>,
 
     #[serde(default, deserialize_with = "de_opt_lenient_bool")]
     cookie_secure: Option<bool>,
@@ -285,7 +288,8 @@ impl Config {
              s3_endpoint = {}\n\
              s3_public_url = {}\n\n\
              # Uploads\n\
-             max_upload_size_mb = {}\n\n\
+             max_upload_size_mb = {}\n\
+             upload_token_expiry_secs = {}\n\n\
              # Security / sessions\n\
              cookie_secure = {}\n\
              session_lifetime_hours = {}\n\
@@ -326,6 +330,7 @@ impl Config {
             opt_str(&self.s3_endpoint),
             opt_str(&self.s3_public_url),
             self.max_upload_size_bytes / (1024 * 1024),
+            self.upload_token_expiry_secs,
             self.cookie_secure,
             self.session_lifetime_hours,
             self.public_registration_enabled,
@@ -390,6 +395,7 @@ impl RawConfig {
             backup_s3_public_url: self.backup_s3_public_url,
             backup_encryption_key: self.backup_encryption_key,
             max_upload_size_bytes: self.max_upload_size_mb.unwrap_or(50) * 1024 * 1024,
+            upload_token_expiry_secs: self.upload_token_expiry_secs.unwrap_or(900),
             cookie_secure: self.cookie_secure.unwrap_or(false),
             session_lifetime_hours: self.session_lifetime_hours.unwrap_or(24),
             public_registration_enabled: self.public_registration_enabled.unwrap_or(false),
@@ -473,7 +479,9 @@ pub fn default_config_toml() -> String {
          # s3_endpoint = \"https://s3.example.com\"\n\
          # s3_public_url = \"https://cdn.example.com\"\n\n\
          # --- Uploads ---\n\
-         max_upload_size_mb = 50\n\n\
+         max_upload_size_mb = 50\n\
+         # Signed upload URL lifetime (seconds)\n\
+         upload_token_expiry_secs = 900\n\n\
          # --- Security / sessions ---\n\
          cookie_secure = false\n\
          session_lifetime_hours = 24\n\
diff --git a/apps/backend/src/handlers/file_handler.rs b/apps/backend/src/handlers/file_handler.rs
index 70cb0a93..83533579 100644
--- a/apps/backend/src/handlers/file_handler.rs
+++ b/apps/backend/src/handlers/file_handler.rs
@@ -6,7 +6,7 @@ use axum::{
     response::{IntoResponse, Response},
 };
 use axum_extra::extract::multipart::Multipart;
-use bytes::Bytes;
+use futures_util::StreamExt;
 use serde::Deserialize;
 use serde_json::json;
 use std::sync::Arc;
@@ -24,7 +24,8 @@ use crate::models::file::{BatchFileIds, FileWithUrl};
 use crate::repository::Repository;
 use crate::repository::traits::ListFilesParams;
 use crate::services::Services;
-use crate::services::file::UploadFileRequest;
+use crate::services::file::StreamingUploadRequest;
+use crate::signed_upload::{SignedUploadError, SignedUploadToken};
 use crate::storage::{StorageProvider, StorageRegistry};
 
 #[derive(Deserialize, utoipa::IntoParams)]
@@ -124,12 +125,11 @@ pub async fn list_files(
     security(("bearer" = []), ("access_token" = [])),
     tag = "files"
 )]
-#[instrument(skip(repository, services, config, ctx, multipart, storage_registry))]
+#[instrument(skip(repository, services, ctx, multipart, storage_registry))]
 pub async fn upload_file(
     ctx: RequestContext,
     Extension(repository): Extension<Repository>,
     Extension(services): Extension<Services>,
-    Extension(config): Extension<Config>,
     Extension(storage_registry): Extension<Arc<StorageRegistry>>,
     mut multipart: Multipart,
 ) -> Response {
@@ -144,76 +144,151 @@ pub async fn upload_file(
         .await
         .unwrap_or_else(|_| "filesystem".into());
 
-    let mut file_data: Option<Bytes> = None;
-    let mut file_name: Option<String> = None;
-    let mut file_content_type: Option<String> = None;
+    let storage = match get_storage_for_site(&storage_provider, &storage_registry) {
+        Ok(s) => s,
+        Err(status) => return (status, Json(json!({"error": "Storage not configured"}))).into_response(),
+    };
+    let created_by = ctx.auth.actor.user_id().map(String::from);
+
+    // Stream the "file" field straight into storage (constant memory); size cap
+    // and content sniffing are enforced by the service while streaming.
+    let mut uploaded: Option<Result<FileWithUrl, crate::services::file::FileError>> = None;
 
-    while let Ok(Some(mut field)) = multipart.next_field().await {
+    while let Ok(Some(field)) = multipart.next_field().await {
         let name = field.name().unwrap_or("").to_string();
 
-        if name == "file" {
-            file_name = field.file_name().map(String::from);
-            file_content_type = field.content_type().map(String::from);
+        if name == "file" && uploaded.is_none() {
+            let file_name = sanitize_filename(field.file_name().unwrap_or("upload"));
+            let content_type = field
+                .content_type()
+                .map(String::from)
+                .unwrap_or_else(|| "application/octet-stream".into());
 
-            // Stream the field in chunks, enforcing the size cap incrementally so an
-            // oversized upload is rejected without first buffering it whole.
-            let max = config.max_upload_size_bytes;
-            let mut buf: Vec<u8> = Vec::new();
-            loop {
+            let stream = Box::pin(futures_util::stream::unfold(field, |mut field| async move {
                 match field.chunk().await {
-                    Ok(Some(chunk)) => {
-                        if buf.len() + chunk.len() > max {
-                            return (
-                                StatusCode::PAYLOAD_TOO_LARGE,
-                                Json(json!({
-                                    "error": format!("File too large. Maximum size is {}MB", max / (1024 * 1024))
-                                })),
-                            )
-                                .into_response();
-                        }
-                        buf.extend_from_slice(&chunk);
-                    }
-                    Ok(None) => break,
-                    Err(e) => {
-                        return (
-                            StatusCode::BAD_REQUEST,
-                            Json(json!({"error": format!("Failed to read file: {}", e)})),
-                        )
-                            .into_response();
-                    }
+                    Ok(Some(chunk)) => Some((Ok(chunk), field)),
+                    Ok(None) => None,
+                    Err(e) => Some((Err(Box::new(e) as Box<dyn std::error::Error + Send + Sync>), field)),
                 }
-            }
-            file_data = Some(Bytes::from(buf));
+            }));
+
+            uploaded = Some(
+                services
+                    .file
+                    .upload_file_streaming(
+                        StreamingUploadRequest {
+                            site_id: &site_id,
+                            file_id: None,
+                            filename: &file_name,
+                            content_type: &content_type,
+                            created_by: created_by.as_deref(),
+                            storage: storage.clone(),
+                            storage_provider: &storage_provider,
+                        },
+                        stream,
+                    )
+                    .await,
+            );
         }
     }
 
-    let file_data = match file_data {
-        Some(d) => d,
-        None => {
-            return (StatusCode::BAD_REQUEST, Json(json!({"error": "No file provided"}))).into_response();
+    match uploaded {
+        Some(Ok(file)) => (StatusCode::CREATED, Json(file)).into_response(),
+        Some(Err(e)) => e.into_response(),
+        None => (StatusCode::BAD_REQUEST, Json(json!({"error": "No file provided"}))).into_response(),
+    }
+}
+
+#[utoipa::path(
+    put,
+    path = "/api/v1/files/upload/{token}",
+    request_body(content = Vec<u8>, description = "Raw file bytes", content_type = "application/octet-stream"),
+    responses(
+        (status = 201, description = "File uploaded", body = FileWithUrl),
+        (status = 400, description = "Bad request (content mismatch or unreadable body)"),
+        (status = 401, description = "Invalid token"),
+        (status = 409, description = "Upload URL already used"),
+        (status = 410, description = "Upload URL expired"),
+        (status = 413, description = "File too large"),
+    ),
+    tag = "files"
+)]
+#[instrument(skip(services, config, storage_registry, headers, body))]
+pub async fn upload_via_signed_url(
+    Path(token): Path<String>,
+    headers: HeaderMap,
+    Extension(services): Extension<Services>,
+    Extension(config): Extension<Config>,
+    Extension(storage_registry): Extension<Arc<StorageRegistry>>,
+    body: Body,
+) -> Response {
+    // The token is the auth: HMAC-signed by the server, time-limited, single-use.
+    let token = match SignedUploadToken::verify(&token, &config.hmac_secret) {
+        Ok(t) => t,
+        Err(SignedUploadError::Expired) => {
+            return (StatusCode::GONE, Json(json!({"error": "Upload URL expired"}))).into_response();
+        }
+        Err(_) => {
+            return (StatusCode::UNAUTHORIZED, Json(json!({"error": "Invalid upload token"}))).into_response();
         }
     };
 
-    let file_name = sanitize_filename(&file_name.unwrap_or_else(|| "upload".into()));
-    let content_type = file_content_type.unwrap_or_else(|| "application/octet-stream".into());
-    let created_by = ctx.auth.actor.user_id();
+    // Fast reject when the client announces an oversized body upfront.
+    if let Some(len) = headers
+        .get(header::CONTENT_LENGTH)
+        .and_then(|v| v.to_str().ok())
+        .and_then(|v| v.parse::<u64>().ok())
+        && len > config.max_upload_size_bytes as u64
+    {
+        return (
+            StatusCode::PAYLOAD_TOO_LARGE,
+            Json(json!({
+                "error": format!("File too large. Maximum size is {}MB", config.max_upload_size_bytes / (1024 * 1024))
+            })),
+        )
+            .into_response();
+    }
 
-    let storage = match get_storage_for_site(&storage_provider, &storage_registry) {
+    // The upload's content type was fixed when the URL was minted; a
+    // contradicting header is a client bug worth failing loudly on.
+    if let Some(ct) = headers.get(header::CONTENT_TYPE).and_then(|v| v.to_str().ok()) {
+        let declared = ct.split(';').next().unwrap_or(ct).trim();
+        if !declared.eq_ignore_ascii_case(&token.content_type) {
+            return (
+                StatusCode::BAD_REQUEST,
+                Json(json!({
+                    "error": format!("Content-Type '{}' does not match the upload URL's '{}'", declared, token.content_type)
+                })),
+            )
+                .into_response();
+        }
+    }
+
+    let storage = match get_storage_for_site(&token.storage_provider, &storage_registry) {
         Ok(s) => s,
         Err(status) => return (status, Json(json!({"error": "Storage not configured"}))).into_response(),
     };
 
+    let file_name = sanitize_filename(&token.filename);
+    let stream = Box::pin(
+        body.into_data_stream()
+            .map(|r| r.map_err(|e| Box::new(e) as Box<dyn std::error::Error + Send + Sync>)),
+    );
+
     match services
         .file
-        .upload_file(UploadFileRequest {
-            site_id: &site_id,
-            data: file_data,
-            filename: &file_name,
-            content_type: &content_type,
-            created_by,
-            storage,
-            storage_provider: &storage_provider,
-        })
+        .upload_file_streaming(
+            StreamingUploadRequest {
+                site_id: &token.site_id,
+                file_id: Some(&token.file_id),
+                filename: &file_name,
+                content_type: &token.content_type,
+                created_by: None,
+                storage,
+                storage_provider: &token.storage_provider,
+            },
+            stream,
+        )
         .await
     {
         Ok(file) => (StatusCode::CREATED, Json(file)).into_response(),
diff --git a/apps/backend/src/router/files.rs b/apps/backend/src/router/files.rs
index 8ad48968..257fac30 100644
--- a/apps/backend/src/router/files.rs
+++ b/apps/backend/src/router/files.rs
@@ -1,13 +1,14 @@
 use axum::extract::DefaultBodyLimit;
 use axum::{
     Router,
-    routing::{delete, get, post},
+    routing::{delete, get, post, put},
 };
 use tower_http::limit::RequestBodyLimitLayer;
 
 use crate::handlers::file_handler::{
     batch_delete_files, batch_permanent_delete_files, batch_restore_files, delete_file_handler, get_file,
     get_file_references, list_files, restore_file, serve_file, serve_file_thumbnail, upload_file,
+    upload_via_signed_url,
 };
 
 /// Public API CRUD routes (mounted at /api/v1)
@@ -36,6 +37,16 @@ pub fn file_serve_routes() -> Router {
         .route("/api/files/{id}/thumbnail", get(serve_file_thumbnail))
 }
 
+/// Signed-URL upload — standalone, no auth middleware: the HMAC token in the
+/// path is the credential (minted by the MCP `create_upload_url` tool).
+/// Registered at the literal path the tool advertises.
+pub fn signed_upload_routes(max_upload_bytes: usize) -> Router {
+    Router::new()
+        .route("/api/v1/files/upload/{token}", put(upload_via_signed_url))
+        .layer(DefaultBodyLimit::disable())
+        .layer(RequestBodyLimitLayer::new(max_upload_bytes))
+}
+
 /// Dashboard routes (mounted under /api/dashboard/sites/{site_id})
 pub fn dashboard_routes(max_upload_bytes: usize) -> Router {
     Router::new()
diff --git a/apps/backend/src/router/mod.rs b/apps/backend/src/router/mod.rs
index 9bc212fd..ce2c4a53 100644
--- a/apps/backend/src/router/mod.rs
+++ b/apps/backend/src/router/mod.rs
@@ -142,6 +142,8 @@ pub fn create_router(
         )
         // ── File serving (no auth — file IDs are effectively opaque) ──
         .merge(files::file_serve_routes())
+        // ── Signed-URL upload (no auth — the HMAC token is the credential) ──
+        .merge(files::signed_upload_routes(max_upload_bytes))
         // ── Dashboard API (/api/dashboard/*) ──
         .nest(
             "/api/dashboard",
diff --git a/apps/backend/src/router/openapi.rs b/apps/backend/src/router/openapi.rs
index df9fda4f..5affdfcc 100644
--- a/apps/backend/src/router/openapi.rs
+++ b/apps/backend/src/router/openapi.rs
@@ -41,6 +41,7 @@ use crate::models::site::Site;
         // Public API: Files
         crate::handlers::file_handler::list_files,
         crate::handlers::file_handler::upload_file,
+        crate::handlers::file_handler::upload_via_signed_url,
         crate::handlers::file_handler::get_file,
         crate::handlers::file_handler::delete_file_handler,
         crate::handlers::file_handler::get_file_references,
diff --git a/apps/backend/src/signed_upload.rs b/apps/backend/src/signed_upload.rs
index a8f99372..cbaa3db9 100644
--- a/apps/backend/src/signed_upload.rs
+++ b/apps/backend/src/signed_upload.rs
@@ -5,7 +5,9 @@ use thiserror::Error;
 
 type HmacSha256 = Hmac<Sha256>;
 
-const UPLOAD_TOKEN_EXPIRY_SECS: i64 = 900; // 15 minutes
+/// Default signed-URL lifetime; the runtime value comes from
+/// `Config::upload_token_expiry_secs` (default 900).
+pub const DEFAULT_UPLOAD_TOKEN_EXPIRY_SECS: i64 = 900;
 
 #[derive(Debug, Clone)]
 pub struct SignedUploadToken {
@@ -35,31 +37,14 @@ pub enum SignedUploadError {
 
 impl SignedUploadToken {
     pub fn generate(site_id: &str, filename: &str, content_type: &str, hmac_secret: &str) -> (Self, String) {
-        let file_id = uuid::Uuid::now_v7().to_string();
-        let storage_provider = "filesystem".to_string();
-        let expires_at = chrono::Utc::now().timestamp() + UPLOAD_TOKEN_EXPIRY_SECS;
-
-        let payload = format!(
-            "{}:{}:{}:{}:{}:{}",
-            file_id, site_id, filename, content_type, storage_provider, expires_at
-        );
-
-        let mut mac = HmacSha256::new_from_slice(hmac_secret.as_bytes()).expect("HMAC can take key of any size");
-        mac.update(payload.as_bytes());
-        let signature = hex::encode(mac.finalize().into_bytes());
-
-        let token = Self {
-            file_id,
-            site_id: site_id.to_string(),
-            filename: filename.to_string(),
-            content_type: content_type.to_string(),
-            storage_provider,
-            expires_at,
-            signature,
-        };
-
-        let encoded = Self::encode(&token);
-        (token, encoded)
+        Self::generate_with_storage_provider(
+            site_id,
+            filename,
+            content_type,
+            "filesystem",
+            hmac_secret,
+            DEFAULT_UPLOAD_TOKEN_EXPIRY_SECS,
+        )
     }
 
     pub fn generate_with_storage_provider(
@@ -68,9 +53,10 @@ impl SignedUploadToken {
         content_type: &str,
         storage_provider: &str,
         hmac_secret: &str,
+        expiry_secs: i64,
     ) -> (Self, String) {
         let file_id = uuid::Uuid::now_v7().to_string();
-        let expires_at = chrono::Utc::now().timestamp() + UPLOAD_TOKEN_EXPIRY_SECS;
+        let expires_at = chrono::Utc::now().timestamp() + expiry_secs;
 
         let payload = format!(
             "{}:{}:{}:{}:{}:{}",
@@ -211,11 +197,31 @@ mod tests {
 
     #[test]
     fn test_generate_with_storage_provider() {
-        let (token, encoded) =
-            SignedUploadToken::generate_with_storage_provider("site-123", "doc.pdf", "application/pdf", "s3", "secret");
+        let (token, encoded) = SignedUploadToken::generate_with_storage_provider(
+            "site-123",
+            "doc.pdf",
+            "application/pdf",
+            "s3",
+            "secret",
+            DEFAULT_UPLOAD_TOKEN_EXPIRY_SECS,
+        );
         assert_eq!(token.storage_provider, "s3");
 
         let verified = SignedUploadToken::verify(&encoded, "secret").unwrap();
         assert_eq!(verified.storage_provider, "s3");
     }
+
+    #[test]
+    fn test_verify_expired_token() {
+        let (_, encoded) = SignedUploadToken::generate_with_storage_provider(
+            "site-123",
+            "doc.pdf",
+            "application/pdf",
+            "filesystem",
+            "secret",
+            -10,
+        );
+        let result = SignedUploadToken::verify(&encoded, "secret");
+        assert!(matches!(result, Err(SignedUploadError::Expired)));
+    }
 }
diff --git a/apps/backend/tests/common/server.rs b/apps/backend/tests/common/server.rs
index 7f5803fa..b3feda33 100644
--- a/apps/backend/tests/common/server.rs
+++ b/apps/backend/tests/common/server.rs
@@ -74,6 +74,8 @@ impl TestServer {
             db_acquire_timeout_secs: 30,
             db_idle_timeout_secs: 5,
             max_upload_size_bytes: 50 * 1024 * 1024,
+            // `Config::default()` leaves this 0 => tokens minted already expired.
+            upload_token_expiry_secs: 900,
             public_registration_enabled: true,
             bcrypt_cost: bcrypt::DEFAULT_COST,
             webhook_allow_private_targets: true,

From adceb99b50bb8c97b87d676f27438f602d2cfd84 Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Thu, 2 Jul 2026 19:41:04 +0530
Subject: [PATCH 26/44] feat(mcp): improve create_upload_url with content
 validation

- Validate content type against the whitelist at mint time (fail fast
  instead of returning a URL doomed to a 400 PUT)
- Resolve the site's actual storage provider instead of hardcoding
  'filesystem'
- Use configurable upload_token_expiry_secs
- Expanded tool description explaining the PUT workflow
---
 apps/backend/src/mcp/server.rs     | 14 ++++++++++++--
 apps/backend/src/mcp/tools/file.rs | 20 +++++++++++++++++++-
 2 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/apps/backend/src/mcp/server.rs b/apps/backend/src/mcp/server.rs
index 6e3fd9af..23264eae 100644
--- a/apps/backend/src/mcp/server.rs
+++ b/apps/backend/src/mcp/server.rs
@@ -238,7 +238,9 @@ impl CmsServer {
         file::get_file(&self.authorizer, &self.services, &actor, params).await
     }
 
-    #[tool(description = "Create a signed upload URL for uploading a file")]
+    #[tool(
+        description = "Create a single-use signed upload URL. To upload: send an HTTP PUT to upload_url with the raw file bytes as the request body and a Content-Type header equal to content_type. The URL expires at expires_at and can be used exactly once. The PUT response body is the created file record (JSON, includes the file id and url)."
+    )]
     async fn create_upload_url(
         &self,
         ctx: RequestContext<RoleServer>,
@@ -246,7 +248,15 @@ impl CmsServer {
     ) -> Result<CallToolResult, McpError> {
         let actor = self.resolve_actor(&ctx)?;
         let public_base_url = self.public_base_url(&ctx);
-        file::create_upload_url(&self.authorizer, &self.config, &actor, public_base_url, params).await
+        file::create_upload_url(
+            &self.authorizer,
+            &self.services,
+            &self.config,
+            &actor,
+            public_base_url,
+            params,
+        )
+        .await
     }
 
     #[tool(description = "Delete a file (soft delete)")]
diff --git a/apps/backend/src/mcp/tools/file.rs b/apps/backend/src/mcp/tools/file.rs
index d43a9f8a..52394de5 100644
--- a/apps/backend/src/mcp/tools/file.rs
+++ b/apps/backend/src/mcp/tools/file.rs
@@ -113,6 +113,7 @@ fn default_content_type() -> String {
 
 pub async fn create_upload_url(
     authorization: &Arc<AuthorizationService>,
+    services: &Arc<Services>,
     config: &Arc<Config>,
     actor: &Actor,
     public_base_url: Option<String>,
@@ -126,11 +127,28 @@ pub async fn create_upload_url(
         return Ok(tool_error(e));
     }
 
-    let (token, upload_path) = SignedUploadToken::generate(
+    // Fail fast at mint time instead of returning a URL doomed to a 400 PUT.
+    if !crate::utils::content_types::is_allowed(&params.0.content_type) {
+        return Ok(tool_error(crate::services::error::ServiceError::BadRequest(format!(
+            "Content type '{}' is not allowed. Accepted types: images, videos, audio, documents, archives",
+            params.0.content_type
+        ))));
+    }
+
+    // Mint against the site's actual storage provider, not a hardcoded default.
+    let storage_provider = services
+        .file
+        .get_storage_provider(&site_id)
+        .await
+        .unwrap_or_else(|_| "filesystem".into());
+
+    let (token, upload_path) = SignedUploadToken::generate_with_storage_provider(
         &site_id,
         &params.0.filename,
         &params.0.content_type,
+        &storage_provider,
         &config.hmac_secret,
+        config.upload_token_expiry_secs,
     );
 
     let fallback_base_url = format!("http://{}", config.bind_address);

From 92a6fee3dd2b18a5848dfd5d82640ef564a389d8 Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Thu, 2 Jul 2026 19:41:12 +0530
Subject: [PATCH 27/44] perf(auth): debounce session/token last-sSeen timestamp
 updates

Skip the unconditional per-request UPDATE on sessions and access
tokens when the 'last seen' timestamp is less than 60s old. This keeps
the auth hot path read-only for most requests while still recording
activity at a reasonable granularity.

- Add parse_db_timestamp() for lenient RFC3339/Postgres/SQLite timestamp
  parsing
- Add needs_touch() helper used by both REST middleware and gRPC
  interceptor
- Touch interval is 60 seconds (TOUCH_INTERVAL_SECS)
---
 apps/backend/src/grpc/interceptor.rs |  6 +++--
 apps/backend/src/middleware/auth.rs  | 38 +++++++++++++++++++++++++---
 2 files changed, 39 insertions(+), 5 deletions(-)

diff --git a/apps/backend/src/grpc/interceptor.rs b/apps/backend/src/grpc/interceptor.rs
index 9ac4b810..de35e06d 100644
--- a/apps/backend/src/grpc/interceptor.rs
+++ b/apps/backend/src/grpc/interceptor.rs
@@ -89,7 +89,7 @@ async fn validate_auth(ctx: &AuthContext, repository: &Repository) -> Result<Grp
         tonic::Status::internal("Authentication service unavailable")
     })?;
 
-    for (key_id, site_id, stored_hash, stored_hmac, expires_at, revoked_at, permission) in keys {
+    for (key_id, site_id, stored_hash, stored_hmac, expires_at, revoked_at, permission, last_used_at) in keys {
         let valid = if let Some(ref stored) = stored_hmac {
             stored == &ctx.hmac
         } else {
@@ -111,7 +111,9 @@ async fn validate_auth(ctx: &AuthContext, repository: &Repository) -> Result<Grp
             return Err(tonic::Status::unauthenticated("Access token has expired"));
         }
 
-        if let Err(e) = repository.access_token.update_last_used(&key_id).await {
+        if crate::middleware::auth::needs_touch(last_used_at.as_deref())
+            && let Err(e) = repository.access_token.update_last_used(&key_id).await
+        {
             tracing::warn!(error = ?e, key_id = %key_id, "Failed to update last_used");
         }
 
diff --git a/apps/backend/src/middleware/auth.rs b/apps/backend/src/middleware/auth.rs
index 1dd04b9f..0d1e51dd 100644
--- a/apps/backend/src/middleware/auth.rs
+++ b/apps/backend/src/middleware/auth.rs
@@ -176,6 +176,34 @@ fn extract_csrf_token(parts: &Parts) -> Option<String> {
 
 // ── HMAC / sessions ──
 
+/// How stale a session/token "last seen" timestamp may get before we rewrite
+/// it. Skipping the unconditional per-request UPDATE keeps the auth hot path
+/// read-only for most requests.
+pub(crate) const TOUCH_INTERVAL_SECS: i64 = 60;
+
+/// Lenient parse of the backend-specific timestamp texts: RFC3339, Postgres
+/// `::text` (`YYYY-MM-DD HH:MM:SS[.fff]+00`), or naive UTC (SQLite/MySQL).
+pub(crate) fn parse_db_timestamp(s: &str) -> Option<chrono::DateTime<chrono::Utc>> {
+    if let Ok(dt) = chrono::DateTime::parse_from_rfc3339(s) {
+        return Some(dt.with_timezone(&chrono::Utc));
+    }
+    if let Ok(dt) = chrono::DateTime::parse_from_str(s, "%Y-%m-%d %H:%M:%S%.f%#z") {
+        return Some(dt.with_timezone(&chrono::Utc));
+    }
+    chrono::NaiveDateTime::parse_from_str(s, "%Y-%m-%d %H:%M:%S%.f")
+        .ok()
+        .map(|naive| naive.and_utc())
+}
+
+/// True when a "last seen/used" timestamp is missing, unparseable, or older
+/// than [`TOUCH_INTERVAL_SECS`] — i.e. it should be rewritten (safe fallback).
+pub(crate) fn needs_touch(last: Option<&str>) -> bool {
+    match last.and_then(parse_db_timestamp) {
+        Some(ts) => (chrono::Utc::now() - ts).num_seconds() > TOUCH_INTERVAL_SECS,
+        None => true,
+    }
+}
+
 pub fn compute_key_hmac(key: &str, hmac_secret: &str) -> String {
     let mut mac = HmacSha256::new_from_slice(hmac_secret.as_bytes()).expect("HMAC can take key of any size");
     mac.update(key.as_bytes());
@@ -193,7 +221,9 @@ pub async fn verify_session(
         .await
         .map_err(|_| AuthError::unauthorized("Authentication service unavailable"))?
         .ok_or_else(|| AuthError::unauthorized("Invalid or expired session"))?;
-    let _ = repository.session.touch(&session.id).await;
+    if needs_touch(Some(&session.last_seen_at)) {
+        let _ = repository.session.touch(&session.id).await;
+    }
     Ok(UserActor {
         user_id: session.user_id,
         session_id: session.id,
@@ -221,7 +251,7 @@ pub(crate) async fn verify_access_token(
 
     let token_hmac = compute_key_hmac(token, hmac_secret);
 
-    for (token_id, site_id, stored_hash, stored_hmac, expires_at, revoked_at, permission) in keys {
+    for (token_id, site_id, stored_hash, stored_hmac, expires_at, revoked_at, permission, last_used_at) in keys {
         if let Some(ref stored) = stored_hmac {
             if stored != &token_hmac {
                 continue;
@@ -242,7 +272,9 @@ pub(crate) async fn verify_access_token(
             .parse::<AccessTokenPermission>()
             .map_err(|_| AuthError::unauthorized("Invalid access token"))?;
 
-        let _ = repository.access_token.update_last_used(&token_id).await;
+        if needs_touch(last_used_at.as_deref()) {
+            let _ = repository.access_token.update_last_used(&token_id).await;
+        }
 
         Span::current().record("site_id", tracing::field::display(&site_id));
         return Ok(Actor::ApiKey(ApiKeyActor {

From 9463bdf529d2fe414da81073ec35e227f2264959 Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Thu, 2 Jul 2026 19:41:22 +0530
Subject: [PATCH 28/44] perf(search): make indexer purely event-driven, remove
 polling

The search indexer no longer polls on a 2s interval. Since all content
producers run in the server process (vcms mcp stdio is an HTTP proxy),
every enqueue rings the in-process Notify. The loop now sleeps until
notified, with a one-time startup drain for rows left by a crash.

The queue's documentation is updated to clarify it exists purely for
durability (crash recovery), not cross-process signaling.
---
 apps/backend/src/services/search/indexer.rs | 26 +++++++++++----------
 apps/backend/src/services/search/queue.rs   | 16 ++++++-------
 2 files changed, 22 insertions(+), 20 deletions(-)

diff --git a/apps/backend/src/services/search/indexer.rs b/apps/backend/src/services/search/indexer.rs
index 5e2f9f52..3d169813 100644
--- a/apps/backend/src/services/search/indexer.rs
+++ b/apps/backend/src/services/search/indexer.rs
@@ -1,34 +1,36 @@
 //! The single-consumer search indexer.
 //!
 //! Spawned once by the running server (it owns the Tantivy writer). It drains the
-//! [`SearchQueue`] — populated by content writes from *any* process — and applies
-//! the changes to the index. It wakes immediately on a local enqueue (via the
-//! queue's `Notify`) and also polls on an interval to pick up enqueues from other
-//! processes (e.g. `vcms mcp stdio`).
+//! [`SearchQueue`] and applies the changes to the index. The server is the only
+//! process that writes content (`vcms mcp stdio` is an HTTP proxy to it), and
+//! every enqueue rings the queue's in-process `Notify`, so the indexer is purely
+//! event-driven: one startup drain for rows a previous process left behind
+//! (crash recovery), then sleep until notified.
 
 use std::collections::HashSet;
 use std::sync::Arc;
-use std::time::Duration;
 
 use super::SearchError;
 use super::SearchService;
 use super::queue::SearchQueue;
 use crate::repository::Repository;
 
-/// Fallback poll interval for enqueues made by other processes (which can't ring
-/// this process's in-memory `Notify`).
-const POLL_INTERVAL: Duration = Duration::from_secs(2);
 /// Max rows processed per drain iteration.
 const BATCH_SIZE: i64 = 256;
 
 /// Run the indexer loop forever. Owns the writer-side `SearchService`.
 pub async fn run(search: Arc<SearchService>, queue: Arc<SearchQueue>, repository: Arc<Repository>) {
     let notify = queue.notify_handle();
+
+    // Startup drain: pick up rows committed before a crash/restart. `Notify`
+    // stores a permit, so an enqueue racing this drain is never lost — it just
+    // wakes the loop below for an empty (cheap) drain in the worst case.
+    if let Err(e) = drain(&search, &queue, &repository).await {
+        tracing::error!("Search indexer startup drain failed: {}", e);
+    }
+
     loop {
-        tokio::select! {
-            _ = notify.notified() => {}
-            _ = tokio::time::sleep(POLL_INTERVAL) => {}
-        }
+        notify.notified().await;
         if let Err(e) = drain(&search, &queue, &repository).await {
             tracing::error!("Search indexer drain failed: {}", e);
         }
diff --git a/apps/backend/src/services/search/queue.rs b/apps/backend/src/services/search/queue.rs
index dab97821..756c34d4 100644
--- a/apps/backend/src/services/search/queue.rs
+++ b/apps/backend/src/services/search/queue.rs
@@ -1,10 +1,11 @@
-//! Durable, cross-process queue of pending search-index updates
-//! (`search_index_queue` table).
+//! Durable queue of pending search-index updates (`search_index_queue` table).
 //!
-//! Producers (any process that writes entry content) call [`SearchQueue::enqueue`]
-//! after a write. The single writer-owning server drains the queue via the
-//! [`indexer`](super::indexer). Because the queue lives in the database it works
-//! across processes (e.g. a separate `vcms mcp stdio`) and survives restarts.
+//! Content writes call [`SearchQueue::enqueue`] after committing; the server's
+//! [`indexer`](super::indexer) drains the queue. All producers run in the server
+//! process (`vcms mcp stdio` is an HTTP proxy), so every enqueue also rings the
+//! in-process `Notify` and the indexer needs no polling. The queue lives in the
+//! database purely for durability: rows enqueued before a crash are drained on
+//! the next startup.
 
 use std::sync::Arc;
 
@@ -31,8 +32,7 @@ pub struct QueueRow {
 /// Handle for enqueuing index updates and draining them.
 pub struct SearchQueue {
     pool: DbPool,
-    /// Wakes the in-process indexer immediately on a local enqueue (cross-process
-    /// enqueues are picked up by the indexer's poll fallback instead).
+    /// Wakes the indexer immediately on an enqueue (all producers are in-process).
     notify: Arc<Notify>,
 }
 

From 77591e0824a4805379d21ed9c0580e5d4670cd54 Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Thu, 2 Jul 2026 19:41:28 +0530
Subject: [PATCH 29/44] feat(dashboard): add ETag and cache-control headers for
 embedded assets

Embedded SPA assets now serve with proper HTTP caching:
- assets/ (content-hashed by Vite): immutable, max-age=1y
- index.html: no-cache (revalidate every time)
- Other files (favicon etc): max-age=1h

ETags (embed-time sha256) enable 304 Not Modified responses. The
HeaderMap is threaded through to the dashboard handler.
---
 .../backend/src/handlers/dashboard_handler.rs | 58 ++++++++++++++++---
 apps/backend/src/router/dashboard.rs          |  8 ++-
 2 files changed, 57 insertions(+), 9 deletions(-)

diff --git a/apps/backend/src/handlers/dashboard_handler.rs b/apps/backend/src/handlers/dashboard_handler.rs
index 1f546f94..13cf99a8 100644
--- a/apps/backend/src/handlers/dashboard_handler.rs
+++ b/apps/backend/src/handlers/dashboard_handler.rs
@@ -4,6 +4,8 @@ use axum::{
     response::{IntoResponse, Response},
 };
 
+#[cfg(feature = "embed-dashboard")]
+use axum::http::HeaderMap;
 #[cfg(feature = "embed-dashboard")]
 use mime_guess::from_path;
 
@@ -15,19 +17,61 @@ use rust_embed::RustEmbed;
 #[folder = "../dashboard/dist"]
 pub struct Assets;
 
+/// Cache policy for an embedded asset path: Vite content-hashes everything
+/// under `assets/`, so those are immutable; `index.html` (and the SPA
+/// fallback) must revalidate every time; the rest (favicon etc.) get a short
+/// TTL. ETags (embed-time sha256) let revalidations answer with a 304.
+#[cfg(feature = "embed-dashboard")]
+fn cache_control_for(path: &str) -> &'static str {
+    if path.starts_with("assets/") {
+        "public, max-age=31536000, immutable"
+    } else if path == "index.html" {
+        "no-cache"
+    } else {
+        "public, max-age=3600"
+    }
+}
+
 #[cfg(feature = "embed-dashboard")]
-pub async fn dashboard_handler(Path(path): Path<String>) -> Response {
+fn serve_embedded(path: &str, content: rust_embed::EmbeddedFile, headers: &HeaderMap) -> Response {
+    let etag = format!("\"{}\"", hex::encode(content.metadata.sha256_hash()));
+    let cache_control = cache_control_for(path);
+
+    if headers
+        .get(header::IF_NONE_MATCH)
+        .and_then(|v| v.to_str().ok())
+        .is_some_and(|inm| inm == etag)
+    {
+        return (
+            StatusCode::NOT_MODIFIED,
+            [(header::ETAG, etag), (header::CACHE_CONTROL, cache_control.to_string())],
+        )
+            .into_response();
+    }
+
+    let mime = from_path(path).first_or_octet_stream();
+    (
+        StatusCode::OK,
+        [
+            (header::CONTENT_TYPE, mime.as_ref().to_string()),
+            (header::ETAG, etag),
+            (header::CACHE_CONTROL, cache_control.to_string()),
+        ],
+        content.data,
+    )
+        .into_response()
+}
+
+#[cfg(feature = "embed-dashboard")]
+pub async fn dashboard_handler(Path(path): Path<String>, headers: HeaderMap) -> Response {
     let requested_path = if path.is_empty() { "index.html" } else { path.as_str() };
 
     match Assets::get(requested_path) {
-        Some(content) => {
-            let mime = from_path(requested_path).first_or_octet_stream();
-            (StatusCode::OK, [(header::CONTENT_TYPE, mime.as_ref())], content.data).into_response()
-        }
+        Some(content) => serve_embedded(requested_path, content, &headers),
         None => {
             // SPA fallback
             if let Some(index) = Assets::get("index.html") {
-                (StatusCode::OK, [(header::CONTENT_TYPE, "text/html")], index.data).into_response()
+                serve_embedded("index.html", index, &headers)
             } else {
                 StatusCode::NOT_FOUND.into_response()
             }
@@ -36,7 +80,7 @@ pub async fn dashboard_handler(Path(path): Path<String>) -> Response {
 }
 
 #[cfg(not(feature = "embed-dashboard"))]
-pub async fn dashboard_handler(Path(_path): Path<String>) -> Response {
+pub async fn dashboard_handler(Path(_path): Path<String>, _headers: axum::http::HeaderMap) -> Response {
     (
         StatusCode::SERVICE_UNAVAILABLE,
         [(header::CONTENT_TYPE, "text/plain")],
diff --git a/apps/backend/src/router/dashboard.rs b/apps/backend/src/router/dashboard.rs
index 58739107..06e680b9 100644
--- a/apps/backend/src/router/dashboard.rs
+++ b/apps/backend/src/router/dashboard.rs
@@ -6,14 +6,18 @@ pub fn dashboard_routes() -> Router {
     Router::new()
         .route(
             "/dashboard",
-            get(|| async { dashboard_handler(axum::extract::Path("".into())).await }),
+            get(|headers: axum::http::HeaderMap| async move {
+                dashboard_handler(axum::extract::Path("".into()), headers).await
+            }),
         )
         // Bare `/dashboard/` (trailing slash) matches neither `/dashboard` nor the
         // `{*file}` wildcard (which needs ≥1 segment); serve the SPA shell here too so a
         // refresh on a client route URL ending in `/` still loads the app.
         .route(
             "/dashboard/",
-            get(|| async { dashboard_handler(axum::extract::Path("".into())).await }),
+            get(|headers: axum::http::HeaderMap| async move {
+                dashboard_handler(axum::extract::Path("".into()), headers).await
+            }),
         )
         .route("/dashboard/{*file}", get(dashboard_handler))
 }

From 1773b57f84a32d4a7a82e624f2e5aade3dc658c9 Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Thu, 2 Jul 2026 19:41:36 +0530
Subject: [PATCH 30/44] fix(server): pre-bind TCP listeners before declaring
 readiness

Bind both REST and gRPC listeners before spawning serve loops so a port
conflict surfaces as a startup error instead of a background task
failure. Add an on_ready callback parameter to server::run() that fires
once startup has actually succeeded (DB open, migrations done, ports
bound).

Startup error messages now include context prefixes (e.g. 'preparing
data directories:', 'opening database:') for easier debugging from
service hosts where bare IO errors are otherwise opaque.

The gRPC server now accepts a pre-bound TcpListener instead of a
SocketAddr, using TcpListenerStream for graceful shutdown.
---
 apps/backend/src/grpc/server.rs | 10 ++++----
 apps/backend/src/main.rs        |  2 +-
 apps/backend/src/server.rs      | 44 +++++++++++++++++++++++----------
 3 files changed, 37 insertions(+), 19 deletions(-)

diff --git a/apps/backend/src/grpc/server.rs b/apps/backend/src/grpc/server.rs
index 88ff63bb..ec45d671 100644
--- a/apps/backend/src/grpc/server.rs
+++ b/apps/backend/src/grpc/server.rs
@@ -1,8 +1,8 @@
 use std::future::Future;
-use std::net::SocketAddr;
 use std::pin::Pin;
 use std::sync::Arc;
 
+use tokio_stream::wrappers::TcpListenerStream;
 use tonic::transport::Server;
 
 use crate::config::Config;
@@ -25,7 +25,7 @@ pub async fn start_grpc_server(
     repository: Arc<Repository>,
     config: Arc<Config>,
     storage_registry: Arc<StorageRegistry>,
-    grpc_addr: SocketAddr,
+    listener: tokio::net::TcpListener,
     shutdown: impl Future<Output = ()> + Send + 'static,
 ) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
     let collection_svc = CollectionServiceImpl::new(services.collection.clone(), repository.clone());
@@ -91,7 +91,7 @@ pub async fn start_grpc_server(
         .add_service(file_svc)
         .add_service(site_svc)
         .add_service(webhook_svc)
-        .serve_with_shutdown(grpc_addr, shutdown)
+        .serve_with_incoming_shutdown(TcpListenerStream::new(listener), shutdown)
         .await?;
 
     Ok(())
@@ -102,7 +102,7 @@ pub fn spawn_grpc_server(
     repository: Arc<Repository>,
     config: Arc<Config>,
     storage_registry: Arc<StorageRegistry>,
-    grpc_addr: SocketAddr,
+    listener: tokio::net::TcpListener,
     shutdown: Pin<Box<dyn Future<Output = ()> + Send>>,
 ) -> GrpcServerFuture {
     Box::pin(start_grpc_server(
@@ -110,7 +110,7 @@ pub fn spawn_grpc_server(
         repository,
         config,
         storage_registry,
-        grpc_addr,
+        listener,
         shutdown,
     ))
 }
diff --git a/apps/backend/src/main.rs b/apps/backend/src/main.rs
index 1a877e68..50774c57 100644
--- a/apps/backend/src/main.rs
+++ b/apps/backend/src/main.rs
@@ -49,7 +49,7 @@ async fn main() {
         Some(Command::Mcp {
             transport: McpTransport::Stdio,
         }) => run_mcp_stdio().await,
-        Some(Command::Serve) | None => cms::server::run(&cli, cms::server::shutdown_signal()).await,
+        Some(Command::Serve) | None => cms::server::run(&cli, cms::server::shutdown_signal(), || {}).await,
     };
 
     if let Err(e) = result {
diff --git a/apps/backend/src/server.rs b/apps/backend/src/server.rs
index 99c3504b..7522ed3c 100644
--- a/apps/backend/src/server.rs
+++ b/apps/backend/src/server.rs
@@ -31,11 +31,20 @@ const ADMIN_EMAIL: &str = "admin@cms.local";
 ///
 /// Shared by the foreground `serve` command and the OS service runners. The
 /// `shutdown` future is the single trigger that gracefully drains both the REST
-/// and gRPC listeners.
-pub async fn run(cli: &Cli, shutdown: impl Future<Output = ()> + Send + 'static) -> Result<(), Box<dyn Error>> {
-    crate::paths::ensure()?;
-    crate::secrets::ensure()?;
-    let config = Config::load(cli)?;
+/// and gRPC listeners. `on_ready` fires once startup has actually succeeded —
+/// database open + migrated and both listeners bound — so a service host (the
+/// Windows SCM runner) can report `Running` truthfully instead of optimistically.
+pub async fn run(
+    cli: &Cli,
+    shutdown: impl Future<Output = ()> + Send + 'static,
+    on_ready: impl FnOnce(),
+) -> Result<(), Box<dyn Error>> {
+    // Each early step gets a context prefix: a bare io error ("Access is denied.
+    // (os error 5)") from a service host is undebuggable without knowing which
+    // file/step produced it.
+    crate::paths::ensure().map_err(|e| format!("preparing data directories: {e}"))?;
+    crate::secrets::ensure().map_err(|e| format!("initializing secrets.toml: {e}"))?;
+    let config = Config::load(cli).map_err(|e| format!("loading configuration: {e}"))?;
 
     let _guard = crate::tracing::init_tracing(&config);
 
@@ -43,7 +52,9 @@ pub async fn run(cli: &Cli, shutdown: impl Future<Output = ()> + Send + 'static)
         return Err(format!("Invalid production security configuration: {e}").into());
     }
 
-    let pool = init_db_with_config(&config).await?;
+    let pool = init_db_with_config(&config)
+        .await
+        .map_err(|e| format!("opening database: {e}"))?;
 
     let repository = Repository::new(&pool);
 
@@ -122,6 +133,18 @@ pub async fn run(cli: &Cli, shutdown: impl Future<Output = ()> + Send + 'static)
         .map_err(|e| format!("Invalid GRPC_BIND_ADDRESS '{}': {e}", config.grpc_bind_address))?;
     info!("gRPC server running on {}", grpc_addr);
 
+    // Bind both listeners *before* declaring readiness (and before the serve loops
+    // spawn): a bind failure — the classic "port already taken" — must surface as a
+    // startup error, not as a background task that dies after we claimed to be up.
+    let rest_listener = tokio::net::TcpListener::bind(addr)
+        .await
+        .map_err(|e| format!("Failed to bind REST address {addr}: {e}"))?;
+    let grpc_listener = tokio::net::TcpListener::bind(grpc_addr)
+        .await
+        .map_err(|e| format!("Failed to bind gRPC address {grpc_addr}: {e}"))?;
+
+    on_ready();
+
     // One shutdown signal fans out to both listeners via a watch channel: the
     // injected `shutdown` future flips it, and both servers drain on the change.
     let (shutdown_tx, shutdown_rx) = tokio::sync::watch::channel(false);
@@ -133,13 +156,8 @@ pub async fn run(cli: &Cli, shutdown: impl Future<Output = ()> + Send + 'static)
 
     let rest_rx = shutdown_rx.clone();
     let rest_handle = tokio::spawn(async move {
-        let listener = tokio::net::TcpListener::bind(addr).await.map_err(|e| {
-            tracing::error!("Failed to bind REST address {addr}: {e}");
-            e
-        })?;
-
         axum::serve(
-            listener,
+            rest_listener,
             app.into_make_service_with_connect_info::<std::net::SocketAddr>(),
         )
         .with_graceful_shutdown(wait_for_shutdown(rest_rx))
@@ -155,7 +173,7 @@ pub async fn run(cli: &Cli, shutdown: impl Future<Output = ()> + Send + 'static)
         repository_arc.clone(),
         config_arc.clone(),
         storage_registry.clone(),
-        grpc_addr,
+        grpc_listener,
         Box::pin(wait_for_shutdown(shutdown_rx)),
     ));
 

From 72770bd5dbaba7c35fa11b87263b4fd0edddb5cd Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Thu, 2 Jul 2026 19:41:46 +0530
Subject: [PATCH 31/44] fix(windows): improve service lifecycle, error
 reporting, and ACL hardening

Lifecycle:
- Report StartPending during boot, Running only from on_ready callback
- start() now waits for Running state before claiming success
- stop() waits for Stopped state (with 30s timeout)
- Exit code uses ServiceSpecific(1) for vcms failures (visible in
  Event Log)
- Default LOG_OUTPUT to 'file' in service context (no console)
- Write failures to logs/service-error.log (plain std::fs, no tracing)
- Installer surfaces recent service errors directly in the failure msg

ACL hardening:
- Two-pass icacls: pass 1 hardens root dir only, pass 2 /reset's
  children so they re-inherit. Fixes the bug where the old single-pass
  /T left pre-existing files with an empty DACL (deny-everyone),
  bricking secrets.toml and vcms.db on reinstall.
- Added unit tests exercising both the happy path and repair of bricked
  files
---
 apps/backend/src/service/windows.rs | 238 +++++++++++++++++++++++++---
 1 file changed, 214 insertions(+), 24 deletions(-)

diff --git a/apps/backend/src/service/windows.rs b/apps/backend/src/service/windows.rs
index 7a445836..c741cf86 100644
--- a/apps/backend/src/service/windows.rs
+++ b/apps/backend/src/service/windows.rs
@@ -105,9 +105,9 @@ fn install() -> Result<(), Box<dyn std::error::Error>> {
     // printed "started" unconditionally, which is how a crash-on-boot slipped through.
     if !wait_for_state(&service, ServiceState::Running, SCM_WAIT) {
         return Err(format!(
-            "Service '{SERVICE_NAME}' was installed but did not reach Running. Check the logs under \
-             {}\\logs (read them from an elevated terminal). A common cause is another process already \
-             bound to the REST/gRPC ports.",
+            "Service '{SERVICE_NAME}' was installed but did not reach Running.{} Full logs are under \
+             {}\\logs (read them from an elevated terminal).",
+            recent_service_errors(),
             service_home().display()
         )
         .into());
@@ -197,16 +197,32 @@ fn wait_until_deleted(manager: &ServiceManager, timeout: Duration) -> bool {
 }
 
 fn start() -> Result<(), Box<dyn std::error::Error>> {
-    let service = open_service(ServiceAccess::START)?;
+    let service = open_service(ServiceAccess::START | ServiceAccess::QUERY_STATUS)?;
     service.start::<&str>(&[])?;
+    // Wait for Running before claiming success (same rationale as install()).
+    if !wait_for_state(&service, ServiceState::Running, SCM_WAIT) {
+        return Err(format!(
+            "Service '{SERVICE_NAME}' was told to start but did not reach Running.{} Full logs are under \
+             {}\\logs (read them from an elevated terminal).",
+            recent_service_errors(),
+            service_home().display()
+        )
+        .into());
+    }
     println!("Service '{SERVICE_NAME}' started.");
     Ok(())
 }
 
 fn stop() -> Result<(), Box<dyn std::error::Error>> {
-    let service = open_service(ServiceAccess::STOP)?;
+    let service = open_service(ServiceAccess::STOP | ServiceAccess::QUERY_STATUS)?;
+    // Unlike stop_and_wait (which tolerates already-stopped during teardown), an
+    // explicit user stop should surface the SCM error.
     service.stop()?;
-    println!("Service '{SERVICE_NAME}' stop requested.");
+    if wait_for_state(&service, ServiceState::Stopped, SCM_WAIT) {
+        println!("Service '{SERVICE_NAME}' stopped.");
+    } else {
+        println!("Service '{SERVICE_NAME}' stop requested; still stopping after 30s — check `vcms service status`.");
+    }
     Ok(())
 }
 
@@ -252,22 +268,126 @@ fn prepare_home() -> Result<(), Box<dyn std::error::Error>> {
 /// works regardless of the OS display language (`S-1-5-18` = LocalSystem,
 /// `S-1-5-32-544` = Administrators).
 fn harden_acl(path: &std::path::Path) -> Result<(), Box<dyn std::error::Error>> {
-    let status = std::process::Command::new("icacls")
-        .arg(path)
+    harden_acl_for(path, &["*S-1-5-18:(OI)(CI)F", "*S-1-5-32-544:(OI)(CI)F"])
+}
+
+/// The two-pass icacls sequence behind [`harden_acl`], parameterized over the grant
+/// specs so a non-elevated unit test can exercise it with the current user.
+///
+/// Pass 1 hardens the **root directory only**: strip inherited ACEs, drop broad
+/// explicit ACEs (Everyone `S-1-1-0`, Users `S-1-5-32-545`, Authenticated Users
+/// `S-1-5-11`), grant the given principals as inheritable ACEs. Pass 2 `/reset`s
+/// every child so it re-inherits from the root.
+///
+/// Never apply pass 1's inheritance-flagged grants to files (the old code's `/T`):
+/// icacls silently *drops* an `(OI)(CI)` grant on a file while `/inheritance:r`
+/// still strips its existing ACEs, leaving an **empty DACL — deny everyone,
+/// including SYSTEM**. That bricked every pre-existing file (db, secrets.toml) on
+/// reinstall, which is why the service booted fresh but died with "Access is
+/// denied (os error 5)" after an uninstall/install cycle. Pass 2 also *repairs*
+/// trees damaged that way.
+fn harden_acl_for(path: &std::path::Path, grant_specs: &[&str]) -> Result<(), Box<dyn std::error::Error>> {
+    let mut root = std::process::Command::new("icacls");
+    root.arg(path)
         .arg("/inheritance:r")
-        // Drop explicit broad ACEs a pre-existing dir may carry (`/inheritance:r` only
-        // removes *inherited* ones): Everyone, Users, Authenticated Users.
-        .args(["/remove:g", "*S-1-1-0", "*S-1-5-32-545", "*S-1-5-11"])
-        .args(["/grant:r", "*S-1-5-18:(OI)(CI)F"])
-        .args(["/grant:r", "*S-1-5-32-544:(OI)(CI)F"])
-        .arg("/T")
-        .status()?;
+        .args(["/remove:g", "*S-1-1-0", "*S-1-5-32-545", "*S-1-5-11"]);
+    for spec in grant_specs {
+        root.args(["/grant:r", spec]);
+    }
+    let status = root.status()?;
     if !status.success() {
         return Err(format!("icacls failed to harden {} ({status})", path.display()).into());
     }
+
+    // `<path>\*` matches the immediate children; `/T` recurses below them. An empty
+    // dir makes icacls fail with "file not found" — fine, nothing to reset.
+    let mut children = std::ffi::OsString::from(path);
+    children.push(r"\*");
+    let reset = std::process::Command::new("icacls")
+        .arg(children)
+        .args(["/reset", "/T", "/Q"])
+        .status()?;
+    if !reset.success() && path.read_dir().map(|mut d| d.next().is_some()).unwrap_or(false) {
+        return Err(format!(
+            "icacls failed to reset file ACLs under {} ({reset}); if files there were left \
+             inaccessible by an older vcms install, run `takeown /f {} /r /d y` once and re-run \
+             `vcms service install`",
+            path.display(),
+            path.display()
+        )
+        .into());
+    }
     Ok(())
 }
 
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// `DOMAIN\user:(OI)(CI)F` for the current account — lets the tests run the real
+    /// icacls sequence on a user-owned temp dir without elevation.
+    fn current_user_grant() -> String {
+        let domain = std::env::var("USERDOMAIN").unwrap_or_default();
+        let user = std::env::var("USERNAME").expect("USERNAME is always set on Windows");
+        if domain.is_empty() {
+            format!("{user}:(OI)(CI)F")
+        } else {
+            format!("{domain}\\{user}:(OI)(CI)F")
+        }
+    }
+
+    /// Regression: the old single-pass `icacls ... /grant:r X:(OI)(CI)F /T` left every
+    /// *pre-existing file* with an empty DACL (deny-everyone) because icacls drops
+    /// inheritance-flagged grants on files. The two-pass sequence must keep such files
+    /// readable — this is the exact bug that made the Windows service fail to start
+    /// after an uninstall/reinstall cycle.
+    #[test]
+    fn harden_keeps_existing_files_readable() {
+        let dir = tempfile::tempdir().expect("temp dir");
+        let pre_existing = dir.path().join("secrets.toml");
+        std::fs::write(&pre_existing, "hmac_secret = \"x\"").expect("write");
+
+        let grant = current_user_grant();
+        harden_acl_for(dir.path(), &[grant.as_str()]).expect("harden");
+
+        let read = std::fs::read_to_string(&pre_existing).expect("pre-existing file must stay readable");
+        assert_eq!(read, "hmac_secret = \"x\"");
+
+        // Files created after hardening inherit from the root and stay readable too.
+        let created_after = dir.path().join("vcms.db");
+        std::fs::write(&created_after, "db").expect("write after harden");
+        assert_eq!(std::fs::read_to_string(&created_after).expect("readable"), "db");
+    }
+
+    /// The children `/reset` pass must also *repair* a tree bricked by the old
+    /// sequence (files left with an empty DACL by a previous vcms install).
+    #[test]
+    fn harden_repairs_files_bricked_by_old_sequence() {
+        let dir = tempfile::tempdir().expect("temp dir");
+        let file = dir.path().join("vcms.db");
+        std::fs::write(&file, "data").expect("write");
+
+        // Reproduce the old bug: inheritance-flagged grant with /T strips the file's
+        // ACEs without adding effective ones.
+        let grant = current_user_grant();
+        let status = std::process::Command::new("icacls")
+            .arg(dir.path())
+            .arg("/inheritance:r")
+            .args(["/grant:r", &grant])
+            .arg("/T")
+            .status()
+            .expect("icacls runs");
+        assert!(status.success());
+        assert!(
+            std::fs::read_to_string(&file).is_err(),
+            "old sequence should brick the file (if this fails, icacls semantics changed)"
+        );
+
+        harden_acl_for(dir.path(), &[grant.as_str()]).expect("harden");
+        assert_eq!(std::fs::read_to_string(&file).expect("repaired and readable"), "data");
+    }
+}
+
 // ----- SCM-hosted run path -----
 
 define_windows_service!(ffi_service_main, service_main);
@@ -282,13 +402,57 @@ fn run_dispatcher() -> Result<(), Box<dyn std::error::Error>> {
             std::env::set_var(crate::paths::CMS_HOME_ENV, service_home());
         }
     }
+    // A service has no console, so the default stdout logging goes nowhere. Default
+    // to file output (lands in the home's logs/ — where install() tells the user to
+    // look); an explicit LOG_OUTPUT (env or .env) still wins.
+    if std::env::var_os("LOG_OUTPUT").is_none() {
+        // SAFETY: same single-threaded process-start window as above.
+        unsafe {
+            std::env::set_var("LOG_OUTPUT", "file");
+        }
+    }
     service_dispatcher::start(SERVICE_NAME, ffi_service_main)?;
     Ok(())
 }
 
 fn service_main(_arguments: Vec<OsString>) {
     if let Err(e) = run_service_session() {
-        eprintln!("vcms service error: {e}");
+        // No console exists here — stderr goes nowhere — so failures land in a file.
+        log_service_error(&format!("vcms service error: {e}"));
+    }
+}
+
+/// Tail of `service-error.log`, pre-formatted for appending to a start-failure
+/// message. The installer runs elevated (it can read the ACL-locked home), so it
+/// surfaces the service's own boot error directly instead of making the user go
+/// find it. Empty string when the file is absent/unreadable.
+fn recent_service_errors() -> String {
+    let path = service_home().join("logs").join("service-error.log");
+    let Ok(contents) = std::fs::read_to_string(path) else {
+        return String::new();
+    };
+    let mut tail: Vec<&str> = contents.lines().rev().take(5).collect();
+    tail.reverse();
+    if tail.is_empty() {
+        return String::new();
+    }
+    format!(" Recent service errors:\n  {}\n", tail.join("\n  "))
+}
+
+/// Append a fatal service error to `<home>\logs\service-error.log`. Deliberately
+/// plain `std::fs` (no tracing): it must work even when startup failed before —
+/// or because — tracing/config initialization broke. Best-effort: a service can't
+/// report its reporter failing.
+fn log_service_error(msg: &str) {
+    use std::io::Write;
+    let dir = service_home().join("logs");
+    let _ = std::fs::create_dir_all(&dir);
+    if let Ok(mut file) = std::fs::OpenOptions::new()
+        .create(true)
+        .append(true)
+        .open(dir.join("service-error.log"))
+    {
+        let _ = writeln!(file, "[{}] {msg}", crate::services::backup::now_iso());
     }
 }
 
@@ -330,31 +494,57 @@ fn run_service_session() -> Result<(), Box<dyn std::error::Error>> {
     })?;
     *status_handle_cell.lock().map_err(|e| format!("{e}"))? = Some(status_handle);
 
-    let running = ServiceStatus {
+    // Report StartPending while the server actually boots (home preflight, secrets,
+    // config, DB open + migrations, port binds). Running is published only from the
+    // readiness hook below — the old code set Running up front, so install() saw a
+    // healthy service even when boot failed a moment later.
+    let start_pending = ServiceStatus {
         service_type: ServiceType::OWN_PROCESS,
-        current_state: ServiceState::Running,
-        controls_accepted: ServiceControlAccept::STOP | ServiceControlAccept::SHUTDOWN,
+        current_state: ServiceState::StartPending,
+        controls_accepted: ServiceControlAccept::empty(),
         exit_code: ServiceExitCode::Win32(0),
         checkpoint: 0,
-        wait_hint: Duration::default(),
+        wait_hint: Duration::from_secs(60),
         process_id: None,
     };
-    status_handle.set_service_status(running.clone())?;
+    status_handle.set_service_status(start_pending)?;
+
+    let ready_handle = status_handle;
+    let on_ready = move || {
+        let _ = ready_handle.set_service_status(ServiceStatus {
+            service_type: ServiceType::OWN_PROCESS,
+            current_state: ServiceState::Running,
+            controls_accepted: ServiceControlAccept::STOP | ServiceControlAccept::SHUTDOWN,
+            exit_code: ServiceExitCode::Win32(0),
+            checkpoint: 0,
+            wait_hint: Duration::default(),
+            process_id: None,
+        });
+    };
 
     // This thread is owned by the SCM dispatcher (not a tokio worker), so building
     // a fresh runtime here is safe — no nested-runtime panic.
     let runtime = tokio::runtime::Builder::new_multi_thread().enable_all().build()?;
     let shutdown = async move { notify.notified().await };
-    let result = runtime.block_on(crate::server::run(&Cli::default(), shutdown));
+    let result = runtime.block_on(crate::server::run(&Cli::default(), shutdown, on_ready));
 
+    if let Err(e) = &result {
+        log_service_error(&format!("server startup/run failed: {e}"));
+    }
     let stopped = ServiceStatus {
+        service_type: ServiceType::OWN_PROCESS,
         current_state: ServiceState::Stopped,
+        controls_accepted: ServiceControlAccept::empty(),
+        // ServiceSpecific(1) (instead of a generic Win32 code) marks "vcms itself
+        // failed" in the SCM/Event Log; details are in logs\service-error.log.
         exit_code: if result.is_ok() {
             ServiceExitCode::Win32(0)
         } else {
-            ServiceExitCode::Win32(1)
+            ServiceExitCode::ServiceSpecific(1)
         },
-        ..running
+        checkpoint: 0,
+        wait_hint: Duration::default(),
+        process_id: None,
     };
     status_handle.set_service_status(stopped)?;
     result

From f1034afdb94a332bb3ec93544ea9d436ee72b706 Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Thu, 2 Jul 2026 19:41:57 +0530
Subject: [PATCH 32/44] fix(macos): poll for process exit on service stop

After sending SIGTERM via launchctl kill, poll launchctl print for up
to 10s to confirm the process actually exited. Prints a clear status
message on success or a 'check vcms service status' hint on timeout.
---
 apps/backend/src/service/macos.rs | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

diff --git a/apps/backend/src/service/macos.rs b/apps/backend/src/service/macos.rs
index a68e18a1..cb07a1a7 100644
--- a/apps/backend/src/service/macos.rs
+++ b/apps/backend/src/service/macos.rs
@@ -87,8 +87,28 @@ fn start() -> Result<(), Box<dyn std::error::Error>> {
 fn stop() -> Result<(), Box<dyn std::error::Error>> {
     require_root("stop")?;
     run(Command::new("launchctl").args(["kill", "SIGTERM", &target()]))?;
-    println!("Service '{LAUNCHD_LABEL}' stop signal sent.");
-    Ok(())
+    // launchctl kill only sends the signal; poll briefly so the user learns
+    // whether the process actually exited.
+    let deadline = std::time::Instant::now() + std::time::Duration::from_secs(10);
+    loop {
+        let running = Command::new("launchctl")
+            .args(["print", &target()])
+            .output()
+            .ok()
+            .filter(|out| out.status.success())
+            .is_some_and(|out| String::from_utf8_lossy(&out.stdout).contains("pid ="));
+        if !running {
+            println!("Service '{LAUNCHD_LABEL}' stopped.");
+            return Ok(());
+        }
+        if std::time::Instant::now() >= deadline {
+            println!(
+                "Service '{LAUNCHD_LABEL}' stop signal sent; still running after 10s — check `vcms service status`."
+            );
+            return Ok(());
+        }
+        std::thread::sleep(std::time::Duration::from_millis(500));
+    }
 }
 
 fn status() -> Result<(), Box<dyn std::error::Error>> {

From 949658e8a4d83dc98bcfb38a473e53ea9c5bf254 Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Thu, 2 Jul 2026 19:42:05 +0530
Subject: [PATCH 33/44] perf(repo): wrap collection migration in transaction;
 batch file refs

Collection migration (rename_map field references): wrap the per-entry
UPDATE loop in a single transaction so partial renames are never left
behind and per-statement commit overhead is eliminated.

Entry file reference inserts: replace per-file-id INSERT with a single
multi-row statement (IN/ANY clause). Reduces N round-trips to 1 for
entries with many file references.
---
 .../src/repository/mysql/collection.rs        |  6 ++++-
 apps/backend/src/repository/mysql/entry.rs    | 26 ++++++++++++-------
 .../src/repository/postgres/collection.rs     |  6 ++++-
 apps/backend/src/repository/postgres/entry.rs | 10 ++++---
 .../src/repository/sqlite/collection.rs       |  6 ++++-
 apps/backend/src/repository/sqlite/entry.rs   | 26 ++++++++++++-------
 6 files changed, 54 insertions(+), 26 deletions(-)

diff --git a/apps/backend/src/repository/mysql/collection.rs b/apps/backend/src/repository/mysql/collection.rs
index affed4a6..13ef3847 100644
--- a/apps/backend/src/repository/mysql/collection.rs
+++ b/apps/backend/src/repository/mysql/collection.rs
@@ -125,6 +125,9 @@ impl CollectionRepository for MysqlCollectionRepository {
         entry_items: &[Entry],
         rename_map: &std::collections::HashMap<String, String>,
     ) -> Result<(), RepositoryError> {
+        // One transaction for the whole migration: per-statement commit overhead
+        // dominated this loop, and a partial rename is never left behind.
+        let mut tx = self.pool.begin().await?;
         for entry in entry_items {
             if let Ok(mut data) = serde_json::from_str::<serde_json::Value>(&entry.data)
                 && let Some(obj) = data.as_object_mut()
@@ -140,10 +143,11 @@ impl CollectionRepository for MysqlCollectionRepository {
                 sqlx::query("UPDATE entries SET data = ?, updated_at = NOW() WHERE id = ?")
                     .bind(&new_data_str)
                     .bind(&entry.id)
-                    .execute(&self.pool)
+                    .execute(&mut *tx)
                     .await?;
             }
         }
+        tx.commit().await?;
         Ok(())
     }
 }
diff --git a/apps/backend/src/repository/mysql/entry.rs b/apps/backend/src/repository/mysql/entry.rs
index 5e158d6f..bb0222d8 100644
--- a/apps/backend/src/repository/mysql/entry.rs
+++ b/apps/backend/src/repository/mysql/entry.rs
@@ -334,16 +334,22 @@ impl EntryRepository for MysqlEntryRepository {
             .execute(&mut *tx)
             .await?;
 
-        for file_id in &file_ids {
-            sqlx::query(
-                "INSERT IGNORE INTO entry_file_references (entry_id, file_id, site_id) SELECT ?, id, ? FROM files WHERE id = ? AND site_id = ?",
-            )
-            .bind(entry_id)
-            .bind(site_id)
-            .bind(file_id)
-            .bind(site_id)
-            .execute(&mut *tx)
-            .await?;
+        if !file_ids.is_empty() {
+            // One multi-row statement instead of a query per file id; the
+            // SELECT keeps the "file must exist in this site" filter.
+            let placeholders = vec!["?"; file_ids.len()].join(", ");
+            let sql = format!(
+                "INSERT IGNORE INTO entry_file_references (entry_id, file_id, site_id)
+                 SELECT ?, id, ? FROM files WHERE site_id = ? AND id IN ({placeholders})",
+            );
+            let mut query = sqlx::query(sqlx::AssertSqlSafe(sql.as_str()))
+                .bind(entry_id)
+                .bind(site_id)
+                .bind(site_id);
+            for file_id in &file_ids {
+                query = query.bind(file_id);
+            }
+            query.execute(&mut *tx).await?;
         }
 
         tx.commit().await?;
diff --git a/apps/backend/src/repository/postgres/collection.rs b/apps/backend/src/repository/postgres/collection.rs
index 1fbc607c..11544168 100644
--- a/apps/backend/src/repository/postgres/collection.rs
+++ b/apps/backend/src/repository/postgres/collection.rs
@@ -127,6 +127,9 @@ impl CollectionRepository for PostgresCollectionRepository {
         entry_items: &[Entry],
         rename_map: &std::collections::HashMap<String, String>,
     ) -> Result<(), RepositoryError> {
+        // One transaction for the whole migration: per-statement commit overhead
+        // dominated this loop, and a partial rename is never left behind.
+        let mut tx = self.pool.begin().await?;
         for entry in entry_items {
             if let Ok(mut data) = serde_json::from_str::<serde_json::Value>(&entry.data)
                 && let Some(obj) = data.as_object_mut()
@@ -142,10 +145,11 @@ impl CollectionRepository for PostgresCollectionRepository {
                 sqlx::query("UPDATE entries SET data = $1::jsonb, updated_at = NOW() WHERE id = $2")
                     .bind(&new_data_str)
                     .bind(&entry.id)
-                    .execute(&self.pool)
+                    .execute(&mut *tx)
                     .await?;
             }
         }
+        tx.commit().await?;
         Ok(())
     }
 }
diff --git a/apps/backend/src/repository/postgres/entry.rs b/apps/backend/src/repository/postgres/entry.rs
index a8cb9280..cbeaca43 100644
--- a/apps/backend/src/repository/postgres/entry.rs
+++ b/apps/backend/src/repository/postgres/entry.rs
@@ -346,14 +346,18 @@ impl EntryRepository for PostgresEntryRepository {
             .execute(&mut *tx)
             .await?;
 
-        for file_id in &file_ids {
+        if !file_ids.is_empty() {
+            // One multi-row statement instead of a query per file id; the
+            // SELECT keeps the "file must exist in this site" filter.
             sqlx::query(
-                "INSERT INTO entry_file_references (entry_id, file_id, site_id) SELECT $1, id, $2 FROM files WHERE id = $3 AND site_id = $4 ON CONFLICT DO NOTHING",
+                "INSERT INTO entry_file_references (entry_id, file_id, site_id)
+                 SELECT $1, id, $2 FROM files WHERE site_id = $3 AND id = ANY($4)
+                 ON CONFLICT DO NOTHING",
             )
             .bind(entry_id)
             .bind(site_id)
-            .bind(file_id)
             .bind(site_id)
+            .bind(&file_ids)
             .execute(&mut *tx)
             .await?;
         }
diff --git a/apps/backend/src/repository/sqlite/collection.rs b/apps/backend/src/repository/sqlite/collection.rs
index 436a790d..147ed49d 100644
--- a/apps/backend/src/repository/sqlite/collection.rs
+++ b/apps/backend/src/repository/sqlite/collection.rs
@@ -127,6 +127,9 @@ impl CollectionRepository for SqliteCollectionRepository {
         entry_items: &[Entry],
         rename_map: &std::collections::HashMap<String, String>,
     ) -> Result<(), RepositoryError> {
+        // One transaction for the whole migration: per-statement commit overhead
+        // dominated this loop, and a partial rename is never left behind.
+        let mut tx = self.pool.begin().await?;
         for entry in entry_items {
             if let Ok(mut data) = serde_json::from_str::<serde_json::Value>(&entry.data)
                 && let Some(obj) = data.as_object_mut()
@@ -142,10 +145,11 @@ impl CollectionRepository for SqliteCollectionRepository {
                 sqlx::query("UPDATE entries SET data = ?, updated_at = datetime('now') WHERE id = ?")
                     .bind(&new_data_str)
                     .bind(&entry.id)
-                    .execute(&self.pool)
+                    .execute(&mut *tx)
                     .await?;
             }
         }
+        tx.commit().await?;
         Ok(())
     }
 }
diff --git a/apps/backend/src/repository/sqlite/entry.rs b/apps/backend/src/repository/sqlite/entry.rs
index dcdd3c1c..3d709416 100644
--- a/apps/backend/src/repository/sqlite/entry.rs
+++ b/apps/backend/src/repository/sqlite/entry.rs
@@ -376,16 +376,22 @@ impl EntryRepository for SqliteEntryRepository {
             .execute(&mut *tx)
             .await?;
 
-        for file_id in &file_ids {
-            sqlx::query(
-                "INSERT OR IGNORE INTO entry_file_references (entry_id, file_id, site_id) SELECT ?, id, ? FROM files WHERE id = ? AND site_id = ?",
-            )
-            .bind(entry_id)
-            .bind(site_id)
-            .bind(file_id)
-            .bind(site_id)
-            .execute(&mut *tx)
-            .await?;
+        if !file_ids.is_empty() {
+            // One multi-row statement instead of a query per file id; the
+            // SELECT keeps the "file must exist in this site" filter.
+            let placeholders = vec!["?"; file_ids.len()].join(", ");
+            let sql = format!(
+                "INSERT OR IGNORE INTO entry_file_references (entry_id, file_id, site_id)
+                 SELECT ?, id, ? FROM files WHERE site_id = ? AND id IN ({placeholders})",
+            );
+            let mut query = sqlx::query(sqlx::AssertSqlSafe(sql.as_str()))
+                .bind(entry_id)
+                .bind(site_id)
+                .bind(site_id);
+            for file_id in &file_ids {
+                query = query.bind(file_id);
+            }
+            query.execute(&mut *tx).await?;
         }
 
         tx.commit().await?;

From 95fd2b0df35a8ab967c904b6d1c2b569bace6b63 Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Thu, 2 Jul 2026 19:42:15 +0530
Subject: [PATCH 34/44] perf(backup): offload CPU-bound compression and
 encryption to blocking pool

tar building, zstd compression, and AES-256-GCM encryption are now run
via tokio::task::spawn_blocking so they don't starve the async runtime
during large backups. Similarly, decrypt/zstd-decode/untar during
restore run on the blocking pool.

The wrap/open methods are refactored into static functions
(wrap_bytes/open_bytes) that take owned parameters for spawn_blocking
compatibility. inspect_sites() is now async.
---
 apps/backend/src/handlers/backup_handler.rs |  4 +-
 apps/backend/src/services/backup/mod.rs     | 49 +++++++++++++++------
 2 files changed, 37 insertions(+), 16 deletions(-)

diff --git a/apps/backend/src/handlers/backup_handler.rs b/apps/backend/src/handlers/backup_handler.rs
index 90c8cb65..dded2a7b 100644
--- a/apps/backend/src/handlers/backup_handler.rs
+++ b/apps/backend/src/handlers/backup_handler.rs
@@ -679,7 +679,7 @@ pub async fn inspect_instance_backup(
         Ok(b) => b,
         Err(r) => return r,
     };
-    inspect_response(backup.inspect_sites(&bytes), None)
+    inspect_response(backup.inspect_sites(bytes).await, None)
 }
 
 /// Inspect an uploaded backup file, list its sites, and stage the bytes so the
@@ -699,7 +699,7 @@ pub async fn inspect_instance_backup_upload(
     };
     // Validate + read the site list before staging, so a bad file is rejected
     // without leaving an orphan temp object.
-    let (manifest, sites) = match backup.inspect_sites(&bytes) {
+    let (manifest, sites) = match backup.inspect_sites(bytes.clone()).await {
         Ok(v) => v,
         Err(e) => return err_response(e),
     };
diff --git a/apps/backend/src/services/backup/mod.rs b/apps/backend/src/services/backup/mod.rs
index 8b73ac43..051bfb9d 100644
--- a/apps/backend/src/services/backup/mod.rs
+++ b/apps/backend/src/services/backup/mod.rs
@@ -230,11 +230,19 @@ impl BackupService {
             files: file_manifest,
         };
 
-        let tar_bytes = build_tar(&manifest, &tar_tables, &file_blobs)?;
-        let compressed =
-            zstd::stream::encode_all(&tar_bytes[..], self.zstd_level).map_err(|e| BackupError::Io(e.to_string()))?;
-        let outer = self.wrap(compressed, encrypt)?;
-        Ok((manifest, outer))
+        // tar + zstd + AES-GCM are CPU-bound; keep them off the async runtime
+        // so a large backup doesn't starve request handling.
+        let zstd_level = self.zstd_level;
+        let key = self.encryption_key;
+        tokio::task::spawn_blocking(move || {
+            let tar_bytes = build_tar(&manifest, &tar_tables, &file_blobs)?;
+            let compressed =
+                zstd::stream::encode_all(&tar_bytes[..], zstd_level).map_err(|e| BackupError::Io(e.to_string()))?;
+            let outer = Self::wrap_bytes(key, compressed, encrypt)?;
+            Ok((manifest, outer))
+        })
+        .await
+        .map_err(|e| BackupError::Io(format!("backup task failed: {e}")))?
     }
 
     /// Run a backup: build the artifact, write it to the destination, and record
@@ -378,16 +386,16 @@ impl BackupService {
     // --- Restore ---
 
     /// Inspect a backup artifact's manifest (decrypting/decompressing as needed).
-    pub fn inspect(&self, bytes: &[u8]) -> Result<Manifest, BackupError> {
-        let (manifest, _, _) = self.open(bytes)?;
+    pub async fn inspect(&self, bytes: Vec<u8>) -> Result<Manifest, BackupError> {
+        let (manifest, _, _) = self.open_blocking(bytes).await?;
         Ok(manifest)
     }
 
     /// Inspect a backup artifact and list the sites it contains, so a caller can
     /// offer a pick-list. An instance backup yields every site in its `sites`
     /// table; a site backup yields its single site.
-    pub fn inspect_sites(&self, bytes: &[u8]) -> Result<(Manifest, Vec<SiteRef>), BackupError> {
-        let (manifest, tables_ndjson, _) = self.open(bytes)?;
+    pub async fn inspect_sites(&self, bytes: Vec<u8>) -> Result<(Manifest, Vec<SiteRef>), BackupError> {
+        let (manifest, tables_ndjson, _) = self.open_blocking(bytes).await?;
         let sites = match tables_ndjson.get("sites") {
             Some(ndjson) => parse_ndjson(ndjson)?
                 .iter()
@@ -442,7 +450,7 @@ impl BackupService {
             RestoreSource::Destination(key) => self.read_destination(key).await?,
         };
 
-        let (manifest, tables_ndjson, file_blobs) = self.open(&bytes)?;
+        let (manifest, tables_ndjson, file_blobs) = self.open_blocking(bytes).await?;
 
         if manifest.format_version > FORMAT_VERSION {
             return Err(BackupError::Invalid(format!(
@@ -583,11 +591,15 @@ impl BackupService {
 
     // --- Artifact wrapping ---
 
-    fn wrap(&self, compressed: Vec<u8>, encrypt: bool) -> Result<Vec<u8>, BackupError> {
+    fn wrap_bytes(
+        encryption_key: Option<[u8; 32]>,
+        compressed: Vec<u8>,
+        encrypt: bool,
+    ) -> Result<Vec<u8>, BackupError> {
         let mut out = Vec::with_capacity(compressed.len() + 32);
         out.extend_from_slice(MAGIC);
         if encrypt {
-            let key = self.encryption_key.ok_or(BackupError::MissingKey)?;
+            let key = encryption_key.ok_or(BackupError::MissingKey)?;
             out.push(FLAG_ENCRYPTED);
             let cipher = Aes256Gcm::new(&Key::<Aes256Gcm>::from(key));
             let mut nonce_bytes = [0u8; 12];
@@ -605,8 +617,17 @@ impl BackupService {
         Ok(out)
     }
 
+    /// Async wrapper for [`Self::open_bytes`]: decrypt/zstd-decode/untar are
+    /// CPU-bound, so they run on the blocking pool.
+    async fn open_blocking(&self, bytes: Vec<u8>) -> Result<ArtifactBundle, BackupError> {
+        let key = self.encryption_key;
+        tokio::task::spawn_blocking(move || Self::open_bytes(key, &bytes))
+            .await
+            .map_err(|e| BackupError::Io(format!("restore task failed: {e}")))?
+    }
+
     /// Decrypt/decompress an artifact into (manifest, table NDJSON, file blobs).
-    fn open(&self, bytes: &[u8]) -> Result<ArtifactBundle, BackupError> {
+    fn open_bytes(encryption_key: Option<[u8; 32]>, bytes: &[u8]) -> Result<ArtifactBundle, BackupError> {
         if bytes.len() < MAGIC.len() + 1 || &bytes[..MAGIC.len()] != MAGIC {
             return Err(BackupError::Invalid("not a CMS backup artifact".into()));
         }
@@ -614,7 +635,7 @@ impl BackupService {
         let body = &bytes[MAGIC.len() + 1..];
 
         let compressed = if flags & FLAG_ENCRYPTED != 0 {
-            let key = self.encryption_key.ok_or(BackupError::MissingKey)?;
+            let key = encryption_key.ok_or(BackupError::MissingKey)?;
             if body.len() < 12 {
                 return Err(BackupError::Invalid("truncated encrypted backup".into()));
             }

From c2801220fff6a1a52717b429f3f84f868a9491a4 Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Thu, 2 Jul 2026 19:42:23 +0530
Subject: [PATCH 35/44] docs: update agent instructions for streaming uploads
 and search

- Add UPLOAD_TOKEN_EXPIRY_SECS env var documentation
- Update search indexer docs: purely event-driven model, no cross-process
  polling, durability-only queue semantics
---
 AGENTS.md |  1 +
 CLAUDE.md | 17 ++++++++++-------
 2 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index ca10f176..2b70d98f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -211,6 +211,7 @@ Logging keys map to the `[log]` table: `RUST_LOG`→`log.level`, `LOG_OUTPUT`→
 | `BACKUP_S3_SECRET_ACCESS_KEY` | - | S3 backup secret key (secret, env-only) |
 | `BACKUP_ENCRYPTION_KEY` | auto | AES-256 backup key (hex); auto-generated to `secrets.toml` |
 | `MAX_UPLOAD_SIZE_MB` | `50` | Max upload size in MB |
+| `UPLOAD_TOKEN_EXPIRY_SECS` | `900` | Signed upload URL lifetime (seconds) |
 | `COOKIE_SECURE` | `false` | Require HTTPS cookies |
 | `DB_MAX_CONNECTIONS` | `10` | Max DB connections |
 | `DB_MIN_CONNECTIONS` | `2` | Min DB connections |
diff --git a/CLAUDE.md b/CLAUDE.md
index a8fb3a63..5e942c60 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -206,6 +206,7 @@ Logging keys map to the `[log]` table: `RUST_LOG`→`log.level`, `LOG_OUTPUT`→
 | `SEARCH_ENABLED` | `true` | Build/use the Tantivy full-text index for entry search (else SQL `LIKE`) |
 | `SEARCH_INDEX_PATH` | `<cache dir>/search` | Directory for the Tantivy search index |
 | `MAX_UPLOAD_SIZE_MB` | `50` | Max upload size in MB |
+| `UPLOAD_TOKEN_EXPIRY_SECS` | `900` | Signed upload URL lifetime (seconds) |
 | `COOKIE_SECURE` | `false` | Require HTTPS cookies |
 | `DB_MAX_CONNECTIONS` | `10` | Max DB connections |
 | `DB_MIN_CONNECTIONS` | `2` | Min DB connections |
@@ -332,12 +333,15 @@ is **derived** and fully rebuildable.
   the DB by reusing `EntryRepository::list` (covers singletons too). Write/commit on
   a read-only instance returns `SearchError::ReadOnly`.
 - `queue.rs` — `SearchQueue` over the `search_index_queue` table (migration
-  `20260618000000`). Content writes from *any* process enqueue here
+  `20260618000000`). Content writes enqueue here
   (`enqueue`/`dequeue_batch`/`delete_ids`); UUIDv7 ids order the queue chronologically.
+  The table exists purely for **durability** (crash recovery), not cross-process
+  signaling — all producers run in the server process (`vcms mcp stdio` is an HTTP proxy).
 - `indexer.rs` — the **single consumer**, spawned once by the server (it owns the
   writer). Drains the queue in batches (present in DB ⇒ upsert doc, absent ⇒ delete
-  doc — `op` is advisory), commits per batch, deletes processed rows. Wakes instantly
-  on a local enqueue (`Notify`) and polls every 2s to catch other processes' enqueues.
+  doc — `op` is advisory), commits per batch, deletes processed rows. **Purely
+  event-driven**: one startup drain (rows left by a crash), then sleeps until an
+  enqueue rings the in-process `Notify` — no polling.
 
 Wiring: `Services` holds `search: Option<Arc<SearchService>>` (reads) and
 `search_queue: Option<Arc<SearchQueue>>` (writes). `Services::new` opens the index
@@ -352,10 +356,9 @@ index builds on startup when empty, rebuilds after a restore, and exposes
 owner/operator reindex routes: `POST /api/dashboard/instance/search/reindex` and
 `POST /api/dashboard/sites/{site_id}/search/reindex`.
 
-This is the cross-process model: writes from any process land in the durable queue
-and the running server indexes them; if the server is down they drain on its next
-start. The remaining hard limit is *concurrent writers* — only one
-process indexes at a time.
+Writes land in the durable queue and the running server indexes them; rows enqueued
+before a crash drain on the next start. The remaining hard limit is *concurrent
+writers* — only one process indexes at a time.
 
 ### No typo tolerance (deliberate) — and how to add it
 

From f40e42e8e7d6e660fe09fd9e75ce0e55503644ab Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Thu, 2 Jul 2026 19:42:30 +0530
Subject: [PATCH 36/44] test: add integration tests for streaming uploads,
 sniffing, and signed URLs

REST tests:
- Signed URL happy path, expired token, tampered signature, single-use
  enforcement, magic byte mismatch, content-type header mismatch,
  oversize rejection, multipart magic byte mismatch

gRPC tests:
- body_for_mime() helper sends correct magic bytes per declared type

MCP tests:
- End-to-end create_upload_url then PUT (single-use, file visibility)
- Read-only token rejected for upload URL creation
- Disallowed content type rejected at mint time
---
 apps/backend/tests/grpc/files_tests.rs |  18 ++-
 apps/backend/tests/mcp/file_tests.rs   |  81 ++++++++++++
 apps/backend/tests/rest/files_tests.rs | 174 +++++++++++++++++++++++++
 3 files changed, 272 insertions(+), 1 deletion(-)

diff --git a/apps/backend/tests/grpc/files_tests.rs b/apps/backend/tests/grpc/files_tests.rs
index 01b3967b..e6bd89fb 100644
--- a/apps/backend/tests/grpc/files_tests.rs
+++ b/apps/backend/tests/grpc/files_tests.rs
@@ -19,10 +19,26 @@ async fn seed_file(ctx: &GrpcTestContext, site_id: &str, name: &str) -> String {
     body["id"].as_str().unwrap().to_string()
 }
 
+/// Minimal bytes carrying the right magic signature — uploads are now sniffed
+/// against the declared mime type, so plain text can't pose as png/jpeg/pdf.
+fn body_for_mime(mime_type: &str) -> Vec<u8> {
+    match mime_type {
+        "image/png" => vec![0x89, b'P', b'N', b'G', 0x0D, 0x0A, 0x1A, 0x0A, 0, 0, 0, 0],
+        "image/jpeg" => vec![0xFF, 0xD8, 0xFF, 0xE0, 0, 0, 0, 0],
+        "application/pdf" => b"%PDF-1.4 test".to_vec(),
+        _ => b"test content".to_vec(),
+    }
+}
+
 async fn seed_file_with_mime(ctx: &GrpcTestContext, site_id: &str, name: &str, mime_type: &str) -> String {
     let ext = mime_type.split('/').next_back().unwrap_or("bin");
     let body = ctx
-        .upload_file(site_id, &format!("{}.{}", name, ext), b"test content", mime_type)
+        .upload_file(
+            site_id,
+            &format!("{}.{}", name, ext),
+            &body_for_mime(mime_type),
+            mime_type,
+        )
         .await;
     body["id"].as_str().unwrap().to_string()
 }
diff --git a/apps/backend/tests/mcp/file_tests.rs b/apps/backend/tests/mcp/file_tests.rs
index 7d01e77b..c1d976d0 100644
--- a/apps/backend/tests/mcp/file_tests.rs
+++ b/apps/backend/tests/mcp/file_tests.rs
@@ -53,6 +53,87 @@ async fn test_create_upload_url() {
     assert_eq!(data["content_type"].as_str().unwrap(), "text/plain");
 }
 
+/// End-to-end: mint an upload URL via MCP, PUT the bytes to it, and verify the
+/// file exists (both via the MCP get_file tool and the returned record).
+#[tokio::test]
+async fn test_create_upload_url_then_put_uploads_file() {
+    let server = start_mcp_server().await;
+    let (_, token) = setup_site_token(&server).await;
+
+    let result = mcp_call_tool(
+        &server.base_url,
+        &token,
+        "create_upload_url",
+        serde_json::json!({
+            "filename": "e2e.txt",
+            "content_type": "text/plain",
+        }),
+    )
+    .await;
+    let data = mcp_tool_json(&result);
+    let upload_url = data["upload_url"].as_str().unwrap();
+    let file_id = data["file_id"].as_str().unwrap();
+
+    // The URL derives its host from the request's Host header, so it points at
+    // this test server and is directly PUT-able.
+    let client = reqwest::Client::new();
+    let resp = client
+        .put(upload_url)
+        .header(reqwest::header::CONTENT_TYPE, "text/plain")
+        .body("mcp e2e upload")
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), 201, "{}", resp.text().await.unwrap_or_default());
+    let created: serde_json::Value = resp.json().await.unwrap();
+    assert_eq!(created["id"].as_str().unwrap(), file_id);
+
+    // Reuse must be rejected (single-use).
+    let again = client.put(upload_url).body("again").send().await.unwrap();
+    assert_eq!(again.status(), 409);
+
+    // The file is visible through MCP.
+    let got = mcp_call_tool(
+        &server.base_url,
+        &token,
+        "get_file",
+        serde_json::json!({"file_id": file_id}),
+    )
+    .await;
+    let got_data = mcp_tool_json(&got);
+    assert_eq!(got_data["original_name"].as_str().unwrap(), "e2e.txt");
+}
+
+#[tokio::test]
+async fn test_create_upload_url_requires_editor() {
+    let server = start_mcp_server().await;
+    let (_, token) = setup_site_read_token(&server).await;
+
+    let result = mcp_call_tool(
+        &server.base_url,
+        &token,
+        "create_upload_url",
+        serde_json::json!({"filename": "x.txt", "content_type": "text/plain"}),
+    )
+    .await;
+    assert!(mcp_is_error(&result), "read-only token must not mint upload URLs");
+}
+
+#[tokio::test]
+async fn test_create_upload_url_rejects_disallowed_content_type() {
+    let server = start_mcp_server().await;
+    let (_, token) = setup_site_token(&server).await;
+
+    let result = mcp_call_tool(
+        &server.base_url,
+        &token,
+        "create_upload_url",
+        serde_json::json!({"filename": "x.exe", "content_type": "application/x-executable"}),
+    )
+    .await;
+    assert!(mcp_is_error(&result), "disallowed content type must fail at mint time");
+}
+
 #[tokio::test]
 async fn test_list_files_with_pagination() {
     let server = start_mcp_server().await;
diff --git a/apps/backend/tests/rest/files_tests.rs b/apps/backend/tests/rest/files_tests.rs
index 043376a9..b921a904 100644
--- a/apps/backend/tests/rest/files_tests.rs
+++ b/apps/backend/tests/rest/files_tests.rs
@@ -342,3 +342,177 @@ async fn test_upload_file_invalid_mime_type() {
         error
     );
 }
+
+// ── Signed-URL uploads ──────────────────────────────────────────────────────
+//
+// Tokens are minted directly with the lib (same HMAC secret as TestServer), so
+// these tests cover the PUT endpoint without an MCP round-trip.
+
+const TEST_HMAC_SECRET: &str = "test-hmac-secret-integration";
+
+fn mint_upload_url(server: &TestServer, site_id: &str, filename: &str, mime: &str, expiry_secs: i64) -> String {
+    let (_, encoded) = cms::signed_upload::SignedUploadToken::generate_with_storage_provider(
+        site_id,
+        filename,
+        mime,
+        "filesystem",
+        TEST_HMAC_SECRET,
+        expiry_secs,
+    );
+    format!("{}/api/v1/files/upload/{}", server.base_url, encoded)
+}
+
+#[tokio::test]
+async fn test_signed_upload_happy_path() {
+    let server = TestServer::start().await;
+    let (_token, _csrf, site_id) = setup(&server).await;
+    let client = reqwest::Client::builder().build().unwrap();
+
+    let url = mint_upload_url(&server, &site_id, "signed.txt", "text/plain", 900);
+    let resp = client
+        .put(&url)
+        .header(reqwest::header::CONTENT_TYPE, "text/plain")
+        .body("signed upload body")
+        .send()
+        .await
+        .unwrap();
+
+    assert_eq!(resp.status(), 201, "{}", resp.text().await.unwrap_or_default());
+    let body: Value = resp.json().await.unwrap();
+    let file_id = body["id"].as_str().unwrap();
+    assert_eq!(body["original_name"], "signed.txt");
+    assert_eq!(body["mime_type"], "text/plain");
+    assert_eq!(body["size"], 18);
+
+    // The stored bytes are servable through the public file route.
+    let served = client
+        .get(format!("{}/api/files/{}", server.base_url, file_id))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(served.status(), 200);
+    assert_eq!(served.text().await.unwrap(), "signed upload body");
+}
+
+#[tokio::test]
+async fn test_signed_upload_expired_token() {
+    let server = TestServer::start().await;
+    let (_token, _csrf, site_id) = setup(&server).await;
+    let client = reqwest::Client::builder().build().unwrap();
+
+    let url = mint_upload_url(&server, &site_id, "late.txt", "text/plain", -10);
+    let resp = client.put(&url).body("too late").send().await.unwrap();
+    assert_eq!(resp.status(), 410);
+}
+
+#[tokio::test]
+async fn test_signed_upload_tampered_signature() {
+    let server = TestServer::start().await;
+    let (_token, _csrf, site_id) = setup(&server).await;
+    let client = reqwest::Client::builder().build().unwrap();
+
+    // Minted with a different secret => signature check must fail.
+    let (_, encoded) = cms::signed_upload::SignedUploadToken::generate_with_storage_provider(
+        &site_id,
+        "evil.txt",
+        "text/plain",
+        "filesystem",
+        "not-the-server-secret",
+        900,
+    );
+    let url = format!("{}/api/v1/files/upload/{}", server.base_url, encoded);
+    let resp = client.put(&url).body("nope").send().await.unwrap();
+    assert_eq!(resp.status(), 401);
+}
+
+#[tokio::test]
+async fn test_signed_upload_single_use() {
+    let server = TestServer::start().await;
+    let (_token, _csrf, site_id) = setup(&server).await;
+    let client = reqwest::Client::builder().build().unwrap();
+
+    let url = mint_upload_url(&server, &site_id, "once.txt", "text/plain", 900);
+    let first = client.put(&url).body("first").send().await.unwrap();
+    assert_eq!(first.status(), 201);
+
+    let second = client.put(&url).body("second").send().await.unwrap();
+    assert_eq!(second.status(), 409, "reused upload URL must be rejected");
+}
+
+#[tokio::test]
+async fn test_signed_upload_magic_byte_mismatch() {
+    let server = TestServer::start().await;
+    let (_token, _csrf, site_id) = setup(&server).await;
+    let client = reqwest::Client::builder().build().unwrap();
+
+    // Token says PNG; body is plain text => sniffed mismatch => 400.
+    let url = mint_upload_url(&server, &site_id, "fake.png", "image/png", 900);
+    let resp = client
+        .put(&url)
+        .header(reqwest::header::CONTENT_TYPE, "image/png")
+        .body("definitely not a png")
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), 400);
+}
+
+#[tokio::test]
+async fn test_signed_upload_content_type_header_mismatch() {
+    let server = TestServer::start().await;
+    let (_token, _csrf, site_id) = setup(&server).await;
+    let client = reqwest::Client::builder().build().unwrap();
+
+    let url = mint_upload_url(&server, &site_id, "a.txt", "text/plain", 900);
+    let resp = client
+        .put(&url)
+        .header(reqwest::header::CONTENT_TYPE, "application/pdf")
+        .body("hello")
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), 400);
+}
+
+#[tokio::test]
+async fn test_signed_upload_oversize_rejected() {
+    let server = TestServer::start().await;
+    let (_token, _csrf, site_id) = setup(&server).await;
+    let client = reqwest::Client::builder().build().unwrap();
+
+    let url = mint_upload_url(&server, &site_id, "big.txt", "text/plain", 900);
+    // 52MB > the 50MB cap; the Content-Length fast path rejects upfront.
+    let body = vec![b'a'; 52 * 1024 * 1024];
+    let result = client.put(&url).body(body).send().await;
+    match result {
+        Ok(resp) => assert_eq!(resp.status(), 413, "{}", resp.text().await.unwrap_or_default()),
+        Err(e) => assert!(
+            !e.is_connect() && !e.is_timeout() && !e.is_builder(),
+            "unexpected transport error: {e}"
+        ),
+    }
+}
+
+/// Multipart path enforces the same sniffing as the signed path.
+#[tokio::test]
+async fn test_multipart_upload_magic_byte_mismatch() {
+    let server = TestServer::start().await;
+    let (token, csrf, site_id) = setup(&server).await;
+    let api_key = get_api_key(&server, &token, &csrf, &site_id).await;
+    let client = reqwest::Client::builder().build().unwrap();
+
+    let part = reqwest::multipart::Part::bytes(b"just some text".to_vec())
+        .file_name("fake.png")
+        .mime_str("image/png")
+        .unwrap();
+    let form = reqwest::multipart::Form::new().part("file", part);
+
+    let resp = client
+        .post(format!("{}/files", server.base_url))
+        .headers(api_key_header(&api_key))
+        .multipart(form)
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), 400);
+}

From 59b68e0eb52ebde111e37ed5f344960af0aefdd2 Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Fri, 3 Jul 2026 12:19:28 +0530
Subject: [PATCH 37/44] refactor: simplify sudo user validation logic in
 resolve_run_user function

---
 apps/backend/src/service/mod.rs | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/apps/backend/src/service/mod.rs b/apps/backend/src/service/mod.rs
index 40c12241..6e6de445 100644
--- a/apps/backend/src/service/mod.rs
+++ b/apps/backend/src/service/mod.rs
@@ -229,11 +229,12 @@ pub(crate) fn resolve_run_user(explicit: Option<&str>) -> Result<String, Box<dyn
         }
         return Ok(user.to_string());
     }
-    if let Ok(sudo_user) = std::env::var("SUDO_USER") {
-        if !sudo_user.is_empty() && sudo_user != "root" {
-            validate_username(&sudo_user)?;
-            return Ok(sudo_user);
-        }
+    if let Ok(sudo_user) = std::env::var("SUDO_USER")
+        && !sudo_user.is_empty()
+        && sudo_user != "root"
+    {
+        validate_username(&sudo_user)?;
+        return Ok(sudo_user);
     }
     let current = std::env::var("USER").unwrap_or_default();
     if current.is_empty() || current == "root" {

From 044c2370ff17b4b0cd947c5c6419d2024c7c4c3f Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Fri, 3 Jul 2026 16:46:05 +0530
Subject: [PATCH 38/44] docs: clarify VCMS_HOME resolution order in README

---
 README.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 5bcb0c8e..28f87a3f 100644
--- a/README.md
+++ b/README.md
@@ -125,8 +125,10 @@ By default, runtime files go to the platform-conventional per-type directories
 | `search/` (rebuildable index) | `~/.cache/vcms` | `~/Library/Caches/vcms` | `%LOCALAPPDATA%\vcms\cache` |
 | `logs/` | `~/.local/state/vcms` | `~/Library/Application Support/vcms` | `%LOCALAPPDATA%\vcms\data` |
 
-Set **`$VCMS_HOME`** to keep everything under a single root instead (and an existing
-`~/.vcms` is honored automatically, so upgrades don't move your data).
+Set **`$VCMS_HOME`** to keep everything under a single root instead. When several
+locations exist, the first match wins: **`$VCMS_HOME`** → the service's system
+directory (below) → a legacy `~/.vcms` (honored automatically, so upgrades don't
+move your data) → the split per-type defaults above.
 
 The `vcms service` installer stores the daemon's data under one system dir —
 `/var/lib/vcms` (Linux), `/Library/Application Support/vcms` (macOS), or

From db11d7daa8a1c8a189a6611be2dc2e88ff91420f Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Fri, 3 Jul 2026 16:46:11 +0530
Subject: [PATCH 39/44] docs(cli): clarify Windows service --user flag behavior

---
 apps/backend/src/cli.rs | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/apps/backend/src/cli.rs b/apps/backend/src/cli.rs
index ce41b2ba..63a5c2e0 100644
--- a/apps/backend/src/cli.rs
+++ b/apps/backend/src/cli.rs
@@ -130,7 +130,8 @@ pub enum ServiceAction {
         /// OS account the service runs as.
         ///
         /// Defaults to the real invoking user (`$SUDO_USER` when run via sudo). The
-        /// service never runs as root. Ignored on Windows (runs as LocalSystem).
+        /// service never runs as root. On Windows the service always runs as
+        /// LocalSystem; custom accounts are unsupported and passing `--user` fails.
         #[arg(long, value_name = "NAME")]
         user: Option<String>,
     },

From 3c0642048cedd88d83628185912a79ad6e80eed5 Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Fri, 3 Jul 2026 16:46:16 +0530
Subject: [PATCH 40/44] fix(config): validate upload_token_expiry_secs is
 positive and use constant

---
 apps/backend/src/config.rs | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/apps/backend/src/config.rs b/apps/backend/src/config.rs
index 3049728f..b5865f0c 100644
--- a/apps/backend/src/config.rs
+++ b/apps/backend/src/config.rs
@@ -370,6 +370,15 @@ impl RawConfig {
 
         let log = self.log.unwrap_or_default();
 
+        let upload_token_expiry_secs = self
+            .upload_token_expiry_secs
+            .unwrap_or(crate::signed_upload::DEFAULT_UPLOAD_TOKEN_EXPIRY_SECS);
+        if upload_token_expiry_secs <= 0 {
+            return Err(Box::new(figment::Error::from(format!(
+                "upload_token_expiry_secs must be positive (got {upload_token_expiry_secs})"
+            ))));
+        }
+
         Ok(Config {
             database_url: self.database_url.unwrap_or_else(paths::default_database_url),
             hmac_secret,
@@ -395,7 +404,7 @@ impl RawConfig {
             backup_s3_public_url: self.backup_s3_public_url,
             backup_encryption_key: self.backup_encryption_key,
             max_upload_size_bytes: self.max_upload_size_mb.unwrap_or(50) * 1024 * 1024,
-            upload_token_expiry_secs: self.upload_token_expiry_secs.unwrap_or(900),
+            upload_token_expiry_secs,
             cookie_secure: self.cookie_secure.unwrap_or(false),
             session_lifetime_hours: self.session_lifetime_hours.unwrap_or(24),
             public_registration_enabled: self.public_registration_enabled.unwrap_or(false),
@@ -481,7 +490,7 @@ pub fn default_config_toml() -> String {
          # --- Uploads ---\n\
          max_upload_size_mb = 50\n\
          # Signed upload URL lifetime (seconds)\n\
-         upload_token_expiry_secs = 900\n\n\
+         upload_token_expiry_secs = {default_upload_expiry}\n\n\
          # --- Security / sessions ---\n\
          cookie_secure = false\n\
          session_lifetime_hours = 24\n\
@@ -534,6 +543,7 @@ pub fn default_config_toml() -> String {
          format = \"pretty\"   # pretty | json\n\
          annotations = false  # include file + line numbers\n\
          dir = \"logs\"        # used when output = \"file\"\n",
+        default_upload_expiry = crate::signed_upload::DEFAULT_UPLOAD_TOKEN_EXPIRY_SECS,
     )
 }
 

From 4e14df8e83b30526de5b030090558a221e172461 Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Fri, 3 Jul 2026 16:46:22 +0530
Subject: [PATCH 41/44] fix(mysql): pin session timezone to UTC via
 after_connect

---
 apps/backend/src/database/pool.rs | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/apps/backend/src/database/pool.rs b/apps/backend/src/database/pool.rs
index 04c59e27..997d0db0 100644
--- a/apps/backend/src/database/pool.rs
+++ b/apps/backend/src/database/pool.rs
@@ -49,6 +49,14 @@ impl DbPool {
                     .min_connections(config.db_min_connections)
                     .acquire_timeout(Duration::from_secs(config.db_acquire_timeout_secs))
                     .idle_timeout(Duration::from_secs(config.db_idle_timeout_secs))
+                    // Pin the session to UTC so NOW()/CURRENT_TIMESTAMP agree with the
+                    // chrono::Utc timestamps the app writes and compares against.
+                    .after_connect(|conn, _meta| {
+                        Box::pin(async move {
+                            sqlx::query("SET time_zone = '+00:00'").execute(&mut *conn).await?;
+                            Ok(())
+                        })
+                    })
                     .connect(&config.database_url)
                     .await?;
                 Ok(DbPool::MySql(pool))

From d7ee538e8cb7b62948942c01791a751bd71b3aba Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Fri, 3 Jul 2026 16:46:28 +0530
Subject: [PATCH 42/44] test(dashboard): add unit tests for cache-control
 headers and ETag 304

---
 .../backend/src/handlers/dashboard_handler.rs | 35 +++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/apps/backend/src/handlers/dashboard_handler.rs b/apps/backend/src/handlers/dashboard_handler.rs
index 13cf99a8..a4014468 100644
--- a/apps/backend/src/handlers/dashboard_handler.rs
+++ b/apps/backend/src/handlers/dashboard_handler.rs
@@ -79,6 +79,41 @@ pub async fn dashboard_handler(Path(path): Path<String>, headers: HeaderMap) ->
     }
 }
 
+#[cfg(all(test, feature = "embed-dashboard"))]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn cache_control_hashed_assets_are_immutable() {
+        assert_eq!(
+            cache_control_for("assets/index-abc123.js"),
+            "public, max-age=31536000, immutable"
+        );
+    }
+
+    #[test]
+    fn cache_control_index_html_revalidates() {
+        assert_eq!(cache_control_for("index.html"), "no-cache");
+    }
+
+    #[test]
+    fn cache_control_other_files_get_short_ttl() {
+        assert_eq!(cache_control_for("favicon.ico"), "public, max-age=3600");
+    }
+
+    #[test]
+    fn serve_embedded_returns_304_on_matching_etag() {
+        let Some(content) = Assets::get("index.html") else {
+            return; // no dashboard build embedded in this test run
+        };
+        let etag = format!("\"{}\"", hex::encode(content.metadata.sha256_hash()));
+        let mut headers = HeaderMap::new();
+        headers.insert(header::IF_NONE_MATCH, etag.parse().unwrap());
+        let response = serve_embedded("index.html", content, &headers);
+        assert_eq!(response.status(), StatusCode::NOT_MODIFIED);
+    }
+}
+
 #[cfg(not(feature = "embed-dashboard"))]
 pub async fn dashboard_handler(Path(_path): Path<String>, _headers: axum::http::HeaderMap) -> Response {
     (

From ea6c3424122f7d9eb455a01c26e282a9f93f9669 Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Fri, 3 Jul 2026 16:46:34 +0530
Subject: [PATCH 43/44] fix(server): await both servers on graceful shutdown
 and handle admin seed errors

---
 apps/backend/src/server.rs | 50 ++++++++++++++++++++++++--------------
 1 file changed, 32 insertions(+), 18 deletions(-)

diff --git a/apps/backend/src/server.rs b/apps/backend/src/server.rs
index 7522ed3c..b47aea02 100644
--- a/apps/backend/src/server.rs
+++ b/apps/backend/src/server.rs
@@ -155,7 +155,7 @@ pub async fn run(
     });
 
     let rest_rx = shutdown_rx.clone();
-    let rest_handle = tokio::spawn(async move {
+    let mut rest_handle = tokio::spawn(async move {
         axum::serve(
             rest_listener,
             app.into_make_service_with_connect_info::<std::net::SocketAddr>(),
@@ -168,7 +168,7 @@ pub async fn run(
         })
     });
 
-    let grpc_handle = tokio::spawn(spawn_grpc_server(
+    let mut grpc_handle = tokio::spawn(spawn_grpc_server(
         services.clone(),
         repository_arc.clone(),
         config_arc.clone(),
@@ -177,25 +177,32 @@ pub async fn run(
         Box::pin(wait_for_shutdown(shutdown_rx)),
     ));
 
-    tokio::select! {
-        result = rest_handle => {
+    // Whichever server finishes first flips the shutdown signal; the sibling is
+    // then awaited so both are fully drained before `run()` returns.
+    let (rest_result, grpc_result) = tokio::select! {
+        result = &mut rest_handle => {
             let _ = shutdown_tx2.send(true);
-            match result {
-                Ok(Ok(())) => {}
-                Ok(Err(e)) => return Err(e.into()),
-                Err(e) => return Err(e.into()),
-            }
+            let grpc_result = grpc_handle.await;
+            (result, grpc_result)
         }
-        result = grpc_handle => {
+        result = &mut grpc_handle => {
             let _ = shutdown_tx2.send(true);
-            match result {
-                Ok(Ok(())) => {}
-                // gRPC's error is `Box<dyn Error + Send + Sync>`; format it so the
-                // conversion to this fn's `Box<dyn Error>` is unambiguous.
-                Ok(Err(e)) => return Err(format!("gRPC server error: {e}").into()),
-                Err(e) => return Err(format!("gRPC server task panicked: {e}").into()),
-            }
+            let rest_result = rest_handle.await;
+            (rest_result, result)
         }
+    };
+
+    match rest_result {
+        Ok(Ok(())) => {}
+        Ok(Err(e)) => return Err(e.into()),
+        Err(e) => return Err(e.into()),
+    }
+    match grpc_result {
+        Ok(Ok(())) => {}
+        // gRPC's error is `Box<dyn Error + Send + Sync>`; format it so the
+        // conversion to this fn's `Box<dyn Error>` is unambiguous.
+        Ok(Err(e)) => return Err(format!("gRPC server error: {e}").into()),
+        Err(e) => return Err(format!("gRPC server task panicked: {e}").into()),
     }
 
     Ok(())
@@ -280,7 +287,14 @@ pub fn initialize_storage(config: &Config) -> Arc<StorageRegistry> {
 
 async fn seed_admin(repository: &Repository) {
     debug!("Checking if admin user needs to be seeded");
-    if !repository.user.exists(ADMIN_EMAIL).await.unwrap_or(false) {
+    let exists = match repository.user.exists(ADMIN_EMAIL).await {
+        Ok(exists) => exists,
+        Err(e) => {
+            tracing::error!("Failed to check for existing admin user; skipping seed: {e}");
+            return;
+        }
+    };
+    if !exists {
         info!("Seeding default admin user");
         let id = uuid::Uuid::now_v7().to_string();
         let password_hash = bcrypt::hash("admin", bcrypt::DEFAULT_COST).expect("Failed to hash password");

From 3138ca7a31b794e44bbd1d87624b4685f44ad543 Mon Sep 17 00:00:00 2001
From: Krishna Santosh <75202541+krishna-santosh@users.noreply.github.com>
Date: Fri, 3 Jul 2026 16:46:39 +0530
Subject: [PATCH 44/44] fix(search): add retry with exponential backoff to
 indexer drain

---
 apps/backend/src/services/search/indexer.rs | 29 +++++++++++++++++----
 1 file changed, 24 insertions(+), 5 deletions(-)

diff --git a/apps/backend/src/services/search/indexer.rs b/apps/backend/src/services/search/indexer.rs
index 3d169813..2064ab3e 100644
--- a/apps/backend/src/services/search/indexer.rs
+++ b/apps/backend/src/services/search/indexer.rs
@@ -18,6 +18,9 @@ use crate::repository::Repository;
 /// Max rows processed per drain iteration.
 const BATCH_SIZE: i64 = 256;
 
+/// Retries after a failed drain before giving up until the next enqueue.
+const MAX_DRAIN_RETRIES: u32 = 5;
+
 /// Run the indexer loop forever. Owns the writer-side `SearchService`.
 pub async fn run(search: Arc<SearchService>, queue: Arc<SearchQueue>, repository: Arc<Repository>) {
     let notify = queue.notify_handle();
@@ -25,14 +28,30 @@ pub async fn run(search: Arc<SearchService>, queue: Arc<SearchQueue>, repository
     // Startup drain: pick up rows committed before a crash/restart. `Notify`
     // stores a permit, so an enqueue racing this drain is never lost — it just
     // wakes the loop below for an empty (cheap) drain in the worst case.
-    if let Err(e) = drain(&search, &queue, &repository).await {
-        tracing::error!("Search indexer startup drain failed: {}", e);
-    }
+    drain_with_retry(&search, &queue, &repository).await;
 
     loop {
         notify.notified().await;
-        if let Err(e) = drain(&search, &queue, &repository).await {
-            tracing::error!("Search indexer drain failed: {}", e);
+        drain_with_retry(&search, &queue, &repository).await;
+    }
+}
+
+/// Drain, retrying transient failures with exponential backoff so queued rows
+/// don't sit stuck until the next enqueue. After [`MAX_DRAIN_RETRIES`] the rows
+/// stay in the durable queue for the next notification or restart.
+async fn drain_with_retry(search: &SearchService, queue: &SearchQueue, repository: &Repository) {
+    let mut delay = std::time::Duration::from_millis(500);
+    for attempt in 0..=MAX_DRAIN_RETRIES {
+        match drain(search, queue, repository).await {
+            Ok(()) => return,
+            Err(e) if attempt == MAX_DRAIN_RETRIES => {
+                tracing::error!("Search indexer drain failed after {MAX_DRAIN_RETRIES} retries: {e}");
+            }
+            Err(e) => {
+                tracing::warn!("Search indexer drain failed (attempt {}): {e}; retrying", attempt + 1);
+                tokio::time::sleep(delay).await;
+                delay = (delay * 2).min(std::time::Duration::from_secs(10));
+            }
         }
     }
 }