verikloak 0.4.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2acaa72f8a2eee680d3c439b99488a48e7f512de4fb1ab2092ff781f13799c89
-  data.tar.gz: 5918e081c8be11ef410170f38cd4f520c2cfe55a5b34ac9e5363eddedc297a75
+  metadata.gz: be8192b1562ca02e7da55d8451e5588907707b3677c7343c14fc9448c8dc8cdc
+  data.tar.gz: f2eed617dbcae935e8691c72230361da981046414b9c64557d73e5a3a683df42
 SHA512:
-  metadata.gz: 8ee86f3b6586beac55b0a4e54f9815f58c99edf57bb2661851ae39e4f9f0bab80126643b903802ec90c266ca9fd16bac92550fd18d0c21be52487bfbb80c756e
-  data.tar.gz: 83f47c238874faee6b3391a833e7e3966b04637b3859b64e01943243d5aa1c64bf22986586a00c85ac651928cec476b7a8e05b030fd23172abf5ce60a3ff0e65
+  metadata.gz: a5b3aef46de49a76e52a19edf022a079a343df6ec583da65f193708a0dbd950874d2a2f0e1538f3748f7ce77c78da1ff7386ee177628f8054937f2d08ddb4e22
+  data.tar.gz: 5160853c31143b7581b512022047ab4990d39bda1644d7d57622ca22cfed15506669a10a77c809af0e220cbddd4e7b347ff58bd96037d5d6ec6605894a3910b5

data/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.0.0] - 2026-02-15
+
+### Security
+- **JWKs URI SSRF protection**: `JwksCache` now validates `jwks_uri` from discovery documents against private IP ranges (RFC 1918, loopback, link-local), preventing a malicious discovery endpoint from directing JWKs fetches to internal services
+
+### Fixed
+- **`TokenDecoder` error classification**: `invalid_signature` and `unsupported_algorithm` error codes were never returned due to dead `case/when` branches — replaced with `if/elsif` chain so `JWT::VerificationError` and `JWT::IncorrectAlgorithm` are classified correctly
+
+### Added
+- **`rack` runtime dependency**: Added `rack >= 2.2, < 4.0` to gemspec (was previously required but undeclared)
+
+### Changed
+- **`json` dependency relaxed**: `~> 2.18` → `~> 2.6` to broaden compatibility with older Ruby versions and bundled json gems
+- **v1.0.0 stable release**: Public API is now considered stable under Semantic Versioning
+
+---
+
 ## [0.4.1] - 2026-02-15
 
 ### Added

data/README.md

@@ -18,7 +18,7 @@ Verikloak is a plug-and-play solution for Ruby (especially Rails API) apps that
 - Rails/Rack middleware support
 - Faraday-based customizable HTTP layer
 - HTTPS enforcement for Discovery and JWKs endpoints (with `allow_http:` escape hatch for development)
-- SSRF protection — redirect targets validated against private IP ranges (including IPv4-mapped IPv6 normalisation)
+- SSRF protection — discovery redirect targets **and** `jwks_uri` values validated against private IP ranges (including IPv4-mapped IPv6 normalisation)
 - HTTPS redirect enforcement — redirect targets are scheme-checked to prevent HTTPS→HTTP downgrade
 - JWT size limit (8 KB) to mitigate denial-of-service via oversized tokens
 - Header injection prevention in `WWW-Authenticate` responses
@@ -225,6 +225,7 @@ For a full list of error cases and detailed explanations, please see the [ERRORS
 | `discovery_redirect_error` | 503 Service Unavailable   | Discovery redirect error: missing/invalid Location header, redirect target resolves to a private IP (SSRF protection), redirect uses non-HTTPS scheme, or unsupported scheme |
 | `insecure_discovery_url`   | 503 Service Unavailable   | Discovery URL uses `http://` and `allow_http: true` is not set                               |
 | `insecure_jwks_uri`        | 503 Service Unavailable   | JWKs URI uses `http://` and `allow_http: true` is not set                                    |
+| `jwks_ssrf_blocked`        | 503 Service Unavailable   | JWKs URI hostname resolves to a private/loopback IP address (SSRF protection)                |
 | `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.  

data/lib/verikloak/jwks_cache.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
 require 'faraday'
+require 'ipaddr'
 require 'json'
+require 'resolv'
+require 'uri'
 
 require 'verikloak/http'
 
@@ -39,7 +42,7 @@ module Verikloak
     # @param jwks_uri [String] HTTPS URL of the JWKs endpoint
     # @param connection [Faraday::Connection, nil] Optional Faraday connection for HTTP requests
     # @param allow_http [Boolean] When false (default), raises on plain HTTP URIs. Set true for local development only.
-    # @raise [JwksCacheError] if the URI is not an HTTP(S) URL
+    # @raise [JwksCacheError] if the URI is not an HTTP(S) URL or resolves to a private/internal address
     def initialize(jwks_uri:, connection: nil, allow_http: false)
       unless jwks_uri.is_a?(String)
         raise JwksCacheError.new('Invalid JWKs URI: must be a non-empty HTTP(S) URL', code: 'jwks_fetch_failed')
@@ -58,6 +61,8 @@ module Verikloak
         )
       end
 
+      validate_not_private!(clean_jwks_uri)
+
       @jwks_uri    = clean_jwks_uri
       @connection  = connection || Verikloak::HTTP.default_connection
       @cached_keys = nil
@@ -155,6 +160,41 @@ module Verikloak
       (Time.now - @fetched_at) < @max_age
     end
 
+    # Validates that the JWKs URI does not resolve to a private/internal IP address (SSRF protection).
+    #
+    # The discovery redirect flow already validates redirect targets, but the `jwks_uri` value
+    # extracted from the discovery JSON document itself was not previously validated, allowing a
+    # compromised or malicious discovery endpoint to point JWKs fetching at internal services.
+    #
+    # IPv4-mapped IPv6 addresses (e.g. `::ffff:127.0.0.1`) are normalised to their native IPv4
+    # form before comparison, consistent with {Verikloak::Discovery}.
+    #
+    # @api private
+    # @param url [String] The JWKs URI to validate
+    # @raise [JwksCacheError] when the URI resolves to a private/internal address
+    def validate_not_private!(url)
+      uri = URI.parse(url)
+      host = uri.host
+      return unless host
+
+      Resolv.getaddresses(host).each do |addr|
+        ip = IPAddr.new(addr)
+        ip = ip.native if ip.ipv4_mapped?
+        next unless Verikloak::PRIVATE_IP_RANGES.any? { |range| range.include?(ip) }
+
+        raise JwksCacheError.new(
+          "JWKs URI resolves to a private/internal address (#{host})",
+          code: 'jwks_ssrf_blocked'
+        )
+      end
+    rescue URI::InvalidURIError => e
+      raise JwksCacheError.new("Invalid JWKs URI: #{e.message}", code: 'jwks_fetch_failed')
+    rescue IPAddr::InvalidAddressError
+      # If the address cannot be parsed, allow the request to proceed
+      # (Faraday will handle the actual connection error)
+      nil
+    end
+
     # @api private
     # Parses a `Cache-Control` header and extracts `max-age` in seconds.
     #

data/lib/verikloak/token_decoder.rb

@@ -199,20 +199,27 @@ module Verikloak
       # Pass through our own structured errors without rewrapping
       raise e
     rescue *jwt_errors => e
-      code = case e
-             when JWT::ExpiredSignature then 'expired_token'
-             when JWT::ImmatureSignature then 'not_yet_valid'
-             when JWT::InvalidIssuerError then 'invalid_issuer'
-             when JWT::InvalidAudError then 'invalid_audience'
-             when defined?(JWT::VerificationError) && e.is_a?(JWT::VerificationError) then 'invalid_signature'
-             when defined?(JWT::IncorrectAlgorithm) && e.is_a?(JWT::IncorrectAlgorithm) then 'unsupported_algorithm'
-             else 'invalid_token'
-             end
+      code = classify_jwt_error(e)
       raise TokenDecoderError.new(jwt_error_message(e), code: code)
     rescue StandardError => e
       raise TokenDecoderError.new("Unexpected token verification error: #{e.message}", code: 'invalid_token')
     end
 
+    # Map a JWT exception to a machine-friendly error code.
+    #
+    # @param error [Exception]
+    # @return [String]
+    def classify_jwt_error(error)
+      return 'expired_token'        if error.is_a?(JWT::ExpiredSignature)
+      return 'not_yet_valid'        if error.is_a?(JWT::ImmatureSignature)
+      return 'invalid_issuer'       if error.is_a?(JWT::InvalidIssuerError)
+      return 'invalid_audience'     if error.is_a?(JWT::InvalidAudError)
+      return 'unsupported_algorithm' if defined?(JWT::IncorrectAlgorithm) && error.is_a?(JWT::IncorrectAlgorithm)
+      return 'invalid_signature' if defined?(JWT::VerificationError) && error.is_a?(JWT::VerificationError)
+
+      'invalid_token'
+    end
+
     # JWT-related exceptions to catch and rewrap.
     #
     # @return [Array<Class>]

data/lib/verikloak/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 1.0.0
 platform: ruby
 authors:
 - taiyaky
@@ -55,14 +55,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.18'
+        version: '2.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.18'
+        version: '2.6'
 - !ruby/object:Gem::Dependency
   name: jwt
   requirement: !ruby/object:Gem::Requirement
@@ -83,6 +83,26 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !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
@@ -111,7 +131,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.4.1
+  documentation_uri: https://rubydoc.info/gems/verikloak/1.0.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: