Add JWT logout with server-side token revocation

README.md

@@ -42,9 +42,15 @@ Sign in with an existing admin account. To create the first one:
 - **Local development:** load [`seed_dev.sql`](seed_dev.sql), which seeds
   `admin@test.com` / `password` (alongside a seed driver).
 
-Deactivating a user blocks new logins immediately, but it doesn't revoke
-sessions already issued — any existing session cookie or JWT for that user
-stays valid until it expires (up to 24 hours).
+Signing out of the admin UI revokes that session's token server-side, so the
+cookie is dead even if someone copied its value — the same revocation
+`POST /api/v1/auth/logout` performs for API clients.
+
+Deactivating a user still blocks new logins immediately without revoking
+sessions already issued: an existing session cookie or JWT for that user stays
+valid until it expires (up to 24 hours) or until that session is logged out.
+Forcing a deactivated user's sessions to end is a follow-up — it needs a
+per-user cutoff rather than the per-token blocklist added here.
 
 Behind a reverse proxy (nginx, an ALB, etc.), set `TRUST_PROXY_HEADERS=true`
 so the server reads the real client IP and scheme from `X-Forwarded-For` /
@@ -228,6 +234,7 @@ The feed is served at a configurable HTTP endpoint (e.g., `GET /gtfs-rt/vehicle-
 |Endpoint                        |Method|Purpose                                             |
 |--------------------------------|------|----------------------------------------------------|
 |`POST /api/v1/auth/login`       |POST  |Driver login → returns JWT                          |
+|`POST /api/v1/auth/logout`      |POST  |Revoke the caller's own JWT → 204 No Content        |
 |`POST /api/v1/locations`        |POST  |Single location report from driver app              |
 |`GET /gtfs-rt/vehicle-positions`|GET   |GTFS-RT feed (protobuf or JSON)                     |
 |`GET /api/v1/admin/vehicles`    |GET   |List vehicles                                       |
@@ -319,6 +326,45 @@ export LOCATION_RETENTION_PERIOD=2160h
 export LOCATION_PRUNE_INTERVAL=1h
 ```
 
+**`POST /api/v1/auth/logout` — token revocation**
+
+JWTs are stateless, so until now the only way to end a session early was to
+rotate `JWT_SECRET`, which logs out every user at once. Logout records the
+token's `jti` claim in a `revoked_tokens` blocklist, and every authenticated
+request checks it, so a single token can be retired for the rest of its
+lifetime.
+
+- Authenticated (`Authorization: Bearer <token>`), but not admin-only — every
+  user can log themselves out.
+- Revokes the caller's own token; there is no way to revoke someone else's.
+- Returns `204 No Content` on success, `401 Unauthorized` without a valid
+  token, and `500 Internal Server Error` if the revocation can't be recorded.
+- The revocation check fails closed: if the database is unreachable,
+  authenticated requests are rejected rather than allowed through.
+- The admin UI's `vp_session` cookie carries the same JWT, so logging out
+  through the API also ends that browser session (and vice versa).
+
+```bash
+# Log in, use the token, then revoke it
+TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"admin@test.com","password":"password"}' | jq -r .token)
+
+curl -i -X POST http://localhost:8080/api/v1/auth/logout \
+  -H "Authorization: Bearer $TOKEN"          # -> 204 No Content
+
+curl -i http://localhost:8080/api/v1/admin/status \
+  -H "Authorization: Bearer $TOKEN"          # -> 401 {"error":"invalid token"}
+```
+
+Tokens issued before this endpoint existed carry no `jti` and cannot be
+revoked. They are still accepted (so deploying doesn't sign everyone out) and
+logged with a warning; because tokens live 24 hours, that warning stops
+appearing within a day of deploying.
+
+Revocation rows are never deleted — the table grows one row per logout. A
+periodic cleanup job keyed on `expires_at` is a planned follow-up.
+
 **Technology Stack:**
 
 - **Language:** Go (aligns with Maglev and OTSF’s server-side direction)
@@ -454,6 +500,7 @@ This timeline follows the GSoC 2026 standard coding period (May 25 – August 24
 
 - Implement user authentication:
   - `POST /api/v1/auth/login` — email + password → JWT token
+  - `POST /api/v1/auth/logout` — revoke the caller's token server-side
   - JWT middleware for all authenticated endpoints
   - Token refresh flow
 - Implement API key authentication for feed consumers (separate from user auth)

admin_page_handlers.go

@@ -78,6 +78,8 @@ type adminUI struct {
 	vehicleCreator VehicleCreator
 	userManager    userManager
 	assignments    assignmentManager
+	tokenChecker   TokenChecker
+	tokenRevoker   TokenRevoker
 	jwtSecret      []byte
 	loginLimiter   *LoginRateLimiter
 	cfg            adminUIConfig
@@ -107,6 +109,8 @@ func newAdminUI(store appStore, tracker *Tracker, jwtSecret []byte, limiter *Log
 		vehicleCreator: store,
 		userManager:    store,
 		assignments:    store,
+		tokenChecker:   store,
+		tokenRevoker:   store,
 		jwtSecret:      jwtSecret,
 		loginLimiter:   limiter,
 		cfg:            cfg,
@@ -117,7 +121,7 @@ func newAdminUI(store appStore, tracker *Tracker, jwtSecret []byte, limiter *Log
 // static assets — that's the caller's responsibility (main's handler
 // construction), keeping this function focused on admin routes only.
 func registerAdminUI(mux *http.ServeMux, ui *adminUI) {
-	protect := requireAdminPage(ui.jwtSecret)
+	protect := requireAdminPage(ui.jwtSecret, ui.tokenChecker)
 
 	mux.HandleFunc("GET /admin/login", ui.loginPage)
 	mux.HandleFunc("POST /admin/login", ui.loginSubmit)
@@ -146,15 +150,15 @@ func registerAdminUI(mux *http.ServeMux, ui *adminUI) {
 }
 
 func (ui *adminUI) rootRedirect(w http.ResponseWriter, r *http.Request) {
-	if _, ok := adminClaimsFromCookie(r, ui.jwtSecret); ok {
+	if _, ok := adminClaimsFromCookie(r, ui.jwtSecret, ui.tokenChecker); ok {
 		http.Redirect(w, r, "/admin/dashboard", http.StatusSeeOther)
 		return
 	}
 	http.Redirect(w, r, "/admin/login", http.StatusSeeOther)
 }
 
 func (ui *adminUI) loginPage(w http.ResponseWriter, r *http.Request) {
-	if _, ok := adminClaimsFromCookie(r, ui.jwtSecret); ok {
+	if _, ok := adminClaimsFromCookie(r, ui.jwtSecret, ui.tokenChecker); ok {
 		http.Redirect(w, r, "/admin/dashboard", http.StatusSeeOther)
 		return
 	}
@@ -227,7 +231,14 @@ func (ui *adminUI) renderLogin(w http.ResponseWriter, status int, errMsg, email
 	})
 }
 
+// logout revokes the session's JWT server-side and clears the cookie. The
+// route is deliberately unauthenticated (an expired session must still be
+// able to log out), so a cookie that no longer validates is simply cleared.
+// A revocation failure is logged but still clears the cookie and redirects:
+// leaving the user stuck on an error page would not make the token any less
+// valid.
 func (ui *adminUI) logout(w http.ResponseWriter, r *http.Request) {
+	revokeSessionCookie(r, ui.jwtSecret, ui.tokenRevoker)
 	clearSessionCookie(w)
 	http.Redirect(w, r, "/admin/login", http.StatusSeeOther)
 }

admin_page_handlers_test.go

@@ -151,6 +151,40 @@ func TestAdminLogout(t *testing.T) {
 	assert.Equal(t, -1, w.Result().Cookies()[0].MaxAge)
 }
 
+// TestAdminLogoutRevokesSession verifies the admin UI's sign-out ends the
+// token server-side, not just the browser's copy of it: after logging out,
+// the same cookie value must no longer open an admin page.
+func TestAdminLogoutRevokesSession(t *testing.T) {
+	ui := newTestAdminUI(t)
+	revocations := newFakeRevocations()
+	ui.tokenChecker = revocations
+	ui.tokenRevoker = revocations
+	mux := http.NewServeMux()
+	registerAdminUI(mux, ui)
+
+	cookie := cookieFor(t, "admin")
+
+	before := httptest.NewRequest(http.MethodGet, "/admin/dashboard", nil)
+	before.AddCookie(cookie)
+	beforeRec := httptest.NewRecorder()
+	mux.ServeHTTP(beforeRec, before)
+	require.Equal(t, http.StatusOK, beforeRec.Code, "the session must work before logout")
+
+	logout := httptest.NewRequest(http.MethodPost, "/admin/logout", nil)
+	logout.AddCookie(cookie)
+	logoutRec := httptest.NewRecorder()
+	mux.ServeHTTP(logoutRec, logout)
+	require.Equal(t, http.StatusSeeOther, logoutRec.Code)
+	assert.Contains(t, revocations.revoked, jtiOf(t, cookie.Value), "sign-out must revoke the session token")
+
+	after := httptest.NewRequest(http.MethodGet, "/admin/dashboard", nil)
+	after.AddCookie(cookie)
+	afterRec := httptest.NewRecorder()
+	mux.ServeHTTP(afterRec, after)
+	assert.Equal(t, http.StatusSeeOther, afterRec.Code, "a replayed cookie must no longer work")
+	assert.Equal(t, "/admin/login", afterRec.Header().Get("Location"))
+}
+
 func TestAdminPagesRedirectWithoutSession(t *testing.T) {
 	ui := newTestAdminUI(t)
 	mux := http.NewServeMux()

admin_session.go

@@ -3,7 +3,7 @@ package main
 import (
 	"log/slog"
 	"net/http"
-	"time"
+	"strconv"
 
 	"github.com/golang-jwt/jwt/v5"
 )
@@ -31,13 +31,56 @@ func setSessionCookie(w http.ResponseWriter, r *http.Request, token string, trus
 		Name:     sessionCookieName,
 		Value:    token,
 		Path:     "/",
-		MaxAge:   int((24 * time.Hour).Seconds()),
+		MaxAge:   int(tokenLifetime.Seconds()),
 		HttpOnly: true,
 		SameSite: http.SameSiteLaxMode,
 		Secure:   requestIsSecure(r, trustProxy),
 	})
 }
 
+// revokeSessionCookie revokes the JWT carried by the session cookie, so
+// signing out of the admin UI ends the token itself and not just the browser's
+// copy of it. It is best-effort by design: the caller clears the cookie and
+// redirects regardless, and a cookie that no longer parses has nothing to
+// revoke. Errors are logged rather than returned for the same reason.
+func revokeSessionCookie(r *http.Request, secret []byte, revoker TokenRevoker) {
+	c, err := r.Cookie(sessionCookieName)
+	if err != nil || c.Value == "" {
+		return
+	}
+	claims, err := parseSessionToken(c.Value, secret)
+	if err != nil {
+		slog.Debug("admin logout: session cookie no longer valid, nothing to revoke", "error", err)
+		return
+	}
+	jti, _ := claims["jti"].(string)
+	if jti == "" {
+		// Pre-revocation token; see checkRevoked.
+		slog.Warn("admin logout: session token has no jti, nothing to revoke", "sub", claims["sub"])
+		return
+	}
+	sub, err := claims.GetSubject()
+	if err != nil {
+		slog.Warn("admin logout: unreadable sub claim", "error", err)
+		return
+	}
+	userID, err := strconv.ParseInt(sub, 10, 64)
+	if err != nil {
+		slog.Warn("admin logout: sub claim is not a user ID", "sub", sub, "error", err)
+		return
+	}
+	expiresAt, err := claims.GetExpirationTime()
+	if err != nil || expiresAt == nil {
+		slog.Warn("admin logout: unreadable exp claim", "sub", sub, "error", err)
+		return
+	}
+	if err := revoker.RevokeToken(r.Context(), jti, userID, expiresAt.Time); err != nil {
+		slog.Error("admin logout: failed to revoke session token", "sub", sub, "error", err)
+		return
+	}
+	slog.Info("admin session token revoked", "sub", sub)
+}
+
 func clearSessionCookie(w http.ResponseWriter) {
 	http.SetCookie(w, &http.Cookie{
 		Name:     sessionCookieName,
@@ -50,8 +93,14 @@ func clearSessionCookie(w http.ResponseWriter) {
 }
 
 // adminClaimsFromCookie validates the session cookie's JWT via the shared
-// parseSessionToken path and additionally requires the admin role.
-func adminClaimsFromCookie(r *http.Request, secret []byte) (jwt.MapClaims, bool) {
+// parseSessionToken path, rejects a revoked token via the shared checkRevoked
+// path, and additionally requires the admin role.
+//
+// This is the browser half of the revocation enforcement in requireAuth: both
+// carry the same JWT, so a token revoked through POST /api/v1/auth/logout must
+// end the admin session too. A checker error is treated as "no session" —
+// fail closed, matching requireAuth.
+func adminClaimsFromCookie(r *http.Request, secret []byte, checker TokenChecker) (jwt.MapClaims, bool) {
 	c, err := r.Cookie(sessionCookieName)
 	if err != nil || c.Value == "" {
 		return nil, false
@@ -60,6 +109,15 @@ func adminClaimsFromCookie(r *http.Request, secret []byte) (jwt.MapClaims, bool)
 	if err != nil {
 		return nil, false
 	}
+	revoked, err := checkRevoked(r.Context(), claims, checker)
+	if err != nil {
+		slog.Error("admin session: revocation check failed", "error", err, "path", r.URL.Path)
+		return nil, false
+	}
+	if revoked {
+		slog.Warn("admin session: rejected revoked token", "sub", claims["sub"], "path", r.URL.Path)
+		return nil, false
+	}
 	if role, _ := claims["role"].(string); role != roleAdmin {
 		return nil, false
 	}
@@ -68,10 +126,10 @@ func adminClaimsFromCookie(r *http.Request, secret []byte) (jwt.MapClaims, bool)
 
 // requireAdminPage guards HTML admin pages: unauthenticated or non-admin
 // visitors are redirected to the login page (303) rather than given JSON.
-func requireAdminPage(secret []byte) func(http.Handler) http.Handler {
+func requireAdminPage(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) {
-			claims, ok := adminClaimsFromCookie(r, secret)
+			claims, ok := adminClaimsFromCookie(r, secret, checker)
 			if !ok {
 				http.Redirect(w, r, "/admin/login", http.StatusSeeOther)
 				return