jwk-loader 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67a15a343d854ec41ad0a81e27bb56d1d31d4ffbeba011f07297fc97476f3527
-  data.tar.gz: 5bf06d581feafa9d0e8596beea16cf09edd2589ec09cf7934d1451a706320843
+  metadata.gz: fd8e5e883d3fe957a51bb6b11cd3b024e76df71f20f640c18778d4bd84c983a4
+  data.tar.gz: e6d02926c9d98cc4bdf956c9aa07bd5ab9098c8acee3c054f622609365ae3ddd
 SHA512:
-  metadata.gz: ec4bbbeadaba81fb48a30958d3e1ee1393b82bb96094b995f2f2fdd85ce91cab0bbe39a361aa065b1da4f87a94ccfd954fd199b46d0a4339554bb53bc78487e6
-  data.tar.gz: df1a43c04b157c052593e3bcb1acc12df6d219fe62f33af53652ee5d6ce49054b6a0d3605775ed41a8b22eb39bc3329a957e75d33a49feb26c3dbdde7770f745
+  metadata.gz: 41aad8101ea210f2f5a892b4374676671b465f5598e4889a680c3c46db414db04dee61f4bf4152b7600501e3cf7df8d7feea5514db9e0e0ab707e0a77932bd30
+  data.tar.gz: b9127234138694fff757f5813a9ac6f307f277ef181bd0007829d01bc8932e805349e5fa4def48de0ab2f8f7f077144441b366f112b1634c72dd207468e205b1

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "1.2.0"
+  ".": "1.3.0"
 }

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.3.0](https://github.com/anakinj/jwk-loader/compare/v1.2.0...v1.3.0) (2026-11-03)
+
+
+### Features
+
+* add optional maximum JWKS cache age ([#23](https://github.com/anakinj/jwk-loader/issues/23)) ([725482e](https://github.com/anakinj/jwk-loader/commit/725482e97cfb30ddc7792eb35d9f35fb792cba2d))
+
+
+### Bug Fixes
+
+* handle absent cache entries during invalidation ([#18](https://github.com/anakinj/jwk-loader/issues/18)) ([0942d81](https://github.com/anakinj/jwk-loader/commit/0942d81b924928687e7408c85a9378ac9427af45))
+* preserve cached JWKS when refreshing fails ([#17](https://github.com/anakinj/jwk-loader/issues/17)) ([cd4e68b](https://github.com/anakinj/jwk-loader/commit/cd4e68b6f4f6c01ef5aa7b1be430da4df606a0e8))
+* reject unsuccessful JWKS HTTP responses ([#16](https://github.com/anakinj/jwk-loader/issues/16)) ([edf46b9](https://github.com/anakinj/jwk-loader/commit/edf46b92001c5348e51c309fa24523991b91275a))
+
 ## [1.2.0](https://github.com/anakinj/jwk-loader/compare/v1.1.0...v1.2.0) (2025-07-02)
 
 

data/README.md

@@ -26,6 +26,20 @@ require "jwk-loader"
 JWT.decode(token, nil, true, algorithm: "RS512", jwks: JwkLoader.for_uri(uri: "https://url/to/public/jwks") )
 ```
 
+### Handling loading errors
+
+Non-2xx JWKS responses raise native HTTP errors before JSON parsing; handle `Net::HTTPExceptions` alongside `JWT::DecodeError`. Invalid URIs, connection/TLS failures, timeouts, malformed JSON, and invalid keys propagate unchanged; examples include `URI::InvalidURIError`, `Net::OpenTimeout`, `JSON::ParserError`, or `JWT::JWKError`.
+
+```ruby
+class AuthenticationError < StandardError; end
+
+begin
+  JWT.decode(token, nil, true, algorithm: "RS512", jwks: JwkLoader.for_uri(uri: jwks_uri))
+rescue Net::HTTPExceptions, JWT::DecodeError => error
+  raise AuthenticationError, "Token verification failed", cause: error
+end
+```
+
 ### Testing endpoints protected by JWT tokens
 
 When testing HTTP endpoints protected by asymmetric JWT keys the mechanism in `jwk_loader/test` can be used to simplify the process.
@@ -49,12 +63,15 @@ end
 
 ### Configuring the gem
 
+The default `cache_grace_period` is 900 seconds, measured from the last successful fetch. An unknown-key or explicit invalidation hint can refresh a cached set once that period has elapsed; it is a refresh cooldown, not a maximum lifetime for known keys. Refreshing leaves the previous cached set available until its replacement has loaded successfully.
+
 ```ruby
 require "jwt-loader"
 
 JwkLoader.configure do |config|
   config[:cache] = YetAnotherCache.new
   config[:cache_grace_period] = 999
+  config[:cache_max_age] = 600
 end
 ```
 
@@ -66,9 +83,22 @@ require "jwt-loader"
 JwkLoader.configure do |config|
   config.cache = YetAnotherCache.new
   config.cache_grace_period = 999
+  config.cache_max_age = 600
 end
 ```
 
+`cache_max_age` optionally limits the lifetime of remotely cached sets, in seconds since the last successful fetch. It defaults to `nil` (no expiry). Once the age limit is reached, the next lookup fetches a replacement even for a known key and even within `cache_grace_period`. Expiry fails closed: if that fetch fails, the error propagates and expired keys are not returned. There is no background refresh or expired-key fallback. Use a finite non-negative number of seconds; `0` refreshes on every lookup. Locally supplied test keys are unaffected.
+
+The maximum age can also be set per URI; an explicit `nil` disables a global limit for that provider:
+
+```ruby
+JwkLoader.for_uri(uri: jwks_uri, cache_max_age: 300)
+JwkLoader.for_uri(uri: jwks_uri, cache_max_age: nil)
+```
+
+A failed refresh propagates the original loading exception for both `kid_not_found` and `invalidate` hints, without deleting the previous set or changing its timestamp. The triggering `JWT.decode` call fails with that exception. Subsequent ordinary lookups can still use preserved keys that have not expired. Since failures do not advance the timestamp, a later lookup requiring a refresh can retry; there is no separate failed-fetch cooldown.
+
+Invalidation hints are safe when the cache entry is absent or has been evicted: the provider performs an ordinary lookup, using locally supplied test keys or fetching the URI when needed.
 
 ## Development
 

data/lib/jwk-loader.rb

@@ -12,6 +12,7 @@ module JwkLoader
     def for_uri(**options)
       options[:cache] ||= config[:cache]
       options[:cache_grace_period] ||= config[:cache_grace_period]
+      options[:cache_max_age] = config[:cache_max_age] unless options.key?(:cache_max_age)
       JwksUriProvider.new(**options)
     end
 
@@ -27,6 +28,7 @@ module JwkLoader
       @config ||= JwkLoader::Config.new.tap do |cfg|
         cfg[:cache] = MemoryCache.new
         cfg[:cache_grace_period] = 900
+        cfg[:cache_max_age] = nil
       end
     end
 

data/lib/jwk_loader/config/config.rb

@@ -13,7 +13,7 @@ module JwkLoader
     end
 
     def [](key)
-      registry[key] || (raise ConfigurationNotFound, key)
+      registry.fetch(key) { raise ConfigurationNotFound, key }
     end
 
     def method_missing(name, *args)

data/lib/jwk_loader/jwks.rb

@@ -11,6 +11,8 @@ module JwkLoader
         uri = URI.parse(uri) unless uri.is_a?(URI)
 
         response = Net::HTTP.get_response(uri)
+        response.value # Raises for non-2xx HTTP responses.
+
         from_json(response.body)
       end
 

data/lib/jwk_loader/jwks_uri_provider.rb

@@ -2,33 +2,53 @@
 
 module JwkLoader
   class JwksUriProvider
-    attr_reader :uri, :cache, :cache_grace_period
+    attr_reader :uri, :cache, :cache_grace_period, :cache_max_age
 
-    def initialize(uri:, cache:, cache_grace_period:)
+    def initialize(uri:, cache:, cache_grace_period:, cache_max_age: nil)
       @uri          = uri
       @cache        = cache
       @cache_grace_period = cache_grace_period
+      @cache_max_age = cache_max_age
+      validate_cache_max_age!
     end
 
     def call(options)
-      invalidate_cache! if options[:kid_not_found] || options[:invalidate]
-      jwks
+      refreshed = refresh_cache! if options[:kid_not_found] || options[:invalidate]
+      refreshed || jwks
     end
 
     private
 
+    def validate_cache_max_age!
+      return if cache_max_age.nil?
+      return if cache_max_age.is_a?(Numeric) && cache_max_age.real? &&
+                cache_max_age.finite? && cache_max_age >= 0
+
+      raise ArgumentError, "cache_max_age must be nil or a finite non-negative number of seconds"
+    end
+
     def jwks
       from_cache || from_memory || from_uri
     end
 
-    def invalidate_cache!
-      return if Time.now - cache_entry.fetch(:fetched_at) < cache_grace_period
+    def refresh_cache!
+      entry = cache_entry
+      return if entry.nil? || Time.now - entry.fetch(:fetched_at) < cache_grace_period
 
-      cache.delete(uri)
+      if (keys = from_memory)
+        cache.delete(uri)
+        keys
+      else
+        from_uri
+      end
     end
 
     def from_cache
-      cache_entry&.fetch(:jwks)
+      entry = cache_entry
+      return if entry.nil?
+      return if cache_max_age && Time.now - entry.fetch(:fetched_at) >= cache_max_age
+
+      entry.fetch(:jwks)
     end
 
     def from_memory

data/lib/jwk_loader/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JwkLoader
-  VERSION = "1.2.0"
+  VERSION = "1.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jwk-loader
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Joakim Antman
@@ -75,7 +75,7 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/anakinj/jwk-loader
   source_code_uri: https://github.com/anakinj/jwk-loader
-  changelog_uri: https://github.com/anakinj/jwk-loader/blob/1.2.0/CHANGELOG.md
+  changelog_uri: https://github.com/anakinj/jwk-loader/blob/1.3.0/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -91,7 +91,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Tooling for handling JWK loading, parsing and caching
 test_files: []