verikloak 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05c91b8c75eff0da030bf668fa5c1ab1dece887a6cfaae8717ee7d82fbf5a637
-  data.tar.gz: 7b7c2188b441e81fea22194fb1309c4436d321702ffc5ce5dc215286263821f2
+  metadata.gz: 3b7e22a96384ccea0cb43c2c611f7106d0e88b23793279f2ee105d68da226bb0
+  data.tar.gz: d83ba8ebe7834895d1a3f6e39c26dae02713611fc767177c909987ef1111cf50
 SHA512:
-  metadata.gz: 6cf6fedad6a1ff8fd77ad25c91e97920e778a533b802da33f3b9c478637a271732c4c47f9ee8c8fa53e2b23716c60c75f34d068ef7177d1555dc9ceb8c7704bf
-  data.tar.gz: fc32dda5c37fef1d339f4478f1b96db406b24910ec2e19c402d53b685a84194336cd66ef96996b10f44a81964d03ae42f906da72aa07af8aae87496fbf68c2af
+  metadata.gz: 40481fc255490d0c22c2808cf00e8c0e136488f755e6dc2e388c4ab81978975c6ee478a2916d61fe564bd25984898f74ddeccacfe1ae8006a081b3bfc441bc41
+  data.tar.gz: 0aaf942838e33a618197d0fb6d5446c6a9ffaa5b529db50902f2ab403b884b03ee0c87bdf8c99e4c8b069cad1f566026bb05fb16ab3583339493a4891eeb4f88

data/CHANGELOG.md

@@ -7,16 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.1.4] - 2025-09-20
+
+### Chore
+- Bump dev dependency `rexml` to 3.4.2 (PR #15).
+
+---
+
+## [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 `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.
+- Middleware: TokenDecoder instances are now cached per JWKs fetch for performance improvement.
 - Internal: RuboCop style fixes (`HashExcept`, `HashTransformKeys`, long line splits).
 
 ---
@@ -38,7 +56,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
@@ -55,7 +73,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/badge/ruby-%3E%3D%203.0-blue)
+![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,7 +53,7 @@ config.middleware.use Verikloak::Middleware,
 
 #### 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.
+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:
 
@@ -88,7 +88,7 @@ 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::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
@@ -99,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
 
@@ -146,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:
@@ -160,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
@@ -187,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"
 }
 ```
 
@@ -225,9 +218,9 @@ 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                           |
@@ -249,7 +242,7 @@ For a full list of error cases and detailed explanations, please see the [ERRORS
 | `jwks_cache`    | No       | Inject custom JwksCache instance (advanced/testing) |
 | `leeway`       | No       | Clock skew tolerance (seconds) applied during JWT verification. Defaults to `TokenDecoder::DEFAULT_LEEWAY`. |
 | `token_verify_options` | No | Hash of advanced JWT verification options passed through to TokenDecoder. For example: `{ verify_iat: false, leeway: 10, algorithms: ["RS256"] }`. If both `leeway:` and `token_verify_options[:leeway]` are set, the latter takes precedence. |
-| `connection`   | No       | Inject a Faraday::Connection used for both Discovery and JWKS fetches. Allows unified timeout, retry, and headers. |
+| `connection`   | No       | Inject a Faraday::Connection used for both Discovery and JWKs fetches. Allows unified timeout, retry, and headers. |
 
 #### Option: `skip_paths`
 
@@ -271,7 +264,7 @@ 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
+#### 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:
@@ -289,7 +282,7 @@ config.middleware.use Verikloak::Middleware,
     connection: connection
   )
 ```
-This makes it easy to apply consistent Faraday settings across both discovery and JWKS fetches.
+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:
@@ -325,9 +318,9 @@ config.middleware.use Verikloak::Middleware,
 
 #### Performance note
 
-Internally, Verikloak caches `TokenDecoder` instances per JWKS fetch to avoid reinitializing
+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.
+revalidated when JWKs is refreshed.
 
 ## Architecture
 
@@ -337,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   |
 
@@ -405,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:
@@ -34,12 +34,12 @@ module Verikloak
   # 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:, 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
@@ -50,7 +50,7 @@ module Verikloak
       @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`.
@@ -103,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
@@ -161,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]
@@ -213,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)
@@ -229,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
@@ -246,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

@@ -86,12 +86,12 @@ module Verikloak
 
   # @api private
   #
-  # Internal mixin for JWT verification and discovery/JWKS management.
+  # 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
+    # Determines whether a token verification failure warrants a one-time JWKs refresh
     # and retry (e.g., after key rotation).
     #
     # @param error [Exception]
@@ -105,7 +105,7 @@ module Verikloak
     end
 
     # Returns a cached TokenDecoder instance for current inputs.
-    # Cache key uses issuer, audience, leeway, token_verify_options, and JWKS fetched_at timestamp.
+    # 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
@@ -127,7 +127,7 @@ module Verikloak
       end
     end
 
-    # Ensures JWKS are up-to-date by invoking {#ensure_jwks_cache!}.
+    # Ensures JWKs are up-to-date by invoking {#ensure_jwks_cache!}.
     # Errors are not swallowed and are handled by the caller.
     #
     # @return [void]
@@ -136,8 +136,8 @@ module Verikloak
       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.
+    # 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
@@ -145,7 +145,7 @@ module Verikloak
     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')
+        raise MiddlewareError.new('JWKs cache is empty, cannot verify token', code: 'jwks_cache_miss')
       end
 
       # First attempt
@@ -154,7 +154,7 @@ module Verikloak
       begin
         decoder.decode!(token)
       rescue TokenDecoderError => e
-        # On key rotation or signature mismatch, refresh JWKS and retry once.
+        # On key rotation or signature mismatch, refresh JWKs and retry once.
         raise unless retryable_decoder_error?(e)
 
         refresh_jwks!
@@ -165,11 +165,11 @@ module Verikloak
       end
     end
 
-    # Ensures that discovery metadata and JWKS cache are initialized and up-to-date.
+    # Ensures that discovery metadata and JWKs cache are initialized and up-to-date.
     # This method is thread-safe.
     #
     # * When the cache instance is missing, it is created from discovery metadata.
-    # * JWKS are (re)fetched every time; ETag/Cache-Control headers minimize traffic.
+    # * JWKs are (re)fetched every time; ETag/Cache-Control headers minimize traffic.
     #
     # @return [void]
     # @raise [Verikloak::DiscoveryError, Verikloak::JwksCacheError, Verikloak::MiddlewareError]
@@ -188,7 +188,7 @@ module Verikloak
       # 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')
+      raise MiddlewareError.new("Failed to initialize JWKs cache: #{e.message}", code: 'jwks_fetch_failed')
     end
   end
 
@@ -267,7 +267,7 @@ 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
@@ -283,7 +283,7 @@ module Verikloak
     # @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 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
@@ -332,7 +332,7 @@ module Verikloak
 
     private
 
-    # Returns the Faraday connection used for HTTP operations (Discovery/JWKS).
+    # Returns the Faraday connection used for HTTP operations (Discovery/JWKs).
     # Exposed for tests; not part of public API.
     def http_connection
       @connection

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,7 +24,7 @@ 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.
@@ -106,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

data/lib/verikloak/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
 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.2
+  documentation_uri: https://rubydoc.info/gems/verikloak/0.1.4
   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:
   - - ">="