verikloak 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d16d7e5f8602a8484837e30752c190825e5f83b3ad9cb6b90d5e827b910b0daa
-  data.tar.gz: 135a5eadb529463081cfcf414d48ce13328fecf13b95963eff010a211f541c8f
+  metadata.gz: 05c91b8c75eff0da030bf668fa5c1ab1dece887a6cfaae8717ee7d82fbf5a637
+  data.tar.gz: 7b7c2188b441e81fea22194fb1309c4436d321702ffc5ce5dc215286263821f2
 SHA512:
-  metadata.gz: 5d476daca7174cb474771005affced764ad2093d633809c4206d54e5d0467b45e903bf998cbbca5cb9e25802e29cfaae20dd04d2820d53fc59c844af5cd886c7
-  data.tar.gz: f66dba005f8ad96afb0de678ab65e76a99d4f08dbcc98d4bc7468a6c5183781b10f10c4916a24c28ab7e8b459e6f252dbac01fc536f5d0f99e116a38d7c24485
+  metadata.gz: 6cf6fedad6a1ff8fd77ad25c91e97920e778a533b802da33f3b9c478637a271732c4c47f9ee8c8fa53e2b23716c60c75f34d068ef7177d1555dc9ceb8c7704bf
+  data.tar.gz: fc32dda5c37fef1d339f4478f1b96db406b24910ec2e19c402d53b685a84194336cd66ef96996b10f44a81964d03ae42f906da72aa07af8aae87496fbf68c2af

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.1.2] - 2025-08-31
+
+### Added
+- Middleware: new `connection:` option to inject a Faraday::Connection, shared by Discovery and JWKS.
+- Middleware: new `leeway:` and `token_verify_options:` options, delegated to TokenDecoder.
+- README: documented usage of `connection`, leeway/options, and clarified `skip_paths` behavior.
+
+### Changed
+- Middleware: `skip_paths` semantics clarified — plain paths are exact-match only, use `/*` for prefix matching.
+- 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

data/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/taiyaky/verikloak/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/taiyaky/verikloak/actions/workflows/ci.yml)
 [![Gem Version](https://img.shields.io/gem/v/verikloak)](https://rubygems.org/gems/verikloak)
-![Ruby Version](https://img.shields.io/gem/rt/ruby/verikloak)
+![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.0-blue)
 [![Downloads](https://img.shields.io/gem/dt/verikloak)](https://rubygems.org/gems/verikloak)
 
 A lightweight Rack middleware for verifying Keycloak JWT access tokens via OpenID Connect.
@@ -53,21 +53,44 @@ config.middleware.use Verikloak::Middleware,
 
 #### Handling Authentication Failures
 
-By default, invalid or missing tokens will raise a `Verikloak::Errors::InvalidToken` error.  
-In a Rails app, you can rescue this globally and return a consistent JSON response:
+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.
+
+If you use Verikloak components directly (bypassing the Rack middleware) or prefer centralized error handling, rescue from the base class `Verikloak::Error`. You can also match subclasses such as `Verikloak::TokenDecoderError`, `Verikloak::DiscoveryError`, or `Verikloak::JwksCacheError` depending on your needs:
 
 ```ruby
 class ApplicationController < ActionController::API
-  rescue_from Verikloak::Errors::InvalidToken do |e|
-    render json: { error: e.message }, status: :unauthorized
+  rescue_from Verikloak::Error do |e|
+    status =
+      case e
+      when Verikloak::TokenDecoderError
+        :unauthorized
+      when Verikloak::DiscoveryError, Verikloak::JwksCacheError
+        :service_unavailable
+      else
+        :unauthorized
+      end
+
+    render json: { error: e.class.name, message: e.message }, status: status
   end
 end
 ```
 
-This ensures clients always receive a structured `401 Unauthorized` response.
+This ensures that even if you bypass the middleware, clients still receive
+structured error responses.
+
+> **Note:** When the Rack middleware is enabled, it already renders JSON error responses.
+> The `rescue_from` example above is only necessary if you bypass the middleware or want custom behavior.
 
 ---
+#### Error Hierarchy
 
+All Verikloak errors inherit from `Verikloak::Error`:
+
+- `Verikloak::TokenDecoderError` – token parsing/verification (`401 Unauthorized`)
+- `Verikloak::DiscoveryError` – OIDC discovery fetch/parse (`503 Service Unavailable`)
+- `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
 
 ```ruby
@@ -210,7 +233,7 @@ Verikloak returns JSON error responses in a consistent format with structured er
 | `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.  
+> **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.
@@ -224,27 +247,88 @@ For a full list of error cases and detailed explanations, please see the [ERRORS
 | `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. |
+| `connection`   | No       | Inject a Faraday::Connection used for both Discovery and JWKS fetches. Allows unified timeout, retry, and headers. |
 
 #### Option: `skip_paths`
 
+Plain paths are exact-match only, while `/*` at the end enables prefix matching.
+
 `skip_paths` lets you specify paths (or wildcard patterns) where authentication should be **skipped**.  
 For example:
 
 ```ruby
-skip_paths: ['/', '/health', '/public/*', '/rails/*']
+skip_paths: ['/', '/health', '/rails/*', '/public/src']
 ```
 - `'/'` matches only the root path.
-- `'/foo/*'` matches `/foo` and any subpath like `/foo/bar` or `/foo/bar/baz`.
-- `'/api/public'` matches **only** `/api/public` (for subpaths, use `'/api/public/*'`).
+- `'/health'` matches **only** `/health` (for subpaths, use `'/health/*'`).
 - `'/rails/*'` matches `/rails` itself as well as `/rails/foo`, `/rails/foo/bar`, etc.
+- `'/public/src'` matches `/public/src`, but does **not** match `/public`, any subpath like `/public/src/html` or other siblings like `/public/css`.
 
 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.
 
+#### Customizing Faraday for Discovery and JWKS
+
+Both `Discovery` and `JwksCache` accept a `Faraday::Connection`.  
+This allows you to configure timeouts, retries, logging, and shared headers:
+
+```ruby
+connection = Faraday.new(request: { timeout: 5 }) do |f|
+  f.response :logger
+end
+
+config.middleware.use Verikloak::Middleware,
+  discovery_url: ENV["DISCOVERY_URL"],
+  audience: ENV["CLIENT_ID"],
+  jwks_cache: Verikloak::JwksCache.new(
+    jwks_uri: "https://example.com/realms/myrealm/protocol/openid-connect/certs",
+    connection: connection
+  )
+```
+This makes it easy to apply consistent Faraday settings across both discovery and JWKS fetches.
+
+```ruby
+# Alternatively, you can pass the connection directly to the middleware:
+config.middleware.use Verikloak::Middleware,
+  discovery_url: ENV["DISCOVERY_URL"],
+  audience: ENV["CLIENT_ID"],
+  connection: connection
+```
+
+#### Customizing token verification (leeway and options)
+
+You can fine-tune how JWTs are verified by setting `leeway` or providing advanced options via `token_verify_options`. For example:
+
+```ruby
+config.middleware.use Verikloak::Middleware,
+  discovery_url: ENV["DISCOVERY_URL"],
+  audience: ENV["CLIENT_ID"],
+  leeway: 30, # allow 30s clock skew
+  token_verify_options: {
+    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:` sets the default skew tolerance in seconds.
+- `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
+
+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.
+
 ## Architecture
 
 Verikloak consists of modular components, each with a focused responsibility:

data/lib/verikloak/jwks_cache.rb

@@ -28,15 +28,22 @@ module Verikloak
   #
   # @see #fetch!
   # @see #cached
+  #
+  # ## Dependency Injection
+  # Pass a preconfigured `Faraday::Connection` via `connection:` to control timeouts,
+  # adapters, and shared headers (kept consistent with Discovery).
+  #   `JwksCache.new(jwks_uri: "...", connection: Faraday.new { |f| f.request :retry })`
   class JwksCache
     # @param jwks_uri [String] HTTPS URL of the JWKS endpoint
+    # @param connection [Faraday::Connection, nil] Optional Faraday connection for HTTP requests
     # @raise [JwksCacheError] if the URI is not an HTTP(S) URL
-    def initialize(jwks_uri:)
+    def initialize(jwks_uri:, connection: nil)
       unless jwks_uri.is_a?(String) && jwks_uri.strip.match?(%r{^https?://})
         raise JwksCacheError.new('Invalid JWKS URI: must be a non-empty HTTP(S) URL', code: 'jwks_fetch_failed')
       end
 
       @jwks_uri    = jwks_uri
+      @connection  = connection || Faraday.new
       @cached_keys = nil
       @etag        = nil
       @fetched_at  = nil
@@ -56,7 +63,7 @@ module Verikloak
         # Build conditional request headers (ETag-based)
         headers  = build_conditional_headers
         # Perform HTTP GET request
-        response = Faraday.get(@jwks_uri, nil, headers)
+        response = @connection.get(@jwks_uri, nil, headers)
         # Handle HTTP response according to status code
         handle_response(response)
       end
@@ -72,6 +79,10 @@ module Verikloak
     # @return [Time, nil]
     attr_reader :fetched_at
 
+    # Injected Faraday connection (for testing and shared config across the gem)
+    # @return [Faraday::Connection]
+    attr_reader :connection
+
     # Whether the cache is considered stale.
     #
     # Uses `Cache-Control: max-age` semantics when available:

data/lib/verikloak/middleware.rb

@@ -2,17 +2,204 @@
 
 require 'rack'
 require 'json'
+require 'set'
+require 'faraday'
 
 module Verikloak
-  # Internal helper mixin that encapsulates error-to-HTTP mapping logic
-  # used by {Verikloak::Middleware}. By extracting this mapping into a
-  # separate module, the middleware class remains shorter and easier to
-  # reason about.
+  # @api private
   #
-  # This module does not depend on Rack internals; it only interprets
-  # Verikloak error objects and their `code` attributes.
+  # Internal mixin for skip-path normalization and matching.
+  # Extracted from Middleware to reduce class length and improve testability.
+  module SkipPathMatcher
+    private
+
+    # Checks whether the request path matches any compiled skip pattern.
+    #
+    # Supported patterns:
+    # * `'/'`           — matches only the root path
+    # * `'/foo'`        — exact-match only (matches `/foo` but **not** `/foo/...`)
+    # * `'/foo/*'`      — prefix match (matches `/foo` and any nested path under it)
+    #
+    # @param path [String]
+    # @return [Boolean]
+    def skip?(path)
+      np = normalize_path(path)
+      return true if @skip_root && np == '/'
+      return true if @skip_exacts.include?(np)
+
+      @skip_prefixes.any? { |prefix| np == prefix || np.start_with?("#{prefix}/") }
+    end
+
+    # Normalizes paths for stable comparisons:
+    # - ensures leading slash
+    # - collapses multiple slashes (e.g. //foo///bar -> /foo/bar)
+    # - removes trailing slash except for root
+    #
+    # @param path [String, nil]
+    # @return [String]
+    def normalize_path(path)
+      s = (path || '').to_s
+      s = "/#{s}" unless s.start_with?('/')
+      s = s.gsub(%r{/+}, '/')
+      s.length > 1 ? s.chomp('/') : s
+    end
+
+    # Pre-compiles {skip_paths} into fast lookup structures.
+    #
+    # * `@skip_root` — whether `'/'` is present
+    # * `@skip_exacts` — exact-match set (e.g. `'/health'`)
+    # * `@skip_prefixes` — wildcard prefixes for `'/*'` (e.g. `'/public'`)
+    #
+    # @param paths [Array<String>]
+    # @return [void]
+    def compile_skip_paths(paths)
+      @skip_root     = false
+      @skip_exacts   = Set.new
+      @skip_prefixes = []
+
+      Array(paths).each do |raw|
+        next if raw.nil?
+
+        s = raw.to_s.strip
+        next if s.empty?
+
+        if s == '/'
+          @skip_root = true
+          next
+        end
+
+        if s.end_with?('/*')
+          prefix = normalize_path(s.chomp('/*'))
+          next if prefix == '/' # root is handled by @skip_root
+
+          @skip_prefixes << prefix
+        else
+          exact = normalize_path(s)
+          @skip_exacts << exact
+          # Do NOT add to @skip_prefixes here; plain '/foo' is exact-match only.
+        end
+      end
+
+      @skip_prefixes.uniq!
+    end
+  end
+
+  # @api private
   #
+  # Internal mixin for JWT verification and discovery/JWKS management.
+  # Extracted from Middleware to reduce class length and improve clarity.
+  module MiddlewareTokenVerification
+    private
+
+    # Determines whether a token verification failure warrants a one-time JWKS refresh
+    # and retry (e.g., after key rotation).
+    #
+    # @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
+    end
+
+    # Returns a cached TokenDecoder instance for current inputs.
+    # Cache key uses issuer, audience, leeway, token_verify_options, and JWKS fetched_at timestamp.
+    def decoder_for
+      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
+      @mutex.synchronize do
+        @decoder_cache[cache_key] ||= TokenDecoder.new(
+          jwks: keys,
+          issuer: @issuer,
+          audience: @audience,
+          leeway: @leeway,
+          options: @token_verify_options
+        )
+      end
+    end
+
+    # Ensures JWKS are up-to-date by invoking {#ensure_jwks_cache!}.
+    # Errors are not swallowed and are handled by the caller.
+    #
+    # @return [void]
+    # @raise [Verikloak::DiscoveryError, Verikloak::JwksCacheError]
+    def refresh_jwks!
+      ensure_jwks_cache!
+    end
+
+    # 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
+    # @raise [Verikloak::Error] bubbles up verification/fetch errors for centralized handling
+    def decode_token(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
+
+      # First attempt
+      decoder = decoder_for
+
+      begin
+        decoder.decode!(token)
+      rescue TokenDecoderError => e
+        # On key rotation or signature mismatch, refresh JWKS and retry once.
+        raise unless retryable_decoder_error?(e)
+
+        refresh_jwks!
+
+        # Rebuild decoder with refreshed keys and try once more.
+        decoder = decoder_for
+        decoder.decode!(token)
+      end
+    end
+
+    # 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.
+    #
+    # @return [void]
+    # @raise [Verikloak::DiscoveryError, Verikloak::JwksCacheError, Verikloak::MiddlewareError]
+    def ensure_jwks_cache!
+      @mutex.synchronize do
+        if @jwks_cache.nil?
+          config   = @discovery.fetch!
+          @issuer  = config['issuer']
+          jwks_uri = config['jwks_uri']
+          @jwks_cache = JwksCache.new(jwks_uri: jwks_uri, connection: @connection)
+        end
+
+        @jwks_cache.fetch!
+      end
+    rescue Verikloak::DiscoveryError, Verikloak::JwksCacheError => e
+      # Re-raise so that specific error codes can be mapped in the middleware
+      raise e
+    rescue StandardError => e
+      raise MiddlewareError.new("Failed to initialize JWKS cache: #{e.message}", code: 'jwks_fetch_failed')
+    end
+  end
+
   # @api private
+  #
+  # Internal mixin that encapsulates error-to-HTTP mapping logic used by
+  # {Verikloak::Middleware}. By extracting this mapping into a separate module,
+  # the middleware class stays concise and easier to reason about.
+  #
+  # This module does not depend on Rack internals; it only interprets
+  # Verikloak error objects and their `code` attributes.
   module MiddlewareErrorMapping
     # Set of token/client-side error codes that should map to **401 Unauthorized**.
     # @return [Array<String>]
@@ -25,6 +212,8 @@ module Verikloak
     # @return [Array<String>]
     INFRA_ERROR_CODES = %w[jwks_fetch_failed jwks_cache_miss].freeze
 
+    private
+
     # @param code [String, nil] short error code
     # @return [Boolean] true if the error should be treated as a 403 Forbidden
     def forbidden?(code)
@@ -85,37 +274,53 @@ module Verikloak
   #
   # Failures are converted to JSON error responses with appropriate status codes.
   class Middleware
+    include MiddlewareErrorMapping
+    include SkipPathMatcher
+    include MiddlewareTokenVerification
+
     # @param app [#call] downstream Rack app
     # @param discovery_url [String] OIDC discovery endpoint URL
-    # @param audience [String] Expected `aud` claim
-    # @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)
+    # @param audience [String] expected `aud` claim
+    # @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)
+    # @param connection [Faraday::Connection, nil] Optional injected Faraday connection (defaults to Faraday.new)
+    # @param leeway [Integer] Clock skew tolerance in seconds for token verification (delegated to TokenDecoder)
+    # @param token_verify_options [Hash] Additional JWT verification options passed through
+    #   to TokenDecoder.
+    #   e.g., { verify_iat: false, leeway: 10 }
     def initialize(app,
                    discovery_url:,
                    audience:,
                    skip_paths: [],
                    discovery: nil,
-                   jwks_cache: nil)
+                   jwks_cache: nil,
+                   connection: nil,
+                   leeway: Verikloak::TokenDecoder::DEFAULT_LEEWAY,
+                   token_verify_options: {})
       @app           = app
       @audience      = audience
-      @skip_paths    = skip_paths
       @discovery     = discovery || Discovery.new(discovery_url: discovery_url)
       @jwks_cache    = jwks_cache
+      @connection    = connection || Faraday.new
+      @leeway        = leeway
+      @token_verify_options = token_verify_options || {}
       @issuer        = nil
       @mutex         = Mutex.new
+      @decoder_cache = {}
+
+      compile_skip_paths(skip_paths)
     end
 
     # Rack entrypoint.
     #
     # @param env [Hash] Rack environment
-    # @return [Array(Integer, Hash, Array<String>)] standard Rack response
+    # @return [Array(Integer, Hash, Array<String>)] standard Rack response triple
     def call(env)
       path = env['PATH_INFO']
       return @app.call(env) if skip?(path)
 
       token = extract_token(env)
-
       handle_request(env, token)
     rescue Verikloak::Error => e
       code, status = map_error(e)
@@ -127,61 +332,17 @@ module Verikloak
 
     private
 
-    include MiddlewareErrorMapping
-
-    # Determines whether a token verification failure warrants a one-time JWKS refresh
-    # and retry (e.g., after key rotation).
-    #
-    # @param error [Exception]
-    # @return [Boolean]
-    # @api private
-    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
-    end
-
-    # Ensures JWKS are up-to-date by invoking {#ensure_jwks_cache!}.
-    # Errors are not swallowed and are handled by the caller.
-    #
-    # @return [void]
-    # @raise [Verikloak::DiscoveryError, Verikloak::JwksCacheError]
-    # @api private
-    def refresh_jwks!
-      # Ensure discovery has been performed so we have a jwks_cache instance.
-      ensure_jwks_cache!
-    end
-
-    # Checks whether the request path matches any skip pattern.
-    #
-    # Supported patterns:
-    # * `'/'` — matches only the root path
-    # * `'/foo/*'` — matches `/foo` itself and any nested path under it
-    # * `'/api/public'` — exact match only (no wildcard)
-    #
-    # @param path [String]
-    # @return [Boolean]
-    def skip?(path)
-      @skip_paths.any? do |pattern|
-        if pattern == '/'
-          path == '/'
-        elsif pattern.end_with?('/*')
-          prefix = pattern.chomp('/*')
-          path == prefix || path.start_with?("#{prefix}/")
-        else
-          path == pattern || path.start_with?("#{pattern}/")
-        end
-      end
+    # Returns the Faraday connection used for HTTP operations (Discovery/JWKS).
+    # Exposed for tests; not part of public API.
+    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]
-    # @return [Array(Integer, Hash, Array<String>)]
+    # @return [Array(Integer, Hash, Array<String>)] Rack response triple
     def handle_request(env, token)
       claims = decode_token(token)
       env['verikloak.token'] = token
@@ -209,69 +370,6 @@ module Verikloak
       token
     end
 
-    # 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
-    # @raise [Verikloak::Error] bubbles up verification/fetch errors for centralized handling
-    def decode_token(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
-
-      # First attempt
-      decoder = TokenDecoder.new(
-        jwks: @jwks_cache.cached,
-        issuer: @issuer,
-        audience: @audience
-      )
-
-      begin
-        decoder.decode!(token)
-      rescue TokenDecoderError => e
-        # On key rotation or signature mismatch, refresh JWKS and retry once.
-        raise unless retryable_decoder_error?(e)
-
-        refresh_jwks!
-
-        # Rebuild decoder with refreshed keys and try once more.
-        decoder = TokenDecoder.new(
-          jwks: @jwks_cache.cached,
-          issuer: @issuer,
-          audience: @audience
-        )
-        decoder.decode!(token)
-      end
-    end
-
-    # 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.
-    #
-    # @return [void]
-    # @raise [Verikloak::DiscoveryError, Verikloak::JwksCacheError, Verikloak::MiddlewareError]
-    def ensure_jwks_cache!
-      @mutex.synchronize do
-        if @jwks_cache.nil?
-          config   = @discovery.fetch!
-          @issuer  = config['issuer']
-          jwks_uri = config['jwks_uri']
-          @jwks_cache = JwksCache.new(jwks_uri: jwks_uri)
-        end
-
-        @jwks_cache.fetch!
-      end
-    rescue Verikloak::DiscoveryError, Verikloak::JwksCacheError => e
-      # Re-raise so that specific error codes can be mapped in the middleware
-      raise e
-    rescue StandardError => e
-      raise MiddlewareError.new("Failed to initialize JWKS cache: #{e.message}", code: 'jwks_fetch_failed')
-    end
-
     # Converts a raised error into a `[code, http_status]` tuple for response rendering.
     #
     # @param error [Exception]
@@ -313,7 +411,6 @@ module Verikloak
     #
     # @param error [Exception]
     # @return [void]
-    # @api private
     def log_internal_error(error)
       warn "[verikloak] Internal error: #{error.class} - #{error.message}"
       warn error.backtrace.join("\n") if error.backtrace

data/lib/verikloak/token_decoder.rb

@@ -30,11 +30,18 @@ module Verikloak
     # @param issuer   [String]      Expected `iss` value in the token.
     # @param audience [String]      Expected `aud` value in the token.
     # @param leeway   [Integer]     Clock skew tolerance in seconds (optional).
-    def initialize(jwks:, issuer:, audience:, leeway: DEFAULT_LEEWAY)
+    # @param options [Hash] Extra JWT verification options.
+    #   Mirrors ruby-jwt options (e.g., :leeway, :verify_iat, :verify_expiration, :verify_not_before, :algorithms).
+    #   NOTE: If both `leeway:` and `options[:leeway]` are provided, `options[:leeway]` takes precedence.
+    def initialize(jwks:, issuer:, audience:, leeway: DEFAULT_LEEWAY, options: {})
       @jwks     = jwks
       @issuer   = issuer
       @audience = audience
+      # Keep backward compatibility; can be overridden by options[:leeway]
       @leeway   = leeway
+      # Normalize and store verification options
+      @options  = symbolize_keys(options || {})
+      @options_without_leeway = @options.except(:leeway).freeze
 
       # Build a kid-indexed hash for O(1) JWK lookup
       @jwk_by_kid = {}
@@ -42,6 +49,7 @@ module Verikloak
         kid_key = fetch_indifferent(j, 'kid')
         @jwk_by_kid[kid_key] = j if kid_key
       end
+      @options.freeze
     end
 
     # Decodes and verifies a JWT.
@@ -123,8 +131,7 @@ module Verikloak
     #
     # @return [Hash]
     def jwt_decode_options
-      {
-        # Specify allowed algorithms explicitly as an array to prevent header tampering
+      base = {
         algorithms: ['RS256'],
         iss: @issuer,
         verify_iss: true,
@@ -132,9 +139,14 @@ module Verikloak
         verify_aud: true,
         verify_iat: true,
         verify_expiration: true,
-        verify_not_before: true,
-        leeway: @leeway # allow clock skew tolerance
+        verify_not_before: true
       }
+      # options[:leeway] overrides top-level @leeway if provided
+      leeway = @options.key?(:leeway) ? @options[:leeway] : @leeway
+      merged = base.merge(leeway: leeway)
+      # Merge remaining options last (excluding :leeway which is already applied)
+      extra = @options_without_leeway
+      merged.merge(extra)
     end
 
     # Imports an OpenSSL::PKey::RSA public key from the given JWK.
@@ -242,5 +254,11 @@ module Verikloak
         "JWT verification failed: #{error.message}"
       end
     end
+
+    def symbolize_keys(hash)
+      return {} unless hash.is_a?(Hash)
+
+      hash.transform_keys(&:to_sym)
+    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.1'
+  VERSION = '0.1.2'
 end

metadata

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