verikloak 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24bc2b5eb7f699c9f8bc4970a2b0b6cdca87b7c7e37d9718c51d85d8cf58a8cc
-  data.tar.gz: 439ec2fb34a67140476aff243addfaac8cb8d5ac18ef7b6915d3a9ba6dc5947d
+  metadata.gz: a8fea8bb10499fcd42f05ecc1eadda3008c5215b1907807351c9b4a8a4a420a4
+  data.tar.gz: '05476942149fcdf5f5cbe9605524c8a8ea79359f1b9533b623d08e7b130a0290'
 SHA512:
-  metadata.gz: 61be82820e149b89c7e5dead4bc79aef1da0959b85ba447e7bf9d6a346efb331f378030620c2ee42d2b41e5c3e21d89346f405ad16b6264f9452fc49771fc2d4
-  data.tar.gz: 9bec7c747971154c59321505fdd2817487e09013eb8e32d3defe86a7dc38a4731c5e01d113639cd3eae1a33e9073b932dfa5d9a243b65a1609d9b3549cb48129
+  metadata.gz: 3133b44cd8ada0217916d82b5b725ed5bd50c445c727969478b6af67cb712de8247d7a124585f5ca2ee763ec69171f3c65b70be60fdb91c16f6d5467b2853b9a
+  data.tar.gz: c790ce4825f32e2d17187b2de7e3564e765274517b4ca59f0fbd8b61a7fbe22edac4e9f72cee91a92ec7e9b2bc6529da74e4d9b3d22abf3d068a3bff2f78a4df

data/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.4.0] - 2026-02-15
+
+### Security
+- **CVE-2026-25765**: Bump `faraday` runtime dependency to `>= 2.14.1`
+- **Header injection**: Sanitize CR/LF characters in `WWW-Authenticate` header values via `Verikloak::ErrorResponse`
+- **JWT size limit**: Reject tokens exceeding 8 KB (`MAX_TOKEN_BYTES = 8192`) to mitigate denial-of-service
+- **HTTPS enforcement**: `Discovery` and `JwksCache` now reject `http://` URLs unless `allow_http: true` is explicitly set
+- **HTTPS redirect enforcement**: Redirect targets during OIDC discovery are now scheme-checked — plain HTTP redirects are blocked unless `allow_http: true`, and non-HTTP(S) schemes (e.g. `ftp://`) are always rejected
+- **SSRF protection**: Redirect targets in OIDC discovery are validated against private IP ranges (RFC 1918, loopback, link-local)
+- **IPv4-mapped IPv6 SSRF hardening**: IPv4-mapped IPv6 addresses (e.g. `::ffff:127.0.0.1`) are normalised to native IPv4 before private-range checks, preventing bypass via mapped addresses
+- **URL normalisation**: `Discovery` and `JwksCache` now strip leading/trailing whitespace from URLs during initialisation, ensuring the validated URL matches what is used for HTTP requests
+
+### Added
+- `Verikloak::ErrorResponse` — shared RFC 6750-compliant JSON error response builder
+- `Verikloak::SkipPathMatcher` — extracted reusable skip-path matching module
+- `Verikloak::Error#http_status` attribute for structured error hierarchy
+- `allow_http:` option on `Middleware`, `Discovery`, and `JwksCache`
+
+### Changed
+- **BREAKING**: Minimum `faraday` version raised to `2.14.1`
+- **BREAKING**: Minimum `faraday-retry` version raised to `2.4.0`
+- Runtime dependency `json` added (`~> 2.18`)
+- Dev dependency `rspec` pinned to `~> 3.13`, `rubocop-rspec` pinned to `~> 3.9`, `webmock` pinned to `~> 3.26`
+
+---
+
 ## [0.3.0] - 2025-12-31
 
 ### Added

data/README.md

@@ -17,6 +17,12 @@ Verikloak is a plug-and-play solution for Ruby (especially Rails API) apps that
 - `aud`, `iss`, `exp`, `nbf` claim validation
 - 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)
+- 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
+- URL normalisation — leading/trailing whitespace stripped from discovery and JWKs URLs
 
 ## Installation
 
@@ -67,7 +73,8 @@ config.middleware.use Verikloak::Middleware,
   token_env_key: "rack.session.token",     # Custom token storage key
   user_env_key: "rack.session.claims",     # Custom user claims storage key
   realm: "my-api",                         # Custom realm for WWW-Authenticate header
-  logger: Rails.logger                     # Logger for internal errors
+  logger: Rails.logger,                    # Logger for internal errors
+  allow_http: false                        # Set true only for local development (disables HTTPS enforcement)
 ```
 
 **Additional middleware options:**
@@ -215,11 +222,14 @@ For a full list of error cases and detailed explanations, please see the [ERRORS
 | `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                           |
+| `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                                    |
 | `internal_server_error`    | 500 Internal Server Error | Unexpected internal error (catch-all)                                                        |
 
 > **Note:** The `decode_with_public_key` method ensures consistent error codes for all JWT verification failures.  
-> It may raise `invalid_signature`, `unsupported_algorithm`, `expired_token`, `invalid_issuer`, `invalid_audience`, or `not_yet_valid` depending on the verification outcome.
+> It may raise `invalid_signature`, `unsupported_algorithm`, `expired_token`, `invalid_issuer`, `invalid_audience`, or `not_yet_valid` depending on the verification outcome.  
+> Additionally, tokens exceeding 8 KB are rejected with `invalid_token` before decoding to mitigate denial-of-service.
 
 ## Configuration Options
 
@@ -239,6 +249,7 @@ For a full list of error cases and detailed explanations, please see the [ERRORS
 | `user_env_key`  | No       | Rack env key for decoded claims. Defaults to `verikloak.user`. |
 | `realm`         | No       | Value used in the `WWW-Authenticate` header. Defaults to `verikloak`. |
 | `logger`        | No       | Logger for unexpected internal failures (responds to `error`, optionally `debug`). |
+| `allow_http`    | No       | When `false` (default), `Discovery` and `JwksCache` reject plain `http://` URLs. Set `true` **only** for local development against a non-TLS Keycloak instance. |
 
 #### Option: `skip_paths`
 
@@ -373,6 +384,8 @@ Verikloak consists of modular components, each with a focused responsibility:
 | `HTTP`          | Provides shared Faraday connection with retries/timeouts | Network layer|
 | `JwksCache`     | Fetches & caches JWKs public keys (with ETag)        | Cache layer  |
 | `TokenDecoder`  | Decodes and verifies JWTs (signature, exp, nbf, iss, aud) | Crypto layer |
+| `ErrorResponse`  | RFC 6750 compliant JSON error response builder       | Core layer   |
+| `SkipPathMatcher`| Reusable skip-path normalization and matching mixin  | Core layer   |
 | `Errors`        | Centralized error hierarchy                          | Core layer   |
 
 This separation enables better testing, modular reuse, and flexibility.

data/lib/verikloak/discovery.rb

@@ -1,12 +1,29 @@
 # frozen_string_literal: true
 
 require 'faraday'
+require 'ipaddr'
 require 'json'
+require 'resolv'
 require 'uri'
 
 require 'verikloak/http'
 
 module Verikloak
+  # Private IP ranges that must not be targets of redirects (SSRF protection).
+  # Includes RFC 1918, loopback, link-local, and IPv6 equivalents.
+  # @api private
+  PRIVATE_IP_RANGES = [
+    IPAddr.new('10.0.0.0/8'),
+    IPAddr.new('172.16.0.0/12'),
+    IPAddr.new('192.168.0.0/16'),
+    IPAddr.new('127.0.0.0/8'),
+    IPAddr.new('169.254.0.0/16'),
+    IPAddr.new('0.0.0.0/8'),
+    IPAddr.new('::1/128'),
+    IPAddr.new('fc00::/7'),
+    IPAddr.new('fe80::/10')
+  ].freeze
+
   # Fetches and caches the OpenID Connect Discovery document.
   #
   # This class retrieves the discovery metadata from an OpenID Connect provider
@@ -43,16 +60,27 @@ module Verikloak
     # @param discovery_url [String] The full URL to the `.well-known/openid-configuration`.
     # @param connection [Faraday::Connection] Optional Faraday client (for DI/tests).
     # @param cache_ttl [Integer] Cache TTL in seconds (default: 3600).
+    # @param allow_http [Boolean] When false (default), raises on plain HTTP URLs. Set true for local development only.
     # @raise [DiscoveryError] when `discovery_url` is not a valid HTTP(S) URL
-    def initialize(discovery_url:, connection: Verikloak::HTTP.default_connection, cache_ttl: 3600)
-      unless discovery_url.is_a?(String) && discovery_url.strip.match?(%r{^https?://})
+    def initialize(discovery_url:, connection: Verikloak::HTTP.default_connection, cache_ttl: 3600, allow_http: false)
+      normalized_url = discovery_url.is_a?(String) ? discovery_url.strip : discovery_url
+
+      unless normalized_url.is_a?(String) && normalized_url.match?(%r{^https?://})
         raise DiscoveryError.new('Invalid discovery URL: must be a non-empty HTTP(S) URL',
                                  code: 'invalid_discovery_url')
       end
 
-      @discovery_url = discovery_url
+      unless allow_http || normalized_url.start_with?('https://')
+        raise DiscoveryError.new(
+          'Discovery URL must use HTTPS. Set allow_http: true to permit plain HTTP (development only).',
+          code: 'insecure_discovery_url'
+        )
+      end
+
+      @discovery_url = normalized_url
       @conn          = connection
       @cache_ttl     = cache_ttl
+      @allow_http    = allow_http
       @cached_json   = nil
       @fetched_at    = nil
       @mutex         = Mutex.new
@@ -98,30 +126,28 @@ module Verikloak
     # @return [Hash]
     # @raise [DiscoveryError]
     def handle_final_response(response)
+      return parse_json(response.body) if response.status == 200
+
+      raise DiscoveryError.new(failure_message(response), code: 'discovery_metadata_fetch_failed')
+    end
+
+    # Builds the error message for non-200 final responses.
+    # @api private
+    def failure_message(response)
       status = response.status
-      return parse_json(response.body) if status == 200
-
-      if status == 404
-        # If the 404 occurred after a redirect (final URL differs from the original discovery URL),
-        # keep the generic message to align with redirect tests; otherwise use a specific "not found" message.
-        final_url = response.respond_to?(:env) && response.env&.url ? response.env.url.to_s : nil
-        message = if final_url && final_url != @discovery_url
-                    'Failed to fetch discovery document: status 404'
-                  else
-                    'Discovery document not found (404)'
-                  end
-        raise DiscoveryError.new(message, code: 'discovery_metadata_fetch_failed')
-      end
-      if (500..599).cover?(status)
-        raise DiscoveryError.new("Discovery endpoint server error: status #{status}",
-                                 code: 'discovery_metadata_fetch_failed')
-      end
+      return "Discovery endpoint server error: status #{status}" if (500..599).cover?(status)
+      return "Failed to fetch discovery document: status #{status}" unless status == 404
 
-      raise DiscoveryError.new("Failed to fetch discovery document: status #{status}",
-                               code: 'discovery_metadata_fetch_failed')
+      final_url = response.respond_to?(:env) && response.env&.url&.to_s
+      if final_url && final_url != @discovery_url
+        'Failed to fetch discovery document: status 404'
+      else
+        'Discovery document not found (404)'
+      end
     end
 
     # Follows HTTP redirects up to `max_hops`, resolving relative `Location` values.
+    # Validates that redirect targets do not point to private/internal networks (SSRF protection).
     # @api private
     # @param response [Faraday::Response]
     # @param max_hops [Integer]
@@ -141,6 +167,7 @@ module Verikloak
 
         location = location_from(current)
         url = absolutize_location(location, base)
+        validate_redirect_target!(url)
         current = @conn.get(url)
         base = url
         hops += 1
@@ -163,9 +190,7 @@ module Verikloak
     # @return [String] absolute or relative URL string
     # @raise [DiscoveryError]
     def location_from(response)
-      raw = response.headers || {}
-      headers = {}
-      raw.each { |k, v| headers[k.to_s.downcase] = v }
+      headers = (response.headers || {}).transform_keys { |k| k.to_s.downcase }
       location = headers['location'].to_s.strip
       raise DiscoveryError.new('Redirect without Location header', code: 'discovery_redirect_error') if location.empty?
 
@@ -199,16 +224,70 @@ module Verikloak
       raise DiscoveryError.new('Discovery response is not valid JSON', code: 'discovery_metadata_invalid')
     end
 
-    # Validates HTTP response success status (helper, currently unused).
+    # Validates that a redirect target URL uses a permitted scheme and does not resolve
+    # to a private/internal IP address.
+    #
+    # Scheme check: rejects non-HTTP(S) schemes unconditionally, and rejects plain HTTP
+    # when `@allow_http` is false — preventing HTTPS→HTTP downgrade attacks.
+    #
+    # SSRF check: resolves the target hostname and compares each address against
+    # {PRIVATE_IP_RANGES}. IPv4-mapped IPv6 addresses (e.g. `::ffff:127.0.0.1`) are
+    # normalised to their native IPv4 form before comparison.
+    #
     # @api private
-    # @param response [Faraday::Response]
-    # @return [void]
+    # @param url [String] The redirect target URL
+    # @raise [DiscoveryError] when the target uses a disallowed scheme or resolves to a private IP
+    def validate_redirect_target!(url)
+      uri = URI.parse(url)
+      validate_redirect_scheme!(uri)
+      validate_redirect_not_private!(uri)
+    rescue URI::InvalidURIError => e
+      raise DiscoveryError.new("Invalid redirect URL: #{e.message}", code: 'discovery_redirect_error')
+    end
+
+    # Validates that the redirect URI uses an allowed HTTP(S) scheme.
+    # @api private
+    # @param uri [URI] Parsed redirect target
+    # @raise [DiscoveryError]
+    def validate_redirect_scheme!(uri)
+      unless %w[http https].include?(uri.scheme)
+        raise DiscoveryError.new(
+          "Redirect target uses unsupported scheme: #{uri.scheme}",
+          code: 'discovery_redirect_error'
+        )
+      end
+
+      return if @allow_http || uri.scheme == 'https'
+
+      raise DiscoveryError.new(
+        'Redirect target must use HTTPS (set allow_http: true for development)',
+        code: 'discovery_redirect_error'
+      )
+    end
+
+    # Validates that the redirect target does not resolve to a private/internal IP.
+    # IPv4-mapped IPv6 addresses are normalised before comparison.
+    # @api private
+    # @param uri [URI] Parsed redirect target
     # @raise [DiscoveryError]
-    def validate_http_status!(response)
-      return if response.success?
+    def validate_redirect_not_private!(uri)
+      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 PRIVATE_IP_RANGES.any? { |range| range.include?(ip) }
 
-      raise DiscoveryError.new("Failed to fetch discovery document: status #{response.status}",
-                               code: 'discovery_metadata_fetch_failed')
+        raise DiscoveryError.new(
+          "Redirect target resolves to a private/internal address (#{host})",
+          code: 'discovery_redirect_error'
+        )
+      end
+    rescue IPAddr::InvalidAddressError
+      # If the address cannot be parsed, allow the request to proceed
+      # (Faraday will handle the actual connection error)
+      nil
     end
 
     # Wraps a block with network and parsing error handling and re-raising as {DiscoveryError}.

data/lib/verikloak/error_response.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Verikloak
+  # Shared helpers for building RFC 6750 compliant JSON error responses.
+  #
+  # Provides a consistent format for error responses across all Verikloak middleware:
+  # - JSON body with `{ error:, message: }` structure
+  # - `WWW-Authenticate` header with Bearer scheme for 401 responses
+  # - Header value sanitization to prevent injection attacks
+  module ErrorResponse
+    module_function
+
+    # Build a JSON error response with optional RFC 6750 `WWW-Authenticate` header.
+    #
+    # @param code [String] The error code (e.g. "unauthorized", "insufficient_audience")
+    # @param message [String] Human-readable error message
+    # @param status [Integer] HTTP status code
+    # @param realm [String] The realm value for WWW-Authenticate (default: "verikloak")
+    # @return [Array(Integer, Hash, Array<String>)] Rack response triple
+    def build(code:, message:, status:, realm: 'verikloak')
+      body = { error: code, message: message }.to_json
+      headers = { 'Content-Type' => 'application/json' }
+
+      if status == 401
+        realm_val = sanitize_header_value(realm)
+        code_val  = sanitize_header_value(code)
+        msg_val   = sanitize_header_value(message)
+        headers['WWW-Authenticate'] =
+          %(Bearer realm="#{realm_val}", error="#{code_val}", error_description="#{msg_val}")
+      end
+
+      [status, headers, [body]]
+    end
+
+    # Sanitizes a value for safe inclusion in HTTP header quoted-string fields.
+    # Escapes backslashes and double-quotes, and strips CR/LF and other control characters.
+    #
+    # @param val [String, nil]
+    # @return [String]
+    def sanitize_header_value(val)
+      s = val.to_s
+      # Truncate at first CRLF sequence to prevent header injection
+      s = s.split("\r\n", 2).first.to_s
+      # Replace remaining lone CR or LF with spaces
+      s = s.gsub(/[\r\n]/, ' ')
+      s.gsub(/(["\\])/) { |m| "\\#{m}" }
+       .gsub(/[[:cntrl:]]/, '')
+    end
+  end
+end

data/lib/verikloak/errors.rb

@@ -10,17 +10,23 @@ module Verikloak
   #
   # @attr_reader [String, Symbol, nil] code
   #   A short error code identifier suitable for programmatic handling.
+  # @attr_reader [Integer, nil] http_status
+  #   HTTP status code associated with the error (e.g. 401, 403, 500, 503).
   #
   # @example Raising with a code
   #   raise Verikloak::Error.new("Something went wrong", code: "internal_error")
+  # @example Raising with a code and HTTP status
+  #   raise Verikloak::Error.new("Forbidden", code: "forbidden", http_status: 403)
   class Error < StandardError
-    attr_reader :code
+    attr_reader :code, :http_status
 
     # @param message [String, nil] Human-readable error message.
     # @param code [String, Symbol, nil] Optional short error code for programmatic handling.
-    def initialize(message = nil, code: nil)
+    # @param http_status [Integer, nil] Optional HTTP status code.
+    def initialize(message = nil, code: nil, http_status: nil)
       super(message)
       @code = code
+      @http_status = http_status
     end
   end
 

data/lib/verikloak/jwks_cache.rb

@@ -38,13 +38,27 @@ module Verikloak
   class JwksCache
     # @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
-    def initialize(jwks_uri:, connection: nil)
-      unless jwks_uri.is_a?(String) && jwks_uri.strip.match?(%r{^https?://})
+    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')
       end
 
-      @jwks_uri    = jwks_uri
+      clean_jwks_uri = jwks_uri.strip
+
+      unless clean_jwks_uri.match?(%r{^https?://})
+        raise JwksCacheError.new('Invalid JWKs URI: must be a non-empty HTTP(S) URL', code: 'jwks_fetch_failed')
+      end
+
+      unless allow_http || clean_jwks_uri.start_with?('https://')
+        raise JwksCacheError.new(
+          'JWKs URI must use HTTPS. Set allow_http: true to permit plain HTTP (development only).',
+          code: 'insecure_jwks_uri'
+        )
+      end
+
+      @jwks_uri    = clean_jwks_uri
       @connection  = connection || Verikloak::HTTP.default_connection
       @cached_keys = nil
       @etag        = nil

data/lib/verikloak/middleware.rb

@@ -6,86 +6,10 @@ require 'set'
 require 'faraday'
 
 require 'verikloak/http'
+require 'verikloak/skip_path_matcher'
+require 'verikloak/error_response'
 
 module Verikloak
-  # @api private
-  #
-  # 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 audience resolution with dynamic callable support.
@@ -492,7 +416,7 @@ module Verikloak
           # Use configured issuer if provided, otherwise use discovered issuer
           @issuer  = @configured_issuer || config['issuer']
           jwks_uri = config['jwks_uri']
-          @jwks_cache = JwksCache.new(jwks_uri: jwks_uri, connection: @connection)
+          @jwks_cache = JwksCache.new(jwks_uri: jwks_uri, connection: @connection, allow_http: @allow_http)
         elsif @configured_issuer.nil? && @issuer.nil?
           # If jwks_cache was injected but no issuer configured and not yet discovered, fetch discovery to set issuer
           config = @discovery.fetch!
@@ -665,12 +589,15 @@ module Verikloak
                    token_env_key: DEFAULT_TOKEN_ENV_KEY,
                    user_env_key: DEFAULT_USER_ENV_KEY,
                    realm: DEFAULT_REALM,
-                   logger: nil)
+                   logger: nil,
+                   allow_http: false)
       @app             = app
       @connection      = connection || Verikloak::HTTP.default_connection
       @audience_source = audience
-      @discovery       = discovery || Discovery.new(discovery_url: discovery_url, connection: @connection)
+      @discovery       = discovery || Discovery.new(discovery_url: discovery_url, connection: @connection,
+                                                    allow_http: allow_http)
       @jwks_cache      = jwks_cache
+      @allow_http      = allow_http
       @leeway = leeway
       @token_verify_options = token_verify_options || {}
       @decoder_cache_limit = normalize_decoder_cache_limit(decoder_cache_limit)
@@ -709,6 +636,10 @@ module Verikloak
       error_response('internal_server_error', 'An unexpected error occurred', 500)
     end
 
+    # Maximum token size in bytes to prevent DoS via oversized JWTs.
+    # Aligned with BFF's {Verikloak::BFF::Constants::MAX_TOKEN_BYTES}.
+    MAX_TOKEN_BYTES = 8192
+
     private
 
     # Returns the Faraday connection used for HTTP operations (Discovery/JWKs).
@@ -748,6 +679,10 @@ module Verikloak
         raise MiddlewareError.new('Invalid Authorization header format', code: 'invalid_authorization_header')
       end
 
+      if token.bytesize > MAX_TOKEN_BYTES
+        raise MiddlewareError.new('Token exceeds maximum allowed size', code: 'invalid_token')
+      end
+
       token
     end
 
@@ -773,19 +708,14 @@ module Verikloak
     end
 
     # Builds a JSON error response with RFC 6750 `WWW-Authenticate` header for 401.
+    # Delegates to {Verikloak::ErrorResponse} for consistent formatting across gems.
     #
     # @param code [String] The error code to include in the response
     # @param message [String] The error message to include in the response
     # @param status [Integer] The HTTP status code for the response
     # @return [Array(Integer, Hash, Array<String>)] Rack response triple
     def error_response(code = 'unauthorized', message = 'Unauthorized', status = 401)
-      body = { error: code, message: message }.to_json
-      headers = { 'Content-Type' => 'application/json' }
-      if status == 401
-        headers['WWW-Authenticate'] =
-          %(Bearer realm="#{@realm}", error="#{code}", error_description="#{message.gsub('"', '\\"')}")
-      end
-      [status, headers, [body]]
+      Verikloak::ErrorResponse.build(code: code, message: message, status: status, realm: @realm)
     end
 
     # Logs unexpected internal errors to STDERR (non-PII). Used for diagnostics only.

data/lib/verikloak/skip_path_matcher.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Verikloak
+  # Reusable mixin for skip-path normalization and matching.
+  #
+  # Include this module and call {#compile_skip_paths} during initialization,
+  # then call {#skip?} per-request to check whether the path should bypass processing.
+  #
+  # 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)
+  module SkipPathMatcher
+    private
+
+    # Checks whether the request path matches any compiled skip pattern.
+    #
+    # @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
+        end
+      end
+
+      @skip_prefixes.uniq!
+    end
+  end
+end

data/lib/verikloak/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - taiyaky
@@ -15,7 +15,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: 2.14.1
     - - "<"
       - !ruby/object:Gem::Version
         version: '3.0'
@@ -25,7 +25,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: 2.14.1
     - - "<"
       - !ruby/object:Gem::Version
         version: '3.0'
@@ -35,7 +35,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: 2.4.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '3.0'
@@ -45,7 +45,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: 2.4.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '3.0'
@@ -55,14 +55,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.6'
+        version: '2.18'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.6'
+        version: '2.18'
 - !ruby/object:Gem::Dependency
   name: jwt
   requirement: !ruby/object:Gem::Requirement
@@ -96,10 +96,12 @@ files:
 - README.md
 - lib/verikloak.rb
 - lib/verikloak/discovery.rb
+- lib/verikloak/error_response.rb
 - lib/verikloak/errors.rb
 - lib/verikloak/http.rb
 - lib/verikloak/jwks_cache.rb
 - lib/verikloak/middleware.rb
+- lib/verikloak/skip_path_matcher.rb
 - lib/verikloak/token_decoder.rb
 - lib/verikloak/version.rb
 homepage: https://github.com/taiyaky/verikloak
@@ -109,7 +111,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.3.0
+  documentation_uri: https://rubydoc.info/gems/verikloak/0.4.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: