Add API error model, auth, and rate limiting

Author: devblac

api/httpapi/httpapi.go

@@ -2,8 +2,12 @@ package httpapi
 
 import (
 	"encoding/json"
+	"net"
 	"net/http"
 	"strconv"
+	"strings"
+	"sync"
+	"time"
 
 	wsadapter "gamifykit/adapters/websocket"
 	"gamifykit/core"
@@ -17,6 +21,14 @@ type Options struct {
 	PathPrefix string
 	// AllowCORSOrigin, if non-empty, enables basic CORS with the given origin (use "*" for any).
 	AllowCORSOrigin string
+	// APIKeys, if non-empty, enables static API key auth via Authorization: Bearer or X-API-Key.
+	APIKeys []string
+	// RateLimitEnabled toggles rate limiting.
+	RateLimitEnabled bool
+	// RateLimitRPM is the allowed requests per minute per client key.
+	RateLimitRPM int
+	// RateLimitBurst defines burst capacity.
+	RateLimitBurst int
 }
 
 // NewMux builds an http.Handler exposing a minimal Gamify REST API and WebSocket stream.
@@ -42,49 +54,74 @@ func NewMux(svc *engine.GamifyService, hub *realtime.Hub, opts Options) http.Han
 	// Users API
 	mux.HandleFunc(withPrefix(opts.PathPrefix, "/users/"), func(w http.ResponseWriter, r *http.Request) {
 		if r.Method != http.MethodGet && r.Method != http.MethodPost {
-			http.NotFound(w, r)
+			writeError(w, http.StatusNotFound, "not_found", "route not found", nil)
 			return
 		}
 		parts := split(r.URL.Path, '/')
 		if len(parts) < 2 {
-			http.NotFound(w, r)
+			writeError(w, http.StatusNotFound, "not_found", "route not found", nil)
+			return
+		}
+		user, err := core.NormalizeUserID(core.UserID(parts[1]))
+		if err != nil {
+			writeError(w, http.StatusBadRequest, "invalid_user", err.Error(), nil)
 			return
 		}
-		user := core.UserID(parts[1])
 		switch r.Method {
 		case http.MethodPost:
 			if len(parts) >= 3 && parts[2] == "points" {
 				metric := core.Metric(r.URL.Query().Get("metric"))
 				if metric == "" {
 					metric = core.MetricXP
 				}
-				delta, _ := strconv.ParseInt(r.URL.Query().Get("delta"), 10, 64)
+				delta, err := strconv.ParseInt(r.URL.Query().Get("delta"), 10, 64)
+				if err != nil {
+					writeError(w, http.StatusBadRequest, "invalid_delta", "delta must be an integer", nil)
+					return
+				}
 				total, err := svc.AddPoints(r.Context(), user, metric, delta)
-				writeJSON(w, map[string]any{"total": total, "err": errString(err)})
+				if err != nil {
+					writeError(w, http.StatusBadRequest, "invalid_input", err.Error(), nil)
+					return
+				}
+				writeJSON(w, map[string]any{"total": total})
 				return
 			}
 			if len(parts) >= 4 && parts[2] == "badges" {
 				badge := core.Badge(parts[3])
-				err := svc.AwardBadge(r.Context(), user, badge)
-				writeJSON(w, map[string]any{"ok": err == nil, "err": errString(err)})
+				if err := core.ValidateBadgeID(badge); err != nil {
+					writeError(w, http.StatusBadRequest, "invalid_badge", err.Error(), nil)
+					return
+				}
+				if err := svc.AwardBadge(r.Context(), user, badge); err != nil {
+					writeError(w, http.StatusBadRequest, "invalid_input", err.Error(), nil)
+					return
+				}
+				writeJSON(w, map[string]any{"ok": true})
 				return
 			}
 		case http.MethodGet:
 			st, err := svc.GetState(r.Context(), user)
 			if err != nil {
-				http.Error(w, err.Error(), http.StatusInternalServerError)
+				writeError(w, http.StatusInternalServerError, "internal", err.Error(), nil)
 				return
 			}
 			writeJSON(w, st)
 			return
 		}
-		http.NotFound(w, r)
+		writeError(w, http.StatusNotFound, "not_found", "route not found", nil)
 	})
 
 	var handler http.Handler = mux
 	if opts.AllowCORSOrigin != "" {
 		handler = withCORS(handler, opts.AllowCORSOrigin)
 	}
+	if len(opts.APIKeys) > 0 {
+		handler = withAPIKeyAuth(handler, opts.APIKeys)
+	}
+	if opts.RateLimitEnabled && opts.RateLimitRPM > 0 && opts.RateLimitBurst > 0 {
+		handler = withRateLimit(handler, opts.RateLimitRPM, opts.RateLimitBurst)
+	}
 	return handler
 }
 
@@ -155,11 +192,16 @@ func writeJSON(w http.ResponseWriter, v any) {
 	_ = json.NewEncoder(w).Encode(v)
 }
 
-func errString(err error) any {
-	if err == nil {
-		return nil
-	}
-	return err.Error()
+type apiError struct {
+	Code    string `json:"code"`
+	Message string `json:"message"`
+	Details any    `json:"details,omitempty"`
+}
+
+func writeError(w http.ResponseWriter, status int, code, msg string, details any) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	_ = json.NewEncoder(w).Encode(apiError{Code: code, Message: msg, Details: details})
 }
 
 // withCORS wraps a handler with a minimal CORS policy.
@@ -176,3 +218,107 @@ func withCORS(next http.Handler, origin string) http.Handler {
 		next.ServeHTTP(w, r)
 	})
 }
+
+// withAPIKeyAuth enforces a shared API key list.
+func withAPIKeyAuth(next http.Handler, apiKeys []string) http.Handler {
+	allowed := make(map[string]struct{}, len(apiKeys))
+	for _, k := range apiKeys {
+		k = strings.TrimSpace(k)
+		if k != "" {
+			allowed[k] = struct{}{}
+		}
+	}
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		key := extractAPIKey(r)
+		if key == "" {
+			writeError(w, http.StatusUnauthorized, "unauthorized", "missing API key", nil)
+			return
+		}
+		if _, ok := allowed[key]; !ok {
+			writeError(w, http.StatusUnauthorized, "unauthorized", "invalid API key", nil)
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+
+// withRateLimit applies a simple token-bucket limiter per client key.
+func withRateLimit(next http.Handler, rpm int, burst int) http.Handler {
+	limiter := newRateLimiter(rpm, burst)
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		key := clientKey(r)
+		if !limiter.allow(key) {
+			writeError(w, http.StatusTooManyRequests, "rate_limited", "too many requests", nil)
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+
+func extractAPIKey(r *http.Request) string {
+	auth := r.Header.Get("Authorization")
+	if strings.HasPrefix(strings.ToLower(auth), "bearer ") {
+		return strings.TrimSpace(auth[7:])
+	}
+	if key := r.Header.Get("X-API-Key"); key != "" {
+		return key
+	}
+	return ""
+}
+
+// clientKey uses API key if present, otherwise remote IP.
+func clientKey(r *http.Request) string {
+	if key := extractAPIKey(r); key != "" {
+		return key
+	}
+	host, _, err := net.SplitHostPort(r.RemoteAddr)
+	if err != nil {
+		return r.RemoteAddr
+	}
+	return host
+}
+
+type rateLimiter struct {
+	rpm   float64
+	burst float64
+	mu    sync.Mutex
+	b     map[string]*bucket
+}
+
+type bucket struct {
+	tokens float64
+	last   time.Time
+}
+
+func newRateLimiter(rpm, burst int) *rateLimiter {
+	return &rateLimiter{
+		rpm:   float64(rpm),
+		burst: float64(burst),
+		b:     make(map[string]*bucket),
+	}
+}
+
+func (l *rateLimiter) allow(key string) bool {
+	now := time.Now()
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	b, ok := l.b[key]
+	if !ok {
+		l.b[key] = &bucket{tokens: l.burst - 1, last: now}
+		return true
+	}
+
+	elapsed := now.Sub(b.last).Minutes()
+	b.tokens += elapsed * l.rpm
+	if b.tokens > l.burst {
+		b.tokens = l.burst
+	}
+	if b.tokens < 1 {
+		b.last = now
+		return false
+	}
+	b.tokens--
+	b.last = now
+	return true
+}

cmd/gamifykit-server/app.go

@@ -62,8 +62,12 @@ func provideService(hub *realtime.Hub, storage engine.Storage) *engine.GamifySer
 
 func provideHandler(svc *engine.GamifyService, hub *realtime.Hub, cfg *config.Config) http.Handler {
 	return httpapi.NewMux(svc, hub, httpapi.Options{
-		PathPrefix:      cfg.Server.PathPrefix,
-		AllowCORSOrigin: cfg.Server.CORSOrigin,
+		PathPrefix:       cfg.Server.PathPrefix,
+		AllowCORSOrigin:  cfg.Server.CORSOrigin,
+		APIKeys:          cfg.Security.APIKeys,
+		RateLimitEnabled: cfg.Security.EnableRateLimit,
+		RateLimitRPM:     cfg.Security.RateLimit.RequestsPerMinute,
+		RateLimitBurst:   cfg.Security.RateLimit.BurstSize,
 	})
 }
 

config/config.go

@@ -60,10 +60,10 @@ type ServerConfig struct {
 
 // StorageConfig holds storage adapter configuration
 type StorageConfig struct {
-	Adapter string         `json:"adapter" env:"GAMIFYKIT_STORAGE_ADAPTER"`
-	Redis   redis.Config   `json:"redis,omitempty"`
-	SQL     sqlx.Config    `json:"sql,omitempty"`
-	File    FileConfig     `json:"file,omitempty"`
+	Adapter string       `json:"adapter" env:"GAMIFYKIT_STORAGE_ADAPTER"`
+	Redis   redis.Config `json:"redis,omitempty"`
+	SQL     sqlx.Config  `json:"sql,omitempty"`
+	File    FileConfig   `json:"file,omitempty"`
 }
 
 // FileConfig holds JSON file storage configuration
@@ -89,8 +89,9 @@ type MetricsConfig struct {
 
 // SecurityConfig holds security-related configuration
 type SecurityConfig struct {
-	EnableRateLimit bool           `json:"enable_rate_limit" env:"GAMIFYKIT_SECURITY_RATE_LIMIT_ENABLED"`
+	EnableRateLimit bool            `json:"enable_rate_limit" env:"GAMIFYKIT_SECURITY_RATE_LIMIT_ENABLED"`
 	RateLimit       RateLimitConfig `json:"rate_limit,omitempty"`
+	APIKeys         []string        `json:"api_keys,omitempty" env:"GAMIFYKIT_SECURITY_API_KEYS"`
 }
 
 // RateLimitConfig holds rate limiting configuration
@@ -100,6 +101,28 @@ type RateLimitConfig struct {
 	CleanupInterval   time.Duration `json:"cleanup_interval" env:"GAMIFYKIT_SECURITY_RATE_LIMIT_CLEANUP"`
 }
 
+// Validate validates security settings.
+func (s SecurityConfig) Validate() error {
+	var errs []string
+	if s.EnableRateLimit {
+		if s.RateLimit.RequestsPerMinute <= 0 {
+			errs = append(errs, "rate_limit.requests_per_minute must be > 0 when rate limiting is enabled")
+		}
+		if s.RateLimit.BurstSize <= 0 {
+			errs = append(errs, "rate_limit.burst_size must be > 0 when rate limiting is enabled")
+		}
+	}
+	for i, key := range s.APIKeys {
+		if strings.TrimSpace(key) == "" {
+			errs = append(errs, fmt.Sprintf("api_keys[%d] is empty", i))
+		}
+	}
+	if len(errs) > 0 {
+		return errors.New(strings.Join(errs, "; "))
+	}
+	return nil
+}
+
 // Load loads configuration from environment variables and validates it
 func Load() (*Config, error) {
 	cfg := DefaultConfig()
@@ -214,6 +237,7 @@ func DefaultConfig() *Config {
 				BurstSize:         10,
 				CleanupInterval:   5 * time.Minute,
 			},
+			APIKeys: []string{},
 		},
 	}
 }
@@ -247,6 +271,11 @@ func (c *Config) Validate() error {
 		errs = append(errs, fmt.Sprintf("metrics config: %v", err))
 	}
 
+	// Validate security config
+	if err := c.Security.Validate(); err != nil {
+		errs = append(errs, fmt.Sprintf("security config: %v", err))
+	}
+
 	if len(errs) > 0 {
 		return errors.New(strings.Join(errs, "; "))
 	}