verikloak 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d175a574b17bd1ce5e096dbb69769d12a470f49c8444a5246881afd61d06fa52
-  data.tar.gz: 3c59a660bb142c194b6e0db2d338952c41c8a88afc479382203b4d767ab7691c
+  metadata.gz: 24bc2b5eb7f699c9f8bc4970a2b0b6cdca87b7c7e37d9718c51d85d8cf58a8cc
+  data.tar.gz: 439ec2fb34a67140476aff243addfaac8cb8d5ac18ef7b6915d3a9ba6dc5947d
 SHA512:
-  metadata.gz: 92edd8a2df134f115c3f887683246278c5778291bb86bfff22ebc873b2b92d6ff09d9c85a1f798e2f49caa09adc8c3ef18ffc83309f95799997ebbdb54b58228
-  data.tar.gz: 0e223f0055e69448899be53fc22c9ac32c5d43c410aa041daa38761ed13a00aae8d655bcb6eaff521927a5a029937fcd480c7b90dcfccddf8e6b028aaf0bf555
+  metadata.gz: 61be82820e149b89c7e5dead4bc79aef1da0959b85ba447e7bf9d6a346efb331f378030620c2ee42d2b41e5c3e21d89346f405ad16b6264f9452fc49771fc2d4
+  data.tar.gz: 9bec7c747971154c59321505fdd2817487e09013eb8e32d3defe86a7dc38a4731c5e01d113639cd3eae1a33e9073b932dfa5d9a243b65a1609d9b3549cb48129

data/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.3.0] - 2025-12-31
+
+### Added
+- **NEW**: `issuer` parameter for `Middleware#initialize` to optionally override the discovered issuer
+  - When provided, the configured issuer takes precedence over the OIDC discovery document's issuer
+  - This enables compatibility with `verikloak-rails` which passes `issuer` from configuration
+  - If not provided, the middleware continues to use the issuer from OIDC discovery (existing behavior)
+
+### Changed
+- Internal issuer handling now distinguishes between `@configured_issuer` (user-provided) and `@issuer` (discovered/effective)
+- When `jwks_cache` is injected, discovery is only fetched once (and skipped entirely if `issuer` is provided)
+
+## [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
@@ -17,8 +46,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### 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
@@ -31,15 +58,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
@@ -49,8 +72,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
@@ -63,8 +84,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
@@ -72,8 +91,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

@@ -41,10 +41,42 @@ Add the middleware in `config/application.rb`:
 ```ruby
 config.middleware.use Verikloak::Middleware,
   discovery_url: "https://keycloak.example.com/realms/myrealm/.well-known/openid-configuration",
-  audience: "your-client-id",
-  skip_paths: ['/skip_path']
+  audience: "your-client-id"
 ```
 
+For production environments, use environment variables:
+
+```ruby
+config.middleware.use Verikloak::Middleware,
+  discovery_url: ENV.fetch("DISCOVERY_URL"),
+  audience: ENV.fetch("CLIENT_ID"),
+  skip_paths: ['/', '/health', '/public/*', '/rails/*']
+```
+
+#### Advanced configuration
+
+For more complex setups, Verikloak supports additional configuration options:
+
+```ruby
+config.middleware.use Verikloak::Middleware,
+  discovery_url: ENV.fetch("DISCOVERY_URL"),
+  audience: ENV.fetch("CLIENT_ID"),
+  issuer: "https://custom.issuer.example.com/realms/myrealm", # Optional: override discovered issuer
+  skip_paths: ['/', '/health', '/public/*', '/rails/*'],
+  leeway: 30, # Allow 30 seconds clock skew
+  token_env_key: "rack.session.token",     # Custom token storage key
+  user_env_key: "rack.session.claims",     # Custom user claims storage key
+  realm: "my-api",                         # Custom realm for WWW-Authenticate header
+  logger: Rails.logger                     # Logger for internal errors
+```
+
+**Additional middleware options:**
+
+- `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
+
 #### Handling Authentication Failures
 
 When you use the Rack middleware, authentication failures are automatically converted into JSON error responses (for example, `401` for token issues, `503` for JWKs/discovery errors). In most cases **you do not need to add custom `rescue_from` handlers** in Rails controllers.
@@ -84,40 +116,25 @@ All Verikloak errors inherit from `Verikloak::Error`:
 - `Verikloak::JwksCacheError` – JWKs fetch/parse/cache (`503 Service Unavailable`)
 - `Verikloak::MiddlewareError` – header/infra issues surfaced by the middleware (usually `401`, sometimes `503`)
 
-#### Recommended: use environment variables in production
+### Standalone Rack app
 
 ```ruby
-config.middleware.use Verikloak::Middleware,
-  discovery_url: ENV.fetch("DISCOVERY_URL"),
-  audience: ENV.fetch("CLIENT_ID"),
-  skip_paths: ['/', '/health', '/public/*', '/rails/*']
-```
-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:
+# config.ru example for a standalone Rack app
+require "verikloak"
 
-- `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
+use Verikloak::Middleware,
+  discovery_url: "https://keycloak.example.com/realms/myrealm/.well-known/openid-configuration",
+  audience: "my-client-id"
 
-```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
+run ->(env) {
+  user = env["verikloak.user"] # Decoded JWT claims hash (if token is valid)
+  [200, { "Content-Type" => "application/json" }, [user.to_json]]
+}
 ```
 
 ### Accessing claims in controllers
 
-Once the middleware is enabled, Verikloak adds the decoded token and raw JWT to the Rack environment.  
-You can access them in any Rails controller:
+Once the middleware is enabled, Verikloak adds the decoded token and raw JWT to the Rack environment:
 
 ```ruby
 class Api::V1::NotesController < ApplicationController
@@ -131,22 +148,6 @@ class Api::V1::NotesController < ApplicationController
 end
 ```
 
-### Standalone Rack app
-
-```ruby
-# config.ru example for a standalone Rack app
-require "verikloak"
-
-use Verikloak::Middleware,
-  discovery_url: "https://keycloak.example.com/realms/myrealm/.well-known/openid-configuration",
-  audience: "my-client-id"
-
-run ->(env) {
-  user = env["verikloak.user"] # Decoded JWT claims hash (if token is valid)
-  [200, { "Content-Type" => "application/json" }, [user.to_json]]
-}
-```
-
 ## How It Works
 
 1. Extracts the `Authorization: Bearer <token>` header
@@ -194,26 +195,7 @@ Verikloak returns JSON error responses in a consistent format with structured er
 }
 ```
 
-```json
-{
-  "error": "jwks_parse_failed",
-  "message": "Failed to parse JWKs"
-}
-```
-
-```json
-{
-  "error": "discovery_metadata_fetch_failed",
-  "message": "Failed to fetch OIDC discovery document"
-}
-```
-
-```json
-{
-  "error": "discovery_metadata_invalid",
-  "message": "Failed to parse OIDC discovery document"
-}
-```
+For a full list of error cases and detailed explanations, please see the [ERRORS.md](ERRORS.md) file.
 
 ### Error Types
 
@@ -223,36 +205,40 @@ Verikloak returns JSON error responses in a consistent format with structured er
 | `expired_token`            | 401 Unauthorized          | The token has expired                                                                        |
 | `missing_authorization_header` | 401 Unauthorized      | The `Authorization` header is missing                                                        |
 | `invalid_authorization_header` | 401 Unauthorized      | The `Authorization` header format is invalid                                                 |
-| `unsupported_algorithm`    | 401 Unauthorized          | The token’s signing algorithm is not supported                                               |
+| `unsupported_algorithm`    | 401 Unauthorized          | The token's signing algorithm is not supported                                               |
 | `invalid_signature`        | 401 Unauthorized          | The token signature could not be verified                                                    |
 | `invalid_issuer`           | 401 Unauthorized          | Invalid `iss` claim                                                                          |
 | `invalid_audience`         | 401 Unauthorized          | Invalid `aud` claim                                                                          |
 | `not_yet_valid`            | 401 Unauthorized          | The token is not yet valid (`nbf` in the future)                                             |
-| `jwks_fetch_failed`        | 503 Service Unavailable   | Failed to fetch JWKs                                                                    |
-| `jwks_parse_failed`        | 503 Service Unavailable   | Failed to parse JWKs                                                                    |
+| `jwks_fetch_failed`        | 503 Service Unavailable   | Failed to fetch JWKs                                                                         |
+| `jwks_parse_failed`        | 503 Service Unavailable   | Failed to parse JWKs                                                                         |
 | `jwks_cache_miss`          | 503 Service Unavailable   | JWKs cache is empty (e.g., 304 Not Modified without prior cache)                             |
 | `discovery_metadata_fetch_failed` | 503 Service Unavailable   | Failed to fetch OIDC discovery document                                               |
-| `discovery_metadata_invalid` | 503 Service Unavailable   | Failed to parse OIDC discovery document                                                    |
+| `discovery_metadata_invalid` | 503 Service Unavailable   | Failed to parse OIDC discovery document                                                     |
 | `discovery_redirect_error` | 503 Service Unavailable   | Discovery response was a redirect without a valid Location header                           |
 | `internal_server_error`    | 500 Internal Server Error | Unexpected internal error (catch-all)                                                        |
 
 > **Note:** The `decode_with_public_key` method ensures consistent error codes for all JWT verification failures.  
 > It may raise `invalid_signature`, `unsupported_algorithm`, `expired_token`, `invalid_issuer`, `invalid_audience`, or `not_yet_valid` depending on the verification outcome.
 
-For a full list of error cases and detailed explanations, please see the [ERRORS.md](ERRORS.md) file.
-
 ## Configuration Options
 
 | Key             | Required | Description                                 |
 | --------------- | -------- | ------------------------------------------- |
 | `discovery_url` | Yes   | Full URL to your realm's OIDC discovery doc |
 | `audience`      | Yes   | Your client ID (checked against `aud`). Accepts a String or callable returning a String/Array per request. |
+| `issuer`        | No       | Optional override for the expected `iss` claim; defaults to the discovery `issuer`. |
 | `skip_paths`    | No       | Array of paths or wildcards to skip authentication, e.g. `['/', '/health', '/public/*']`. **Note:** Regex patterns are not supported. |
 | `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. |
+| `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. |
+| `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`. |
+| `realm`         | No       | Value used in the `WWW-Authenticate` header. Defaults to `verikloak`. |
+| `logger`        | No       | Logger for unexpected internal failures (responds to `error`, optionally `debug`). |
 
 #### Option: `skip_paths`
 
@@ -272,11 +258,11 @@ skip_paths: ['/', '/health', '/rails/*', '/public/src']
 Paths **not matched** by any `skip_paths` entry will require a valid JWT.
 
 **Note:** Regex patterns are not supported. Only literal paths and `*` wildcards are allowed.  
-Internally, `*` expands to match nested paths, so patterns like `/rails/*` are valid. This differs from regex — for example, `'/rails'` alone matches only `/rails`, while `'/rails/*'` covers both `/rails` and deeper subpaths.
+Internally, `*` expands to match nested paths, so patterns like `/rails/*` are valid. This differs from regex; for example, `'/rails'` alone matches only `/rails`, while `'/rails/*'` covers both `/rails` and deeper subpaths.
 
 #### 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,
@@ -342,11 +328,39 @@ 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
+## Performance & Caching
+
+#### 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,14 +486,21 @@ 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']
+          # 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)
+        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
 
         @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 +508,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 +559,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,6 +625,9 @@ module Verikloak
   class Middleware
     include MiddlewareErrorMapping
     include SkipPathMatcher
+    include MiddlewareConfiguration
+    include MiddlewareAudienceResolution
+    include MiddlewareDecoderCache
     include MiddlewareTokenVerification
 
     DEFAULT_REALM = 'verikloak'
@@ -357,6 +638,7 @@ module Verikloak
     # @param discovery_url [String] OIDC discovery endpoint URL
     # @param audience [String, #call] Expected `aud` claim. When a callable is provided it
     #   receives the Rack env and may return a String or Array of audiences.
+    # @param issuer [String, nil] Optional issuer override (defaults to discovery `issuer`)
     # @param skip_paths [Array<String>] literal paths or wildcard patterns to bypass auth
     # @param discovery [Discovery, nil] custom discovery instance (for DI/tests)
     # @param jwks_cache [JwksCache, nil] custom JWKs cache instance (for DI/tests)
@@ -367,15 +649,19 @@ module Verikloak
     #   to TokenDecoder.
     #   e.g., { verify_iat: false, leeway: 10 }
     # rubocop:disable Metrics/ParameterLists
+    DEFAULT_DECODER_CACHE_LIMIT = 128
+
     def initialize(app,
                    discovery_url:,
                    audience:,
+                   issuer: nil,
                    skip_paths: [],
                    discovery: nil,
                    jwks_cache: nil,
                    connection: nil,
                    leeway: Verikloak::TokenDecoder::DEFAULT_LEEWAY,
                    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,
@@ -387,9 +673,15 @@ module Verikloak
       @jwks_cache      = jwks_cache
       @leeway = leeway
       @token_verify_options = token_verify_options || {}
-      @issuer        = nil
+      @decoder_cache_limit = normalize_decoder_cache_limit(decoder_cache_limit)
+      # 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
+      @issuer        = @configured_issuer
       @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)
@@ -421,14 +713,16 @@ 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)
@@ -439,8 +733,8 @@ module Verikloak
 
     # 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']
@@ -459,8 +753,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
 
@@ -480,9 +774,9 @@ 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
@@ -509,52 +803,5 @@ module Verikloak
         warn backtrace if backtrace
       end
     end
-
-    def logger_available?
-      return false unless @logger
-
-      @logger.respond_to?(:error) || @logger.respond_to?(:warn) || @logger.respond_to?(:debug)
-    end
-
-    def log_with_logger(message, backtrace)
-      log_message(@logger, message)
-      log_backtrace(@logger, backtrace)
-    end
-
-    def log_message(logger, message)
-      if logger.respond_to?(:error)
-        logger.error(message)
-      elsif logger.respond_to?(:warn)
-        logger.warn(message)
-      end
-    end
-
-    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
-
-    def normalize_env_key(value, option_name)
-      normalized = value.to_s.strip
-      raise ArgumentError, "#{option_name} cannot be blank" if normalized.empty?
-
-      normalized
-    end
-
-    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
   end
 end

data/lib/verikloak/version.rb

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

metadata

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