verikloak 0.1.5 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41b02d67b2d6182f8af59436549e9d68cccf08559ecdee0539793ee3baef77a7
-  data.tar.gz: 5cd807c55d6635370149cf0090644698f470d15c9e01dc78a9332adb6659e2f8
+  metadata.gz: 743b7db62f39f179fe22804c61144e661992625e43f3b411ea965f85364b6f50
+  data.tar.gz: ea9fea3cc08d53d076c60e946a39dad3594468dc16574b6a1f3a0e4574f9d80c
 SHA512:
-  metadata.gz: eba3a601c8c67080326955bd0557cfcc8d8098469694ef42ffac590b10a91c48cf4c3cb7250645d6db39e8208a8a05bd0bfa8b59cbdb9ced6e57e55241aa4da1
-  data.tar.gz: 553050d22b04de79bac27c00358f2c1a0779d380556297ffa2ca7bb5fa1944fe9ee55f9450ccc52cf004c7899c880484457b703d149404e80097079fff303341
+  metadata.gz: 89d6398d946686f61ec67dd93a2f807f38b4cc828bf86b4023787ea3aece53ebac95b08306827a06507883d1ef3f1711571af01db0c7ac5e2e4cc5340d92d34b
+  data.tar.gz: 5469a3833cde3b5f5e21439cdd19bb6638ef0e3b49fd2da64e7398dcd24a8851eec11f985ab0821a23b7446d275983b62e87804b541299ec486b88113d8b89ee

data/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.2.1] - 2025-09-23
+
+### Changed
+- **BREAKING**: `JwksCache` is now thread-safe with Mutex synchronization around all cache operations
+- Middleware code organization: split large modules into focused, single-responsibility components:
+  - `SkipPathMatcher`: Path matching and normalization logic
+  - `MiddlewareAudienceResolution`: Audience resolution with dynamic callable support
+  - `MiddlewareConfiguration`: Configuration validation and logging utilities
+  - `MiddlewareDecoderCache`: LRU cache management for TokenDecoder instances
+  - `MiddlewareTokenVerification`: JWT verification and JWKs management
+  - `MiddlewareErrorMapping`: Error-to-HTTP status code mapping
+
+### Fixed
+- Removed duplicate method definitions that were causing code bloat
+- Audience callable parameter detection now handles edge cases more reliably
+- Thread-safety issues in concurrent environments resolved
+
+## [0.2.0] - 2025-09-22
+
+### Added
+- Middleware options `token_env_key` and `user_env_key` for customizing where the token and decoded claims are stored in the Rack env.
+- Middleware option `realm` to change the `WWW-Authenticate` realm value emitted on 401 responses.
+- Middleware option `logger` so unexpected internal errors can be sent to the host application's logger instead of STDERR.
+
+### Changed
+- Update gem version to 0.2.0 to stay aligned with the rest of the Verikloak ecosystem gems.
+
 ## [0.1.5] - 2025-09-21
 
 ### Added
@@ -19,15 +46,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Dependencies
 - Declare `faraday-retry` as a runtime dependency so the default HTTP connection can load the retry middleware.
 
----
-
 ## [0.1.4] - 2025-09-20
 
 ### Chore
 - Bump dev dependency `rexml` to 3.4.2 (PR #15).
 
----
-
 ## [0.1.3] - 2025-09-15
 
 ### Changed
@@ -37,8 +60,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Bump dev dependency `rubocop` to 1.80.2 (PR #13).
 - Bump dev dependency `rubocop-rspec` to 3.7.0 (PR #12).
 
----
-
 ## [0.1.2] - 2025-08-31
 
 ### Added
@@ -51,8 +72,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Middleware: TokenDecoder instances are now cached per JWKs fetch for performance improvement.
 - Internal: RuboCop style fixes (`HashExcept`, `HashTransformKeys`, long line splits).
 
----
-
 ## [0.1.1] - 2025-08-24
 
 ### Changed
@@ -60,8 +79,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Updated dependency constraints in gemspec (`json` ~> 2.6, `jwt` ~> 2.7) for better compatibility control
 - Updated README badges (Gem version, Ruby version, downloads)
 
----
-
 ## [0.1.0] - 2025-08-17
 
 ### Added

data/README.md

@@ -94,6 +94,26 @@ config.middleware.use Verikloak::Middleware,
 ```
 This makes the configuration secure and flexible across environments.
 
+#### Advanced middleware options
+
+`Verikloak::Middleware` exposes a few optional knobs that help integrate with
+different Rack stacks:
+
+- `token_env_key` (default: `"verikloak.token"`) — where the raw JWT is stored in the Rack env
+- `user_env_key` (default: `"verikloak.user"`) — where decoded claims are stored
+- `realm` (default: `"verikloak"`) — value used in the `WWW-Authenticate` header for 401 responses
+- `logger` — an object responding to `error` (and optionally `debug`) that receives unexpected 500-level failures
+
+```ruby
+config.middleware.use Verikloak::Middleware,
+  discovery_url: ENV.fetch("DISCOVERY_URL"),
+  audience: ENV.fetch("CLIENT_ID"),
+  token_env_key: "rack.session.token",
+  user_env_key: "rack.session.claims",
+  realm: "my-api",
+  logger: Rails.logger
+```
+
 ### Accessing claims in controllers
 
 Once the middleware is enabled, Verikloak adds the decoded token and raw JWT to the Rack environment.  
@@ -232,6 +252,7 @@ For a full list of error cases and detailed explanations, please see the [ERRORS
 | `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. |
+| `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. |
 | `connection`   | No       | Inject a Faraday::Connection used for both Discovery and JWKs fetches. Defaults to a safe connection with timeouts and retries. |
 
 #### Option: `skip_paths`
@@ -256,7 +277,7 @@ Internally, `*` expands to match nested paths, so patterns like `/rails/*` are v
 
 #### Option: `audience`
 
-The `audience` option may be either a static String or any callable object (Proc, lambda, object responding to `#call`). When a callable is provided it receives the Rack `env` and can return a different audience for each request. This is useful when a single gateway serves multiple downstream clients:
+The `audience` option may be either a static String or any callable object (Proc, lambda, object responding to `#call`). When a callable is provided it receives the Rack `env` (either as a positional argument or keyword `env:`) and can return a different audience for each request. This is useful when a single gateway serves multiple downstream clients:
 
 ```ruby
 Verikloak::Middleware.new(app,
@@ -322,11 +343,37 @@ config.middleware.use Verikloak::Middleware,
 - `token_verify_options:` is passed directly to TokenDecoder (and ultimately to `JWT.decode`).
 - If both are set, `token_verify_options[:leeway]` takes precedence.
 
-#### Performance note
+#### Decoder cache & performance
 
 Internally, Verikloak caches `TokenDecoder` instances per JWKs fetch to avoid reinitializing
-them on every request. This improves performance while still ensuring that keys are
-revalidated when JWKs is refreshed.
+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.
+
+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).
+
+#### Sharing caches across verikloak gems
+
+When combining `verikloak` with companion gems (such as `verikloak-rails`, `verikloak-bff`, etc.),
+reusing infrastructure objects avoids redundant HTTP calls:
+
+```ruby
+connection = Verikloak::HTTP.default_connection
+jwks_cache = Verikloak::JwksCache.new(jwks_uri: ENV['JWKS_URI'], connection: connection)
+
+use Verikloak::Middleware,
+    discovery_url: ENV['DISCOVERY_URL'],
+    audience: ->(env) { env['verikloak.audience'] },
+    connection: connection,
+    jwks_cache: jwks_cache
+
+# Rails initializer or service object can now reuse `connection` and `jwks_cache`
+# when configuring other verikloak-* gems.
+```
+
+Sharing the Faraday connection keeps retry/time-out policies consistent, while a single `JwksCache`
+ensures all middleware layers refresh keys in unison.
 
 ## Architecture
 

data/lib/verikloak/jwks_cache.rb

@@ -50,6 +50,7 @@ module Verikloak
       @etag        = nil
       @fetched_at  = nil
       @max_age     = nil
+      @mutex       = Mutex.new
     end
 
     # Fetches the JWKs and updates the in-memory cache.
@@ -61,27 +62,31 @@ module Verikloak
     # @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!
-      return @cached_keys if fresh_by_ttl?
+      @mutex.synchronize do
+        return @cached_keys if fresh_by_ttl_locked?
 
-      with_error_handling do
-        # Build conditional request headers (ETag-based)
-        headers  = build_conditional_headers
-        # Perform HTTP GET request
-        response = @connection.get(@jwks_uri, nil, headers)
-        # Handle HTTP response according to status code
-        handle_response(response)
+        with_error_handling do
+          # Build conditional request headers (ETag-based)
+          headers  = build_conditional_headers
+          # Perform HTTP GET request
+          response = @connection.get(@jwks_uri, nil, headers)
+          # Handle HTTP response according to status code
+          handle_response(response)
+        end
       end
     end
 
     # Returns the last cached JWKs without performing a network request.
     # @return [Array<Hash>, nil] cached keys, or nil if never fetched
     def cached
-      @cached_keys
+      @mutex.synchronize { @cached_keys }
     end
 
     # Timestamp of the last successful fetch or revalidation.
     # @return [Time, nil]
-    attr_reader :fetched_at
+    def fetched_at
+      @mutex.synchronize { @fetched_at }
+    end
 
     # Injected Faraday connection (for testing and shared config across the gem)
     # @return [Faraday::Connection]
@@ -94,7 +99,7 @@ module Verikloak
     #
     # @return [Boolean]
     def stale?
-      !fresh_by_ttl?
+      @mutex.synchronize { !fresh_by_ttl_locked? }
     end
 
     # @api private
@@ -125,6 +130,12 @@ module Verikloak
     # True when cached keys are still fresh per `Cache-Control: max-age`.
     # @return [Boolean]
     def fresh_by_ttl?
+      @mutex.synchronize { fresh_by_ttl_locked? }
+    end
+
+    private
+
+    def fresh_by_ttl_locked?
       return false unless @cached_keys && @fetched_at && @max_age
 
       (Time.now - @fetched_at) < @max_age

data/lib/verikloak/middleware.rb

@@ -86,6 +86,299 @@ module Verikloak
     end
   end
 
+  # @api private
+  #
+  # Internal mixin for audience resolution with dynamic callable support.
+  # Handles various callable signatures and parameter detection.
+  module MiddlewareAudienceResolution
+    private
+
+    # Resolves the expected audience for the current request.
+    #
+    # @param env [Hash] Rack environment.
+    # @return [String, Array<String>] The expected audience value.
+    # @raise [MiddlewareError] when the resolved audience is blank.
+    def resolve_audience(env)
+      source = @audience_source
+      value = if source.respond_to?(:call)
+                callable = source
+                call_with_optional_env(callable, env)
+              else
+                source
+              end
+
+      raise MiddlewareError.new('Audience is blank for the request', code: 'invalid_audience') if value.nil?
+
+      if value.is_a?(Array)
+        raise MiddlewareError.new('Audience is blank for the request', code: 'invalid_audience') if value.empty?
+
+        return value
+      end
+
+      normalized = value.to_s
+      raise MiddlewareError.new('Audience is blank for the request', code: 'invalid_audience') if normalized.empty?
+
+      normalized
+    end
+
+    # Invokes the audience callable, passing the Rack env only when required.
+    # Falls back to a zero-argument invocation if the callable raises
+    # `ArgumentError` due to an unexpected argument.
+    #
+    # @param callable [#call] Audience resolver callable.
+    # @param env [Hash] Rack environment.
+    # @param arity [Integer, nil] Callable arity when known, nil otherwise.
+    # @return [Object] Audience value returned by the callable.
+    # @raise [ArgumentError] when the callable raises for reasons other than arity mismatch.
+    def call_with_optional_env(callable, env)
+      params = callable_parameters(callable)
+
+      invocation_chain(params).each do |strategy|
+        return strategy.call(callable, env)
+      rescue ArgumentError => e
+        raise unless wrong_arity_error?(e)
+      end
+
+      callable.call
+    end
+
+    # Returns true when the ArgumentError message indicates a wrong arity.
+    #
+    # @param error [ArgumentError]
+    # @return [Boolean]
+    def wrong_arity_error?(error)
+      error.message.include?('wrong number of arguments')
+    end
+
+    # Extracts parameter information from a callable's call method.
+    #
+    # @param callable [#call] The callable object to inspect.
+    # @return [Array<Array>, nil] Parameter information as returned by Method#parameters,
+    #   or nil if the method cannot be resolved.
+    def callable_parameters(callable)
+      callable.method(:call).parameters
+    rescue NameError
+      nil
+    end
+
+    # Builds a chain of invocation strategies based on callable parameters.
+    #
+    # @param params [Array<Array>, nil] Parameter information from Method#parameters.
+    # @return [Array<Proc>] Ordered array of lambda strategies to try when calling the callable.
+    def invocation_chain(params)
+      strategies = []
+
+      if params.nil?
+        # When parameters are unknown, try strategies in safe order:
+        # 1. Try with positional argument first (most common)
+        # 2. Try with no arguments as fallback
+        strategies << ->(callable, env) { callable.call(env) }
+        strategies << ->(callable, _env) { callable.call }
+      else
+        # When parameters are known, try most specific to least specific
+        strategies << ->(callable, env) { callable.call(env: env) } if accepts_keyword_env?(params)
+        strategies << ->(callable, env) { callable.call(env) } if accepts_positional_env?(params)
+        strategies << ->(callable, _env) { callable.call } if accepts_zero_arguments?(params)
+      end
+
+      strategies
+    end
+
+    # Determines if a callable accepts keyword arguments, specifically env: parameter.
+    #
+    # @param params [Array<Array>, nil] Parameter information from Method#parameters.
+    # @return [Boolean] true if the callable accepts keyword arguments including env.
+    def accepts_keyword_env?(params)
+      return false if params.nil?
+
+      params.any? do |type, name|
+        type == :keyrest ||
+          (%i[keyreq key].include?(type) && (name.nil? || name == :env))
+      end
+    end
+
+    # Determines if a callable accepts positional arguments.
+    #
+    # @param params [Array<Array>, nil] Parameter information from Method#parameters.
+    # @return [Boolean] true if the callable accepts positional arguments.
+    def accepts_positional_env?(params)
+      return false if params.nil?
+
+      params.any? { |type, _| %i[req opt rest].include?(type) }
+    end
+
+    # Determines if a callable accepts zero arguments (no required parameters).
+    #
+    # @param params [Array<Array>, nil] Parameter information from Method#parameters.
+    # @return [Boolean] true if the callable can be called with no arguments.
+    def accepts_zero_arguments?(params)
+      return false if params.nil?
+
+      # Only accepts zero arguments if parameters are empty
+      # or all parameters are optional/keyword/blocks
+      params.empty? || params.all? { |type, _| %i[opt key keyrest block].include?(type) }
+    end
+  end
+
+  # @api private
+  #
+  # Internal mixin for configuration validation and logging utilities.
+  # Extracted to keep the main Middleware class focused and under line limits.
+  module MiddlewareConfiguration
+    private
+
+    # Validates and normalizes the decoder cache limit configuration.
+    #
+    # @param limit [Integer, nil] The cache limit value to normalize.
+    # @return [Integer, nil] The normalized limit, or nil if no limit.
+    # @raise [ArgumentError] if the limit is negative or invalid.
+    def normalize_decoder_cache_limit(limit)
+      return nil if limit.nil?
+
+      value = Integer(limit)
+      raise ArgumentError, 'decoder_cache_limit must be zero or positive' if value.negative?
+
+      value
+    rescue ArgumentError, TypeError
+      raise ArgumentError, 'decoder_cache_limit must be zero or positive'
+    end
+
+    # Validates and normalizes environment key configuration.
+    #
+    # @param value [String, #to_s] The environment key to normalize.
+    # @param option_name [String] The name of the option for error messages.
+    # @return [String] The normalized environment key.
+    # @raise [ArgumentError] if the key is blank after normalization.
+    def normalize_env_key(value, option_name)
+      normalized = value.to_s.strip
+      raise ArgumentError, "#{option_name} cannot be blank" if normalized.empty?
+
+      normalized
+    end
+
+    # Validates and normalizes the realm configuration.
+    #
+    # @param value [String, #to_s, nil] The realm value to normalize.
+    # @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?
+
+      normalized = value.to_s.strip
+      raise ArgumentError, 'realm cannot be blank' if normalized.empty?
+
+      normalized
+    end
+
+    # Checks if a logger instance is available and responds to logging methods.
+    #
+    # @return [Boolean] true if a logger is available and can log messages.
+    def logger_available?
+      return false unless @logger
+
+      @logger.respond_to?(:error) || @logger.respond_to?(:warn) || @logger.respond_to?(:debug)
+    end
+
+    # Logs a message and backtrace using the configured logger.
+    #
+    # @param message [String] The primary error message to log.
+    # @param backtrace [String, nil] The backtrace information to log.
+    # @return [void]
+    def log_with_logger(message, backtrace)
+      log_message(@logger, message)
+      log_backtrace(@logger, backtrace)
+    end
+
+    # Logs a message using the most appropriate logger method.
+    #
+    # @param logger [Logger] The logger instance to use.
+    # @param message [String] The message to log.
+    # @return [void]
+    def log_message(logger, message)
+      if logger.respond_to?(:error)
+        logger.error(message)
+      elsif logger.respond_to?(:warn)
+        logger.warn(message)
+      end
+    end
+
+    # Logs backtrace information using the most appropriate logger method.
+    #
+    # @param logger [Logger] The logger instance to use.
+    # @param backtrace [String, nil] The backtrace information to log.
+    # @return [void]
+    def log_backtrace(logger, backtrace)
+      return unless backtrace
+
+      if logger.respond_to?(:debug)
+        logger.debug(backtrace)
+      elsif logger.respond_to?(:error)
+        logger.error(backtrace)
+      elsif logger.respond_to?(:warn)
+        logger.warn(backtrace)
+      end
+    end
+  end
+
+  # @api private
+  #
+  # Internal mixin for decoder cache management with LRU eviction.
+  # Handles TokenDecoder instance caching and cleanup.
+  module MiddlewareDecoderCache
+    private
+
+    # Stores a decoder in the cache and updates access order if tracking is enabled.
+    #
+    # @param cache_key [String] The cache key for the decoder
+    # @param decoder [TokenDecoder] The decoder instance to cache
+    # @return [TokenDecoder] The cached decoder instance
+    def store_decoder_cache(cache_key, decoder)
+      @decoder_cache[cache_key] = decoder
+      touch_decoder_cache(cache_key) if track_decoder_order?
+      decoder
+    end
+
+    # Prunes the decoder cache to stay within the configured limit.
+    # Removes the oldest entries when the cache size exceeds the limit.
+    #
+    # @return [void]
+    def prune_decoder_cache_if_needed
+      return unless track_decoder_order?
+
+      while @decoder_cache_order.length >= @decoder_cache_limit
+        oldest = @decoder_cache_order.shift
+        @decoder_cache.delete(oldest)
+      end
+    end
+
+    # Updates the access order for a cache entry to mark it as recently used.
+    # Moves the cache key to the end of the order queue for LRU tracking.
+    #
+    # @param cache_key [String] The cache key to mark as recently accessed
+    # @return [void]
+    def touch_decoder_cache(cache_key)
+      @decoder_cache_order.delete(cache_key)
+      @decoder_cache_order << cache_key
+    end
+
+    # Checks if decoder cache order tracking is enabled.
+    # Returns true if cache limit is set and positive.
+    #
+    # @return [Boolean] true if order tracking is enabled
+    def track_decoder_order?
+      @decoder_cache_limit&.positive?
+    end
+
+    # Clears all cached decoder instances and order tracking.
+    # Removes all entries from both the cache and order queue.
+    #
+    # @return [void]
+    def clear_decoder_cache
+      @decoder_cache.clear
+      @decoder_cache_order.clear
+    end
+  end
+
   # @api private
   #
   # Internal mixin for JWT verification and discovery/JWKs management.
@@ -108,6 +401,9 @@ module Verikloak
 
     # Returns a cached TokenDecoder instance for current inputs.
     # Cache key uses issuer, audience, leeway, token_verify_options, and JWKs fetched_at timestamp.
+    #
+    # @param audience [String, #call] The audience to create a decoder for
+    # @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
@@ -119,13 +415,23 @@ module Verikloak
         fetched_at
       ].hash
       @mutex.synchronize do
-        @decoder_cache[cache_key] ||= TokenDecoder.new(
+        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
         )
+
+        return decoder if @decoder_cache_limit&.zero?
+
+        prune_decoder_cache_if_needed
+        store_decoder_cache(cache_key, decoder)
       end
     end
 
@@ -141,8 +447,9 @@ module Verikloak
     # Decodes and verifies the JWT using the cached JWKs. On certain verification
     # failures (e.g., key rotation), it refreshes the JWKs and retries once.
     #
-    # @param token [String]
-    # @return [Hash] decoded JWT claims
+    # @param env [Hash] The Rack environment hash
+    # @param token [String] The JWT token to decode and verify
+    # @return [Hash] Decoded JWT claims
     # @raise [Verikloak::Error] bubbles up verification/fetch errors for centralized handling
     def decode_token(env, token)
       ensure_jwks_cache!
@@ -169,73 +476,6 @@ module Verikloak
       end
     end
 
-    # Resolves the expected audience for the current request.
-    #
-    # @param env [Hash] Rack environment.
-    # @return [String, Array<String>] The expected audience value.
-    # @raise [MiddlewareError] when the resolved audience is blank.
-    def resolve_audience(env)
-      source = @audience_source
-      value = if source.respond_to?(:call)
-                callable = source
-                arity = callable.respond_to?(:arity) ? callable.arity : safe_callable_arity(callable)
-                call_with_optional_env(callable, env, arity)
-              else
-                source
-              end
-
-      raise MiddlewareError.new('Audience is blank for the request', code: 'invalid_audience') if value.nil?
-
-      if value.is_a?(Array)
-        raise MiddlewareError.new('Audience is blank for the request', code: 'invalid_audience') if value.empty?
-
-        return value
-      end
-
-      normalized = value.to_s
-      raise MiddlewareError.new('Audience is blank for the request', code: 'invalid_audience') if normalized.empty?
-
-      normalized
-    end
-
-    # Invokes the audience callable, passing the Rack env only when required.
-    # Falls back to a zero-argument invocation if the callable raises
-    # `ArgumentError` due to an unexpected argument.
-    #
-    # @param callable [#call] Audience resolver callable.
-    # @param env [Hash] Rack environment.
-    # @param arity [Integer, nil] Callable arity when known, nil otherwise.
-    # @return [Object] Audience value returned by the callable.
-    # @raise [ArgumentError] when the callable raises for reasons other than arity mismatch.
-    def call_with_optional_env(callable, env, arity)
-      return callable.call if arity&.zero?
-
-      callable.call(env)
-    rescue ArgumentError => e
-      raise unless arity.nil? && wrong_arity_error?(e)
-
-      callable.call
-    end
-
-    # Safely obtains a callable's arity, returning nil when `#method(:call)`
-    # cannot be resolved (e.g., BasicObject-based objects).
-    #
-    # @param callable [#call]
-    # @return [Integer, nil]
-    def safe_callable_arity(callable)
-      callable.method(:call).arity
-    rescue NameError
-      nil
-    end
-
-    # Returns true when the ArgumentError message indicates a wrong arity.
-    #
-    # @param error [ArgumentError]
-    # @return [Boolean]
-    def wrong_arity_error?(error)
-      error.message.include?('wrong number of arguments')
-    end
-
     # Ensures that discovery metadata and JWKs cache are initialized and up-to-date.
     # This method is thread-safe.
     #
@@ -246,6 +486,7 @@ module Verikloak
     # @raise [Verikloak::DiscoveryError, Verikloak::JwksCacheError, Verikloak::MiddlewareError]
     def ensure_jwks_cache!
       @mutex.synchronize do
+        previous_keys_id = cached_keys_identity(@jwks_cache)
         if @jwks_cache.nil?
           config   = @discovery.fetch!
           @issuer  = config['issuer']
@@ -254,6 +495,7 @@ module Verikloak
         end
 
         @jwks_cache.fetch!
+        purge_decoder_cache_if_keys_changed(previous_keys_id)
       end
     rescue Verikloak::DiscoveryError, Verikloak::JwksCacheError => e
       # Re-raise so that specific error codes can be mapped in the middleware
@@ -261,6 +503,33 @@ module Verikloak
     rescue StandardError => e
       raise MiddlewareError.new("Failed to initialize JWKs cache: #{e.message}", code: 'jwks_fetch_failed')
     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.
+    #
+    # @param previous_keys_id [String, nil] The previous JWKs identity hash
+    # @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)
+        clear_decoder_cache
+      end
+
+      @last_cached_keys_id = current_id if current_id
+    end
+
+    # Generates a unique identity hash for the current JWKs set.
+    # Used to detect changes in the key set for cache invalidation.
+    #
+    # @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)
+
+      keys = cache.cached
+      keys&.__id__
+    end
   end
 
   # @api private
@@ -285,13 +554,17 @@ module Verikloak
 
     private
 
-    # @param code [String, nil] short error code
+    # Determines if an error code should result in a 403 Forbidden response.
+    #
+    # @param code [String, nil] The error code to check
     # @return [Boolean] true if the error should be treated as a 403 Forbidden
     def forbidden?(code)
       code == 'forbidden'
     end
 
-    # @param code [String, nil]
+    # Determines if an error code belongs to authentication-related errors.
+    #
+    # @param code [String, nil] The error code to check
     # @return [Boolean] true if the error belongs to {AUTH_ERROR_CODES}
     def auth_error?(code)
       code && AUTH_ERROR_CODES.include?(code)
@@ -347,8 +620,15 @@ module Verikloak
   class Middleware
     include MiddlewareErrorMapping
     include SkipPathMatcher
+    include MiddlewareConfiguration
+    include MiddlewareAudienceResolution
+    include MiddlewareDecoderCache
     include MiddlewareTokenVerification
 
+    DEFAULT_REALM = 'verikloak'
+    DEFAULT_TOKEN_ENV_KEY = 'verikloak.token'
+    DEFAULT_USER_ENV_KEY = 'verikloak.user'
+
     # @param app [#call] downstream Rack app
     # @param discovery_url [String] OIDC discovery endpoint URL
     # @param audience [String, #call] Expected `aud` claim. When a callable is provided it
@@ -362,6 +642,9 @@ module Verikloak
     # @param token_verify_options [Hash] Additional JWT verification options passed through
     #   to TokenDecoder.
     #   e.g., { verify_iat: false, leeway: 10 }
+    # rubocop:disable Metrics/ParameterLists
+    DEFAULT_DECODER_CACHE_LIMIT = 128
+
     def initialize(app,
                    discovery_url:,
                    audience:,
@@ -370,7 +653,12 @@ module Verikloak
                    jwks_cache: nil,
                    connection: nil,
                    leeway: Verikloak::TokenDecoder::DEFAULT_LEEWAY,
-                   token_verify_options: {})
+                   token_verify_options: {},
+                   decoder_cache_limit: DEFAULT_DECODER_CACHE_LIMIT,
+                   token_env_key: DEFAULT_TOKEN_ENV_KEY,
+                   user_env_key: DEFAULT_USER_ENV_KEY,
+                   realm: DEFAULT_REALM,
+                   logger: nil)
       @app             = app
       @connection      = connection || Verikloak::HTTP.default_connection
       @audience_source = audience
@@ -378,12 +666,20 @@ module Verikloak
       @jwks_cache      = jwks_cache
       @leeway = leeway
       @token_verify_options = token_verify_options || {}
+      @decoder_cache_limit = normalize_decoder_cache_limit(decoder_cache_limit)
       @issuer        = nil
       @mutex         = Mutex.new
       @decoder_cache = {}
+      @decoder_cache_order = []
+      @last_cached_keys_id = 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)
+      @logger        = logger
 
       compile_skip_paths(skip_paths)
     end
+    # rubocop:enable Metrics/ParameterLists
 
     # Rack entrypoint.
     #
@@ -407,26 +703,28 @@ module Verikloak
 
     # Returns the Faraday connection used for HTTP operations (Discovery/JWKs).
     # Exposed for tests; not part of public API.
+    #
+    # @return [Faraday::Connection] The HTTP connection instance
     def http_connection
       @connection
     end
 
     # Verifies the token, stores result in Rack env, and forwards to the downstream app.
     #
-    # @param env [Hash]
-    # @param token [String]
+    # @param env [Hash] The Rack environment hash
+    # @param token [String] The extracted JWT token
     # @return [Array(Integer, Hash, Array<String>)] Rack response triple
     def handle_request(env, token)
       claims = decode_token(env, token)
-      env['verikloak.token'] = token
-      env['verikloak.user']  = claims
+      env[@token_env_key] = token
+      env[@user_env_key]  = claims
       @app.call(env)
     end
 
     # Extracts the Bearer token from the `Authorization` header.
     #
-    # @param env [Hash]
-    # @return [String] the raw JWT string
+    # @param env [Hash] The Rack environment hash
+    # @return [String] The raw JWT string
     # @raise [Verikloak::MiddlewareError] when the header is missing or malformed
     def extract_token(env)
       auth = env['HTTP_AUTHORIZATION']
@@ -445,8 +743,8 @@ module Verikloak
 
     # Converts a raised error into a `[code, http_status]` tuple for response rendering.
     #
-    # @param error [Exception]
-    # @return [Array(String, Integer)]
+    # @param error [Exception] The exception to map
+    # @return [Array(String, Integer)] A tuple of error code and HTTP status
     def map_error(error)
       code = error.respond_to?(:code) ? error.code : nil
 
@@ -466,16 +764,16 @@ module Verikloak
 
     # Builds a JSON error response with RFC 6750 `WWW-Authenticate` header for 401.
     #
-    # @param code [String]
-    # @param message [String]
-    # @param status [Integer]
+    # @param code [String] The error code to include in the response
+    # @param message [String] The error message to include in the response
+    # @param status [Integer] The HTTP status code for the response
     # @return [Array(Integer, Hash, Array<String>)] Rack response triple
     def error_response(code = 'unauthorized', message = 'Unauthorized', status = 401)
       body = { error: code, message: message }.to_json
       headers = { 'Content-Type' => 'application/json' }
       if status == 401
         headers['WWW-Authenticate'] =
-          %(Bearer realm="verikloak", error="#{code}", error_description="#{message.gsub('"', '\\"')}")
+          %(Bearer realm="#{@realm}", error="#{code}", error_description="#{message.gsub('"', '\\"')}")
       end
       [status, headers, [body]]
     end
@@ -485,8 +783,15 @@ module Verikloak
     # @param error [Exception]
     # @return [void]
     def log_internal_error(error)
-      warn "[verikloak] Internal error: #{error.class} - #{error.message}"
-      warn error.backtrace.join("\n") if error.backtrace
+      message = "[verikloak] Internal error: #{error.class} - #{error.message}"
+      backtrace = error.backtrace&.join("\n")
+
+      if logger_available?
+        log_with_logger(message, backtrace)
+      else
+        warn message
+        warn backtrace if backtrace
+      end
     end
   end
 end

data/lib/verikloak/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.2.1
 platform: ruby
 authors:
 - taiyaky
@@ -109,7 +109,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/0.1.5
+  documentation_uri: https://rubydoc.info/gems/verikloak/0.2.1
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: