security hardening, approval mode

Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

Author: mudler

core/application/config_file_watcher.go

@@ -207,7 +207,7 @@ func readRuntimeSettingsJson(startupAppConfig config.ApplicationConfig) fileHand
 		envF16 := appConfig.F16 == startupAppConfig.F16
 		envDebug := appConfig.Debug == startupAppConfig.Debug
 		envCORS := appConfig.CORS == startupAppConfig.CORS
-		envCSRF := appConfig.CSRF == startupAppConfig.CSRF
+		envCSRF := appConfig.DisableCSRF == startupAppConfig.DisableCSRF
 		envCORSAllowOrigins := appConfig.CORSAllowOrigins == startupAppConfig.CORSAllowOrigins
 		envP2PToken := appConfig.P2PToken == startupAppConfig.P2PToken
 		envP2PNetworkID := appConfig.P2PNetworkID == startupAppConfig.P2PNetworkID
@@ -313,7 +313,7 @@ func readRuntimeSettingsJson(startupAppConfig config.ApplicationConfig) fileHand
 				appConfig.CORS = *settings.CORS
 			}
 			if settings.CSRF != nil && !envCSRF {
-				appConfig.CSRF = *settings.CSRF
+				appConfig.DisableCSRF = *settings.CSRF
 			}
 			if settings.CORSAllowOrigins != nil && !envCORSAllowOrigins {
 				appConfig.CORSAllowOrigins = *settings.CORSAllowOrigins

core/application/startup.go

@@ -1,6 +1,8 @@
 package application
 
 import (
+	"crypto/rand"
+	"encoding/hex"
 	"encoding/json"
 	"fmt"
 	"os"
@@ -84,14 +86,24 @@ func New(opts ...config.AppOption) (*Application, error) {
 
 	// Initialize auth database if auth is enabled
 	if options.Auth.Enabled {
+		// Auto-generate HMAC secret if not provided
+		if options.Auth.APIKeyHMACSecret == "" {
+			secretFile := filepath.Join(options.DataPath, ".hmac_secret")
+			secret, err := loadOrGenerateHMACSecret(secretFile)
+			if err != nil {
+				return nil, fmt.Errorf("failed to initialize HMAC secret: %w", err)
+			}
+			options.Auth.APIKeyHMACSecret = secret
+		}
+
 		authDB, err := auth.InitDB(options.Auth.DatabaseURL)
 		if err != nil {
 			return nil, fmt.Errorf("failed to initialize auth database: %w", err)
 		}
 		application.authDB = authDB
 		xlog.Info("Auth enabled", "database", options.Auth.DatabaseURL)
 
-		// Start session cleanup goroutine
+		// Start session and expired API key cleanup goroutine
 		go func() {
 			ticker := time.NewTicker(1 * time.Hour)
 			defer ticker.Stop()
@@ -103,6 +115,9 @@ func New(opts ...config.AppOption) (*Application, error) {
 					if err := auth.CleanExpiredSessions(authDB); err != nil {
 						xlog.Error("failed to clean expired sessions", "error", err)
 					}
+					if err := auth.CleanExpiredAPIKeys(authDB); err != nil {
+						xlog.Error("failed to clean expired API keys", "error", err)
+					}
 				}
 			}
 		}()
@@ -461,6 +476,31 @@ func initializeWatchdog(application *Application, options *config.ApplicationCon
 	}
 }
 
+// loadOrGenerateHMACSecret loads an HMAC secret from the given file path,
+// or generates a random 32-byte secret and persists it if the file doesn't exist.
+func loadOrGenerateHMACSecret(path string) (string, error) {
+	data, err := os.ReadFile(path)
+	if err == nil {
+		secret := string(data)
+		if len(secret) >= 32 {
+			return secret, nil
+		}
+	}
+
+	b := make([]byte, 32)
+	if _, err := rand.Read(b); err != nil {
+		return "", fmt.Errorf("failed to generate HMAC secret: %w", err)
+	}
+	secret := hex.EncodeToString(b)
+
+	if err := os.WriteFile(path, []byte(secret), 0600); err != nil {
+		return "", fmt.Errorf("failed to persist HMAC secret: %w", err)
+	}
+
+	xlog.Info("Generated new HMAC secret for API key hashing", "path", path)
+	return secret, nil
+}
+
 // migrateDataFiles moves persistent data files from the old config directory
 // to the new data directory. Only moves files that exist in src but not in dst.
 func migrateDataFiles(srcDir, dstDir string) {

core/cli/run.go

@@ -58,7 +58,7 @@ type RunCMD struct {
 	Address                            string   `env:"LOCALAI_ADDRESS,ADDRESS" default:":8080" help:"Bind address for the API server" group:"api"`
 	CORS                               bool     `env:"LOCALAI_CORS,CORS" help:"" group:"api"`
 	CORSAllowOrigins                   string   `env:"LOCALAI_CORS_ALLOW_ORIGINS,CORS_ALLOW_ORIGINS" group:"api"`
-	CSRF                               bool     `env:"LOCALAI_CSRF" help:"Enables fiber CSRF middleware" group:"api"`
+	DisableCSRF                        bool     `env:"LOCALAI_DISABLE_CSRF" help:"Disable CSRF middleware (enabled by default)" group:"api"`
 	UploadLimit                        int      `env:"LOCALAI_UPLOAD_LIMIT,UPLOAD_LIMIT" default:"15" help:"Default upload-limit in MB" group:"api"`
 	APIKeys                            []string `env:"LOCALAI_API_KEY,API_KEY" help:"List of API Keys to enable API authentication. When this is set, all the requests must be authenticated with one of these API keys" group:"api"`
 	DisableWebUI                       bool     `env:"LOCALAI_DISABLE_WEBUI,DISABLE_WEBUI" default:"false" help:"Disables the web user interface. When set to true, the server will only expose API endpoints without serving the web interface" group:"api"`
@@ -131,8 +131,10 @@ type RunCMD struct {
 	OIDCClientSecret     string `env:"LOCALAI_OIDC_CLIENT_SECRET" help:"OIDC Client Secret" group:"auth"`
 	AuthBaseURL          string `env:"LOCALAI_BASE_URL" help:"Base URL for OAuth callbacks (e.g. http://localhost:8080)" group:"auth"`
 	AuthAdminEmail       string `env:"LOCALAI_ADMIN_EMAIL" help:"Email address to auto-promote to admin role" group:"auth"`
-	AuthRegistrationMode string `env:"LOCALAI_REGISTRATION_MODE" default:"open" help:"Registration mode: 'open' (default) or 'approval'" group:"auth"`
+	AuthRegistrationMode string `env:"LOCALAI_REGISTRATION_MODE" default:"open" help:"Registration mode: 'open' (default), 'approval', or 'invite' (invite code required)" group:"auth"`
 	DisableLocalAuth     bool   `env:"LOCALAI_DISABLE_LOCAL_AUTH" default:"false" help:"Disable local email/password registration and login (use with OAuth/OIDC-only setups)" group:"auth"`
+	AuthAPIKeyHMACSecret string `env:"LOCALAI_AUTH_HMAC_SECRET" help:"HMAC secret for API key hashing (auto-generated if empty)" group:"auth"`
+	DefaultAPIKeyExpiry  string `env:"LOCALAI_DEFAULT_API_KEY_EXPIRY" help:"Default expiry for API keys (e.g. 90d, 1y; empty = no expiry)" group:"auth"`
 
 	Version bool
 }
@@ -178,7 +180,7 @@ func (r *RunCMD) Run(ctx *cliContext.Context) error {
 		config.WithBackendGalleries(r.BackendGalleries),
 		config.WithCors(r.CORS),
 		config.WithCorsAllowOrigins(r.CORSAllowOrigins),
-		config.WithCsrf(r.CSRF),
+		config.WithDisableCSRF(r.DisableCSRF),
 		config.WithThreads(r.Threads),
 		config.WithUploadLimitMB(r.UploadLimit),
 		config.WithApiKeys(r.APIKeys),
@@ -356,6 +358,12 @@ func (r *RunCMD) Run(ctx *cliContext.Context) error {
 		if r.DisableLocalAuth {
 			opts = append(opts, config.WithAuthDisableLocalAuth(true))
 		}
+		if r.AuthAPIKeyHMACSecret != "" {
+			opts = append(opts, config.WithAuthAPIKeyHMACSecret(r.AuthAPIKeyHMACSecret))
+		}
+		if r.DefaultAPIKeyExpiry != "" {
+			opts = append(opts, config.WithAuthDefaultAPIKeyExpiry(r.DefaultAPIKeyExpiry))
+		}
 	}
 
 	if idleWatchDog || busyWatchDog {

core/config/application_config.go

@@ -30,7 +30,7 @@ type ApplicationConfig struct {
 	DynamicConfigsDir             string
 	DynamicConfigsDirPollInterval time.Duration
 	CORS                          bool
-	CSRF                          bool
+	DisableCSRF                   bool
 	PreloadJSONModels             string
 	PreloadModelsFromPath         string
 	CORSAllowOrigins              string
@@ -112,8 +112,10 @@ type AuthConfig struct {
 	OIDCClientSecret   string
 	BaseURL            string // for OAuth callback URLs (e.g. "http://localhost:8080")
 	AdminEmail         string // auto-promote to admin on login
-	RegistrationMode   string // "open" (default), "approval", "invite"
+	RegistrationMode   string // "open", "approval" (default when empty), "invite"
 	DisableLocalAuth   bool   // disable local email/password registration and login
+	APIKeyHMACSecret   string // HMAC secret for API key hashing; auto-generated if empty
+	DefaultAPIKeyExpiry string // default expiry duration for API keys (e.g. "90d"); empty = no expiry
 }
 
 // AgentPoolConfig holds configuration for the LocalAGI agent pool integration.
@@ -214,9 +216,9 @@ func WithP2PNetworkID(s string) AppOption {
 	}
 }
 
-func WithCsrf(b bool) AppOption {
+func WithDisableCSRF(b bool) AppOption {
 	return func(o *ApplicationConfig) {
-		o.CSRF = b
+		o.DisableCSRF = b
 	}
 }
 
@@ -799,6 +801,18 @@ func WithAuthOIDCClientSecret(clientSecret string) AppOption {
 	}
 }
 
+func WithAuthAPIKeyHMACSecret(secret string) AppOption {
+	return func(o *ApplicationConfig) {
+		o.Auth.APIKeyHMACSecret = secret
+	}
+}
+
+func WithAuthDefaultAPIKeyExpiry(expiry string) AppOption {
+	return func(o *ApplicationConfig) {
+		o.Auth.DefaultAPIKeyExpiry = expiry
+	}
+}
+
 // ToConfigLoaderOptions returns a slice of ConfigLoader Option.
 // Some options defined at the application level are going to be passed as defaults for
 // all the configuration for the models.
@@ -838,7 +852,7 @@ func (o *ApplicationConfig) ToRuntimeSettings() RuntimeSettings {
 	enableTracing := o.EnableTracing
 	enableBackendLogging := o.EnableBackendLogging
 	cors := o.CORS
-	csrf := o.CSRF
+	csrf := o.DisableCSRF
 	corsAllowOrigins := o.CORSAllowOrigins
 	p2pToken := o.P2PToken
 	p2pNetworkID := o.P2PNetworkID
@@ -1046,7 +1060,7 @@ func (o *ApplicationConfig) ApplyRuntimeSettings(settings *RuntimeSettings) (req
 		o.CORS = *settings.CORS
 	}
 	if settings.CSRF != nil {
-		o.CSRF = *settings.CSRF
+		o.DisableCSRF = *settings.CSRF
 	}
 	if settings.CORSAllowOrigins != nil {
 		o.CORSAllowOrigins = *settings.CORSAllowOrigins

core/config/application_config_test.go

@@ -26,7 +26,7 @@ var _ = Describe("ApplicationConfig RuntimeSettings Conversion", func() {
 				F16:                      true,
 				Debug:                    true,
 				CORS:                     true,
-				CSRF:                     true,
+				DisableCSRF:                     true,
 				CORSAllowOrigins:         "https://example.com",
 				P2PToken:                 "test-token",
 				P2PNetworkID:             "test-network",
@@ -377,7 +377,7 @@ var _ = Describe("ApplicationConfig RuntimeSettings Conversion", func() {
 			appConfig.ApplyRuntimeSettings(rs)
 
 			Expect(appConfig.CORS).To(BeTrue())
-			Expect(appConfig.CSRF).To(BeTrue())
+			Expect(appConfig.DisableCSRF).To(BeTrue())
 			Expect(appConfig.CORSAllowOrigins).To(Equal("https://example.com,https://other.com"))
 		})
 
@@ -463,7 +463,7 @@ var _ = Describe("ApplicationConfig RuntimeSettings Conversion", func() {
 				F16:                      true,
 				Debug:                    false,
 				CORS:                     true,
-				CSRF:                     false,
+				DisableCSRF:                     false,
 				CORSAllowOrigins:         "https://test.com",
 				P2PToken:                 "round-trip-token",
 				P2PNetworkID:             "round-trip-network",
@@ -495,7 +495,7 @@ var _ = Describe("ApplicationConfig RuntimeSettings Conversion", func() {
 			Expect(target.F16).To(Equal(original.F16))
 			Expect(target.Debug).To(Equal(original.Debug))
 			Expect(target.CORS).To(Equal(original.CORS))
-			Expect(target.CSRF).To(Equal(original.CSRF))
+			Expect(target.DisableCSRF).To(Equal(original.DisableCSRF))
 			Expect(target.CORSAllowOrigins).To(Equal(original.CORSAllowOrigins))
 			Expect(target.P2PToken).To(Equal(original.P2PToken))
 			Expect(target.P2PNetworkID).To(Equal(original.P2PNetworkID))

core/http/app.go

@@ -234,10 +234,42 @@ func API(application *application.Application) (*echo.Echo, error) {
 		e.Use(middleware.CORS())
 	}
 
-	// CSRF middleware
-	if application.ApplicationConfig().CSRF {
-		xlog.Debug("Enabling CSRF middleware. Tokens are now required for state-modifying requests")
-		e.Use(middleware.CSRF())
+	// CSRF middleware (enabled by default, disable with LOCALAI_DISABLE_CSRF=true)
+	//
+	// Protection relies on Echo's Sec-Fetch-Site header check (supported by all
+	// modern browsers). The legacy cookie+token approach is removed because
+	// Echo's Sec-Fetch-Site short-circuit never sets the cookie, so the frontend
+	// could never read a token to send back.
+	if !application.ApplicationConfig().DisableCSRF {
+		xlog.Debug("Enabling CSRF middleware (Sec-Fetch-Site mode)")
+		e.Use(middleware.CSRFWithConfig(middleware.CSRFConfig{
+			Skipper: func(c echo.Context) bool {
+				// Skip CSRF for API clients using auth headers (may be cross-origin)
+				if c.Request().Header.Get("Authorization") != "" {
+					return true
+				}
+				if c.Request().Header.Get("x-api-key") != "" || c.Request().Header.Get("xi-api-key") != "" {
+					return true
+				}
+				// Skip when Sec-Fetch-Site header is absent (older browsers, reverse
+				// proxies that strip the header). The SameSite=Lax cookie attribute
+				// provides baseline CSRF protection for these clients.
+				if c.Request().Header.Get("Sec-Fetch-Site") == "" {
+					return true
+				}
+				return false
+			},
+			// Allow same-site requests (subdomains / different ports) in addition
+			// to same-origin which Echo already permits by default.
+			AllowSecFetchSiteFunc: func(c echo.Context) (bool, error) {
+				secFetchSite := c.Request().Header.Get("Sec-Fetch-Site")
+				if secFetchSite == "same-site" {
+					return true, nil
+				}
+				// cross-site: block
+				return false, nil
+			},
+		}))
 	}
 
 	// Admin middleware: enforces admin role when auth is enabled, no-op otherwise

core/http/auth/apikeys.go

@@ -1,6 +1,7 @@
 package auth
 
 import (
+	"crypto/hmac"
 	"crypto/rand"
 	"crypto/sha256"
 	"encoding/hex"
@@ -18,31 +19,37 @@ const (
 )
 
 // GenerateAPIKey generates a new API key. Returns the plaintext key,
-// its SHA-256 hash, and a display prefix.
-func GenerateAPIKey() (plaintext, hash, prefix string, err error) {
+// its HMAC-SHA256 hash, and a display prefix.
+func GenerateAPIKey(hmacSecret string) (plaintext, hash, prefix string, err error) {
 	b := make([]byte, apiKeyRandBytes)
 	if _, err := rand.Read(b); err != nil {
 		return "", "", "", fmt.Errorf("failed to generate API key: %w", err)
 	}
 
 	randHex := hex.EncodeToString(b)
 	plaintext = apiKeyPrefix + randHex
-	hash = HashAPIKey(plaintext)
+	hash = HashAPIKey(plaintext, hmacSecret)
 	prefix = plaintext[:len(apiKeyPrefix)+keyPrefixLen]
 
 	return plaintext, hash, prefix, nil
 }
 
-// HashAPIKey returns the SHA-256 hex digest of the given plaintext key.
-func HashAPIKey(plaintext string) string {
-	h := sha256.Sum256([]byte(plaintext))
-	return hex.EncodeToString(h[:])
+// HashAPIKey returns the HMAC-SHA256 hex digest of the given plaintext key.
+// If hmacSecret is empty, falls back to plain SHA-256 for backward compatibility.
+func HashAPIKey(plaintext, hmacSecret string) string {
+	if hmacSecret == "" {
+		h := sha256.Sum256([]byte(plaintext))
+		return hex.EncodeToString(h[:])
+	}
+	mac := hmac.New(sha256.New, []byte(hmacSecret))
+	mac.Write([]byte(plaintext))
+	return hex.EncodeToString(mac.Sum(nil))
 }
 
 // CreateAPIKey generates and stores a new API key for the given user.
 // Returns the plaintext key (shown once) and the database record.
-func CreateAPIKey(db *gorm.DB, userID, name, role string) (string, *UserAPIKey, error) {
-	plaintext, hash, prefix, err := GenerateAPIKey()
+func CreateAPIKey(db *gorm.DB, userID, name, role, hmacSecret string, expiresAt *time.Time) (string, *UserAPIKey, error) {
+	plaintext, hash, prefix, err := GenerateAPIKey(hmacSecret)
 	if err != nil {
 		return "", nil, err
 	}
@@ -54,6 +61,7 @@ func CreateAPIKey(db *gorm.DB, userID, name, role string) (string, *UserAPIKey,
 		KeyHash:   hash,
 		KeyPrefix: prefix,
 		Role:      role,
+		ExpiresAt: expiresAt,
 	}
 
 	if err := db.Create(record).Error; err != nil {
@@ -66,14 +74,18 @@ func CreateAPIKey(db *gorm.DB, userID, name, role string) (string, *UserAPIKey,
 // ValidateAPIKey looks up an API key by hashing the plaintext and searching
 // the database. Returns the key record if found, or an error.
 // Updates LastUsed on successful validation.
-func ValidateAPIKey(db *gorm.DB, plaintext string) (*UserAPIKey, error) {
-	hash := HashAPIKey(plaintext)
+func ValidateAPIKey(db *gorm.DB, plaintext, hmacSecret string) (*UserAPIKey, error) {
+	hash := HashAPIKey(plaintext, hmacSecret)
 
 	var key UserAPIKey
 	if err := db.Preload("User").Where("key_hash = ?", hash).First(&key).Error; err != nil {
 		return nil, fmt.Errorf("invalid API key")
 	}
 
+	if key.ExpiresAt != nil && time.Now().After(*key.ExpiresAt) {
+		return nil, fmt.Errorf("API key expired")
+	}
+
 	if key.User.Status != StatusActive {
 		return nil, fmt.Errorf("user account is not active")
 	}
@@ -102,3 +114,8 @@ func RevokeAPIKey(db *gorm.DB, keyID, userID string) error {
 	}
 	return result.Error
 }
+
+// CleanExpiredAPIKeys removes all API keys that have passed their expiry time.
+func CleanExpiredAPIKeys(db *gorm.DB) error {
+	return db.Where("expires_at IS NOT NULL AND expires_at < ?", time.Now()).Delete(&UserAPIKey{}).Error
+}