verikloak 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f694670478e8bbeff2369e0898b96a2d675e052bc19c4ac8437bfb3ff209dc52
-  data.tar.gz: 8c189a0ae636ee82ab5e0589b047327c6bd5c8360d4a40f3fcbb6ebc1491743b
+  metadata.gz: a5d6390b5c664ecb4e4af43fa7090e39920c2d79bc16b524b566a73eda95c6d7
+  data.tar.gz: b971779c56259ebeb0420983612760cb964442150a3f3fbb78dd388e1d46458c
 SHA512:
-  metadata.gz: 456fb93fd6afd7376d4daedc1fe17c708d0b0c7055e5e215874418b84de69fbee048f70fc421560ae3e0296d264f5d4f0be1028382f28798531c292be7bc5ba1
-  data.tar.gz: 2f7f2107e34117cbc644b6b1c862da9521b9f1bda47a862ffb6747ad8a1bd851a3217ebc41113552684e1b67887074dfe845a14e6a0ae50cc7aaa6c4318a9665
+  metadata.gz: 69df466fe17c16a392645ef56a6f6fc19c8e2d5fee3b91be5e1cd3465ce587bc56a7994ac7b3e6a20c91bedc9d98b91f287144084e35a217501fa40beb72aae2
+  data.tar.gz: 1357d43f97c4a0d313e1171ceebb4ca2ac0b7b2313fc4968a055e06a2c4bdd67eb1f59b8a0ff5de65993c2ad79ab75b0fc1c7db6e740324af33f7bd8693e22c6

data/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.1.0] - 2026-07-03
+
+### Changed
+- **JWKs revalidation is now throttled on the request path** (`Middleware`): previously every request synchronized on a single mutex and called `JwksCache#fetch!`, so identity providers that do not send `Cache-Control: max-age` on their JWKs endpoint (including Keycloak's default) caused a conditional HTTP GET — with retries and timeouts — inside the lock on **every** request. The middleware now revalidates at most once per `jwks_refresh_interval` seconds (default `60`) and serves requests within the window lock-free from the in-memory key set. A server-declared `Cache-Control: max-age` **shorter** than the interval is honored: TTL expiry reopens the window early (`JwksCache#ttl_expired?`), so an IdP asking for faster revalidation still gets it — this bounds how long a key the IdP has *removed* keeps verifying by `min(max-age, interval)` rather than the full interval. Key rotation in the other direction (new keys) is not delayed: an unknown `kid` or signature mismatch forces an immediate refresh and one retry. Pass `jwks_refresh_interval: 0` to restore the previous revalidate-on-every-request behavior; passing `nil` now falls back to the default `60` instead of silently meaning `0`. Numeric strings (e.g. from ENV) are coerced like `decoder_cache_limit` already did.
+- **Failure-triggered JWKs refreshes are rate-limited** (`FORCED_REFRESH_MIN_INTERVAL`, 5s): the unknown-`kid`/bad-signature retry path is reachable with unauthenticated requests, and each hit previously performed an upstream HTTP GET (with retry amplification) while holding the middleware mutex — an attacker flooding bogus-`kid` tokens could drive one IdP request per app request and serialize legitimate traffic behind the lock. Keys revalidated within the last 5 seconds cannot have missed a rotation an immediate re-fetch would find, so such retries now proceed on the cached keys instead of re-fetching. Worst case for a genuine rotation landing inside those 5 seconds: the affected token is rejected once and verifies on the client's next attempt.
+- **Decoder cache is now keyed by the exact key snapshot a decoder was built from** (`Middleware`): rotation detection previously compared the cached key array's object identity (`__id__`), so any `200 OK` refresh — even one returning identical keys — purged all cached `TokenDecoder` instances and rebuilt them, and object-id recycling could in principle miss a rotation. The cache key and the purge check now use a SHA-256 digest of the key set content, computed from the snapshot handed to the decoder (memoized per snapshot object, so the request path pays one pointer comparison) and insensitive to the order of keys in the set (kid lookup makes ordering irrelevant, so a reordered but identical response keeps the cache warm). Deriving the key from the snapshot itself also closes a race where a decoder built from pre-rotation keys could be stored under the post-rotation generation by an interleaving forced refresh and then served — permanently, since content digests no longer change on refresh — yielding persistent 401s for valid tokens until process restart. If the digest cannot be computed (exotic injected caches), the failure is logged and decoders are built uncached rather than risking cross-generation collisions.
+- **`kid_not_found` error code** (`TokenDecoder`): an unknown `kid` now raises `TokenDecoderError` with code `kid_not_found` instead of `invalid_token`, and the middleware's refresh-and-retry trigger matches on that code instead of sniffing the error message. HTTP responses are unchanged (still `401` with JSON `error: "invalid_token"`); only `error.code` seen by callers rescuing `Verikloak::TokenDecoderError` directly changes.
+
+### Security
+- **Bumped `jwt` to `3.2.0` and `faraday` to `2.14.3`** in `Gemfile.lock` to clear advisories surfaced by `bundler-audit`: CVE-2026-45363 (jwt: HS256 verification accepts an empty HMAC key — verikloak itself is unaffected as it pins RS256 with RSA keys) and the faraday nested-query-string DoS (GHSA-98m9-hrrm-r99r, fixed in 2.14.3).
+- **Minimum `faraday` runtime dependency raised to `2.14.3`** (gemspec): the `>= 2.14.1` floor was introduced for CVE-2026-25765, but per GHSA-5rv5-xj5j-3484 that fix was incomplete (protocol-relative URIs could still bypass host scoping, completed in 2.14.2), and 2.14.3 additionally fixes the nested-query-string DoS above. The jwt range is intentionally left at `>= 2.7, < 4.0`: only 3.0.0–3.1.x are affected by CVE-2026-45363, jwt 2.x is not, and verikloak's own verification path pins RS256 with RSA keys.
+- **Response size limits**: discovery and JWKs response bodies larger than 1 MB (`Verikloak::HTTP::MAX_RESPONSE_BYTES`) are rejected (`discovery_metadata_invalid` / `jwks_parse_failed`) before JSON parsing, preventing a compromised endpoint from exhausting memory.
+- **`kid` truncation in error messages** (`TokenDecoder`): the attacker-controlled `kid` value echoed in "Key with kid=... not found" messages (and therefore in 401 response bodies and `WWW-Authenticate` headers) is truncated to 64 characters.
+- **DNS rebinding limitation documented** (SECURITY.md): the SSRF checks resolve hostnames at validation time while the HTTP client resolves them again at connection time; the gap and recommended mitigations are now documented.
+
+### Added
+- **`jwks_refresh_interval` middleware option** (default `60`): minimum seconds between JWKs revalidations on the request path.
+- **`Verikloak::SafeUrl`** (internal): shared URL normalization, HTTPS-enforcement, and private-IP resolution helpers previously duplicated between `Discovery` and `JwksCache`. `Verikloak::PRIVATE_IP_RANGES` is unchanged and now lives alongside it.
+- **CI compatibility matrix**: the suite now also runs on Ruby 3.1, 3.2, and 3.3 (via `gemfiles/compat.gemfile`), backing the gemspec's `required_ruby_version >= 3.1` claim; the docker-based job continues to cover 3.4.
+- **Coverage gate**: SimpleCov now runs in CI (`SIMPLECOV=true`) and fails the suite below 90% line coverage (currently ~95%).
+
+### Fixed
+- **Key-rotation retry now bypasses `Cache-Control: max-age` freshness** (`JwksCache#force_fetch!`): when a token failed with an unknown `kid` or bad signature, the forced JWKs refresh previously called plain `fetch!`, which returns the cached keys without any HTTP request while `max-age` is still fresh — so on IdPs that send `max-age` on the JWKs endpoint, tokens signed with rotated keys kept failing until the TTL expired (pre-existing behavior, surfaced by the throttling work). The retry path now revalidates over HTTP (subject to the forced-refresh rate limit above); the ETag conditional request still applies, so an unchanged key set costs only a 304. Injected caches that only implement `fetch!` keep their previous behavior, and `force_fetch!` inspects the receiver's `fetch!` signature so subclasses that override it with the pre-1.1 zero-arg form degrade to a plain fetch instead of raising `ArgumentError`.
+- **A transient empty JWKs response no longer pins 503s for the whole throttle window**: a `200 OK` with `{"keys": []}` used to close the revalidation window, so every request answered `503 jwks_cache_miss` for up to `jwks_refresh_interval` seconds even after the IdP recovered, with no code path able to trigger a re-fetch. An empty key set now leaves the window open (the next request revalidates), and the rotation-retry path re-checks the snapshot after its forced refresh, returning the same `503 jwks_cache_miss` as every other request instead of mislabeling the token `401 invalid_token`.
+- **`realm: nil` no longer raises `NameError`**: `normalize_realm`'s default-realm fallback referenced `DEFAULT_REALM` from a module context where the constant does not resolve; explicitly passing `realm: nil` (expecting the documented default) crashed middleware construction. Both default-constant references are now fully qualified.
+- **CI: the SimpleCov coverage gate now actually runs in the docker job**: the step-level `SIMPLECOV=true` env var stayed on the Actions runner shell and never reached the Compose container, so `ENV['SIMPLECOV']` was unset and the 90% gate silently did not run. The workflow now forwards it with `docker compose run -e SIMPLECOV`.
+- **Audience callable arity fallback no longer swallows application errors**: the retry-on-`ArgumentError` fallback now only matches messages *starting with* `wrong number of arguments`, so an `ArgumentError` raised inside the callable body that merely mentions the phrase propagates instead of triggering a second invocation.
+- **README**: removed the misleading `algorithms:` override example — the token header is validated to be exactly `RS256` before decoding regardless of that option; documented the constraint instead.
+
+---
+
 ## [1.0.2] - 2026-05-09
 
 ### Fixed

data/README.md

@@ -21,8 +21,10 @@ Verikloak is a plug-and-play solution for Ruby (especially Rails API) apps that
 - SSRF protection — discovery redirect targets **and** `jwks_uri` values validated against private IP ranges (including IPv4-mapped IPv6 normalisation); automatically bypassed with `allow_http: true` for local development
 - HTTPS redirect enforcement — redirect targets are scheme-checked to prevent HTTPS→HTTP downgrade
 - JWT size limit (8 KB) to mitigate denial-of-service via oversized tokens
+- Response size limit (1 MB) for discovery and JWKs documents
 - Header injection prevention in `WWW-Authenticate` responses
 - URL normalisation — leading/trailing whitespace stripped from discovery and JWKs URLs
+- Throttled JWKs revalidation (`jwks_refresh_interval`, default 60s) so hot request paths never serialize on network calls; key rotation is still picked up immediately via refresh-and-retry
 
 ## Installation
 
@@ -243,8 +245,9 @@ For a full list of error cases and detailed explanations, please see the [ERRORS
 | `discovery`     | No       | Inject custom Discovery instance (advanced/testing) |
 | `jwks_cache`    | No       | Inject custom JwksCache instance (advanced/testing) |
 | `leeway`       | No       | Clock skew tolerance (seconds) applied during JWT verification. Defaults to `TokenDecoder::DEFAULT_LEEWAY`. |
-| `token_verify_options` | No | Hash of advanced JWT verification options passed through to TokenDecoder. For example: `{ verify_iat: false, leeway: 10, algorithms: ["RS256"] }`. If both `leeway:` and `token_verify_options[:leeway]` are set, the latter takes precedence. |
+| `token_verify_options` | No | Hash of advanced JWT verification options passed through to TokenDecoder. For example: `{ verify_iat: false, leeway: 10 }`. If both `leeway:` and `token_verify_options[:leeway]` are set, the latter takes precedence. |
 | `decoder_cache_limit` | No | Maximum number of `TokenDecoder` instances retained per middleware. Defaults to `128`. Set to `0` to disable caching or `nil` for an unlimited cache. |
+| `jwks_refresh_interval` | No | Minimum seconds between JWKs revalidations on the request path. Defaults to `60` (`nil` also means the default); numeric strings are accepted. Set to `0` to revalidate on every request. A shorter server `Cache-Control: max-age` is honored. Key rotation within the window is still handled immediately: a signature/`kid` mismatch forces a refresh and one retry (rate-limited to one forced refresh per 5s). |
 | `connection`   | No       | Inject a Faraday::Connection used for both Discovery and JWKs fetches. Defaults to a safe connection with timeouts and retries. |
 | `token_env_key` | No       | Rack env key for the raw JWT. Defaults to `verikloak.token`. |
 | `user_env_key`  | No       | Rack env key for decoded claims. Defaults to `verikloak.user`. |
@@ -331,8 +334,7 @@ config.middleware.use Verikloak::Middleware,
     verify_iat: true,
     verify_expiration: true,
     verify_not_before: true,
-    # algorithms: ["RS256"] # override algorithms if needed
-    # leeway: 10            # this overrides the top-level leeway
+    # leeway: 10 # this overrides the top-level leeway
   }
 ```
 
@@ -352,15 +354,39 @@ config.middleware.use Verikloak::Middleware,
     setting `verify_iat: true` (the default) keeps it enabled.
   All other keys are forwarded to `JWT.decode` as-is.
 - If both are set, `token_verify_options[:leeway]` takes precedence.
+- Note that `algorithms:` cannot be used to accept anything other than
+  `RS256`: the token header is validated to be exactly `RS256` before
+  decoding, regardless of this option.
 
 ## Performance & Caching
 
+#### JWKs revalidation throttling
+
+The middleware revalidates JWKs at most once per `jwks_refresh_interval` seconds (default 60)
+on the request path. Within the window, requests use the in-memory key set without taking a
+lock or touching the network — important for identity providers (including Keycloak) that do
+not send `Cache-Control: max-age` on their JWKs endpoint, where every request would otherwise
+perform a conditional HTTP GET. When a revalidation does happen, ETag/`Cache-Control` headers
+still minimize traffic. A server-declared `max-age` **shorter** than the interval is honored:
+once it expires the next request revalidates, so a key the IdP removes stops being accepted
+after at most `min(max-age, jwks_refresh_interval)` seconds.
+
+Key rotation is not delayed by the window: when a token fails with an unknown `kid` or a bad
+signature, the middleware forces an immediate JWKs refresh — bypassing both the throttle window
+and any `Cache-Control: max-age` freshness from the previous response — and retries verification
+once. Because that trigger is reachable with unauthenticated requests, forced refreshes are
+rate-limited to one per 5 seconds; keys fetched more recently than that cannot have missed a
+rotation, so those retries proceed on the cached keys. Set `jwks_refresh_interval: 0` to restore
+the previous revalidate-on-every-request behavior.
+
 #### Decoder cache & performance
 
-Internally, Verikloak caches `TokenDecoder` instances per JWKs fetch to avoid reinitializing
-them on every request. The cache behaves like an LRU with a configurable size (`decoder_cache_limit`)
-so long-running processes do not accumulate decoders for one-off audiences. When the underlying
-JWK set rotates, the middleware now clears the cache to drop decoders that point at stale keys.
+Internally, Verikloak caches `TokenDecoder` instances keyed by the JWKs content to avoid
+reinitializing them on every request. The cache behaves like an LRU with a configurable size
+(`decoder_cache_limit`) so long-running processes do not accumulate decoders for one-off
+audiences. When the underlying JWK set rotates (detected by content, so refreshes that return
+identical keys keep the cache warm), the middleware clears the cache to drop decoders that
+point at stale keys.
 
 Set `decoder_cache_limit` to `0` if you prefer to construct a fresh decoder every time, or `nil`
 when you want the cache to grow without bounds (e.g., in short-lived jobs).

data/lib/verikloak/discovery.rb

@@ -1,29 +1,13 @@
 # frozen_string_literal: true
 
 require 'faraday'
-require 'ipaddr'
 require 'json'
-require 'resolv'
 require 'uri'
 
 require 'verikloak/http'
+require 'verikloak/safe_url'
 
 module Verikloak
-  # Private IP ranges that must not be targets of redirects (SSRF protection).
-  # Includes RFC 1918, loopback, link-local, and IPv6 equivalents.
-  # @api private
-  PRIVATE_IP_RANGES = [
-    IPAddr.new('10.0.0.0/8'),
-    IPAddr.new('172.16.0.0/12'),
-    IPAddr.new('192.168.0.0/16'),
-    IPAddr.new('127.0.0.0/8'),
-    IPAddr.new('169.254.0.0/16'),
-    IPAddr.new('0.0.0.0/8'),
-    IPAddr.new('::1/128'),
-    IPAddr.new('fc00::/7'),
-    IPAddr.new('fe80::/10')
-  ].freeze
-
   # Fetches and caches the OpenID Connect Discovery document.
   #
   # This class retrieves the discovery metadata from an OpenID Connect provider
@@ -63,14 +47,14 @@ module Verikloak
     # @param allow_http [Boolean] When false (default), raises on plain HTTP URLs. Set true for local development only.
     # @raise [DiscoveryError] when `discovery_url` is not a valid HTTP(S) URL
     def initialize(discovery_url:, connection: Verikloak::HTTP.default_connection, cache_ttl: 3600, allow_http: false)
-      normalized_url = discovery_url.is_a?(String) ? discovery_url.strip : discovery_url
+      normalized_url = SafeUrl.normalize(discovery_url)
 
-      unless normalized_url.is_a?(String) && normalized_url.match?(%r{^https?://})
+      unless normalized_url
         raise DiscoveryError.new('Invalid discovery URL: must be a non-empty HTTP(S) URL',
                                  code: 'invalid_discovery_url')
       end
 
-      unless allow_http || normalized_url.start_with?('https://')
+      if SafeUrl.insecure_http?(normalized_url, allow_http: allow_http)
         raise DiscoveryError.new(
           'Discovery URL must use HTTPS. Set allow_http: true to permit plain HTTP (development only).',
           code: 'insecure_discovery_url'
@@ -126,7 +110,15 @@ module Verikloak
     # @return [Hash]
     # @raise [DiscoveryError]
     def handle_final_response(response)
-      return parse_json(response.body) if response.status == 200
+      if response.status == 200
+        body = response.body.to_s
+        if body.bytesize > Verikloak::HTTP::MAX_RESPONSE_BYTES
+          raise DiscoveryError.new('Discovery response exceeds maximum allowed size',
+                                   code: 'discovery_metadata_invalid')
+        end
+
+        return parse_json(body)
+      end
 
       raise DiscoveryError.new(failure_message(response), code: 'discovery_metadata_fetch_failed')
     end
@@ -266,31 +258,19 @@ module Verikloak
     end
 
     # Validates that the redirect target does not resolve to a private/internal IP.
-    # IPv4-mapped IPv6 addresses are normalised before comparison.
+    # IPv4-mapped IPv6 addresses are normalised before comparison (see {SafeUrl}).
     # Skipped when `@allow_http` is true (development mode).
     # @api private
     # @param uri [URI] Parsed redirect target
     # @raise [DiscoveryError]
     def validate_redirect_not_private!(uri)
       return if @allow_http
+      return unless SafeUrl.resolves_to_private_ip?(uri.host)
 
-      host = uri.host
-      return unless host
-
-      Resolv.getaddresses(host).each do |addr|
-        ip = IPAddr.new(addr)
-        ip = ip.native if ip.ipv4_mapped?
-        next unless PRIVATE_IP_RANGES.any? { |range| range.include?(ip) }
-
-        raise DiscoveryError.new(
-          "Redirect target resolves to a private/internal address (#{host})",
-          code: 'discovery_redirect_error'
-        )
-      end
-    rescue IPAddr::InvalidAddressError
-      # If the address cannot be parsed, allow the request to proceed
-      # (Faraday will handle the actual connection error)
-      nil
+      raise DiscoveryError.new(
+        "Redirect target resolves to a private/internal address (#{uri.host})",
+        code: 'discovery_redirect_error'
+      )
     end
 
     # Wraps a block with network and parsing error handling and re-raising as {DiscoveryError}.

data/lib/verikloak/http.rb

@@ -11,6 +11,11 @@ module Verikloak
     # Default open/read timeout (seconds) before establishing the HTTP connection.
     DEFAULT_OPEN_TIMEOUT = 2
 
+    # Maximum accepted response body size (bytes) for discovery and JWKs
+    # documents. Real-world documents are a few KB; the cap guards against a
+    # compromised endpoint exhausting memory with an oversized response.
+    MAX_RESPONSE_BYTES = 1_048_576
+
     # Retry middleware configuration used for idempotent GET requests.
     # Retries on 429/5xx with exponential backoff and jitter.
     RETRY_OPTIONS = {

data/lib/verikloak/jwks_cache.rb

@@ -1,14 +1,66 @@
 # frozen_string_literal: true
 
 require 'faraday'
-require 'ipaddr'
 require 'json'
-require 'resolv'
 require 'uri'
 
 require 'verikloak/http'
+require 'verikloak/safe_url'
 
 module Verikloak
+  # @api private
+  #
+  # Revalidation-policy support for {JwksCache}: forced (TTL-bypassing)
+  # refreshes and server-TTL expiry checks used by the middleware throttle.
+  # Extracted from JwksCache to keep the class within length limits.
+  module JwksCacheRevalidation
+    # Revalidates the JWKs over HTTP regardless of TTL freshness.
+    #
+    # Used by the middleware's key-rotation retry path: a `Cache-Control:
+    # max-age` on the previous response must not delay picking up rotated
+    # keys when a token already failed with an unknown `kid` or bad signature.
+    #
+    # Subclasses that override {JwksCache#fetch!} with the pre-1.1 zero-arg
+    # signature are detected via the override's parameter list and get a plain
+    # `fetch!` call instead of `fetch!(force: true)` (no TTL bypass, but no crash).
+    #
+    # @return [Array<Hash>] the cached JWKs after revalidation
+    # @raise [JwksCacheError] (see JwksCache#fetch!)
+    def force_fetch!
+      fetch_supports_force? ? fetch!(force: true) : fetch!
+    end
+
+    # Whether the server-declared freshness lifetime has elapsed.
+    #
+    # Returns false when the server never sent `Cache-Control: max-age`
+    # (freshness is then governed solely by the caller's own policy).
+    # Reads the two timestamps without the mutex: they are only written
+    # together under it, and a torn pair merely shifts one revalidation
+    # by a single request.
+    #
+    # @return [Boolean]
+    def ttl_expired?
+      fetched_at = @fetched_at
+      max_age = @max_age
+      fetched_at && max_age ? (Time.now - fetched_at) >= max_age : false
+    end
+
+    private
+
+    # Whether the (possibly overridden) fetch! accepts the force: keyword.
+    # Guards {#force_fetch!} against subclasses written for the pre-1.1
+    # zero-arg fetch! signature.
+    #
+    # @return [Boolean]
+    def fetch_supports_force?
+      method(:fetch!).parameters.any? do |type, name|
+        (%i[key keyreq].include?(type) && name == :force) || type == :keyrest
+      end
+    rescue NameError
+      false
+    end
+  end
+
   # Caches and revalidates JSON Web Key Sets (JWKs) fetched from a remote endpoint.
   #
   # This cache supports two HTTP cache mechanisms:
@@ -39,22 +91,20 @@ module Verikloak
   # adapters, and shared headers (kept consistent with Discovery).
   #   `JwksCache.new(jwks_uri: "...", connection: Faraday.new { |f| f.request :retry })`
   class JwksCache
+    include JwksCacheRevalidation
+
     # @param jwks_uri [String] HTTPS URL of the JWKs endpoint
     # @param connection [Faraday::Connection, nil] Optional Faraday connection for HTTP requests
     # @param allow_http [Boolean] When false (default), raises on plain HTTP URIs. Set true for local development only.
     # @raise [JwksCacheError] if the URI is not an HTTP(S) URL or resolves to a private/internal address
     def initialize(jwks_uri:, connection: nil, allow_http: false)
-      unless jwks_uri.is_a?(String)
-        raise JwksCacheError.new('Invalid JWKs URI: must be a non-empty HTTP(S) URL', code: 'jwks_fetch_failed')
-      end
-
-      clean_jwks_uri = jwks_uri.strip
+      clean_jwks_uri = SafeUrl.normalize(jwks_uri)
 
-      unless clean_jwks_uri.match?(%r{^https?://})
+      unless clean_jwks_uri
         raise JwksCacheError.new('Invalid JWKs URI: must be a non-empty HTTP(S) URL', code: 'jwks_fetch_failed')
       end
 
-      unless allow_http || clean_jwks_uri.start_with?('https://')
+      if SafeUrl.insecure_http?(clean_jwks_uri, allow_http: allow_http)
         raise JwksCacheError.new(
           'JWKs URI must use HTTPS. Set allow_http: true to permit plain HTTP (development only).',
           code: 'insecure_jwks_uri'
@@ -78,11 +128,14 @@ module Verikloak
     # - 200: parses/validates body, updates keys, ETag, TTL and `fetched_at`.
     # - 304: keeps cached keys, updates TTL from headers (if present), refreshes `fetched_at`.
     #
+    # @param force [Boolean] When true, revalidates over HTTP even while
+    #   `Cache-Control: max-age` freshness holds (the ETag conditional request
+    #   still applies, so an unchanged key set costs only a 304).
     # @return [Array<Hash>] the cached JWKs after fetch/revalidation
     # @raise [JwksCacheError] on HTTP failures, invalid JSON, invalid structure, or cache miss on 304
-    def fetch!
+    def fetch!(force: false)
       @mutex.synchronize do
-        return @cached_keys if fresh_by_ttl_locked?
+        return @cached_keys if !force && fresh_by_ttl_locked?
 
         with_error_handling do
           # Build conditional request headers (ETag-based)
@@ -170,32 +223,21 @@ module Verikloak
     # compromised or malicious discovery endpoint to point JWKs fetching at internal services.
     #
     # IPv4-mapped IPv6 addresses (e.g. `::ffff:127.0.0.1`) are normalised to their native IPv4
-    # form before comparison, consistent with {Verikloak::Discovery}.
+    # form before comparison (see {SafeUrl}).
     #
     # @api private
     # @param url [String] The JWKs URI to validate
     # @raise [JwksCacheError] when the URI resolves to a private/internal address
     def validate_not_private!(url)
-      uri = URI.parse(url)
-      host = uri.host
-      return unless host
+      host = URI.parse(url).host
+      return unless SafeUrl.resolves_to_private_ip?(host)
 
-      Resolv.getaddresses(host).each do |addr|
-        ip = IPAddr.new(addr)
-        ip = ip.native if ip.ipv4_mapped?
-        next unless Verikloak::PRIVATE_IP_RANGES.any? { |range| range.include?(ip) }
-
-        raise JwksCacheError.new(
-          "JWKs URI resolves to a private/internal address (#{host})",
-          code: 'jwks_ssrf_blocked'
-        )
-      end
+      raise JwksCacheError.new(
+        "JWKs URI resolves to a private/internal address (#{host})",
+        code: 'jwks_ssrf_blocked'
+      )
     rescue URI::InvalidURIError => e
       raise JwksCacheError.new("Invalid JWKs URI: #{e.message}", code: 'jwks_fetch_failed')
-    rescue IPAddr::InvalidAddressError
-      # If the address cannot be parsed, allow the request to proceed
-      # (Faraday will handle the actual connection error)
-      nil
     end
 
     # @api private
@@ -294,7 +336,12 @@ module Verikloak
     # @param response [Faraday::Response]
     # @return [Array<Hash>] parsed and cached keys
     def process_successful_response(response)
-      json = parse_json!(response.body)
+      body = response.body.to_s
+      if body.bytesize > Verikloak::HTTP::MAX_RESPONSE_BYTES
+        raise JwksCacheError.new('JWKs response exceeds maximum allowed size', code: 'jwks_parse_failed')
+      end
+
+      json = parse_json!(body)
       keys = extract_and_validate_keys!(json)
       update_cache_from_ok(response, keys)
       keys

data/lib/verikloak/middleware.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'rack'
+require 'digest'
 require 'json'
 require 'set'
 require 'faraday'
@@ -67,11 +68,13 @@ module Verikloak
     end
 
     # Returns true when the ArgumentError message indicates a wrong arity.
+    # Anchored to the start of the message so ArgumentErrors raised inside the
+    # callable body that merely mention the phrase are not swallowed.
     #
     # @param error [ArgumentError]
     # @return [Boolean]
     def wrong_arity_error?(error)
-      error.message.include?('wrong number of arguments')
+      error.message.start_with?('wrong number of arguments')
     end
 
     # Extracts parameter information from a callable's call method.
@@ -167,6 +170,25 @@ module Verikloak
       raise ArgumentError, 'decoder_cache_limit must be zero or positive'
     end
 
+    # Validates and normalizes the JWKs refresh interval configuration.
+    # Numeric strings are coerced (consistent with decoder_cache_limit) so
+    # ENV-driven configuration works; nil falls back to the default rather
+    # than silently disabling the throttle.
+    #
+    # @param interval [Numeric, String, nil] Minimum seconds between JWKs revalidations.
+    # @return [Numeric] The normalized interval (nil becomes the default of 60).
+    # @raise [ArgumentError] if the interval is negative or not a number.
+    def normalize_jwks_refresh_interval(interval)
+      return Middleware::DEFAULT_JWKS_REFRESH_INTERVAL if interval.nil?
+
+      value = interval.is_a?(Numeric) ? interval : Float(interval)
+      raise ArgumentError, 'jwks_refresh_interval must be zero or positive' if value.negative?
+
+      value
+    rescue ArgumentError, TypeError
+      raise ArgumentError, 'jwks_refresh_interval must be zero or positive'
+    end
+
     # Validates and normalizes environment key configuration.
     #
     # @param value [String, #to_s] The environment key to normalize.
@@ -186,7 +208,7 @@ module Verikloak
     # @return [String] The normalized realm, or DEFAULT_REALM if nil.
     # @raise [ArgumentError] if the realm is blank after normalization.
     def normalize_realm(value)
-      return DEFAULT_REALM if value.nil?
+      return Middleware::DEFAULT_REALM if value.nil?
 
       normalized = value.to_s.strip
       raise ArgumentError, 'realm cannot be blank' if normalized.empty?
@@ -203,6 +225,11 @@ module Verikloak
       @logger.respond_to?(:error) || @logger.respond_to?(:warn) || @logger.respond_to?(:debug)
     end
 
+    # @return [Float] Monotonic clock reading in seconds.
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
     # Logs a message and backtrace using the configured logger.
     #
     # @param message [String] The primary error message to log.
@@ -305,7 +332,7 @@ module Verikloak
 
   # @api private
   #
-  # Internal mixin for JWT verification and discovery/JWKs management.
+  # Internal mixin for JWT verification and decoder caching.
   # Extracted from Middleware to reduce class length and improve clarity.
   module MiddlewareTokenVerification
     private
@@ -316,42 +343,31 @@ module Verikloak
     # @param error [Exception]
     # @return [Boolean]
     def retryable_decoder_error?(error)
-      return false unless error.is_a?(TokenDecoderError)
-      return true if error.code == 'invalid_signature'
-      return true if error.code == 'invalid_token' && error.message&.include?('Key with kid=')
-
-      false
+      error.is_a?(TokenDecoderError) && %w[invalid_signature kid_not_found].include?(error.code)
     end
 
-    # Returns a cached TokenDecoder instance for current inputs.
-    # Cache key uses issuer, audience, leeway, token_verify_options, and JWKs fetched_at timestamp.
+    # Returns a cached TokenDecoder instance built from the given key snapshot.
+    # The cache key derives from the snapshot itself, so a decoder can never be
+    # stored under a generation other than the keys it was built from (a
+    # concurrent refresh between reads previously made that pairing possible).
+    # When the digest is unavailable the decoder is built uncached — correct,
+    # just slower — rather than risking a collision under a shared key.
     #
     # @param audience [String, #call] The audience to create a decoder for
+    # @param keys [Array<Hash>] The JWKs snapshot to build the decoder from
     # @return [TokenDecoder] A decoder instance for the given audience
-    def decoder_for(audience)
-      keys = @jwks_cache.cached
-      fetched_at = @jwks_cache.respond_to?(:fetched_at) ? @jwks_cache.fetched_at : nil
-      cache_key = [
-        @issuer,
-        audience,
-        @leeway,
-        @token_verify_options,
-        fetched_at
-      ].hash
+    def decoder_for(audience, keys)
+      generation = keys_digest(keys)
+      return build_decoder(audience, keys) if generation.nil?
+
+      cache_key = [@issuer, audience, @leeway, @token_verify_options, generation]
       @mutex.synchronize do
         if (decoder = @decoder_cache[cache_key])
           touch_decoder_cache(cache_key) if track_decoder_order?
           return decoder
         end
 
-        decoder = TokenDecoder.new(
-          jwks: keys,
-          issuer: @issuer,
-          audience: audience,
-          leeway: @leeway,
-          options: @token_verify_options
-        )
-
+        decoder = build_decoder(audience, keys)
         return decoder if @decoder_cache_limit&.zero?
 
         prune_decoder_cache_if_needed
@@ -359,13 +375,32 @@ module Verikloak
       end
     end
 
-    # Ensures JWKs are up-to-date by invoking {#ensure_jwks_cache!}.
-    # Errors are not swallowed and are handled by the caller.
+    # @param audience [String, #call]
+    # @param keys [Array<Hash>]
+    # @return [TokenDecoder]
+    def build_decoder(audience, keys)
+      TokenDecoder.new(
+        jwks: keys,
+        issuer: @issuer,
+        audience: audience,
+        leeway: @leeway,
+        options: @token_verify_options
+      )
+    end
+
+    # Reads the current key snapshot, failing as an infrastructure error when
+    # nothing usable is cached. Used on both the first attempt and the
+    # post-refresh retry so an empty key set yields the same 503 on each path.
     #
-    # @return [void]
-    # @raise [Verikloak::DiscoveryError, Verikloak::JwksCacheError]
-    def refresh_jwks!
-      ensure_jwks_cache!
+    # @return [Array<Hash>]
+    # @raise [MiddlewareError] code `jwks_cache_miss` when no keys are cached
+    def current_keys!
+      keys = @jwks_cache.cached
+      if keys.nil? || keys.empty?
+        raise MiddlewareError.new('JWKs cache is empty, cannot verify token', code: 'jwks_cache_miss')
+      end
+
+      keys
     end
 
     # Decodes and verifies the JWT using the cached JWKs. On certain verification
@@ -377,14 +412,10 @@ module Verikloak
     # @raise [Verikloak::Error] bubbles up verification/fetch errors for centralized handling
     def decode_token(env, token)
       ensure_jwks_cache!
-      if @jwks_cache.cached.nil? || @jwks_cache.cached.empty?
-        raise MiddlewareError.new('JWKs cache is empty, cannot verify token', code: 'jwks_cache_miss')
-      end
-
+      keys = current_keys!
       audience = resolve_audience(env)
 
-      # First attempt
-      decoder = decoder_for(audience)
+      decoder = decoder_for(audience, keys)
 
       begin
         decoder.decode!(token)
@@ -392,39 +423,58 @@ module Verikloak
         # On key rotation or signature mismatch, refresh JWKs and retry once.
         raise unless retryable_decoder_error?(e)
 
-        refresh_jwks!
+        ensure_jwks_cache!(force: true)
 
-        # Rebuild decoder with refreshed keys and try once more.
-        decoder = decoder_for(audience)
+        # Re-snapshot and rebuild: the refresh may have rotated or emptied the keys.
+        keys = current_keys!
+        decoder = decoder_for(audience, keys)
         decoder.decode!(token)
       end
     end
+  end
+
+  # @api private
+  #
+  # Internal mixin for discovery/JWKs lifecycle: initialization, throttled and
+  # forced revalidation, and rotation detection (key-set content identity).
+  # Extracted from Middleware to reduce class length and improve clarity.
+  module MiddlewareJwksRefresh
+    # Minimum seconds between failure-triggered (forced) JWKs revalidations.
+    # A token that fails against keys fetched less than this long ago would
+    # fail against an immediate re-fetch too, so skipping the round trip
+    # loses nothing — and it caps the upstream request rate an attacker can
+    # induce by flooding the middleware with unknown-`kid` tokens.
+    FORCED_REFRESH_MIN_INTERVAL = 5
+
+    private
 
     # Ensures that discovery metadata and JWKs cache are initialized and up-to-date.
     # This method is thread-safe.
     #
     # * When the cache instance is missing, it is created from discovery metadata.
-    # * JWKs are (re)fetched every time; ETag/Cache-Control headers minimize traffic.
-    #
+    # * JWKs revalidation is throttled by `jwks_refresh_interval` so that hot
+    #   request paths do not serialize on a network call; ETag/Cache-Control
+    #   headers minimize traffic when a revalidation does happen. A server
+    #   `Cache-Control: max-age` shorter than the interval is honored: TTL
+    #   expiry reopens the window early (see {#jwks_recently_refreshed?}).
+    # * `force: true` bypasses the throttle **and** the cache's own max-age
+    #   freshness (used by the key-rotation retry path), rate-limited to one
+    #   revalidation per {FORCED_REFRESH_MIN_INTERVAL} seconds because the
+    #   trigger is attacker-controllable (any token with an unknown `kid`).
+    #
+    # @param force [Boolean] Revalidate even when the throttle window is still open.
     # @return [void]
     # @raise [Verikloak::DiscoveryError, Verikloak::JwksCacheError, Verikloak::MiddlewareError]
-    def ensure_jwks_cache!
+    def ensure_jwks_cache!(force: false)
+      return if !force && jwks_recently_refreshed?
+
       @mutex.synchronize do
-        previous_keys_id = cached_keys_identity(@jwks_cache)
-        if @jwks_cache.nil?
-          config   = @discovery.fetch!
-          # Use configured issuer if provided, otherwise use discovered issuer
-          @issuer  = @configured_issuer || config['issuer']
-          jwks_uri = config['jwks_uri']
-          @jwks_cache = JwksCache.new(jwks_uri: jwks_uri, connection: @connection, allow_http: @allow_http)
-        elsif @configured_issuer.nil? && @issuer.nil?
-          # If jwks_cache was injected but no issuer configured and not yet discovered, fetch discovery to set issuer
-          config = @discovery.fetch!
-          @issuer = config['issuer']
-        end
+        initialize_jwks_dependencies!
 
-        @jwks_cache.fetch!
-        purge_decoder_cache_if_keys_changed(previous_keys_id)
+        if force ? forced_refresh_allowed? : !jwks_recently_refreshed?
+          refresh_jwks!(force: force)
+          record_refresh!
+        end
       end
     rescue Verikloak::DiscoveryError, Verikloak::JwksCacheError => e
       # Re-raise so that specific error codes can be mapped in the middleware
@@ -433,31 +483,133 @@ module Verikloak
       raise MiddlewareError.new("Failed to initialize JWKs cache: #{e.message}", code: 'jwks_fetch_failed')
     end
 
+    # Records the outcome of a revalidation. Must be called while holding `@mutex`.
+    #
+    # An empty key set does not close the throttle window: leaving
+    # `@last_jwks_refresh_at` unset lets the very next request revalidate, so a
+    # transient `{"keys": []}` from the IdP heals on recovery instead of
+    # pinning 503s for the rest of the window.
+    #
+    # @return [void]
+    def record_refresh!
+      keys = @jwks_cache.respond_to?(:cached) ? @jwks_cache.cached : nil
+      purge_decoder_cache_if_keys_changed(keys)
+      @last_jwks_refresh_at = monotonic_now unless keys.nil? || keys.empty?
+    end
+
+    # Whether a failure-triggered refresh may hit the network. Keys revalidated
+    # within {FORCED_REFRESH_MIN_INTERVAL} seconds cannot have missed a rotation
+    # an immediate re-fetch would find, so the retry proceeds on cached keys.
+    #
+    # @return [Boolean]
+    def forced_refresh_allowed?
+      last = @last_jwks_refresh_at
+      last.nil? || (monotonic_now - last) >= FORCED_REFRESH_MIN_INTERVAL
+    end
+
+    # Creates the JWKs cache from discovery metadata and resolves the effective
+    # issuer. Must be called while holding `@mutex`.
+    #
+    # @return [void]
+    def initialize_jwks_dependencies!
+      if @jwks_cache.nil?
+        config   = @discovery.fetch!
+        # Use configured issuer if provided, otherwise use discovered issuer
+        @issuer  = @configured_issuer || config['issuer']
+        jwks_uri = config['jwks_uri']
+        @jwks_cache = JwksCache.new(jwks_uri: jwks_uri, connection: @connection, allow_http: @allow_http)
+      elsif @configured_issuer.nil? && @issuer.nil?
+        # If jwks_cache was injected but no issuer configured and not yet discovered, fetch discovery to set issuer
+        config = @discovery.fetch!
+        @issuer = config['issuer']
+      end
+    end
+
+    # Revalidates the JWKs cache. On the forced path, prefers
+    # {JwksCache#force_fetch!} so that a `Cache-Control: max-age` from the
+    # previous response cannot short-circuit the revalidation and leave the
+    # retry decoding against pre-rotation keys. Injected caches that only
+    # implement a plain `fetch!` keep their existing behavior.
+    #
+    # @param force [Boolean]
+    # @return [void]
+    def refresh_jwks!(force: false)
+      if force && @jwks_cache.respond_to?(:force_fetch!)
+        @jwks_cache.force_fetch!
+      else
+        @jwks_cache.fetch!
+      end
+    end
+
+    # Whether the JWKs were revalidated within the configured refresh interval.
+    # `@last_jwks_refresh_at` is only stamped after a successful non-empty
+    # refresh inside the mutex, so a non-nil value implies the dependencies are
+    # initialized. A server-declared `Cache-Control: max-age` that expires
+    # before the interval reopens the window early, so an IdP asking for
+    # faster revalidation than the throttle default still gets it.
+    # Reads shared state without the mutex; a stale read only causes an extra
+    # (harmless) pass through the synchronized slow path.
+    #
+    # @return [Boolean]
+    def jwks_recently_refreshed?
+      return false unless @jwks_refresh_interval.positive?
+
+      last = @last_jwks_refresh_at
+      return false if last.nil?
+      return false if @jwks_cache.respond_to?(:ttl_expired?) && @jwks_cache.ttl_expired?
+
+      (monotonic_now - last) < @jwks_refresh_interval
+    end
+
     # Purges the decoder cache if the JWKs have changed since last check.
-    # Compares key set identity to detect key rotation and invalidate cached decoders.
+    # Compares key set content identity to detect key rotation and invalidate
+    # cached decoders. When the digest cannot be computed for a present key
+    # set, the cache is cleared as the safe default (a rotation cannot be
+    # ruled out) and {#decoder_for} runs uncached until digests succeed again.
     #
-    # @param previous_keys_id [String, nil] The previous JWKs identity hash
+    # @param keys [Array<Hash>, nil] The key snapshot taken after the refresh
     # @return [void]
-    def purge_decoder_cache_if_keys_changed(previous_keys_id)
-      current_id = cached_keys_identity(@jwks_cache)
-      if (@last_cached_keys_id && current_id && @last_cached_keys_id != current_id) ||
-         (previous_keys_id && current_id && previous_keys_id != current_id)
+    def purge_decoder_cache_if_keys_changed(keys)
+      current_id = keys_digest(keys)
+      if current_id.nil?
+        clear_decoder_cache if keys
+      elsif @last_cached_keys_id && @last_cached_keys_id != current_id
         clear_decoder_cache
       end
 
-      @last_cached_keys_id = current_id if current_id
+      @last_cached_keys_id = current_id
     end
 
-    # Generates a unique identity hash for the current JWKs set.
-    # Used to detect changes in the key set for cache invalidation.
+    # Content digest of a key snapshot, stable across refreshes that return
+    # the same key set (unlike object identity) — both attribute order within
+    # a JWK and the order of keys in the array are canonicalized, since kid
+    # lookup makes ordering irrelevant to verification. The last
+    # (snapshot, digest) pair is memoized behind a single frozen reference, so
+    # the request path pays one `equal?` check while the cache keeps returning
+    # the same array object (TTL-fresh reads and 304 revalidations do).
+    # Failures are logged and yield nil — callers then skip decoder caching
+    # rather than risk keying different key sets identically.
     #
-    # @param cache [JwksCache] The JWKs cache instance
-    # @return [String, nil] A hash representing the current key set identity
-    def cached_keys_identity(cache)
-      return unless cache.respond_to?(:cached)
+    # @param keys [Array<Hash>, nil]
+    # @return [String, nil]
+    def keys_digest(keys)
+      return nil if keys.nil?
 
-      keys = cache.cached
-      keys&.__id__
+      memo = @keys_digest_memo
+      return memo[1] if memo && keys.equal?(memo[0])
+
+      canonical = Array(keys).map do |key|
+        key.respond_to?(:to_h) ? key.to_h.transform_keys(&:to_s).sort.inspect : key.inspect
+      end
+      digest = Digest::SHA256.hexdigest(canonical.sort.inspect)
+      @keys_digest_memo = [keys, digest].freeze
+      digest
+    rescue StandardError => e
+      if logger_available?
+        log_message(@logger, "[verikloak] JWKs digest failed (#{e.class}: #{e.message}); " \
+                             'decoder caching disabled for this key set')
+      end
+      nil
     end
   end
 
@@ -553,6 +705,7 @@ module Verikloak
     include MiddlewareAudienceResolution
     include MiddlewareDecoderCache
     include MiddlewareTokenVerification
+    include MiddlewareJwksRefresh
 
     DEFAULT_REALM = 'verikloak'
     DEFAULT_TOKEN_ENV_KEY = 'verikloak.token'
@@ -572,8 +725,13 @@ module Verikloak
     # @param token_verify_options [Hash] Additional JWT verification options passed through
     #   to TokenDecoder.
     #   e.g., { verify_iat: false, leeway: 10 }
+    # @param jwks_refresh_interval [Numeric] Minimum seconds between JWKs
+    #   revalidations on the request path. Set to `0` to revalidate on every
+    #   request (pre-1.1 behavior). Key rotation within the window is still
+    #   handled: a signature/kid mismatch forces an immediate refresh and retry.
     # rubocop:disable Metrics/ParameterLists
     DEFAULT_DECODER_CACHE_LIMIT = 128
+    DEFAULT_JWKS_REFRESH_INTERVAL = 60
 
     def initialize(app,
                    discovery_url:,
@@ -586,6 +744,7 @@ module Verikloak
                    leeway: Verikloak::TokenDecoder::DEFAULT_LEEWAY,
                    token_verify_options: {},
                    decoder_cache_limit: DEFAULT_DECODER_CACHE_LIMIT,
+                   jwks_refresh_interval: DEFAULT_JWKS_REFRESH_INTERVAL,
                    token_env_key: DEFAULT_TOKEN_ENV_KEY,
                    user_env_key: DEFAULT_USER_ENV_KEY,
                    realm: DEFAULT_REALM,
@@ -601,6 +760,8 @@ module Verikloak
       @leeway = leeway
       @token_verify_options = token_verify_options || {}
       @decoder_cache_limit = normalize_decoder_cache_limit(decoder_cache_limit)
+      @jwks_refresh_interval = normalize_jwks_refresh_interval(jwks_refresh_interval)
+      @last_jwks_refresh_at = nil
       # Optional user-configured issuer (overrides discovery issuer when provided)
       @configured_issuer = issuer
       # Effective issuer; may be nil initially and set via discovery if not configured
@@ -609,6 +770,7 @@ module Verikloak
       @decoder_cache = {}
       @decoder_cache_order = []
       @last_cached_keys_id = nil
+      @keys_digest_memo = nil
       @token_env_key = normalize_env_key(token_env_key, 'token_env_key')
       @user_env_key  = normalize_env_key(user_env_key, 'user_env_key')
       @realm         = normalize_realm(realm)

data/lib/verikloak/safe_url.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'ipaddr'
+require 'resolv'
+
+module Verikloak
+  # Private IP ranges that must not be targets of outbound requests (SSRF protection).
+  # Includes RFC 1918, loopback, link-local, and IPv6 equivalents.
+  # @api private
+  PRIVATE_IP_RANGES = [
+    IPAddr.new('10.0.0.0/8'),
+    IPAddr.new('172.16.0.0/12'),
+    IPAddr.new('192.168.0.0/16'),
+    IPAddr.new('127.0.0.0/8'),
+    IPAddr.new('169.254.0.0/16'),
+    IPAddr.new('0.0.0.0/8'),
+    IPAddr.new('::1/128'),
+    IPAddr.new('fc00::/7'),
+    IPAddr.new('fe80::/10')
+  ].freeze
+
+  # @api private
+  #
+  # Shared URL normalization and SSRF-protection helpers used by
+  # {Verikloak::Discovery} and {Verikloak::JwksCache}. Callers keep their own
+  # error classes and codes; this module only answers questions about URLs.
+  #
+  # NOTE: The private-IP check resolves the hostname at validation time, while
+  # the HTTP client resolves it again at connection time. A DNS rebinding
+  # attack (short-TTL records) can therefore pass validation and still connect
+  # to a private address. See SECURITY.md ("Known limitations").
+  module SafeUrl
+    module_function
+
+    # Strips surrounding whitespace and verifies the value is an HTTP(S) URL.
+    #
+    # @param url [Object] Candidate URL (any type).
+    # @return [String, nil] The stripped URL string, or nil when the value is
+    #   not a String or does not start with http:// or https://.
+    def normalize(url)
+      return nil unless url.is_a?(String)
+
+      normalized = url.strip
+      normalized.match?(%r{\Ahttps?://}) ? normalized : nil
+    end
+
+    # Whether the URL uses plain HTTP while HTTP is not allowed.
+    #
+    # @param url [String] Normalized URL string.
+    # @param allow_http [Boolean]
+    # @return [Boolean]
+    def insecure_http?(url, allow_http:)
+      !allow_http && !url.start_with?('https://')
+    end
+
+    # Whether the hostname resolves to at least one private/internal address.
+    #
+    # IPv4-mapped IPv6 addresses (e.g. `::ffff:127.0.0.1`) are normalised to
+    # their native IPv4 form before comparison. Addresses that cannot be
+    # parsed are ignored (the HTTP client will surface any real connection
+    # error).
+    #
+    # @param host [String, nil] Hostname or IP literal.
+    # @return [Boolean]
+    def resolves_to_private_ip?(host)
+      return false if host.nil? || host.to_s.empty?
+
+      Resolv.getaddresses(host).any? { |addr| private_address?(addr) }
+    end
+
+    # Whether a single address string falls within {PRIVATE_IP_RANGES}.
+    #
+    # @param address [String]
+    # @return [Boolean]
+    def private_address?(address)
+      ip = IPAddr.new(address)
+      ip = ip.native if ip.ipv4_mapped?
+      PRIVATE_IP_RANGES.any? { |range| range.include?(ip) }
+    rescue IPAddr::InvalidAddressError
+      false
+    end
+  end
+end

data/lib/verikloak/token_decoder.rb

@@ -26,6 +26,10 @@ module Verikloak
     # Default clock skew tolerance in seconds.
     DEFAULT_LEEWAY = 60
 
+    # Maximum length of an attacker-controlled `kid` value echoed back in
+    # error messages (and ultimately in 401 response bodies/headers).
+    MAX_KID_LENGTH_IN_MESSAGE = 64
+
     # Initializes the decoder with a JWKs and verification criteria.
     #
     # @param jwks     [Array<Hash>] List of JWKs from the discovery document.
@@ -65,6 +69,7 @@ module Verikloak
     # @return [Hash] The decoded payload (claims).
     # @raise [TokenDecoderError] If verification fails. Possible error codes:
     #   - invalid_token
+    #   - kid_not_found
     #   - expired_token
     #   - not_yet_valid
     #   - invalid_issuer
@@ -108,16 +113,26 @@ module Verikloak
     #
     # @param header [Hash]
     # @return [Hash] The matching JWK.
-    # @raise [TokenDecoderError] If key not found or unsupported type.
+    # @raise [TokenDecoderError] code: 'kid_not_found' when no JWK matches.
     def find_key_by_kid(header)
       kid = fetch_indifferent(header, 'kid')
       jwk = @jwk_by_kid[kid]
 
-      raise TokenDecoderError.new("Key with kid=#{kid} not found in JWKs", code: 'invalid_token') unless jwk
+      unless jwk
+        raise TokenDecoderError.new("Key with kid=#{truncate_kid(kid)} not found in JWKs", code: 'kid_not_found')
+      end
 
       jwk
     end
 
+    # Truncates an untrusted `kid` value for safe inclusion in error messages.
+    #
+    # @param kid [Object]
+    # @return [String]
+    def truncate_kid(kid)
+      kid.to_s.then { |s| s.length > MAX_KID_LENGTH_IN_MESSAGE ? "#{s[0, MAX_KID_LENGTH_IN_MESSAGE]}..." : s }
+    end
+
     # Decodes and verifies the token using the given public key and decode options.
     #
     # @param token      [String] JWT to verify.
@@ -243,7 +258,7 @@ module Verikloak
     def fetch_indifferent(hash, key)
       return nil unless hash.is_a?(Hash)
 
-      hash[key] || hash[key.to_s] || hash[key.to_sym]
+      hash[key.to_s] || hash[key.to_sym]
     end
 
     # Wraps decoding logic with structured error handling.

data/lib/verikloak/version.rb

@@ -2,5 +2,5 @@
 
 module Verikloak
   # Defines the current version of the Verikloak gem.
-  VERSION = '1.0.2'
+  VERSION = '1.1.0'
 end

data/lib/verikloak.rb

@@ -6,6 +6,7 @@
 require 'verikloak/version'
 require 'verikloak/errors'
 require 'verikloak/http'
+require 'verikloak/safe_url'
 require 'verikloak/discovery'
 require 'verikloak/jwks_cache'
 require 'verikloak/token_decoder'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.0
 platform: ruby
 authors:
 - taiyaky
@@ -15,7 +15,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.14.1
+        version: 2.14.3
     - - "<"
       - !ruby/object:Gem::Version
         version: '3.0'
@@ -25,7 +25,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.14.1
+        version: 2.14.3
     - - "<"
       - !ruby/object:Gem::Version
         version: '3.0'
@@ -121,6 +121,7 @@ files:
 - lib/verikloak/http.rb
 - lib/verikloak/jwks_cache.rb
 - lib/verikloak/middleware.rb
+- lib/verikloak/safe_url.rb
 - lib/verikloak/skip_path_matcher.rb
 - lib/verikloak/token_decoder.rb
 - lib/verikloak/version.rb
@@ -131,7 +132,7 @@ metadata:
   source_code_uri: https://github.com/taiyaky/verikloak
   changelog_uri: https://github.com/taiyaky/verikloak/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/taiyaky/verikloak/issues
-  documentation_uri: https://rubydoc.info/gems/verikloak/1.0.2
+  documentation_uri: https://rubydoc.info/gems/verikloak/1.1.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: