verikloak 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d16d7e5f8602a8484837e30752c190825e5f83b3ad9cb6b90d5e827b910b0daa
-  data.tar.gz: 135a5eadb529463081cfcf414d48ce13328fecf13b95963eff010a211f541c8f
+  metadata.gz: 5fb6063573fea932d0e6a73ef18bc31b32be0d36d7c38cef34a7424bfbb3289a
+  data.tar.gz: 25cf61bedbbef60f8136bed435d640ab23993306d363db0ab2fc6fb997b08364
 SHA512:
-  metadata.gz: 5d476daca7174cb474771005affced764ad2093d633809c4206d54e5d0467b45e903bf998cbbca5cb9e25802e29cfaae20dd04d2820d53fc59c844af5cd886c7
-  data.tar.gz: f66dba005f8ad96afb0de678ab65e76a99d4f08dbcc98d4bc7468a6c5183781b10f10c4916a24c28ab7e8b459e6f252dbac01fc536f5d0f99e116a38d7c24485
+  metadata.gz: 82ab3fa49d2f1c82a46d3cd2573b390a744b96e35a688be413da86d715fd845de30ba5d76a83dd4c54e3e2777a1c0c24975c5005179d62a79679e5bf37651619
+  data.tar.gz: cc5a8fcd4a2679f2438390bb5cc1e0818866b162bfc2131724dae21af05fe16c59bf0c23fb70202ca0da34d7231eb720d4fec5c61a5e2405c6427a5d72a722b0

data/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.1.3] - 2025-09-15
+
+### Changed
+- Relax `jwt` runtime dependency to `>= 2.7, < 4.0` to allow jwt 3.x (PR #11).
+
+### Chore
+- 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
+- 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
@@ -24,7 +49,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Rack middleware for verifying JWT access tokens from Keycloak
 - Support for OpenID Connect Discovery (`.well-known/openid-configuration`)
   - Handles up to 3 HTTP redirects and resolves relative `Location` headers
-- JWKS fetching with in-memory caching and ETag validation
+- JWKs fetching with in-memory caching and ETag validation
 - RS256 JWT verification with `kid` matching
 - Claim validation: `aud`, `iss`, `exp`, `nbf`
 - Configurable via `discovery_url`, `audience`, and `skip_paths` options
@@ -41,7 +66,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - RuboCop static analysis configuration
 - Structured error handling & responses:
   - Token/auth errors → **401 Unauthorized** with `WWW-Authenticate` header (RFC 6750)
-  - Discovery/JWKS errors → **503 Service Unavailable**
+  - Discovery/JWKs errors → **503 Service Unavailable**
   - Structured error codes: `invalid_token`, `expired_token`, `not_yet_valid`,
     `invalid_issuer`, `invalid_audience`, `unsupported_algorithm`,
     `jwks_fetch_failed`, `jwks_parse_failed`, `jwks_cache_miss`,

data/README.md

@@ -2,19 +2,19 @@
 
 [![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.1-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.
 
-Verikloak is a plug-and-play solution for Ruby (especially Rails API) apps that need to validate incoming `Bearer` tokens issued by Keycloak. It uses OpenID Connect Discovery and JWKS to fetch the public keys and verify JWT signatures securely.
+Verikloak is a plug-and-play solution for Ruby (especially Rails API) apps that need to validate incoming `Bearer` tokens issued by Keycloak. It uses OpenID Connect Discovery and JWKs to fetch the public keys and verify JWT signatures securely.
 
 ---
 
 ## Features
 
 - OpenID Connect Discovery (`.well-known/openid-configuration`)
-- JWKs auto-fetch and in-memory caching with ETag support
+- JWKs auto-fetching with in-memory caching and ETag support
 - RS256 JWT verification using `kid`
 - `aud`, `iss`, `exp`, `nbf` claim validation
 - Rails/Rack middleware support
@@ -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
@@ -76,14 +99,7 @@ config.middleware.use Verikloak::Middleware,
   audience: ENV.fetch("CLIENT_ID"),
   skip_paths: ['/', '/health', '/public/*', '/rails/*']
 ```
-#### In production, set these variables in your environment for security and flexibility.
-
 This makes the configuration secure and flexible across environments.
-
-```ruby
-request.env["verikloak.user"]  # => JWT claims hash
-request.env["verikloak.token"] # => Raw JWT string
-```
 ---
 ### Accessing claims in controllers
 
@@ -123,7 +139,7 @@ run ->(env) {
 
 1. Extracts the `Authorization: Bearer <token>` header
 2. Fetches the OIDC discovery document (only once or when expired)
-3. Downloads JWKS public keys from the provided `jwks_uri`
+3. Downloads JWKs public keys from the provided `jwks_uri`
 4. Matches the `kid` from JWT header to select the right JWK
 5. Decodes and verifies the JWT using `RS256`
 6. Validates the following claims:
@@ -137,12 +153,12 @@ run ->(env) {
 
 ## Error Responses
 
-Verikloak returns JSON error responses in a consistent format with structured error codes. The HTTP status code reflects the nature of the error: 401 for client-side authentication issues, 503 for server-side discovery/JWKS errors, and 500 for unexpected internal errors.
+Verikloak returns JSON error responses in a consistent format with structured error codes. The HTTP status code reflects the nature of the error: 401 for client-side authentication issues, 503 for server-side discovery/JWKs errors, and 500 for unexpected internal errors.
 
 ### Common HTTP Responses
 
 - `401 Unauthorized`: The access token is missing, invalid, expired, or otherwise not valid.
-- `503 Service Unavailable`: Discovery or JWKS fetch/parsing failed (server-side issue).
+- `503 Service Unavailable`: Discovery or JWKs fetch/parsing failed (server-side issue).
 - `500 Internal Server Error`: An unexpected error occurred.
 
 ### Representative Examples
@@ -164,14 +180,14 @@ Verikloak returns JSON error responses in a consistent format with structured er
 ```json
 {
   "error": "jwks_fetch_failed",
-  "message": "Failed to fetch JWKS keys"
+  "message": "Failed to fetch JWKs"
 }
 ```
 
 ```json
 {
   "error": "jwks_parse_failed",
-  "message": "Failed to parse JWKS keys"
+  "message": "Failed to parse JWKs"
 }
 ```
 
@@ -202,15 +218,15 @@ Verikloak returns JSON error responses in a consistent format with structured er
 | `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 keys                                                                    |
-| `jwks_parse_failed`        | 503 Service Unavailable   | Failed to parse JWKS keys                                                                    |
-| `jwks_cache_miss`          | 503 Service Unavailable   | JWKS cache is empty (e.g., 304 Not Modified without prior cache)                             |
+| `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_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 +240,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:
@@ -253,7 +330,7 @@ Verikloak consists of modular components, each with a focused responsibility:
 |----------------|--------------------------------------------------------|--------------|
 | `Middleware`    | Rack-compatible entry point for token validation     | Rack layer   |
 | `Discovery`     | Fetches OIDC discovery metadata (`.well-known`)      | Network layer|
-| `JwksCache`     | Fetches & caches JWKS public keys (with ETag)        | Cache layer  |
+| `JwksCache`     | Fetches & caches JWKs public keys (with ETag)        | Cache layer  |
 | `TokenDecoder`  | Decodes and verifies JWTs (signature, exp, nbf, iss, aud) | Crypto layer |
 | `Errors`        | Centralized error hierarchy                          | Core layer   |
 
@@ -321,4 +398,4 @@ See [CHANGELOG.md](CHANGELOG.md) for release history.
 
 - [OpenID Connect Discovery 1.0 Spec](https://openid.net/specs/openid-connect-discovery-1_0.html)  
 - [Keycloak Documentation: Securing Apps](https://www.keycloak.org/docs/latest/securing_apps/#openid-connect)  
-- [JWT RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519) 
+- [JWT RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519) 

data/lib/verikloak/errors.rb

@@ -35,7 +35,7 @@ module Verikloak
 
   # Raised for middleware-level failures while processing a Rack request.
   #
-  # Examples include missing/invalid Authorization headers, JWKS cache
+  # Examples include missing/invalid Authorization headers, JWKs cache
   # initialization failures, or infrastructure issues detected by the
   # middleware itself.
   #
@@ -55,7 +55,7 @@ module Verikloak
   # @raise [TokenDecoderError] from {Verikloak::TokenDecoder#decode!}
   class TokenDecoderError < Error; end
 
-  # Raised when JWKS fetching, validation, or cache handling fails.
+  # Raised when JWKs fetching, validation, or cache handling fails.
   #
   # Causes include HTTP failures, invalid JSON, missing required JWK fields,
   # or receiving 304 Not Modified without a prior cached value.

data/lib/verikloak/jwks_cache.rb

@@ -4,14 +4,14 @@ require 'faraday'
 require 'json'
 
 module Verikloak
-  # Caches and revalidates JSON Web Key Sets (JWKS) fetched from a remote endpoint.
+  # Caches and revalidates JSON Web Key Sets (JWKs) fetched from a remote endpoint.
   #
   # This cache supports two HTTP cache mechanisms:
   # - **ETag revalidation** via `If-None-Match` → returns `304 Not Modified` when unchanged.
   # - **TTL freshness** via `Cache-Control: max-age` → avoids HTTP requests while fresh.
   #
   # On a successful `200 OK`, the cache:
-  # - Parses the JWKS JSON (`{"keys":[...]}`) and validates each JWK has `kid`, `kty`, `n`, `e`.
+  # - Parses the JWKs JSON (`{"keys":[...]}`) and validates each JWK has `kid`, `kty`, `n`, `e`.
   # - Stores the keys in-memory, records `ETag`, and computes freshness from `Cache-Control`.
   #
   # On a `304 Not Modified`, the cache:
@@ -28,22 +28,29 @@ 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 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')
+        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
       @max_age     = nil
     end
 
-    # Fetches the JWKS and updates the in-memory cache.
+    # Fetches the JWKs and updates the in-memory cache.
     #
     # Performs an HTTP GET with `If-None-Match` when an ETag is present and handles:
     # - 200: parses/validates body, updates keys, ETag, TTL and `fetched_at`.
@@ -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:
@@ -92,11 +103,11 @@ module Verikloak
     rescue Faraday::ConnectionFailed, Faraday::TimeoutError
       raise JwksCacheError.new('Connection failed', code: 'jwks_fetch_failed')
     rescue Faraday::Error => e
-      raise JwksCacheError.new("JWKS fetch failed: #{e.message}", code: 'jwks_fetch_failed')
+      raise JwksCacheError.new("JWKs fetch failed: #{e.message}", code: 'jwks_fetch_failed')
     rescue JSON::ParserError
       raise JwksCacheError.new('Response is not valid JSON', code: 'jwks_parse_failed')
     rescue StandardError => e
-      raise JwksCacheError.new("Unexpected JWKS fetch error: #{e.message}", code: 'jwks_fetch_failed')
+      raise JwksCacheError.new("Unexpected JWKs fetch error: #{e.message}", code: 'jwks_fetch_failed')
     end
 
     # @api private
@@ -150,7 +161,7 @@ module Verikloak
     end
 
     # @api private
-    # Extracts and validates the `keys` array from a JWKS JSON document.
+    # Extracts and validates the `keys` array from a JWKs JSON document.
     # Ensures each key has `kid`, `kty`, `n`, and `e`.
     #
     # @param json [Hash]
@@ -202,12 +213,12 @@ module Verikloak
         # Revalidation succeeded; update freshness from 304 headers if present
         process_not_modified(response)
       else
-        raise JwksCacheError.new("Failed to fetch JWKS: status #{response.status}", code: 'jwks_fetch_failed')
+        raise JwksCacheError.new("Failed to fetch JWKs: status #{response.status}", code: 'jwks_fetch_failed')
       end
     end
 
     # @api private
-    # Handles a 200 OK JWKS response.
+    # Handles a 200 OK JWKs response.
     # @param response [Faraday::Response]
     # @return [Array<Hash>] parsed and cached keys
     def process_successful_response(response)
@@ -218,7 +229,7 @@ module Verikloak
     end
 
     # @api private
-    # Handles a 304 Not Modified JWKS response: updates TTL and timestamp, returns cached keys.
+    # Handles a 304 Not Modified JWKs response: updates TTL and timestamp, returns cached keys.
     # @param response [Faraday::Response]
     # @return [Array<Hash>]
     # @raise [JwksCacheError] when cache is empty
@@ -235,7 +246,7 @@ module Verikloak
     # @return [Array<Hash>]
     # @raise [JwksCacheError]
     def return_from_cache_or_fail
-      @cached_keys || raise(JwksCacheError.new('JWKS cache is empty but received 304 Not Modified',
+      @cached_keys || raise(JwksCacheError.new('JWKs cache is empty but received 304 Not Modified',
                                                code: 'jwks_cache_miss'))
     end
   end

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)
@@ -78,44 +267,60 @@ module Verikloak
   end
 
   # Rack middleware that verifies incoming JWT access tokens (Keycloak) using
-  # OpenID Connect discovery and JWKS. On success, it populates:
+  # OpenID Connect discovery and JWKs. On success, it populates:
   #
   # * `env['verikloak.token']` — the raw JWT string
   # * `env['verikloak.user']`  — the decoded JWT claims Hash
   #
   # 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

@@ -3,7 +3,7 @@
 require 'jwt'
 
 module Verikloak
-  # Verifies JWT tokens using a JWKS key set.
+  # Verifies JWT tokens using a JWKs.
   #
   # This class validates a JWT's signature and standard claims (`iss`, `aud`, `exp`, `nbf`, etc.)
   # using the appropriate RSA public key selected by the JWT's `kid` header.
@@ -24,17 +24,24 @@ module Verikloak
     # Default clock skew tolerance in seconds.
     DEFAULT_LEEWAY = 60
 
-    # Initializes the decoder with a JWKS and verification criteria.
+    # Initializes the decoder with a JWKs and verification criteria.
     #
     # @param jwks     [Array<Hash>] List of JWKs from the discovery document.
     # @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.
@@ -98,7 +106,7 @@ module Verikloak
       kid = fetch_indifferent(header, 'kid')
       jwk = @jwk_by_kid[kid]
 
-      raise TokenDecoderError.new("Key with kid=#{kid} not found in JWKS", code: 'invalid_token') unless jwk
+      raise TokenDecoderError.new("Key with kid=#{kid} not found in JWKs", code: 'invalid_token') unless jwk
 
       jwk
     end
@@ -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.3'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - taiyaky
@@ -47,20 +47,26 @@ dependencies:
   name: jwt
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
 description: |
   Verikloak is a lightweight Ruby gem that provides JWT access token verification middleware
   for Rack-based applications, including Rails API mode. It uses OpenID Connect discovery
-  and JWKS to securely validate tokens issued by Keycloak.
+  and JWKs to securely validate tokens issued by Keycloak.
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -82,7 +88,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.3
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -91,7 +97,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="