feat: session listing/revocation and refresh token rotation

[Copilot]

Stateless JWTs can't be revoked server-side, and long-lived tokens are a liability. This adds opt-in server-side session tracking with refresh token rotation — both features are strictly additive; existing code without a SessionStore is unaffected.

auth package

• Session / SessionStore — new type and 7-method interface for session CRUD; only the SHA-256 hash of the refresh token is persisted
• CreateTokenWithSession(ctx, userID, sessionID) — embeds session ID as the JWT jti claim
• ParseTokenClaims(tokenString) — validates signature, ignores expiry (used by logout to parse potentially expired access tokens)
• Config.Sessions SessionStore — when set, Middleware and AdminMiddleware validate jti against the store on every request; API key auth bypasses the check

handler package

• AuthHandler gains Sessions, RefreshTokenTTL, RefreshCookieName fields
  • Login/Signup create a session and return refresh_token in the response
  • Logout revokes the session by extracting jti from the (possibly expired) access token
  • New RefreshToken handler: validates the refresh token hash, atomically deletes the old session, issues a new session + rotated token pair
• SessionHandler (new) — List (200), Revoke (204), RevokeAll (204)

Usage

jwtMgr, _ := auth.NewJWTManager(secret, 15*time.Minute, "myapp") // short-lived access tokens

authHandler := &handler.AuthHandler{
    Users:             userStore,
    JWT:               jwtMgr,
    Sessions:          sessionStore,         // enables everything
    RefreshTokenTTL:   7 * 24 * time.Hour,
    RefreshCookieName: "refresh",            // optional HttpOnly cookie
    CookieName:        "session",
    SecureCookies:     true,
}

sessionHandler := &handler.SessionHandler{
    Sessions:     sessionStore,
    URLParamFunc: chi.URLParam,
}

// Middleware validates jti on every request
cfg := auth.Config{CookieName: "session", Sessions: sessionStore}
r.Use(auth.Middleware(jwtMgr, cfg, apiKeyStore))

r.Post("/auth/refresh",    authHandler.RefreshToken)
r.Get("/sessions",         sessionHandler.List)
r.Delete("/sessions/{id}", sessionHandler.Revoke)
r.Delete("/sessions",      sessionHandler.RevokeAll)

[Copilot]

Pull request overview

Adds optional server-side session tracking and refresh token rotation to enable session listing/revocation and mitigate long-lived token risk, while keeping existing JWT-only deployments working when no SessionStore is configured.

Changes:

• Introduces auth.Session / auth.SessionStore and embeds session IDs into JWT jti via CreateTokenWithSession.
• Adds session-aware auth flows in handler.AuthHandler (refresh token issuance, logout revocation, refresh rotation) plus a new SessionHandler for list/revoke endpoints.
• Updates middleware to optionally validate jti against a session store (API keys bypass), and expands tests/docs accordingly.

Show a summary per file

File	Description
handler/session.go	New session management HTTP handler (list/revoke/revoke-all).
handler/session_test.go	Tests for SessionHandler list and revocation behaviors.
handler/helpers.go	Adds refresh-cookie helpers and a token extractor used by logout.
handler/helpers_test.go	Adds a mockSessionStore and a helper for session-enabled auth handler tests.
handler/auth.go	Adds session-aware token issuance, logout session revocation, and refresh rotation endpoint.
handler/auth_test.go	Adds tests for session-enabled login/signup/logout/refresh flows.
auth/types.go	Adds Session model, SessionStore interface, and ErrSessionRevoked.
auth/middleware.go	Extends middleware to return sessionID from JWT and validate sessions via store.
auth/middleware_test.go	Adds mocks and test coverage for session validation + updated resolveUser signature.
auth/jwt.go	Adds CreateTokenWithSession and ParseTokenClaims (signature-validated, time-claims ignored).
auth/jwt_test.go	Adds test coverage for session jti embedding and ParseTokenClaims.
README.md	Documents session store wiring, refresh rotation, and new session endpoints.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comments suppressed due to low confidence (2)

handler/auth.go:301

• In RefreshToken, if two refresh requests race on the same refresh token, the second request can reach DeleteSession after the first has already deleted it; per SessionStore docs DeleteSession should then return sql.ErrNoRows. The current code treats any DeleteSession error as a 500, which would incorrectly surface a server error for an already-consumed/invalid refresh token. Handle sql.ErrNoRows from DeleteSession as an unauthorized "invalid or expired refresh token" response (and consider adjusting the "revoked atomically" comment unless the store guarantees atomic rotation).

	// Revoke the consumed session before issuing a new one.
	if err := h.Sessions.DeleteSession(r.Context(), sess.ID, sess.UserID); err != nil {
		slog.ErrorContext(r.Context(), "failed to revoke old session on refresh", slog.Any("error", err))
		writeError(r.Context(), w, http.StatusInternalServerError, "internal server error")
		return
	}

auth/middleware.go:168

• Session validation treats any SessionStore error (including transient DB outages) as a 401 "session expired or revoked". That can cause hard-to-diagnose auth failures and prevents correct 5xx handling/alerting. Consider: (1) treating sql.ErrNoRows / missing session / expired session as 401, but (2) returning 500 for other store errors (and logging them).

			if cfg.Sessions != nil && sessionID != "" {
				sess, serr := cfg.Sessions.FindSessionByID(r.Context(), sessionID)
				if serr != nil || sess == nil || time.Now().After(sess.ExpiresAt) {
					jsonError(w, http.StatusUnauthorized, "session expired or revoked")
					return
				}

• Files reviewed: 12/12 changed files
• Comments generated: 4