Harden local runtime safety and error handling

internal/appstate/backup.go

@@ -10,6 +10,10 @@ import (
 	"sort"
 	"strings"
 	"time"
+
+	"github.com/glebarez/sqlite"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
 )
 
 type backupPeriod struct {
@@ -250,6 +254,12 @@ func pruneOldBackups(periodDir string, keep int) error {
 }
 
 func createBackupArchive(destPath, dbPath, configPath string) error {
+	snapshotPath, cleanup, err := createSQLiteSnapshot(dbPath)
+	if err != nil {
+		return err
+	}
+	defer cleanup()
+
 	file, err := os.Create(destPath)
 	if err != nil {
 		return err
@@ -257,12 +267,10 @@ func createBackupArchive(destPath, dbPath, configPath string) error {
 	defer file.Close()
 
 	zipWriter := zip.NewWriter(file)
-	if err := addZipFile(zipWriter, dbPath); err != nil {
+	if err := addZipFileAs(zipWriter, snapshotPath, filepath.Base(dbPath)); err != nil {
 		_ = zipWriter.Close()
 		return err
 	}
-	_ = addZipOptionalFile(zipWriter, dbPath+"-wal")
-	_ = addZipOptionalFile(zipWriter, dbPath+"-shm")
 
 	if strings.TrimSpace(configPath) != "" {
 		_ = addZipOptionalFile(zipWriter, configPath)
@@ -274,6 +282,77 @@ func createBackupArchive(destPath, dbPath, configPath string) error {
 	return file.Sync()
 }
 
+func createSQLiteSnapshot(dbPath string) (string, func(), error) {
+	tempFile, err := os.CreateTemp("", "qfs-backup-*.db")
+	if err != nil {
+		return "", func() {}, err
+	}
+	tempPath := tempFile.Name()
+	if err := tempFile.Close(); err != nil {
+		_ = os.Remove(tempPath)
+		return "", func() {}, err
+	}
+	if err := os.Remove(tempPath); err != nil && !os.IsNotExist(err) {
+		return "", func() {}, err
+	}
+
+	cleanup := func() {
+		_ = os.Remove(tempPath)
+	}
+
+	db, err := gorm.Open(sqlite.Open(dbPath), &gorm.Config{
+		Logger: logger.Default.LogMode(logger.Silent),
+	})
+	if err != nil {
+		cleanup()
+		return "", func() {}, err
+	}
+
+	sqlDB, err := db.DB()
+	if err != nil {
+		cleanup()
+		return "", func() {}, err
+	}
+	defer sqlDB.Close()
+
+	if err := db.Exec("PRAGMA busy_timeout = 5000").Error; err != nil {
+		cleanup()
+		return "", func() {}, fmt.Errorf("configure sqlite busy_timeout: %w", err)
+	}
+
+	literalPath := strings.ReplaceAll(tempPath, "'", "''")
+	if err := vacuumIntoWithRetry(db, literalPath); err != nil {
+		cleanup()
+		return "", func() {}, err
+	}
+
+	return tempPath, cleanup, nil
+}
+
+func vacuumIntoWithRetry(db *gorm.DB, literalPath string) error {
+	var lastErr error
+	for attempt := 0; attempt < 3; attempt++ {
+		if err := db.Exec("VACUUM INTO '" + literalPath + "'").Error; err != nil {
+			lastErr = err
+			if !isSQLiteBusyError(err) {
+				return fmt.Errorf("create sqlite snapshot: %w", err)
+			}
+			time.Sleep(time.Duration(attempt+1) * 250 * time.Millisecond)
+			continue
+		}
+		return nil
+	}
+	return fmt.Errorf("create sqlite snapshot after retries: %w", lastErr)
+}
+
+func isSQLiteBusyError(err error) bool {
+	if err == nil {
+		return false
+	}
+	lower := strings.ToLower(err.Error())
+	return strings.Contains(lower, "database is locked") || strings.Contains(lower, "database is busy")
+}
+
 func addZipOptionalFile(writer *zip.Writer, path string) error {
 	if _, err := os.Stat(path); err != nil {
 		return nil
@@ -282,6 +361,10 @@ func addZipOptionalFile(writer *zip.Writer, path string) error {
 }
 
 func addZipFile(writer *zip.Writer, path string) error {
+	return addZipFileAs(writer, path, filepath.Base(path))
+}
+
+func addZipFileAs(writer *zip.Writer, path string, archiveName string) error {
 	in, err := os.Open(path)
 	if err != nil {
 		return err
@@ -297,7 +380,7 @@ func addZipFile(writer *zip.Writer, path string) error {
 	if err != nil {
 		return err
 	}
-	header.Name = filepath.Base(path)
+	header.Name = archiveName
 	header.Method = zip.Deflate
 
 	out, err := writer.CreateHeader(header)

internal/appstate/backup_test.go

@@ -1,11 +1,15 @@
 package appstate
 
 import (
+	"archive/zip"
 	"os"
 	"path/filepath"
 	"strings"
 	"testing"
 	"time"
+
+	"github.com/glebarez/sqlite"
+	"gorm.io/gorm"
 )
 
 func TestEnsureRotatingLocalBackupCreatesAndRotates(t *testing.T) {
@@ -13,8 +17,8 @@ func TestEnsureRotatingLocalBackupCreatesAndRotates(t *testing.T) {
 	dbPath := filepath.Join(temp, "qfs.db")
 	cfgPath := filepath.Join(temp, "config.yaml")
 
-	if err := os.WriteFile(dbPath, []byte("db"), 0644); err != nil {
-		t.Fatalf("write db: %v", err)
+	if err := writeTestSQLiteDB(dbPath); err != nil {
+		t.Fatalf("write sqlite db: %v", err)
 	}
 	if err := os.WriteFile(cfgPath, []byte("cfg"), 0644); err != nil {
 		t.Fatalf("write config: %v", err)
@@ -36,6 +40,7 @@ func TestEnsureRotatingLocalBackupCreatesAndRotates(t *testing.T) {
 	if _, err := os.Stat(dailyArchive); err != nil {
 		t.Fatalf("daily archive missing: %v", err)
 	}
+	assertZipContains(t, dailyArchive, "qfs.db", "config.yaml")
 
 	backupNow = func() time.Time { return time.Date(2026, 2, 12, 10, 0, 0, 0, time.UTC) }
 	created, err = EnsureRotatingLocalBackup(dbPath, cfgPath)
@@ -57,8 +62,8 @@ func TestEnsureRotatingLocalBackupEnvControls(t *testing.T) {
 	dbPath := filepath.Join(temp, "qfs.db")
 	cfgPath := filepath.Join(temp, "config.yaml")
 
-	if err := os.WriteFile(dbPath, []byte("db"), 0644); err != nil {
-		t.Fatalf("write db: %v", err)
+	if err := writeTestSQLiteDB(dbPath); err != nil {
+		t.Fatalf("write sqlite db: %v", err)
 	}
 	if err := os.WriteFile(cfgPath, []byte("cfg"), 0644); err != nil {
 		t.Fatalf("write config: %v", err)
@@ -95,8 +100,8 @@ func TestEnsureRotatingLocalBackupRejectsGitWorktree(t *testing.T) {
 	if err := os.MkdirAll(filepath.Dir(dbPath), 0755); err != nil {
 		t.Fatalf("mkdir data dir: %v", err)
 	}
-	if err := os.WriteFile(dbPath, []byte("db"), 0644); err != nil {
-		t.Fatalf("write db: %v", err)
+	if err := writeTestSQLiteDB(dbPath); err != nil {
+		t.Fatalf("write sqlite db: %v", err)
 	}
 	if err := os.WriteFile(cfgPath, []byte("cfg"), 0644); err != nil {
 		t.Fatalf("write cfg: %v", err)
@@ -110,3 +115,43 @@ func TestEnsureRotatingLocalBackupRejectsGitWorktree(t *testing.T) {
 		t.Fatalf("unexpected error: %v", err)
 	}
 }
+
+func writeTestSQLiteDB(path string) error {
+	db, err := gorm.Open(sqlite.Open(path), &gorm.Config{})
+	if err != nil {
+		return err
+	}
+	sqlDB, err := db.DB()
+	if err != nil {
+		return err
+	}
+	defer sqlDB.Close()
+
+	return db.Exec(`
+		CREATE TABLE sample_items (
+			id INTEGER PRIMARY KEY AUTOINCREMENT,
+			name TEXT NOT NULL
+		);
+		INSERT INTO sample_items(name) VALUES ('backup');
+	`).Error
+}
+
+func assertZipContains(t *testing.T, archivePath string, expected ...string) {
+	t.Helper()
+
+	reader, err := zip.OpenReader(archivePath)
+	if err != nil {
+		t.Fatalf("open archive: %v", err)
+	}
+	defer reader.Close()
+
+	found := make(map[string]bool, len(reader.File))
+	for _, file := range reader.File {
+		found[file.Name] = true
+	}
+	for _, name := range expected {
+		if !found[name] {
+			t.Fatalf("archive %s missing %s", archivePath, name)
+		}
+	}
+}

internal/config/config.go

@@ -180,5 +180,5 @@ func (c *Config) setDefaults() {
 }
 
 func (c *Config) Address() string {
-	return fmt.Sprintf("%s:%d", c.Server.Host, c.Server.Port)
+	return net.JoinHostPort(c.Server.Host, strconv.Itoa(c.Server.Port))
 }

internal/handlers/component.go

@@ -49,7 +49,7 @@ func (h *ComponentHandler) List(c *gin.Context) {
 	offset := (page - 1) * perPage
 	localComps, total, err := h.localDB.ListComponents(localFilter, offset, perPage)
 	if err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusInternalServerError, "internal server error", err)
 		return
 	}
 

internal/handlers/export.go

@@ -58,7 +58,7 @@ type ProjectExportOptionsRequest struct {
 func (h *ExportHandler) ExportCSV(c *gin.Context) {
 	var req ExportRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusBadRequest, "invalid request", err)
 		return
 	}
 
@@ -150,7 +150,7 @@ func (h *ExportHandler) ExportConfigCSV(c *gin.Context) {
 	// Get config before streaming (can return JSON error)
 	config, err := h.configService.GetByUUID(uuid, h.dbUsername)
 	if err != nil {
-		c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusNotFound, "resource not found", err)
 		return
 	}
 
@@ -193,13 +193,13 @@ func (h *ExportHandler) ExportProjectCSV(c *gin.Context) {
 
 	project, err := h.projectService.GetByUUID(projectUUID, h.dbUsername)
 	if err != nil {
-		c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusNotFound, "resource not found", err)
 		return
 	}
 
 	result, err := h.projectService.ListConfigurations(projectUUID, h.dbUsername, "active")
 	if err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusInternalServerError, "internal server error", err)
 		return
 	}
 
@@ -226,19 +226,19 @@ func (h *ExportHandler) ExportProjectPricingCSV(c *gin.Context) {
 
 	var req ProjectExportOptionsRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusBadRequest, "invalid request", err)
 		return
 	}
 
 	project, err := h.projectService.GetByUUID(projectUUID, h.dbUsername)
 	if err != nil {
-		c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusNotFound, "resource not found", err)
 		return
 	}
 
 	result, err := h.projectService.ListConfigurations(projectUUID, h.dbUsername, "active")
 	if err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusInternalServerError, "internal server error", err)
 		return
 	}
 	if len(result.Configs) == 0 {
@@ -256,7 +256,7 @@ func (h *ExportHandler) ExportProjectPricingCSV(c *gin.Context) {
 
 	data, err := h.exportService.ProjectToPricingExportData(result.Configs, opts)
 	if err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusInternalServerError, "internal server error", err)
 		return
 	}
 

internal/handlers/partnumber_books.go

@@ -25,7 +25,7 @@ func (h *PartnumberBooksHandler) List(c *gin.Context) {
 	bookRepo := repository.NewPartnumberBookRepository(h.localDB.DB())
 	books, err := bookRepo.ListBooks()
 	if err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusInternalServerError, "internal server error", err)
 		return
 	}
 
@@ -86,7 +86,7 @@ func (h *PartnumberBooksHandler) GetItems(c *gin.Context) {
 
 	items, total, err := bookRepo.GetBookItemsPage(book.ID, search, page, perPage)
 	if err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusInternalServerError, "internal server error", err)
 		return
 	}
 

internal/handlers/pricelist.go

@@ -34,7 +34,7 @@ func (h *PricelistHandler) List(c *gin.Context) {
 
 	localPLs, err := h.localDB.GetLocalPricelists()
 	if err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusInternalServerError, "internal server error", err)
 		return
 	}
 	if source != "" {
@@ -172,13 +172,13 @@ func (h *PricelistHandler) GetItems(c *gin.Context) {
 	}
 	var total int64
 	if err := dbq.Count(&total).Error; err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusInternalServerError, "internal server error", err)
 		return
 	}
 	offset := (page - 1) * perPage
 
 	if err := dbq.Order("lot_name").Offset(offset).Limit(perPage).Find(&items).Error; err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusInternalServerError, "internal server error", err)
 		return
 	}
 	lotNames := make([]string, len(items))
@@ -241,7 +241,7 @@ func (h *PricelistHandler) GetLotNames(c *gin.Context) {
 	}
 	items, err := h.localDB.GetLocalPricelistItems(localPL.ID)
 	if err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusInternalServerError, "internal server error", err)
 		return
 	}
 	lotNames := make([]string, 0, len(items))

internal/handlers/quote.go

@@ -18,13 +18,13 @@ func NewQuoteHandler(quoteService *services.QuoteService) *QuoteHandler {
 func (h *QuoteHandler) Validate(c *gin.Context) {
 	var req services.QuoteRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusBadRequest, "invalid request", err)
 		return
 	}
 
 	result, err := h.quoteService.ValidateAndCalculate(&req)
 	if err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusBadRequest, "invalid request", err)
 		return
 	}
 
@@ -34,13 +34,13 @@ func (h *QuoteHandler) Validate(c *gin.Context) {
 func (h *QuoteHandler) Calculate(c *gin.Context) {
 	var req services.QuoteRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusBadRequest, "invalid request", err)
 		return
 	}
 
 	result, err := h.quoteService.ValidateAndCalculate(&req)
 	if err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusBadRequest, "invalid request", err)
 		return
 	}
 
@@ -53,13 +53,13 @@ func (h *QuoteHandler) Calculate(c *gin.Context) {
 func (h *QuoteHandler) PriceLevels(c *gin.Context) {
 	var req services.PriceLevelsRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusBadRequest, "invalid request", err)
 		return
 	}
 
 	result, err := h.quoteService.CalculatePriceLevels(&req)
 	if err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusBadRequest, "invalid request", err)
 		return
 	}
 

internal/handlers/respond.go

@@ -0,0 +1,73 @@
+package handlers
+
+import (
+	"encoding/json"
+	"errors"
+	"io"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+)
+
+func RespondError(c *gin.Context, status int, fallback string, err error) {
+	if err != nil {
+		_ = c.Error(err)
+	}
+	c.JSON(status, gin.H{"error": clientFacingErrorMessage(status, fallback, err)})
+}
+
+func clientFacingErrorMessage(status int, fallback string, err error) string {
+	if err == nil {
+		return fallback
+	}
+	if status >= 500 {
+		return fallback
+	}
+	if isRequestDecodeError(err) {
+		return fallback
+	}
+
+	message := strings.TrimSpace(err.Error())
+	if message == "" {
+		return fallback
+	}
+	if looksTechnicalError(message) {
+		return fallback
+	}
+	return message
+}
+
+func isRequestDecodeError(err error) bool {
+	var syntaxErr *json.SyntaxError
+	if errors.As(err, &syntaxErr) {
+		return true
+	}
+
+	var unmarshalTypeErr *json.UnmarshalTypeError
+	if errors.As(err, &unmarshalTypeErr) {
+		return true
+	}
+
+	return errors.Is(err, io.ErrUnexpectedEOF) || errors.Is(err, io.EOF)
+}
+
+func looksTechnicalError(message string) bool {
+	lower := strings.ToLower(strings.TrimSpace(message))
+	needles := []string{
+		"sql",
+		"gorm",
+		"driver",
+		"constraint",
+		"syntax error",
+		"unexpected eof",
+		"record not found",
+		"no such table",
+		"stack trace",
+	}
+	for _, needle := range needles {
+		if strings.Contains(lower, needle) {
+			return true
+		}
+	}
+	return false
+}

internal/handlers/respond_test.go

@@ -0,0 +1,41 @@
+package handlers
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+func TestClientFacingErrorMessageKeepsDomain4xx(t *testing.T) {
+	t.Parallel()
+
+	got := clientFacingErrorMessage(400, "invalid request", &json.SyntaxError{Offset: 1})
+	if got != "invalid request" {
+		t.Fatalf("expected fallback for decode error, got %q", got)
+	}
+}
+
+func TestClientFacingErrorMessagePreservesBusinessMessage(t *testing.T) {
+	t.Parallel()
+
+	err := errString("main project variant cannot be deleted")
+	got := clientFacingErrorMessage(400, "invalid request", err)
+	if got != err.Error() {
+		t.Fatalf("expected business message, got %q", got)
+	}
+}
+
+func TestClientFacingErrorMessageHidesTechnical4xx(t *testing.T) {
+	t.Parallel()
+
+	err := errString("sql: no rows in result set")
+	got := clientFacingErrorMessage(404, "resource not found", err)
+	if got != "resource not found" {
+		t.Fatalf("expected fallback for technical error, got %q", got)
+	}
+}
+
+type errString string
+
+func (e errString) Error() string {
+	return string(e)
+}

internal/handlers/setup.go

@@ -1,6 +1,7 @@
 package handlers
 
 import (
+	"errors"
 	"fmt"
 	"html/template"
 	"log/slog"
@@ -12,8 +13,8 @@ import (
 	qfassets "git.mchus.pro/mchus/quoteforge"
 	"git.mchus.pro/mchus/quoteforge/internal/db"
 	"git.mchus.pro/mchus/quoteforge/internal/localdb"
-	mysqlDriver "github.com/go-sql-driver/mysql"
 	"github.com/gin-gonic/gin"
+	mysqlDriver "github.com/go-sql-driver/mysql"
 	gormmysql "gorm.io/driver/mysql"
 	"gorm.io/gorm"
 	"gorm.io/gorm/logger"
@@ -26,6 +27,8 @@ type SetupHandler struct {
 	restartSig chan struct{}
 }
 
+var errPermissionProbeRollback = errors.New("permission probe rollback")
+
 func NewSetupHandler(localDB *localdb.LocalDB, connMgr *db.ConnectionManager, _ string, restartSig chan struct{}) (*SetupHandler, error) {
 	funcMap := template.FuncMap{
 		"sub": func(a, b int) int { return a - b },
@@ -64,7 +67,8 @@ func (h *SetupHandler) ShowSetup(c *gin.Context) {
 
 	tmpl := h.templates["setup.html"]
 	if err := tmpl.ExecuteTemplate(c.Writer, "setup.html", data); err != nil {
-		c.String(http.StatusInternalServerError, "Template error: %v", err)
+		_ = c.Error(err)
+		c.String(http.StatusInternalServerError, "Template error")
 	}
 }
 
@@ -89,49 +93,16 @@ func (h *SetupHandler) TestConnection(c *gin.Context) {
 	}
 
 	dsn := buildMySQLDSN(host, port, database, user, password, 5*time.Second)
-
-	db, err := gorm.Open(gormmysql.Open(dsn), &gorm.Config{
-		Logger: logger.Default.LogMode(logger.Silent),
-	})
+	lotCount, canWrite, err := validateMariaDBConnection(dsn)
 	if err != nil {
+		_ = c.Error(err)
 		c.JSON(http.StatusOK, gin.H{
 			"success": false,
-			"error":   fmt.Sprintf("Connection failed: %v", err),
+			"error":   "Connection check failed",
 		})
 		return
 	}
 
-	sqlDB, err := db.DB()
-	if err != nil {
-		c.JSON(http.StatusOK, gin.H{
-			"success": false,
-			"error":   fmt.Sprintf("Failed to get database handle: %v", err),
-		})
-		return
-	}
-	defer sqlDB.Close()
-
-	if err := sqlDB.Ping(); err != nil {
-		c.JSON(http.StatusOK, gin.H{
-			"success": false,
-			"error":   fmt.Sprintf("Ping failed: %v", err),
-		})
-		return
-	}
-
-	// Check for required tables
-	var lotCount int64
-	if err := db.Table("lot").Count(&lotCount).Error; err != nil {
-		c.JSON(http.StatusOK, gin.H{
-			"success": false,
-			"error":   fmt.Sprintf("Table 'lot' not found or inaccessible: %v", err),
-		})
-		return
-	}
-
-	// Check write permission
-	canWrite := testWritePermission(db)
-
 	c.JSON(http.StatusOK, gin.H{
 		"success":   true,
 		"lot_count": lotCount,
@@ -164,26 +135,21 @@ func (h *SetupHandler) SaveConnection(c *gin.Context) {
 
 	// Test connection first
 	dsn := buildMySQLDSN(host, port, database, user, password, 5*time.Second)
-
-	db, err := gorm.Open(gormmysql.Open(dsn), &gorm.Config{
-		Logger: logger.Default.LogMode(logger.Silent),
-	})
-	if err != nil {
+	if _, _, err := validateMariaDBConnection(dsn); err != nil {
+		_ = c.Error(err)
 		c.JSON(http.StatusBadRequest, gin.H{
 			"success": false,
-			"error":   fmt.Sprintf("Connection failed: %v", err),
+			"error":   "Connection check failed",
 		})
 		return
 	}
 
-	sqlDB, _ := db.DB()
-	sqlDB.Close()
-
 	// Save settings
 	if err := h.localDB.SaveSettings(host, port, database, user, password); err != nil {
+		_ = c.Error(err)
 		c.JSON(http.StatusInternalServerError, gin.H{
 			"success": false,
-			"error":   fmt.Sprintf("Failed to save settings: %v", err),
+			"error":   "Failed to save settings",
 		})
 		return
 	}
@@ -232,22 +198,6 @@ func (h *SetupHandler) GetStatus(c *gin.Context) {
 	})
 }
 
-func testWritePermission(db *gorm.DB) bool {
-	// Simple check: try to create a temporary table and drop it
-	testTable := fmt.Sprintf("qt_write_test_%d", time.Now().UnixNano())
-
-	// Try to create a test table
-	err := db.Exec(fmt.Sprintf("CREATE TABLE %s (id INT)", testTable)).Error
-	if err != nil {
-		return false
-	}
-
-	// Drop it immediately
-	db.Exec(fmt.Sprintf("DROP TABLE %s", testTable))
-
-	return true
-}
-
 func buildMySQLDSN(host string, port int, database, user, password string, timeout time.Duration) string {
 	cfg := mysqlDriver.NewConfig()
 	cfg.User = user
@@ -263,3 +213,47 @@ func buildMySQLDSN(host string, port int, database, user, password string, timeo
 	}
 	return cfg.FormatDSN()
 }
+
+func validateMariaDBConnection(dsn string) (int64, bool, error) {
+	db, err := gorm.Open(gormmysql.Open(dsn), &gorm.Config{
+		Logger: logger.Default.LogMode(logger.Silent),
+	})
+	if err != nil {
+		return 0, false, fmt.Errorf("open MariaDB connection: %w", err)
+	}
+
+	sqlDB, err := db.DB()
+	if err != nil {
+		return 0, false, fmt.Errorf("get database handle: %w", err)
+	}
+	defer sqlDB.Close()
+
+	if err := sqlDB.Ping(); err != nil {
+		return 0, false, fmt.Errorf("ping MariaDB: %w", err)
+	}
+
+	var lotCount int64
+	if err := db.Table("lot").Count(&lotCount).Error; err != nil {
+		return 0, false, fmt.Errorf("check required table lot: %w", err)
+	}
+
+	return lotCount, testSyncWritePermission(db), nil
+}
+
+func testSyncWritePermission(db *gorm.DB) bool {
+	sentinel := fmt.Sprintf("quoteforge-permission-check-%d", time.Now().UnixNano())
+	err := db.Transaction(func(tx *gorm.DB) error {
+		if err := tx.Exec(`
+			INSERT INTO qt_client_schema_state (username, hostname, last_checked_at, updated_at)
+			VALUES (?, ?, NOW(), NOW())
+			ON DUPLICATE KEY UPDATE
+				last_checked_at = VALUES(last_checked_at),
+				updated_at = VALUES(updated_at)
+		`, sentinel, "setup-check").Error; err != nil {
+			return err
+		}
+		return errPermissionProbeRollback
+	})
+
+	return errors.Is(err, errPermissionProbeRollback)
+}

internal/handlers/sync.go

@@ -116,9 +116,7 @@ func (h *SyncHandler) GetStatus(c *gin.Context) {
 func (h *SyncHandler) GetReadiness(c *gin.Context) {
 	readiness, err := h.syncService.GetReadiness()
 	if err != nil && readiness == nil {
-		c.JSON(http.StatusInternalServerError, gin.H{
-			"error": err.Error(),
-		})
+		RespondError(c, http.StatusInternalServerError, "internal server error", err)
 		return
 	}
 	if readiness == nil {
@@ -158,8 +156,9 @@ func (h *SyncHandler) ensureSyncReadiness(c *gin.Context) bool {
 
 	c.JSON(http.StatusInternalServerError, gin.H{
 		"success": false,
-		"error":   err.Error(),
+		"error":   "internal server error",
 	})
+	_ = c.Error(err)
 	_ = readiness
 	return false
 }
@@ -184,8 +183,9 @@ func (h *SyncHandler) SyncComponents(c *gin.Context) {
 	if err != nil {
 		c.JSON(http.StatusServiceUnavailable, gin.H{
 			"success": false,
-			"error":   "Database connection failed: " + err.Error(),
+			"error":   "database connection failed",
 		})
+		_ = c.Error(err)
 		return
 	}
 
@@ -194,8 +194,9 @@ func (h *SyncHandler) SyncComponents(c *gin.Context) {
 		slog.Error("component sync failed", "error", err)
 		c.JSON(http.StatusInternalServerError, gin.H{
 			"success": false,
-			"error":   err.Error(),
+			"error":   "component sync failed",
 		})
+		_ = c.Error(err)
 		return
 	}
 
@@ -220,8 +221,9 @@ func (h *SyncHandler) SyncPricelists(c *gin.Context) {
 		slog.Error("pricelist sync failed", "error", err)
 		c.JSON(http.StatusInternalServerError, gin.H{
 			"success": false,
-			"error":   err.Error(),
+			"error":   "pricelist sync failed",
 		})
+		_ = c.Error(err)
 		return
 	}
 
@@ -247,8 +249,9 @@ func (h *SyncHandler) SyncPartnumberBooks(c *gin.Context) {
 		slog.Error("partnumber books pull failed", "error", err)
 		c.JSON(http.StatusInternalServerError, gin.H{
 			"success": false,
-			"error":   err.Error(),
+			"error":   "partnumber books sync failed",
 		})
+		_ = c.Error(err)
 		return
 	}
 
@@ -295,8 +298,9 @@ func (h *SyncHandler) SyncAll(c *gin.Context) {
 		slog.Error("pending push failed during full sync", "error", err)
 		c.JSON(http.StatusInternalServerError, gin.H{
 			"success": false,
-			"error":   "Pending changes push failed: " + err.Error(),
+			"error":   "pending changes push failed",
 		})
+		_ = c.Error(err)
 		return
 	}
 
@@ -305,8 +309,9 @@ func (h *SyncHandler) SyncAll(c *gin.Context) {
 	if err != nil {
 		c.JSON(http.StatusServiceUnavailable, gin.H{
 			"success": false,
-			"error":   "Database connection failed: " + err.Error(),
+			"error":   "database connection failed",
 		})
+		_ = c.Error(err)
 		return
 	}
 
@@ -315,8 +320,9 @@ func (h *SyncHandler) SyncAll(c *gin.Context) {
 		slog.Error("component sync failed during full sync", "error", err)
 		c.JSON(http.StatusInternalServerError, gin.H{
 			"success": false,
-			"error":   "Component sync failed: " + err.Error(),
+			"error":   "component sync failed",
 		})
+		_ = c.Error(err)
 		return
 	}
 	componentsSynced = compResult.TotalSynced
@@ -327,10 +333,11 @@ func (h *SyncHandler) SyncAll(c *gin.Context) {
 		slog.Error("pricelist sync failed during full sync", "error", err)
 		c.JSON(http.StatusInternalServerError, gin.H{
 			"success":           false,
-			"error":             "Pricelist sync failed: " + err.Error(),
+			"error":             "pricelist sync failed",
 			"pending_pushed":    pendingPushed,
 			"components_synced": componentsSynced,
 		})
+		_ = c.Error(err)
 		return
 	}
 
@@ -339,11 +346,12 @@ func (h *SyncHandler) SyncAll(c *gin.Context) {
 		slog.Error("project import failed during full sync", "error", err)
 		c.JSON(http.StatusInternalServerError, gin.H{
 			"success":           false,
-			"error":             "Project import failed: " + err.Error(),
+			"error":             "project import failed",
 			"pending_pushed":    pendingPushed,
 			"components_synced": componentsSynced,
 			"pricelists_synced": pricelistsSynced,
 		})
+		_ = c.Error(err)
 		return
 	}
 
@@ -352,7 +360,7 @@ func (h *SyncHandler) SyncAll(c *gin.Context) {
 		slog.Error("configuration import failed during full sync", "error", err)
 		c.JSON(http.StatusInternalServerError, gin.H{
 			"success":           false,
-			"error":             "Configuration import failed: " + err.Error(),
+			"error":             "configuration import failed",
 			"pending_pushed":    pendingPushed,
 			"components_synced": componentsSynced,
 			"pricelists_synced": pricelistsSynced,
@@ -360,6 +368,7 @@ func (h *SyncHandler) SyncAll(c *gin.Context) {
 			"projects_updated":  projectsResult.Updated,
 			"projects_skipped":  projectsResult.Skipped,
 		})
+		_ = c.Error(err)
 		return
 	}
 
@@ -398,8 +407,9 @@ func (h *SyncHandler) PushPendingChanges(c *gin.Context) {
 		slog.Error("push pending changes failed", "error", err)
 		c.JSON(http.StatusInternalServerError, gin.H{
 			"success": false,
-			"error":   err.Error(),
+			"error":   "pending changes push failed",
 		})
+		_ = c.Error(err)
 		return
 	}
 
@@ -426,9 +436,7 @@ func (h *SyncHandler) GetPendingCount(c *gin.Context) {
 func (h *SyncHandler) GetPendingChanges(c *gin.Context) {
 	changes, err := h.localDB.GetPendingChanges()
 	if err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{
-			"error": err.Error(),
-		})
+		RespondError(c, http.StatusInternalServerError, "internal server error", err)
 		return
 	}
 
@@ -445,8 +453,9 @@ func (h *SyncHandler) RepairPendingChanges(c *gin.Context) {
 		slog.Error("repair pending changes failed", "error", err)
 		c.JSON(http.StatusInternalServerError, gin.H{
 			"success": false,
-			"error":   err.Error(),
+			"error":   "pending changes repair failed",
 		})
+		_ = c.Error(err)
 		return
 	}
 
@@ -588,9 +597,7 @@ func (h *SyncHandler) GetUsersStatus(c *gin.Context) {
 
 	users, err := h.syncService.ListUserSyncStatuses(threshold)
 	if err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{
-			"error": err.Error(),
-		})
+		RespondError(c, http.StatusInternalServerError, "internal server error", err)
 		return
 	}
 
@@ -639,7 +646,8 @@ func (h *SyncHandler) SyncStatusPartial(c *gin.Context) {
 	c.Header("Content-Type", "text/html; charset=utf-8")
 	if err := h.tmpl.ExecuteTemplate(c.Writer, "sync_status", data); err != nil {
 		slog.Error("failed to render sync_status template", "error", err)
-		c.String(http.StatusInternalServerError, "Template error: "+err.Error())
+		_ = c.Error(err)
+		c.String(http.StatusInternalServerError, "Template error")
 	}
 }
 
@@ -675,7 +683,7 @@ func (h *SyncHandler) ReportPartnumberSeen(c *gin.Context) {
 		} `json:"items"`
 	}
 	if err := c.ShouldBindJSON(&body); err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusBadRequest, "invalid request", err)
 		return
 	}
 
@@ -691,7 +699,7 @@ func (h *SyncHandler) ReportPartnumberSeen(c *gin.Context) {
 	}
 
 	if err := h.syncService.PushPartnumberSeen(items); err != nil {
-		c.JSON(http.StatusServiceUnavailable, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusServiceUnavailable, "service unavailable", err)
 		return
 	}
 

internal/handlers/vendor_spec.go

@@ -62,7 +62,7 @@ func (h *VendorSpecHandler) PutVendorSpec(c *gin.Context) {
 		VendorSpec []localdb.VendorSpecItem `json:"vendor_spec"`
 	}
 	if err := c.ShouldBindJSON(&body); err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusBadRequest, "invalid request", err)
 		return
 	}
 
@@ -82,11 +82,11 @@ func (h *VendorSpecHandler) PutVendorSpec(c *gin.Context) {
 	spec := localdb.VendorSpec(body.VendorSpec)
 	specJSON, err := json.Marshal(spec)
 	if err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusInternalServerError, "internal server error", err)
 		return
 	}
 	if err := h.localDB.DB().Model(cfg).Update("vendor_spec", string(specJSON)).Error; err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusInternalServerError, "internal server error", err)
 		return
 	}
 
@@ -138,7 +138,7 @@ func (h *VendorSpecHandler) ResolveVendorSpec(c *gin.Context) {
 		VendorSpec []localdb.VendorSpecItem `json:"vendor_spec"`
 	}
 	if err := c.ShouldBindJSON(&body); err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusBadRequest, "invalid request", err)
 		return
 	}
 
@@ -147,14 +147,14 @@ func (h *VendorSpecHandler) ResolveVendorSpec(c *gin.Context) {
 
 	resolved, err := resolver.Resolve(body.VendorSpec)
 	if err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusInternalServerError, "internal server error", err)
 		return
 	}
 
 	book, _ := bookRepo.GetActiveBook()
 	aggregated, err := services.AggregateLOTs(resolved, book, bookRepo)
 	if err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusInternalServerError, "internal server error", err)
 		return
 	}
 
@@ -181,7 +181,7 @@ func (h *VendorSpecHandler) ApplyVendorSpec(c *gin.Context) {
 		} `json:"items"`
 	}
 	if err := c.ShouldBindJSON(&body); err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusBadRequest, "invalid request", err)
 		return
 	}
 
@@ -196,12 +196,12 @@ func (h *VendorSpecHandler) ApplyVendorSpec(c *gin.Context) {
 
 	itemsJSON, err := json.Marshal(newItems)
 	if err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusInternalServerError, "internal server error", err)
 		return
 	}
 
 	if err := h.localDB.DB().Model(cfg).Update("items", string(itemsJSON)).Error; err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusInternalServerError, "internal server error", err)
 		return
 	}
 

internal/handlers/web.go

@@ -1,6 +1,7 @@
 package handlers
 
 import (
+	"fmt"
 	"html/template"
 	"strconv"
 	"strings"
@@ -114,12 +115,14 @@ func (h *WebHandler) render(c *gin.Context, name string, data gin.H) {
 	c.Header("Content-Type", "text/html; charset=utf-8")
 	tmpl, ok := h.templates[name]
 	if !ok {
-		c.String(500, "Template not found: %s", name)
+		_ = c.Error(fmt.Errorf("template %q not found", name))
+		c.String(500, "Template error")
 		return
 	}
 	// Execute the page template which will use base
 	if err := tmpl.ExecuteTemplate(c.Writer, name, data); err != nil {
-		c.String(500, "Template error: %v", err)
+		_ = c.Error(err)
+		c.String(500, "Template error")
 	}
 }
 

internal/handlers/web_test.go

@@ -0,0 +1,47 @@
+package handlers
+
+import (
+	"errors"
+	"html/template"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+)
+
+func TestWebHandlerRenderHidesTemplateExecutionError(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	tmpl := template.Must(template.New("broken.html").Funcs(template.FuncMap{
+		"boom": func() (string, error) {
+			return "", errors.New("secret template failure")
+		},
+	}).Parse(`{{define "broken.html"}}{{boom}}{{end}}`))
+
+	handler := &WebHandler{
+		templates: map[string]*template.Template{
+			"broken.html": tmpl,
+		},
+	}
+
+	rec := httptest.NewRecorder()
+	ctx, _ := gin.CreateTestContext(rec)
+	ctx.Request = httptest.NewRequest(http.MethodGet, "/broken", nil)
+
+	handler.render(ctx, "broken.html", gin.H{})
+
+	if rec.Code != http.StatusInternalServerError {
+		t.Fatalf("expected 500, got %d", rec.Code)
+	}
+	if body := strings.TrimSpace(rec.Body.String()); body != "Template error" {
+		t.Fatalf("expected generic template error, got %q", body)
+	}
+	if len(ctx.Errors) != 1 {
+		t.Fatalf("expected logged template error, got %d", len(ctx.Errors))
+	}
+	if !strings.Contains(ctx.Errors.String(), "secret template failure") {
+		t.Fatalf("expected original error in gin context, got %q", ctx.Errors.String())
+	}
+}