feat(auth): implement JWT logout with token revocation

auth.go

@@ -5,12 +5,13 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
-	"log"
+	"log/slog"
 	"net/http"
 	"strings"
 	"time"
 
 	"github.com/golang-jwt/jwt/v5"
+	"github.com/google/uuid"
 	"github.com/jackc/pgx/v5"
 	"golang.org/x/crypto/bcrypt"
 )
@@ -49,6 +50,16 @@ type UserFetcher interface {
 	GetUserByEmail(ctx context.Context, email string) (*User, error)
 }
 
+// TokenChecker can verify whether a JWT has been revoked.
+type TokenChecker interface {
+	IsTokenRevoked(ctx context.Context, jti string) (bool, error)
+}
+
+// TokenRevoker can invalidate a JWT before its natural expiry.
+type TokenRevoker interface {
+	RevokeToken(ctx context.Context, jti string, expiresAt time.Time) error
+}
+
 func handleLogin(fetcher UserFetcher, secret []byte) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		r.Body = http.MaxBytesReader(w, r.Body, 1<<10)
@@ -71,7 +82,7 @@ func handleLogin(fetcher UserFetcher, secret []byte) http.HandlerFunc {
 				writeJSON(w, http.StatusUnauthorized, map[string]string{"error": "invalid email or password"})
 				return
 			}
-			log.Printf("login: database error: %v", err)
+			slog.Error("login: database error", "error", err)
 			writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "internal server error"})
 			return
 		}
@@ -82,14 +93,14 @@ func handleLogin(fetcher UserFetcher, secret []byte) http.HandlerFunc {
 				writeJSON(w, http.StatusUnauthorized, map[string]string{"error": "invalid email or password"})
 				return
 			}
-			log.Printf("login: bcrypt error: %v", err)
+			slog.Error("login: bcrypt error", "error", err)
 			writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "internal server error"})
 			return
 		}
 
 		tokenStr, err := generateJWT(user, secret)
 		if err != nil {
-			log.Printf("login: failed to generate JWT: %v", err)
+			slog.Error("login: failed to generate JWT", "error", err)
 			writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "internal server error"})
 			return
 		}
@@ -99,6 +110,7 @@ func handleLogin(fetcher UserFetcher, secret []byte) http.HandlerFunc {
 }
 
 // generateJWT creates a signed JWT valid for 24 hours.
+// A unique jti (JWT ID) claim is included so the token can be individually revoked.
 func generateJWT(user *User, secret []byte) (string, error) {
 	now := time.Now()
 
@@ -109,13 +121,15 @@ func generateJWT(user *User, secret []byte) (string, error) {
 		"exp":   now.Add(24 * time.Hour).Unix(),
 		"iat":   now.Unix(),
 		"iss":   "vehicle-positions-api",
+		"jti":   uuid.New().String(),
 	}
 	token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
 	return token.SignedString(secret)
 }
 
 // requireAuth is middleware that validates the Bearer JWT on protected routes.
-func requireAuth(secret []byte) func(http.Handler) http.Handler {
+// It checks the token signature, expiry, and whether the jti has been revoked.
+func requireAuth(secret []byte, checker TokenChecker) func(http.Handler) http.Handler {
 	return func(next http.Handler) http.Handler {
 		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 			authHeader := r.Header.Get("Authorization")
@@ -134,7 +148,7 @@ func requireAuth(secret []byte) func(http.Handler) http.Handler {
 			}, jwt.WithValidMethods([]string{"HS256"}), jwt.WithIssuer("vehicle-positions-api"))
 
 			if err != nil || !token.Valid {
-				log.Printf("auth: token validation failed: %v", err)
+				slog.Warn("auth: token validation failed", "error", err)
 				writeJSON(w, http.StatusUnauthorized, map[string]string{"error": "invalid token"})
 				return
 			}
@@ -144,8 +158,53 @@ func requireAuth(secret []byte) func(http.Handler) http.Handler {
 				writeJSON(w, http.StatusUnauthorized, map[string]string{"error": "invalid token claims"})
 				return
 			}
+
+			if jti, ok := claims["jti"].(string); ok && jti != "" {
+				revoked, err := checker.IsTokenRevoked(r.Context(), jti)
+				if err != nil {
+					slog.Error("auth: revocation check failed", "error", err)
+					writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "internal server error"})
+					return
+				}
+				if revoked {
+					writeJSON(w, http.StatusUnauthorized, map[string]string{"error": "token has been revoked"})
+					return
+				}
+			}
+
 			ctx := context.WithValue(r.Context(), claimsKey, claims)
 			next.ServeHTTP(w, r.WithContext(ctx))
 		})
 	}
 }
+
+func handleLogout(revoker TokenRevoker) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		claims, ok := r.Context().Value(claimsKey).(jwt.MapClaims)
+		if !ok {
+			writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "internal server error"})
+			return
+		}
+
+		jti, ok := claims["jti"].(string)
+		if !ok || jti == "" {
+			writeJSON(w, http.StatusBadRequest, map[string]string{"error": "token missing jti claim"})
+			return
+		}
+
+		expFloat, ok := claims["exp"].(float64)
+		if !ok {
+			writeJSON(w, http.StatusBadRequest, map[string]string{"error": "token missing exp claim"})
+			return
+		}
+		expiresAt := time.Unix(int64(expFloat), 0)
+
+		if err := revoker.RevokeToken(r.Context(), jti, expiresAt); err != nil {
+			slog.Error("logout: failed to revoke token", "error", err)
+			writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "internal server error"})
+			return
+		}
+
+		writeJSON(w, http.StatusOK, map[string]string{"message": "logged out successfully"})
+	}
+}

auth_test.go

@@ -22,6 +22,30 @@ type mockUserStore struct {
 	err  error
 }
 
+type noopTokenChecker struct{}
+
+func (noopTokenChecker) IsTokenRevoked(_ context.Context, _ string) (bool, error) {
+	return false, nil
+}
+
+type mockTokenChecker struct {
+	revokedJTIs map[string]bool
+}
+
+func (m *mockTokenChecker) IsTokenRevoked(_ context.Context, jti string) (bool, error) {
+	return m.revokedJTIs[jti], nil
+}
+
+type mockTokenRevoker struct {
+	calledJTI string
+	err       error
+}
+
+func (m *mockTokenRevoker) RevokeToken(_ context.Context, jti string, _ time.Time) error {
+	m.calledJTI = jti
+	return m.err
+}
+
 var testSecret = []byte("super-secret-test-key-32-bytes!!")
 
 func (m *mockUserStore) GetUserByEmail(ctx context.Context, email string) (*User, error) {
@@ -131,7 +155,7 @@ func TestRequireAuth_MissingHeader(t *testing.T) {
 	req := httptest.NewRequest("POST", "/api/v1/locations", nil)
 	w := httptest.NewRecorder()
 
-	requireAuth(testSecret)(dummyHandler()).ServeHTTP(w, req)
+	requireAuth(testSecret, noopTokenChecker{})(dummyHandler()).ServeHTTP(w, req)
 
 	assert.Equal(t, http.StatusUnauthorized, w.Code)
 }
@@ -151,7 +175,7 @@ func TestRequireAuth_MalformedHeader(t *testing.T) {
 			req.Header.Set("Authorization", tc.header)
 			w := httptest.NewRecorder()
 
-			requireAuth(testSecret)(dummyHandler()).ServeHTTP(w, req)
+			requireAuth(testSecret, noopTokenChecker{})(dummyHandler()).ServeHTTP(w, req)
 
 			assert.Equal(t, http.StatusUnauthorized, w.Code)
 		})
@@ -163,7 +187,7 @@ func TestRequireAuth_InvalidToken(t *testing.T) {
 	req.Header.Set("Authorization", "Bearer notavalidtoken")
 	w := httptest.NewRecorder()
 
-	requireAuth(testSecret)(dummyHandler()).ServeHTTP(w, req)
+	requireAuth(testSecret, noopTokenChecker{})(dummyHandler()).ServeHTTP(w, req)
 
 	assert.Equal(t, http.StatusUnauthorized, w.Code)
 }
@@ -180,7 +204,7 @@ func TestRequireAuth_ExpiredToken(t *testing.T) {
 	req.Header.Set("Authorization", "Bearer "+tokenStr)
 	rr := httptest.NewRecorder()
 
-	middleware := requireAuth(testSecret)
+	middleware := requireAuth(testSecret, noopTokenChecker{})
 	handler := middleware(dummyHandler())
 
 	handler.ServeHTTP(rr, req)
@@ -206,7 +230,7 @@ func TestRequireAuth_ValidToken(t *testing.T) {
 		w.WriteHeader(http.StatusOK)
 	})
 
-	requireAuth(testSecret)(handler).ServeHTTP(w, req)
+	requireAuth(testSecret, noopTokenChecker{})(handler).ServeHTTP(w, req)
 
 	assert.Equal(t, http.StatusOK, w.Code)
 }
@@ -233,6 +257,10 @@ func TestGenerateJWT_Claims(t *testing.T) {
 	exp, ok := claims["exp"].(float64)
 	require.True(t, ok)
 	assert.True(t, exp > float64(time.Now().Unix()))
+
+	jti, ok := claims["jti"].(string)
+	require.True(t, ok)
+	assert.NotEmpty(t, jti)
 }
 
 func TestRequireAuth_WrongSecret(t *testing.T) {
@@ -245,7 +273,7 @@ func TestRequireAuth_WrongSecret(t *testing.T) {
 	req.Header.Set("Authorization", "Bearer "+tokenStr)
 	rr := httptest.NewRecorder()
 
-	middleware := requireAuth(testSecret)
+	middleware := requireAuth(testSecret, noopTokenChecker{})
 	handler := middleware(dummyHandler())
 
 	handler.ServeHTTP(rr, req)
@@ -262,9 +290,100 @@ func TestRequireAuth_AlgorithmConfusion(t *testing.T) {
 	req.Header.Set("Authorization", "Bearer "+tokenStr)
 	rr := httptest.NewRecorder()
 
-	middleware := requireAuth(testSecret)
+	middleware := requireAuth(testSecret, noopTokenChecker{})
 	handler := middleware(dummyHandler())
 
 	handler.ServeHTTP(rr, req)
 	assert.Equal(t, http.StatusUnauthorized, rr.Code)
 }
+
+func TestHandleLogout_Success(t *testing.T) {
+	token, err := generateJWT(&User{ID: 1, Email: "driver@test.com", Role: "driver"}, testSecret)
+	require.NoError(t, err)
+
+	revoker := &mockTokenRevoker{}
+
+	req := httptest.NewRequest("POST", "/api/v1/auth/logout", nil)
+	req.Header.Set("Authorization", "Bearer "+token)
+	w := httptest.NewRecorder()
+
+	requireAuth(testSecret, noopTokenChecker{})(handleLogout(revoker)).ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+	var resp map[string]string
+	err = json.NewDecoder(w.Body).Decode(&resp)
+	require.NoError(t, err)
+	assert.Equal(t, "logged out successfully", resp["message"])
+	assert.NotEmpty(t, revoker.calledJTI)
+}
+
+func TestHandleLogout_RevokerError(t *testing.T) {
+	token, err := generateJWT(&User{ID: 1, Email: "driver@test.com", Role: "driver"}, testSecret)
+	require.NoError(t, err)
+
+	revoker := &mockTokenRevoker{err: assert.AnError}
+
+	req := httptest.NewRequest("POST", "/api/v1/auth/logout", nil)
+	req.Header.Set("Authorization", "Bearer "+token)
+	w := httptest.NewRecorder()
+
+	requireAuth(testSecret, noopTokenChecker{})(handleLogout(revoker)).ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusInternalServerError, w.Code)
+}
+
+func TestRequireAuth_RevokedToken(t *testing.T) {
+	token, err := generateJWT(&User{ID: 1, Email: "driver@test.com", Role: "driver"}, testSecret)
+	require.NoError(t, err)
+
+	parsed, err := jwt.Parse(token, func(t *jwt.Token) (interface{}, error) {
+		return testSecret, nil
+	})
+	require.NoError(t, err)
+	claims, ok := parsed.Claims.(jwt.MapClaims)
+	require.True(t, ok)
+	jti, ok := claims["jti"].(string)
+	require.True(t, ok)
+
+	checker := &mockTokenChecker{revokedJTIs: map[string]bool{jti: true}}
+
+	req := httptest.NewRequest("POST", "/api/v1/locations", nil)
+	req.Header.Set("Authorization", "Bearer "+token)
+	w := httptest.NewRecorder()
+
+	requireAuth(testSecret, checker)(dummyHandler()).ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusUnauthorized, w.Code)
+	var resp map[string]string
+	err = json.NewDecoder(w.Body).Decode(&resp)
+	require.NoError(t, err)
+	assert.Equal(t, "token has been revoked", resp["error"])
+}
+
+func TestLoginLogoutRevokeFlow(t *testing.T) {
+	token, err := generateJWT(&User{ID: 2, Email: "bus@test.com", Role: "driver"}, testSecret)
+	require.NoError(t, err)
+
+	revokedSet := map[string]bool{}
+	checker := &mockTokenChecker{revokedJTIs: revokedSet}
+	revoker := &mockTokenRevoker{}
+
+	req1 := httptest.NewRequest("POST", "/api/v1/locations", nil)
+	req1.Header.Set("Authorization", "Bearer "+token)
+	w1 := httptest.NewRecorder()
+	requireAuth(testSecret, checker)(dummyHandler()).ServeHTTP(w1, req1)
+	assert.Equal(t, http.StatusOK, w1.Code, "token should be valid before logout")
+
+	logoutReq := httptest.NewRequest("POST", "/api/v1/auth/logout", nil)
+	logoutReq.Header.Set("Authorization", "Bearer "+token)
+	logoutW := httptest.NewRecorder()
+	requireAuth(testSecret, checker)(handleLogout(revoker)).ServeHTTP(logoutW, logoutReq)
+	require.Equal(t, http.StatusOK, logoutW.Code, "logout must succeed")
+
+	revokedSet[revoker.calledJTI] = true
+	req2 := httptest.NewRequest("POST", "/api/v1/locations", nil)
+	req2.Header.Set("Authorization", "Bearer "+token)
+	w2 := httptest.NewRecorder()
+	requireAuth(testSecret, checker)(dummyHandler()).ServeHTTP(w2, req2)
+	assert.Equal(t, http.StatusUnauthorized, w2.Code, "token should be rejected after logout")
+}

go.mod

@@ -6,6 +6,7 @@ require (
 	github.com/MobilityData/gtfs-realtime-bindings/golang/gtfs v1.0.0
 	github.com/golang-jwt/jwt/v5 v5.3.1
 	github.com/golang-migrate/migrate/v4 v4.19.1
+	github.com/google/uuid v1.6.0
 	github.com/jackc/pgx/v5 v5.8.0
 	github.com/stretchr/testify v1.11.1
 	golang.org/x/crypto v0.48.0

go.sum

@@ -36,6 +36,8 @@ github.com/golang-migrate/migrate/v4 v4.19.1 h1:OCyb44lFuQfYXYLx1SCxPZQGU7mcaZ7g
 github.com/golang-migrate/migrate/v4 v4.19.1/go.mod h1:CTcgfjxhaUtsLipnLoQRWCrjYXycRz/g5+RWDuYgPrE=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
 github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
 github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=

main.go

@@ -77,9 +77,10 @@ func main() {
 		writeJSON(w, http.StatusOK, map[string]string{"status": "ok"})
 	})
 
-	authMiddleware := requireAuth(jwtSecret)
+	authMiddleware := requireAuth(jwtSecret, store)
 
 	mux.Handle("POST /api/v1/locations", authMiddleware(handlePostLocation(store, tracker, rateLimiter)))
+	mux.Handle("POST /api/v1/auth/logout", authMiddleware(handleLogout(store)))
 
 	srv := &http.Server{
 		Addr:         ":" + port,

migrations/000006_add_revoked_tokens.down.sql

@@ -0,0 +1 @@
+DROP TABLE IF EXISTS revoked_tokens;

migrations/000006_add_revoked_tokens.up.sql

@@ -0,0 +1,4 @@
+CREATE TABLE IF NOT EXISTS revoked_tokens (
+    jti        TEXT PRIMARY KEY,
+    expires_at TIMESTAMPTZ NOT NULL
+);