feat(cache): add configurable token verification cache layer (#132)

* feat(cache): add configurable token verification cache layer

Add an optional cache layer (memory/Redis/Redis-aside) for token
verification to reduce database queries on the ValidateToken hot path.
The cache reuses the existing generic Cache[T] infrastructure and is
disabled by default (TOKEN_CACHE_ENABLED=false).

Key design decisions:
- Only ValidateToken uses the cache; IntrospectToken (RFC 7662) always
  hits the database for authoritative real-time state
- Single-token revocations immediately invalidate the cache
- Bulk revocations (by user, by token family) collect hashes before
  deletion and invalidate each cached entry
- Cache invalidation happens after transaction commit, not inside, to
  avoid premature eviction on rollback

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* test(cache): add cache invalidation tests and fix silent error handling

- Add TestRevokeTokenByID_CacheInvalidated for ID-based revocation
- Add TestEnableToken_CacheInvalidated for disable/enable cycle
- Add TestRevokeAllUserTokens_CacheInvalidated for bulk eviction
- Add TestRefreshAccessToken_RotationMode_CacheInvalidated for rotation
- Add TestRevokeTokenFamily_CacheInvalidated for replay detection
- Log errors from GetActiveTokenHashesByFamilyID instead of discarding
- Log errors from GetTokensByUserID in RevokeAllUserTokens
- Add safe hash truncation in invalidateTokenCache error log

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(cache): only invalidate cache after successful revocation

- Restructure RevokeAllUserTokens to skip cache invalidation when
  DB revocation fails, preventing stale cache entries on error
- Clarify .env.example comment about cache TTL behavior during
  bulk revocation to reflect actual per-token invalidation logic

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(cache): graceful fallback on cache errors and strict token lookup

- Fall back to direct DB lookup when cache backend fails (e.g. Redis
  unavailable) instead of rejecting valid tokens
- Return error from GetAccessTokenByID in RevokeTokenByStatus to prevent
  cache entries from becoming stale when token lookup fails

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* style(cache): fix golines and testifylint issues

- Break long log.Printf lines to satisfy golines max line length
- Use require.Error instead of assert.Error for error assertions

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* test(cache): add tokeninfo integration tests and validation benchmarks

- Add end-to-end handler tests verifying cache population, revoke/disable
  invalidation, and nil-cache regression for /oauth/tokeninfo
- Add benchmarks comparing ValidateToken with and without memory cache
  (4.4x throughput improvement on cache hit path)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor(test): simplify token cache tests

- Remove redundant WHAT-comments, keep only WHY-comments
- Deduplicate NewTokenService calls using core.Cache interface variable

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: appleboy

.env.example

@@ -194,6 +194,27 @@ EXPIRED_TOKEN_CLEANUP_INTERVAL=1h      # How often to run the cleanup (default:
 # Client-side cache size per connection in MB for redis-aside mode only (default: 32MB)
 # CLIENT_COUNT_CACHE_SIZE_PER_CONN=32
 
+# ============================================================
+# Token Cache Settings
+# ============================================================
+# Cache layer for token verification to reduce DB queries.
+# Disabled by default; enable for high-traffic or multi-node deployments.
+# TOKEN_CACHE_ENABLED=false
+
+# Cache backend: memory (single instance), redis, or redis-aside (default: memory)
+# TOKEN_CACHE_TYPE=memory
+
+# Cache lifetime (default: 5m). Bulk revocation attempts per-token cache invalidation; in rare
+# cases where cache invalidation is incomplete or fails, revoked tokens may remain valid in cache
+# for up to this duration. Single-token revocation invalidates cache immediately.
+# TOKEN_CACHE_TTL=5m
+
+# Client-side cache TTL for redis-aside mode only (default: 30s)
+# TOKEN_CACHE_CLIENT_TTL=30s
+
+# Client-side cache size per connection in MB for redis-aside mode only (default: 32MB)
+# TOKEN_CACHE_SIZE_PER_CONN=32
+
 # ============================================================
 # Bootstrap and Shutdown Timeout Settings
 # ============================================================

internal/bootstrap/bootstrap.go

@@ -33,6 +33,8 @@ type Application struct {
 	UserCacheCloser        func() error
 	ClientCountCache       core.Cache[int64]
 	ClientCountCacheCloser func() error
+	TokenCache             core.Cache[models.AccessToken]
+	TokenCacheCloser       func() error
 	RateLimitRedisClient   *redis.Client
 
 	// Services
@@ -114,6 +116,12 @@ func (app *Application) initializeInfrastructure(ctx context.Context) error {
 		return err
 	}
 
+	// Token Cache
+	app.TokenCache, app.TokenCacheCloser, err = initializeTokenCache(ctx, app.Config)
+	if err != nil {
+		return err
+	}
+
 	// Redis (for rate limiting)
 	app.RateLimitRedisClient, err = initializeRateLimitRedisClient(ctx, app.Config)
 	if err != nil {
@@ -144,6 +152,7 @@ func (app *Application) initializeBusinessLayer() {
 		app.UserCache,
 		app.ClientCountCache,
 		app.TokenProvider,
+		app.TokenCache,
 	)
 }
 
@@ -194,6 +203,7 @@ func (app *Application) startWithGracefulShutdown() {
 	addCacheCleanupJob(m, app.MetricsCache, app.Config)
 	addUserCacheCleanupJob(m, app.UserCache, app.Config)
 	addClientCountCacheCleanupJob(m, app.ClientCountCache, app.Config)
+	addTokenCacheCleanupJob(m, app.TokenCache, app.Config)
 	addDatabaseShutdownJob(m, app.DB, app.Config)
 	addAuditLogCleanupJob(m, app.Config, app.AuditService)
 	addExpiredTokenCleanupJob(m, app.DB, app.Config)

internal/bootstrap/cache.go

@@ -113,6 +113,23 @@ func initializeClientCountCache(
 	})
 }
 
+// initializeTokenCache initializes the token verification cache (disabled by default)
+func initializeTokenCache(
+	ctx context.Context,
+	cfg *config.Config,
+) (core.Cache[models.AccessToken], func() error, error) {
+	if !cfg.TokenCacheEnabled {
+		return nil, nil, nil
+	}
+	return initializeCache[models.AccessToken](ctx, cfg, cacheOpts{
+		cacheType:   cfg.TokenCacheType,
+		keyPrefix:   "authgate:tokens:",
+		clientTTL:   cfg.TokenCacheClientTTL,
+		sizePerConn: cfg.TokenCacheSizePerConn,
+		label:       "Token",
+	})
+}
+
 // initializeUserCache initializes the user cache (always enabled, defaults to memory)
 func initializeUserCache(
 	ctx context.Context,

internal/bootstrap/server.go

@@ -262,6 +262,18 @@ func addClientCountCacheCleanupJob(
 	addNamedCacheShutdownJob(m, "client count cache", clientCountCache.Close, cfg.CacheCloseTimeout)
 }
 
+// addTokenCacheCleanupJob adds token cache cleanup on shutdown
+func addTokenCacheCleanupJob(
+	m *graceful.Manager,
+	tokenCache core.Cache[models.AccessToken],
+	cfg *config.Config,
+) {
+	if tokenCache == nil {
+		return
+	}
+	addNamedCacheShutdownJob(m, "token cache", tokenCache.Close, cfg.CacheCloseTimeout)
+}
+
 // addExpiredTokenCleanupJob adds a periodic job that purges expired access tokens
 // and device codes from the database to prevent unbounded table growth.
 func addExpiredTokenCleanupJob(m *graceful.Manager, db *store.Store, cfg *config.Config) {

internal/bootstrap/services.go

@@ -27,6 +27,7 @@ func initializeServices(
 	userCache core.Cache[models.User],
 	clientCountCache core.Cache[int64],
 	tokenProvider core.TokenProvider,
+	tokenCache core.Cache[models.AccessToken],
 ) serviceSet {
 	// Initialize authentication providers
 	localProvider := auth.NewLocalAuthProvider(db)
@@ -51,6 +52,7 @@ func initializeServices(
 		tokenProvider,
 		auditService,
 		prometheusMetrics,
+		tokenCache,
 	)
 	clientService := services.NewClientService(
 		db, auditService, clientCountCache, cfg.ClientCountCacheTTL,

internal/config/config.go

@@ -176,6 +176,13 @@ type Config struct {
 	ClientCountCacheClientTTL   time.Duration // CLIENT_COUNT_CACHE_CLIENT_TTL for redis-aside (default: 10m)
 	ClientCountCacheSizePerConn int           // CLIENT_COUNT_CACHE_SIZE_PER_CONN for redis-aside in MB (default: 32MB)
 
+	// Token Cache settings (reduces DB queries for token verification)
+	TokenCacheEnabled     bool          // TOKEN_CACHE_ENABLED: enable token verification cache (default: false)
+	TokenCacheType        string        // TOKEN_CACHE_TYPE: memory|redis|redis-aside (default: memory)
+	TokenCacheTTL         time.Duration // TOKEN_CACHE_TTL: cache lifetime (default: 5m)
+	TokenCacheClientTTL   time.Duration // TOKEN_CACHE_CLIENT_TTL: redis-aside client-side TTL (default: 30s)
+	TokenCacheSizePerConn int           // TOKEN_CACHE_SIZE_PER_CONN: redis-aside size in MB (default: 32MB)
+
 	// Dynamic Client Registration (RFC 7591)
 	EnableDynamicClientRegistration    bool   // Enable POST /oauth/register endpoint (default: false)
 	DynamicClientRegistrationRateLimit int    // Requests per minute for /oauth/register (default: 5)
@@ -371,6 +378,13 @@ func Load() *Config {
 			32,
 		), // 32MB default
 
+		// Token Cache settings
+		TokenCacheEnabled:     getEnvBool("TOKEN_CACHE_ENABLED", false),
+		TokenCacheType:        getEnv("TOKEN_CACHE_TYPE", CacheTypeMemory),
+		TokenCacheTTL:         getEnvDuration("TOKEN_CACHE_TTL", 5*time.Minute),
+		TokenCacheClientTTL:   getEnvDuration("TOKEN_CACHE_CLIENT_TTL", 30*time.Second),
+		TokenCacheSizePerConn: getEnvInt("TOKEN_CACHE_SIZE_PER_CONN", 32), // 32MB default
+
 		// Dynamic Client Registration (RFC 7591)
 		EnableDynamicClientRegistration:    getEnvBool("ENABLE_DYNAMIC_CLIENT_REGISTRATION", false),
 		DynamicClientRegistrationRateLimit: getEnvInt("DYNAMIC_CLIENT_REGISTRATION_RATE_LIMIT", 5),
@@ -546,6 +560,26 @@ func (c *Config) Validate() error {
 		)
 	}
 
+	// Token cache validation (only when enabled)
+	if c.TokenCacheEnabled {
+		if err := validateCacheType("TOKEN_CACHE_TYPE", c.TokenCacheType, c.RedisAddr); err != nil {
+			return err
+		}
+		if c.TokenCacheTTL <= 0 {
+			return fmt.Errorf(
+				"TOKEN_CACHE_TTL must be a positive duration when TOKEN_CACHE_ENABLED=true (got %s)",
+				c.TokenCacheTTL,
+			)
+		}
+		if c.TokenCacheType == CacheTypeRedisAside && c.TokenCacheClientTTL <= 0 {
+			return fmt.Errorf(
+				"TOKEN_CACHE_CLIENT_TTL must be a positive duration when TOKEN_CACHE_TYPE=%q (got %s)",
+				CacheTypeRedisAside,
+				c.TokenCacheClientTTL,
+			)
+		}
+	}
+
 	// SESSION_REMEMBER_ME_MAX_AGE must be positive when remember-me is enabled.
 	// The gorilla/sessions cookie store codec has a default max-age of 30 days;
 	// values above 2592000 (30 days) may cause cookie decode failures.

internal/core/store.go

@@ -77,6 +77,7 @@ type TokenReader interface {
 		params types.PaginationParams,
 	) ([]models.AccessToken, types.PaginationResult, error)
 	GetTokensByCategoryAndStatus(userID, category, status string) ([]models.AccessToken, error)
+	GetActiveTokenHashesByFamilyID(familyID string) ([]string, error)
 }
 
 // TokenWriter groups token mutation operations.

internal/handlers/session_test.go

@@ -41,7 +41,7 @@ func setupSessionServices(t *testing.T) (*store.Store, *services.TokenService) {
 	auditSvc := services.NewAuditService(s, false, 0)
 	deviceSvc := services.NewDeviceService(s, cfg, auditSvc, metrics.NewNoopMetrics())
 	tokenSvc := services.NewTokenService(
-		s, cfg, deviceSvc, localProvider, auditSvc, metrics.NewNoopMetrics(),
+		s, cfg, deviceSvc, localProvider, auditSvc, metrics.NewNoopMetrics(), nil,
 	)
 
 	return s, tokenSvc