feat: add TTL-based expiration for JWKS cache entries

- Add CacheTTL option to CachingClientOpts with 1-hour default
- Introduce expiresAt field to track cache entry expiration time
- Implement cache expiration checks during key retrieval
- Rename InvalidateCacheIfNeeded to InvalidateCacheIfPossible with bool return
- Update cache invalidation to reset TTL on successful refresh
- Add comprehensive test coverage for TTL expiration scenarios

Author: vasayxtx

jwks/caching_client.go

@@ -17,12 +17,23 @@ import (
 
 const DefaultCacheUpdateMinInterval = time.Minute * 1
 
+// DefaultCacheTTL is the default time-to-live for cached JWKS entries.
+// After this duration, cached entries are considered expired and will be refreshed.
+// This prevents revoked keys from remaining in cache indefinitely.
+const DefaultCacheTTL = time.Hour * 1
+
 // CachingClientOpts contains options for CachingClient.
 type CachingClientOpts struct {
 	ClientOpts
 
 	// CacheUpdateMinInterval is a minimal interval between cache updates for the same issuer.
 	CacheUpdateMinInterval time.Duration
+
+	// CacheTTL is the time-to-live for cached JWKS entries.
+	// After this duration, cached entries expire and will be refreshed on next access.
+	// This prevents revoked keys from remaining in cache indefinitely.
+	// Default: DefaultCacheTTL (1 hour).
+	CacheTTL time.Duration
 }
 
 // CachingClient is a Client for getting keys from remote JWKS with a caching mechanism.
@@ -31,30 +42,40 @@ type CachingClient struct {
 	rawClient              *Client
 	issuerCache            map[string]issuerCacheEntry
 	cacheUpdateMinInterval time.Duration
+	cacheTTL               time.Duration
 }
 
 const missingKeysCacheSize = 100
 
 type issuerCacheEntry struct {
 	updatedAt   time.Time
+	expiresAt   time.Time
 	keys        map[string]interface{}
 	missingKeys *lrucache.LRUCache[string, time.Time]
 }
 
+func (ice *issuerCacheEntry) isExpired() bool {
+	return time.Now().After(ice.expiresAt)
+}
+
 // NewCachingClient returns a new Client that can cache fetched data.
 func NewCachingClient() *CachingClient {
 	return NewCachingClientWithOpts(CachingClientOpts{})
 }
 
 // NewCachingClientWithOpts returns a new Client that can cache fetched data with options.
 func NewCachingClientWithOpts(opts CachingClientOpts) *CachingClient {
-	if opts.CacheUpdateMinInterval == 0 {
+	if opts.CacheUpdateMinInterval <= 0 {
 		opts.CacheUpdateMinInterval = DefaultCacheUpdateMinInterval
 	}
+	if opts.CacheTTL <= 0 {
+		opts.CacheTTL = DefaultCacheTTL
+	}
 	return &CachingClient{
 		rawClient:              NewClientWithOpts(opts.ClientOpts),
 		issuerCache:            make(map[string]issuerCacheEntry),
 		cacheUpdateMinInterval: opts.CacheUpdateMinInterval,
+		cacheTTL:               opts.CacheTTL,
 	}
 }
 
@@ -76,35 +97,38 @@ func (cc *CachingClient) GetRSAPublicKey(ctx context.Context, issuerURL, keyID s
 	return nil, &JWKNotFoundError{IssuerURL: issuerURL, KeyID: keyID}
 }
 
-// InvalidateCacheIfNeeded does cache invalidation for specific issuer URL if it's necessary.
-func (cc *CachingClient) InvalidateCacheIfNeeded(ctx context.Context, issuerURL string) error {
+// InvalidateCacheIfPossible does cache invalidation for specific issuer URL if possible.
+// It returns true if the cache was invalidated, false if invalidation was skipped due to rate limiting.
+func (cc *CachingClient) InvalidateCacheIfPossible(ctx context.Context, issuerURL string) (invalidated bool, err error) {
 	cc.mu.Lock()
 	defer cc.mu.Unlock()
 
 	var missingKeys *lrucache.LRUCache[string, time.Time]
 	issCache, found := cc.issuerCache[issuerURL]
 	if found {
 		if time.Since(issCache.updatedAt) < cc.cacheUpdateMinInterval {
-			return nil
+			return false, nil
 		}
 		missingKeys = issCache.missingKeys
 	} else {
 		var err error
 		if missingKeys, err = lrucache.New[string, time.Time](missingKeysCacheSize, nil); err != nil {
-			return fmt.Errorf("new lru cache for missing keys: %w", err)
+			return false, fmt.Errorf("new lru cache for missing keys: %w", err)
 		}
 	}
 
 	pubKeys, err := cc.rawClient.getRSAPubKeysForIssuer(ctx, issuerURL)
 	if err != nil {
-		return fmt.Errorf("get rsa public keys for issuer %q: %w", issuerURL, err)
+		return false, fmt.Errorf("get rsa public keys for issuer %q: %w", issuerURL, err)
 	}
+	now := time.Now()
 	cc.issuerCache[issuerURL] = issuerCacheEntry{
-		updatedAt:   time.Now(),
+		updatedAt:   now,
+		expiresAt:   now.Add(cc.cacheTTL),
 		keys:        pubKeys,
 		missingKeys: missingKeys,
 	}
-	return nil
+	return true, nil
 }
 
 func (cc *CachingClient) getPubKeyFromCache(
@@ -117,6 +141,12 @@ func (cc *CachingClient) getPubKeyFromCache(
 	if !issFound {
 		return nil, false, true
 	}
+
+	// Check if cache entry has expired based on TTL (if TTL is configured)
+	if issCache.isExpired() {
+		return nil, false, true
+	}
+
 	if pubKey, found = issCache.keys[keyID]; found {
 		return
 	}
@@ -135,12 +165,14 @@ func (cc *CachingClient) getPubKeyFromCacheAndInvalidate(
 
 	var missingKeys *lrucache.LRUCache[string, time.Time]
 	if issCache, issFound := cc.issuerCache[issuerURL]; issFound {
-		if pubKey, found = issCache.keys[keyID]; found {
-			return pubKey, true, nil
-		}
-		missedAt, miss := issCache.missingKeys.Get(keyID)
-		if miss && time.Since(missedAt) < cc.cacheUpdateMinInterval {
-			return nil, false, nil
+		if !issCache.isExpired() {
+			if pubKey, found = issCache.keys[keyID]; found {
+				return pubKey, true, nil
+			}
+			missedAt, miss := issCache.missingKeys.Get(keyID)
+			if miss && time.Since(missedAt) < cc.cacheUpdateMinInterval {
+				return nil, false, nil
+			}
 		}
 		missingKeys = issCache.missingKeys
 	} else {
@@ -158,8 +190,10 @@ func (cc *CachingClient) getPubKeyFromCacheAndInvalidate(
 	if !found {
 		missingKeys.Add(keyID, time.Now())
 	}
+	now := time.Now()
 	cc.issuerCache[issuerURL] = issuerCacheEntry{
-		updatedAt:   time.Now(),
+		updatedAt:   now,
+		expiresAt:   now.Add(cc.cacheTTL),
 		keys:        pubKeys,
 		missingKeys: missingKeys,
 	}