verikloak-bff 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a79baf28ee05a8774b36916c71281bd72cd35825148413c15e9f865b85416cb
-  data.tar.gz: 739244544590c0f306eff4d587c27c312adc4c081646a45d2ec4a58e83ce6abb
+  metadata.gz: 3c5f40a546e7c2d93204ed332332ef0a7856f40b01b1b6ad3ca593ad97fc782d
+  data.tar.gz: 82d641a1d023617ccfdd313228a70e85d5cb314d0de410822789b12210a5b260
 SHA512:
-  metadata.gz: 713b4e27ee284e38917a6fd4880414cdb8792fbffd4f7713112d2fa619f5ecf3120379a4a0b29eb115ce075c6373e0a4b25f1bca38bd8e8af0ff683944dcd8fd
-  data.tar.gz: ed258207b16fdb79fb079656393e0f7fd4bc1a650d942c6c19060c0aeaf45f8e63fa393a115bb8f80ea87f9c0d84cd025bb55a5ffb5259a981007211c896b786
+  metadata.gz: aff00531a727ad605b8b33fc18e0bea74dfebcef456bc3d9f43f1b6274772b00f7694765dffb30cf0be7fd4682d861685117a52fe821cb44405377daad9b7268
+  data.tar.gz: 37acc8610e94b2606c958217b58f1842b47f8b277f57773f096c37b33099545c98b10f984c8102cc3880e7c4f5148140ca7fa0c5213ecfded1174377834cca0f

data/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.4.0] - 2026-02-15
+
+### Security
+- **Log value truncation**: `sanitize_string` now truncates values exceeding 256 characters (`MAX_LOG_FIELD_LENGTH`) to prevent log injection / memory abuse
+
+### Fixed
+- **`MAX_TOKEN_BYTES`**: Raised from 4096 to 8192 to match core gem — prevents behavioural inconsistency (false rejection / inspection bypass) for tokens between 4 KB and 8 KB
+- **IPv4-mapped IPv6 normalisation**: `ProxyTrust.ip_or_nil` now calls `IPAddr#native` so that `::ffff:172.17.0.1` correctly matches `172.17.0.0/16` in Docker/Kubernetes environments
+- **`apply_overrides!` hardening**: Rejects keys starting with `_` or containing `!` to prevent accidental invocation of non-accessor methods (consistent with verikloak-rails `BffConfigurator`)
+- **`ForwardedToken::FORWARDED_HEADER`**: Now references `Verikloak::HeaderSources::DEFAULT_FORWARDED_HEADER` instead of duplicating the string, eliminating maintenance drift risk
+
+### Changed
+- Error responses now delegate to `Verikloak::ErrorResponse.build` for RFC 6750-compliant JSON output
+- Error class hierarchy unified: `Verikloak::BFF::Error` now inherits from `Verikloak::Error`
+- **BREAKING**: Minimum `verikloak` dependency raised to `>= 0.4.0`
+- Dev dependency `rspec` pinned to `~> 3.13`, `rubocop-rspec` pinned to `~> 3.9`
+
+### Inherited from verikloak 0.4.0
+The following security improvements are provided by the core `verikloak` gem and become available through the dependency bump. They are **not implemented in verikloak-bff** itself:
+- Faraday 2.14.1 security update (CVE-2026-25765)
+- Header injection protection via `Verikloak::ErrorResponse.sanitize_header_value`
+- JWT token size limit (`MAX_TOKEN_BYTES = 8192`)
+- HTTPS enforcement and SSRF protection in OIDC discovery
+- URL path-traversal normalisation
+
+---
+
 ## [0.3.0] - 2025-01-01
 
 ### Added

data/README.md

@@ -113,6 +113,7 @@ For full reverse proxy examples (Nginx auth_request / oauth2-proxy), see [docs/r
 
 - Trusted proxy hygiene
   - Keep `trusted_proxies` as specific as possible (individual IPs, tight CIDR ranges, or regexes). Review the list whenever proxy topology changes to avoid unintentionally widening the trust boundary.
+  - IPv4-mapped IPv6 addresses (`::ffff:172.17.0.1`) are automatically normalised to native IPv4 so that plain IPv4 CIDR ranges (e.g. `172.17.0.0/16`) match correctly in Docker / Kubernetes environments.
 
 - Header name customization
   - Forwarded-access-token header can be changed via:

data/lib/verikloak/bff/consistency_checks.rb

@@ -36,7 +36,31 @@ module Verikloak
         return true if mapping.nil? || mapping.empty?
 
         claims = decode_claims(token)
+        enforce_claims(env, claims, mapping, headers_map)
+      end
+
+      # Enforce consistency using pre-decoded claims (avoids redundant JWT parsing).
+      #
+      # @param env [Hash]
+      # @param claims [Hash] pre-decoded JWT claims
+      # @param mapping [Hash]
+      # @param headers_map [Hash{Symbol=>String}, nil]
+      # @return [true, Array(:error, Symbol)]
+      def enforce_with_claims(env, claims, mapping, headers_map = nil)
+        return true if mapping.nil? || mapping.empty?
 
+        claims = {} unless claims.is_a?(Hash)
+        enforce_claims(env, claims, mapping, headers_map)
+      end
+
+      # Shared implementation for enforce! and enforce_with_claims.
+      #
+      # @param env [Hash]
+      # @param claims [Hash]
+      # @param mapping [Hash]
+      # @param headers_map [Hash{Symbol=>String}, nil]
+      # @return [true, Array(:error, Symbol)]
+      def enforce_claims(env, claims, mapping, headers_map)
         mapping.each do |header_key, claim_key|
           hdr_val = extract_header_value(env, header_key, headers_map)
           next if hdr_val.nil? # no header → skip comparison

data/lib/verikloak/bff/constants.rb

@@ -2,8 +2,20 @@
 
 module Verikloak
   module BFF
+    # Shared constants for the BFF middleware layer.
+    # Centralised here so that every module (HeaderGuard, JwtUtils,
+    # ConsistencyChecks, etc.) references the same values.
     module Constants
-      MAX_TOKEN_BYTES = 4096
+      # Maximum JWT byte size accepted for unverified decoding.
+      # Tokens exceeding this limit are treated as opaque (no claim inspection).
+      MAX_TOKEN_BYTES = 8192
+
+      # Regex matching Unicode control characters, used by log sanitisation.
+      LOG_CONTROL_CHARS = /[[:cntrl:]]/
+
+      # Maximum length for individual log field values to prevent log flooding
+      # from oversized or malicious JWT claims.
+      MAX_LOG_FIELD_LENGTH = 256
     end
   end
 end

data/lib/verikloak/bff/errors.rb

@@ -3,15 +3,17 @@
 # Error types emitted by verikloak-bff. These map to RFC6750-style responses
 # with stable error codes for easy handling at clients and logs.
 
+require 'verikloak/errors'
+
 module Verikloak
   module BFF
     # Base error class with HTTP status and short code.
+    # Inherits from {Verikloak::Error} so that `rescue Verikloak::Error` catches all
+    # Verikloak gem errors uniformly.
     #
     # @attr_reader [String] code
     # @attr_reader [Integer] http_status
-    class Error < StandardError
-      attr_reader :code, :http_status
-
+    class Error < Verikloak::Error
       # Build a BFF error with a stable code and HTTP status.
       #
       # @param message [String, nil]
@@ -19,9 +21,7 @@ module Verikloak
       # @param http_status [Integer]
       # @return [void]
       def initialize(message = nil, code: 'bff_error', http_status: 401)
-        super(message || code)
-        @code = code
-        @http_status = http_status
+        super(message || code, code: code, http_status: http_status)
       end
     end
 

data/lib/verikloak/bff/forwarded_token.rb

@@ -4,14 +4,16 @@
 #
 # @see .extract
 
+require 'verikloak/header_sources'
+
 module Verikloak
   module BFF
     # Helpers to extract and normalize forwarded/access token headers.
     module ForwardedToken
       module_function
 
-      FORWARDED_HEADER = 'HTTP_X_FORWARDED_ACCESS_TOKEN'
-      AUTH_HEADER      = 'HTTP_AUTHORIZATION'
+      FORWARDED_HEADER = Verikloak::HeaderSources::DEFAULT_FORWARDED_HEADER
+      AUTH_HEADER      = Verikloak::HeaderSources::AUTHORIZATION_HEADER
 
       # Extract normalized tokens from the Rack env.
       #

data/lib/verikloak/bff/header_guard.rb

@@ -27,7 +27,8 @@ module Verikloak
   module BFF
     # Internal helpers that sanitize tokens and log payloads for HeaderGuard.
     module HeaderGuardSanitizer
-      LOG_CONTROL_CHARS = /[[:cntrl:]]/
+      LOG_CONTROL_CHARS    = Constants::LOG_CONTROL_CHARS
+      MAX_LOG_FIELD_LENGTH = Constants::MAX_LOG_FIELD_LENGTH
 
       module_function
 
@@ -40,15 +41,31 @@ module Verikloak
         return {} unless token
 
         payload, header = decode_unverified(token)
+        token_tags_from_decoded(payload, header)
+      rescue StandardError => e
+        warn("[verikloak-bff] token_tags failed: #{e.class}: #{e.message}") if $DEBUG
+        {}
+      end
+
+      # Build sanitized log tags from pre-decoded JWT payload and header.
+      # Avoids redundant decoding when the caller already has decoded data.
+      #
+      # @param payload [Hash]
+      # @param header [Hash]
+      # @return [Hash{Symbol=>Object}]
+      def token_tags_from_decoded(payload, header)
+        return {} unless payload.is_a?(Hash)
+
         aud = payload['aud']
         aud = aud.join(' ') if aud.is_a?(Array)
         {
           sub: sanitize_log_field(payload['sub']&.to_s),
           iss: sanitize_log_field(payload['iss']&.to_s),
           aud: sanitize_log_field(aud&.to_s),
-          kid: sanitize_log_field(header['kid']&.to_s)
+          kid: sanitize_log_field(header&.dig('kid')&.to_s)
         }.compact
-      rescue StandardError
+      rescue StandardError => e
+        warn("[verikloak-bff] token_tags_from_decoded failed: #{e.class}: #{e.message}") if $DEBUG
         {}
       end
 
@@ -89,12 +106,14 @@ module Verikloak
         end
       end
 
-      # Remove control characters and invalid UTF-8 from a string.
+      # Remove control characters, invalid UTF-8, and truncate to {MAX_LOG_FIELD_LENGTH}.
       #
       # @param value [#to_s]
       # @return [String]
       def sanitize_string(value)
-        value.to_s.encode('UTF-8', invalid: :replace, undef: :replace, replace: '').gsub(LOG_CONTROL_CHARS, '')
+        sanitized = value.to_s.encode('UTF-8', invalid: :replace, undef: :replace, replace: '').gsub(LOG_CONTROL_CHARS,
+                                                                                                     '')
+        sanitized.length > MAX_LOG_FIELD_LENGTH ? "#{sanitized[0, MAX_LOG_FIELD_LENGTH]}..." : sanitized
       end
 
       # Describe the source of the chosen token for logging purposes.
@@ -129,26 +148,38 @@ module Verikloak
       # @param attrs [Hash]
       # @return [void]
       def log_event(env, config, kind, **attrs)
-        lg = config.logger || env['rack.logger']
         payload = { event: 'bff.header_guard', kind: kind, rid: request_id(env) }.merge(attrs).compact
         sanitized = sanitize_payload(payload)
-        if config.log_with.respond_to?(:call)
-          begin
-            config.log_with.call(sanitized)
-          rescue StandardError
-            # ignore log hook failures
-          end
-        end
-        return unless lg
+        invoke_log_hook(config, sanitized)
+        emit_to_logger(config.logger || env['rack.logger'], sanitized, kind)
+      rescue StandardError => e
+        warn("[verikloak-bff] log_event failed: #{e.class}: #{e.message}") if $DEBUG
+      end
+
+      # @param config [Configuration]
+      # @param sanitized [Hash]
+      # @return [void]
+      def invoke_log_hook(config, sanitized)
+        return unless config.log_with.respond_to?(:call)
+
+        config.log_with.call(sanitized)
+      rescue StandardError => e
+        warn("[verikloak-bff] log_with hook failed: #{e.class}: #{e.message}") if $DEBUG
+      end
+
+      # @param logger [Logger, nil]
+      # @param sanitized [Hash]
+      # @param kind [Symbol]
+      # @return [void]
+      def emit_to_logger(logger, sanitized, kind)
+        return unless logger
 
         msg = sanitized.map { |k, v| v.nil? || v.to_s.empty? ? nil : "#{k}=#{v}" }.compact.join(' ')
-        level = (kind == :ok ? :info : :warn)
-        lg.public_send(level, msg)
-      rescue StandardError
-        # no-op on logging errors
+        logger.public_send(kind == :ok ? :info : :warn, msg)
       end
 
       # Build a minimal RFC6750-style error response.
+      # Delegates to {Verikloak::ErrorResponse} for consistent formatting across gems.
       #
       # @param env [Hash]
       # @param config [Configuration]
@@ -156,10 +187,23 @@ module Verikloak
       # @return [Array(Integer, Hash, Array<String>)]
       def respond_with_error(env, config, error)
         log_event(env, config, :error, code: error.code)
-        body = { error: error.code, message: error.message }.to_json
-        headers = { 'Content-Type' => 'application/json',
-                    'WWW-Authenticate' => %(Bearer error="#{error.code}", error_description="#{error.message}") }
-        [error.http_status, headers, [body]]
+        require 'verikloak/error_response'
+        status, headers, body = Verikloak::ErrorResponse.build(
+          code: error.code, message: error.message, status: error.http_status
+        )
+
+        # RFC 6750 §3.1: include WWW-Authenticate on 403 for client diagnostics
+        if status == 403 && !headers.key?('WWW-Authenticate')
+          sanitize = Verikloak::ErrorResponse.method(:sanitize_header_value)
+          headers['WWW-Authenticate'] = format(
+            'Bearer realm="%<realm>s", error="%<code>s", error_description="%<msg>s"',
+            realm: sanitize.call('verikloak-bff'),
+            code: sanitize.call(error.code),
+            msg: sanitize.call(error.message)
+          )
+        end
+
+        [status, headers, body]
       end
     end
 
@@ -168,7 +212,7 @@ module Verikloak
       # Error raised when trusted_proxies is not configured and disabled is not explicitly set.
       class ConfigurationError < StandardError; end
 
-      RequestTokens = Struct.new(:auth, :forwarded, :chosen)
+      RequestTokens = Struct.new(:auth, :forwarded, :chosen, :decoded_payload, :decoded_header)
 
       # Accept both Rack 2 and Rack 3 builder call styles:
       # - new(app, key: val)
@@ -251,6 +295,8 @@ module Verikloak
       end
 
       # Build token state by extracting, validating, and selecting the active token.
+      # Decodes the chosen token once (unverified) so that downstream stages
+      # (claims consistency, logging) can reuse the result without re-parsing.
       #
       # @param env [Hash]
       # @return [RequestTokens]
@@ -261,7 +307,8 @@ module Verikloak
         chosen = choose_token(auth_token, fwd_token)
         chosen = seed_authorization_if_needed(env, chosen)
 
-        RequestTokens.new(auth_token, fwd_token, chosen)
+        payload, header = JwtUtils.decode_unverified(chosen)
+        RequestTokens.new(auth_token, fwd_token, chosen, payload, header)
       end
 
       # Apply header and claim consistency policies for the current request.
@@ -271,7 +318,7 @@ module Verikloak
       # @return [void]
       def enforce_token_policies!(env, tokens)
         enforce_header_consistency!(env, tokens.auth, tokens.forwarded)
-        enforce_claims_consistency!(env, tokens.chosen)
+        enforce_claims_consistency!(env, tokens)
       end
 
       # Mutate the Rack env with normalized headers and logging hints.
@@ -281,18 +328,24 @@ module Verikloak
       # @return [void]
       def finalize_request!(env, tokens)
         ForwardedToken.strip_suspicious!(env, @config.auth_request_headers) if @config.strip_suspicious_headers
-        normalize_authorization!(env, tokens.chosen, tokens.auth, tokens.forwarded)
+        normalize_authorization!(env, tokens)
         expose_env_hints(env, tokens.chosen)
       end
 
       # Apply per-instance configuration overrides.
+      # Keys starting with '_' or containing '!' are rejected to prevent
+      # accidental invocation of non-accessor methods.
       #
       # @param opts [Hash]
       # @return [void]
       def apply_overrides!(opts)
         cfg = @config
         opts.each do |k, v|
-          cfg.public_send("#{k}=", v) if cfg.respond_to?("#{k}=")
+          key_s = k.to_s
+          next if key_s.start_with?('_') || key_s.include?('!')
+
+          writer = "#{key_s}="
+          cfg.public_send(writer, v) if cfg.respond_to?(writer)
         end
       end
 
@@ -347,11 +400,14 @@ module Verikloak
       # Enforce X-Auth-Request-* ↔ JWT claims mapping when configured.
       #
       # @param env [Hash]
-      # @param chosen [String, nil]
+      # @param tokens [RequestTokens]
       # @return [void]
       # @raise [ClaimsMismatchError]
-      def enforce_claims_consistency!(env, chosen)
-        res = ConsistencyChecks.enforce!(env, chosen, @config.enforce_claims_consistency, @config.auth_request_headers)
+      def enforce_claims_consistency!(env, tokens)
+        res = ConsistencyChecks.enforce_with_claims(
+          env, tokens.decoded_payload,
+          @config.enforce_claims_consistency, @config.auth_request_headers
+        )
         return unless res.is_a?(Array) && res.first == :error
 
         field = res.last
@@ -372,18 +428,19 @@ module Verikloak
       end
 
       # Set normalized Authorization header and emit success log.
+      # Reuses pre-decoded token payload/header from {RequestTokens} to avoid
+      # redundant JWT parsing.
       #
       # @param env [Hash]
-      # @param chosen [String, nil]
-      # @param auth_token [String, nil]
-      # @param fwd_token [String, nil]
+      # @param tokens [RequestTokens]
       # @return [void]
-      def normalize_authorization!(env, chosen, auth_token, fwd_token)
-        return unless chosen
+      def normalize_authorization!(env, tokens)
+        return unless tokens.chosen
 
-        ForwardedToken.set_authorization!(env, chosen)
-        source = HeaderGuardSanitizer.token_source(@config.prefer_forwarded, auth_token, fwd_token)
-        HeaderGuardSanitizer.log_event(env, @config, :ok, source: source, **HeaderGuardSanitizer.token_tags(chosen))
+        ForwardedToken.set_authorization!(env, tokens.chosen)
+        source = HeaderGuardSanitizer.token_source(@config.prefer_forwarded, tokens.auth, tokens.forwarded)
+        tags = HeaderGuardSanitizer.token_tags_from_decoded(tokens.decoded_payload, tokens.decoded_header)
+        HeaderGuardSanitizer.log_event(env, @config, :ok, source: source, **tags)
       end
 
       # Resolve the first env header from which to source a bearer token.

data/lib/verikloak/bff/proxy_trust.rb

@@ -54,11 +54,15 @@ module Verikloak
       end
 
       # Parse string to IPAddr or nil on failure.
+      # IPv4-mapped IPv6 addresses (e.g. ::ffff:127.0.0.1) are normalised to
+      # native IPv4 so that CIDR checks against plain IPv4 ranges succeed.
       #
       # @param str [String]
       # @return [IPAddr, nil]
       def ip_or_nil(str)
-        IPAddr.new(str)
+        addr = IPAddr.new(str)
+        addr = addr.native if addr.respond_to?(:native)
+        addr
       rescue StandardError
         nil
       end

data/lib/verikloak/bff/version.rb

@@ -5,6 +5,6 @@
 # @return [String]
 module Verikloak
   module BFF
-    VERSION = '0.3.0'
+    VERSION = '0.4.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak-bff
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - taiyaky
@@ -55,7 +55,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.4.0
     - - "<"
       - !ruby/object:Gem::Version
         version: 1.0.0
@@ -65,7 +65,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.4.0
     - - "<"
       - !ruby/object:Gem::Version
         version: 1.0.0
@@ -101,7 +101,7 @@ metadata:
   source_code_uri: https://github.com/taiyaky/verikloak-bff
   changelog_uri: https://github.com/taiyaky/verikloak-bff/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/taiyaky/verikloak-bff/issues
-  documentation_uri: https://rubydoc.info/gems/verikloak-bff/0.3.0
+  documentation_uri: https://rubydoc.info/gems/verikloak-bff/0.4.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: