feat: implement JWT-based admin API authentication middleware and configuration

Author: maatini

cmd/mail-admin/main.go

@@ -57,7 +57,7 @@ func main() {
 	}
 
 	mux := http.NewServeMux()
-	mux.Handle("/graphql", handler)
+	mux.Handle("/graphql", admin.AuthMiddleware(cfg.AdminAuthSecret)(handler))
 	mux.HandleFunc("/health", func(w http.ResponseWriter, _ *http.Request) {
 		w.WriteHeader(http.StatusOK)
 		_, _ = w.Write([]byte(`{"status":"UP"}`))

go.mod

@@ -24,6 +24,7 @@ require (
 	github.com/go-playground/locales v0.14.1 // indirect
 	github.com/go-playground/universal-translator v0.18.1 // indirect
 	github.com/go-viper/mapstructure/v2 v2.4.0 // indirect
+	github.com/golang-jwt/jwt/v5 v5.3.1 // indirect
 	github.com/hako/durafmt v0.0.0-20210608085754-5c1018a4e16b // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/klauspost/compress v1.18.5 // indirect

go.sum

@@ -28,6 +28,8 @@ github.com/go-playground/validator/v10 v10.30.2 h1:JiFIMtSSHb2/XBUbWM4i/MpeQm9ZK
 github.com/go-playground/validator/v10 v10.30.2/go.mod h1:mAf2pIOVXjTEBrwUMGKkCWKKPs9NheYGabeB04txQSc=
 github.com/go-viper/mapstructure/v2 v2.4.0 h1:EBsztssimR/CONLSZZ04E8qAkxNYq4Qp9LvH92wZUgs=
 github.com/go-viper/mapstructure/v2 v2.4.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
+github.com/golang-jwt/jwt/v5 v5.3.1 h1:kYf81DTWFe7t+1VvL7eS+jKFVWaUnK9cB1qbwn63YCY=
+github.com/golang-jwt/jwt/v5 v5.3.1/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=
 github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
 github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=

internal/admin/auth.go

@@ -0,0 +1,57 @@
+package admin
+
+import (
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"strings"
+
+	"github.com/golang-jwt/jwt/v5"
+)
+
+// AuthMiddleware validates Bearer JWTs signed with HMAC-SHA256.
+// Requests without a valid token receive 401; /health must be registered outside this middleware.
+func AuthMiddleware(secret string) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			tokenStr, ok := bearerToken(r)
+			if !ok {
+				writeUnauthorized(w, r)
+				return
+			}
+
+			_, err := jwt.Parse(tokenStr, func(t *jwt.Token) (any, error) {
+				if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok {
+					return nil, fmt.Errorf("unexpected signing method: %v", t.Header["alg"])
+				}
+				return []byte(secret), nil
+			})
+			if err != nil {
+				writeUnauthorized(w, r)
+				return
+			}
+
+			next.ServeHTTP(w, r)
+		})
+	}
+}
+
+func bearerToken(r *http.Request) (string, bool) {
+	token, found := strings.CutPrefix(r.Header.Get("Authorization"), "Bearer ")
+	return token, found && token != ""
+}
+
+func writeUnauthorized(w http.ResponseWriter, r *http.Request) {
+	slog.Warn("unauthorized request",
+		slog.String("method", r.Method),
+		slog.String("path", r.URL.Path),
+	)
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(http.StatusUnauthorized)
+	_ = json.NewEncoder(w).Encode(map[string]any{
+		"status":  401,
+		"code":    "UNAUTHORIZED",
+		"message": "invalid or missing token",
+	})
+}

internal/admin/auth_test.go

@@ -0,0 +1,79 @@
+package admin
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/golang-jwt/jwt/v5"
+)
+
+const authTestSecret = "test-secret-key"
+
+func signedToken(t *testing.T, secret string, expiry time.Time) string {
+	t.Helper()
+	claims := jwt.RegisteredClaims{ExpiresAt: jwt.NewNumericDate(expiry)}
+	tok, err := jwt.NewWithClaims(jwt.SigningMethodHS256, claims).SignedString([]byte(secret))
+	if err != nil {
+		t.Fatalf("sign token: %v", err)
+	}
+	return tok
+}
+
+func TestAuthMiddleware(t *testing.T) {
+	validToken := signedToken(t, authTestSecret, time.Now().Add(time.Hour))
+	expiredToken := signedToken(t, authTestSecret, time.Now().Add(-time.Hour))
+	wrongSecretToken := signedToken(t, "wrong-secret", time.Now().Add(time.Hour))
+
+	cases := []struct {
+		name       string
+		authHeader string
+		wantStatus int
+	}{
+		{"valid token", "Bearer " + validToken, http.StatusOK},
+		{"no token", "", http.StatusUnauthorized},
+		{"wrong secret", "Bearer " + wrongSecretToken, http.StatusUnauthorized},
+		{"expired token", "Bearer " + expiredToken, http.StatusUnauthorized},
+		{"malformed token", "Bearer notajwt", http.StatusUnauthorized},
+		{"missing bearer prefix", validToken, http.StatusUnauthorized},
+	}
+
+	next := http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	})
+	middleware := AuthMiddleware(authTestSecret)(next)
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			req := httptest.NewRequest(http.MethodPost, "/graphql", nil)
+			if tc.authHeader != "" {
+				req.Header.Set("Authorization", tc.authHeader)
+			}
+			rr := httptest.NewRecorder()
+			middleware.ServeHTTP(rr, req)
+			if rr.Code != tc.wantStatus {
+				t.Errorf("want %d, got %d (body: %s)", tc.wantStatus, rr.Code, rr.Body.String())
+			}
+		})
+	}
+}
+
+func TestAuthMiddleware_ResponseBody(t *testing.T) {
+	next := http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	})
+	middleware := AuthMiddleware(authTestSecret)(next)
+
+	req := httptest.NewRequest(http.MethodPost, "/graphql", nil)
+	rr := httptest.NewRecorder()
+	middleware.ServeHTTP(rr, req)
+
+	if ct := rr.Header().Get("Content-Type"); ct != "application/json" {
+		t.Errorf("Content-Type: want application/json, got %s", ct)
+	}
+	body := rr.Body.String()
+	if body == "" {
+		t.Error("expected non-empty response body on 401")
+	}
+}

internal/config/config.go

@@ -24,6 +24,7 @@ type Config struct {
 	GraphRateLimiterSkip bool
 	GraphProxyURL        string // MS_GRAPH_PROXY_URL — routes Graph calls through Dev Proxy
 	GraphMockToken       string // MS_GRAPH_MOCK_TOKEN — skips OAuth2, makes Graph credentials optional
+	AdminAuthSecret      string // DISPATCH_ADMIN_AUTH_SECRET — HMAC secret for Admin-API JWT auth
 }
 
 func Load() (Config, error) {
@@ -55,6 +56,11 @@ func Load() (Config, error) {
 		}
 	}
 
+	adminAuthSecret := os.Getenv("DISPATCH_ADMIN_AUTH_SECRET")
+	if adminAuthSecret == "" {
+		return Config{}, fmt.Errorf("DISPATCH_ADMIN_AUTH_SECRET is required")
+	}
+
 	bounceMailbox := os.Getenv("MS_GRAPH_BOUNCE_MAILBOX")
 	if bounceMailbox == "" {
 		bounceMailbox = envOr("MS_GRAPH_SENDER_EMAIL", "noreply@dev.local")
@@ -79,6 +85,7 @@ func Load() (Config, error) {
 		GraphRateLimiterSkip: os.Getenv("DISPATCH_GRAPH_RATE_LIMITER_SKIP_SLEEP") == "true",
 		GraphProxyURL:        graphProxyURL,
 		GraphMockToken:       graphMockToken,
+		AdminAuthSecret:      adminAuthSecret,
 	}, nil
 }
 

internal/config/config_test.go

@@ -18,6 +18,7 @@ func setRequiredEnv(t *testing.T) {
 	t.Setenv("MS_GRAPH_CLIENT_ID", "client")
 	t.Setenv("MS_GRAPH_CLIENT_SECRET", "secret")
 	t.Setenv("MS_GRAPH_SENDER_EMAIL", testSenderEmail)
+	t.Setenv("DISPATCH_ADMIN_AUTH_SECRET", "test-secret")
 }
 
 func TestLoad_Success(t *testing.T) {
@@ -60,6 +61,16 @@ func TestLoad_Defaults(t *testing.T) {
 	}
 }
 
+func TestLoad_MissingAdminAuthSecret(t *testing.T) {
+	setRequiredEnv(t)
+	t.Setenv("DISPATCH_ADMIN_AUTH_SECRET", "")
+
+	_, err := Load()
+	if err == nil {
+		t.Fatal("expected error for missing DISPATCH_ADMIN_AUTH_SECRET")
+	}
+}
+
 func TestLoad_MissingNatsURL(t *testing.T) {
 	t.Setenv("NATS_URL", "")
 	t.Setenv("MS_GRAPH_TENANT_ID", "tenant")
@@ -75,6 +86,7 @@ func TestLoad_MissingNatsURL(t *testing.T) {
 
 func TestLoad_MissingGraphCredentials(t *testing.T) {
 	t.Setenv("NATS_URL", testNatsURL)
+	t.Setenv("DISPATCH_ADMIN_AUTH_SECRET", "test-secret")
 	// MS_GRAPH_MOCK_TOKEN is not set → credentials are required
 
 	cases := []struct {
@@ -107,6 +119,7 @@ func TestLoad_MissingGraphCredentials(t *testing.T) {
 func TestLoad_MockTokenSkipsCredentialCheck(t *testing.T) {
 	t.Setenv("NATS_URL", testNatsURL)
 	t.Setenv("MS_GRAPH_MOCK_TOKEN", "dev-token")
+	t.Setenv("DISPATCH_ADMIN_AUTH_SECRET", "test-secret")
 	// deliberately leave Graph credentials unset
 
 	cfg, err := Load()