verikloak-bff 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3034b92c69f7147be681038b8f91a5a0c4ec1d577144a4372cad33b6645adb3a
-  data.tar.gz: a52b1ccc320fee7d5526f612fa509218a5b2232ce678d6d6e03a42d5c0122df0
+  metadata.gz: 6901b11146849ea25306d9f78b3cf7d8903dce4374efcf1322a7aed6a3d52872
+  data.tar.gz: 9a9cd3f59250aa57599de7e973009dedff8d075a395632eef1a19a889fb6257c
 SHA512:
-  metadata.gz: a9e31d538da66f06b1f18412b41520a3c1a5f0f5e3adf88af19f4aa68451420717002c11dc639a2f1dbc9441b64b68b74de2729d2ef8a5af805d862b7568dd75
-  data.tar.gz: cb2f118b465d7cb4a64f0aa9eb77cb81ec0bd5a82ae2b33c1e9992b1b518e5690dee84f7c5ae69189b83e0394de784d559c57daef41154c24f396390cb0d8bab
+  metadata.gz: eed7006bf01e9a51b4824d8e4fdd2a759210270fdf5fdb07617a21b5b6e40862232dc162f8bec8e65fdb89cea59443eee7a030c7fdd2e335446c182b2745936a
+  data.tar.gz: d89ca6f1f4032198704a0167d1c3cad7b8b2b1adc68948bb06b0abbf45c4f51157e2d00f3906ad070c4c59c56ed7ddb31bd8f8a58cd06884304b890889685b91

data/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.1.2] - 2025-09-21
+
+### Added
+- Configuration option `claims_consistency_mode` supporting `:log_only` so deployments can record mismatches without rejecting requests.
+
+### Changed
+- Sanitize log payload strings (including JWT tags) before invoking hooks or emitting to loggers to mitigate log forging attempts.
+
+### Documentation
+- Document trusted proxy hygiene, sanitized logging hooks, and the new log-only mode in the README and Rails guide.
+
+## [0.1.1] - 2025-09-15
+
+### Changed
+- Centralize `MAX_TOKEN_BYTES` in `Verikloak::BFF::Constants` and refactor usages in `HeaderGuard` and `ConsistencyChecks` to avoid duplication.
+
+### Fixed
+- Preserve full token content when forwarded header includes control characters (e.g., `Bearer tok\r\nmal`) by adjusting Bearer parsing in `ForwardedToken.normalize_forwarded`; combined with existing sanitization, Authorization now normalizes to `Bearer tokmal`.
+
+### Tests
+- Add boundary tests for token size limits in `ConsistencyChecks` and `HeaderGuard`.
+
 ## [0.1.0] - 2025-09-14
 
 ### Added

data/README.md

@@ -42,17 +42,18 @@ See `examples/rack.ru` for a tiny Rack app demo.
 
 | Key                          | Type                                 | Default      | Description |
 |----------------------------- |--------------------------------------|--------------|-------------|
-| `trusted_proxies`            | Array[String/Regexp/Proc]            | `[]`         | Allowlist for proxy peers (by IP/CIDR/regex/proc). |
+| `trusted_proxies`            | Array[String/Regexp/Proc]            | *(required)* | Allowlist for proxy peers (by IP/CIDR/regex/proc). |
 | `prefer_forwarded`           | Boolean                              | `true`       | Prefer `X-Forwarded-Access-Token` over `Authorization`. |
 | `require_forwarded_header`   | Boolean                              | `false`      | Reject when no `X-Forwarded-Access-Token` (blocks direct access). |
 | `enforce_header_consistency` | Boolean                              | `true`       | If both headers exist, require identical token values. |
 | `enforce_claims_consistency` | Hash                                 | `{}`         | Mapping of header→claim to compare (e.g., `{ email: :email, user: :sub, groups: :realm_roles }`). |
+| `claims_consistency_mode`    | Symbol (`:enforce`/`:log_only`)      | `:enforce`   | When `:log_only`, mismatches are logged but the request continues (still require downstream JWT verification). |
 | `strip_suspicious_headers`   | Boolean                              | `true`       | Remove external `X-Auth-Request-*` before passing downstream. |
 | `xff_strategy`               | Symbol (`:rightmost`/`:leftmost`)    | `:rightmost` | Which peer to pick from `X-Forwarded-For`. |
 | `peer_preference`            | Symbol (`:remote_then_xff`/`:xff_only`) | `:remote_then_xff` | Whether to prefer `REMOTE_ADDR` before falling back to XFF. |
 | `clock_skew_leeway`          | Integer (seconds)                    | `30`         | Reserved for small exp/nbf skew handled by core verifier. |
 | `logger`                     | `Logger` or `nil`                    | `nil`        | Logger for audit tags (`rid`, `sub`, `kid`, `iss/aud`). |
-| `token_header_priority`      | Array[String]                        | see code     | When Authorization is empty and no token chosen, seed it from these env headers in order. `HTTP_AUTHORIZATION` is ignored as a source; forwarded header is considered only from trusted peers. |
+| `token_header_priority`      | Array[String]                        | `['HTTP_X_FORWARDED_ACCESS_TOKEN']` | When Authorization is empty and no token chosen, seed it from these env headers in order. `HTTP_AUTHORIZATION` is ignored as a source; forwarded header is considered only from trusted peers. |
 | `forwarded_header_name`      | String                               | `HTTP_X_FORWARDED_ACCESS_TOKEN` | Env key for forwarded access token. |
 | `auth_request_headers`       | Hash                                 | see code     | Mapping for `X-Auth-Request-*` env keys: `{ email, user, groups }`. |
 
@@ -69,6 +70,9 @@ For full reverse proxy examples (Nginx auth_request / oauth2-proxy), see [docs/r
   - Set `peer_preference: :remote_then_xff` (default) to evaluate trust using the direct peer first, then fall back to the nearest (rightmost) `X-Forwarded-For` value.
   - If you run only behind a single, known proxy chain and want to rely solely on XFF ordering, use `peer_preference: :xff_only` and control position with `xff_strategy`.
 
+- 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.
+
 - Header name customization
   - Forwarded-access-token header can be changed via:
     - `forwarded_header_name: 'HTTP_X_CUSTOM_FORWARD_TOKEN'`
@@ -81,9 +85,12 @@ For full reverse proxy examples (Nginx auth_request / oauth2-proxy), see [docs/r
 
 - Observability helpers
   - Downstream can inspect `env['verikloak.bff.token']` (chosen token, unverified) and `env['verikloak.bff.selected_peer']` (peer IP selected for trust decisions).
-  - Provide a structured log hook with `log_with: ->(payload) { logger.info(payload.to_json) }` to consume the same fields emitted to `logger`.
+  - Provide a structured log hook with `log_with: ->(payload) { logger.info(payload.to_json) }` to consume the same fields emitted to `logger`. Payload strings are sanitized (control characters removed) before hooks and loggers run to mitigate log forging.
   - Caution: avoid logging the entire Rack `env` in application logs. Treat `env['verikloak.bff.token']` as sensitive; never emit raw tokens or PII (e.g., emails) to logs.
 
+- Claims consistency modes
+  - Default `:enforce` mode rejects requests with mismatches. Switch to `claims_consistency_mode: :log_only` when you only need observability signals; downstream services must continue verifying JWT signatures, issuer, audience, and expirations.
+
 ## Development (for contributors)
 Clone and install dependencies:
 

data/lib/verikloak/bff/configuration.rb

@@ -30,7 +30,8 @@ module Verikloak
                     :enforce_header_consistency, :enforce_claims_consistency,
                     :strip_suspicious_headers, :xff_strategy, :clock_skew_leeway,
                     :logger, :token_header_priority, :peer_preference,
-                    :forwarded_header_name, :auth_request_headers, :log_with
+                    :forwarded_header_name, :auth_request_headers, :log_with,
+                    :claims_consistency_mode
 
       # enforce_claims_consistency example:
       # { email: :email, user: :sub, groups: :realm_roles }
@@ -40,6 +41,7 @@ module Verikloak
         @require_forwarded_header = false
         @enforce_header_consistency = true
         @enforce_claims_consistency = {}
+        @claims_consistency_mode = :enforce
         @strip_suspicious_headers = true
         @xff_strategy = :rightmost
         @peer_preference = :remote_then_xff
@@ -53,10 +55,9 @@ module Verikloak
           groups: 'HTTP_X_AUTH_REQUEST_GROUPS'
         }
         # When Authorization is empty and no chosen token exists, try these env headers (in order)
-        # to seed Authorization, similar to verikloak-rails behavior. HTTP_AUTHORIZATION is ignored as a source.
+        # to seed Authorization, similar to verikloak-rails behavior. HTTP_AUTHORIZATION is always ignored as a source.
         @token_header_priority = %w[
           HTTP_X_FORWARDED_ACCESS_TOKEN
-          HTTP_AUTHORIZATION
         ]
       end
     end

data/lib/verikloak/bff/consistency_checks.rb

@@ -7,6 +7,7 @@
 
 require 'json'
 require 'jwt' # used only to parse segments safely without verify
+require 'verikloak/bff/constants'
 
 module Verikloak
   module BFF
@@ -19,14 +20,12 @@ module Verikloak
       #
       # @param token [String, nil]
       # @return [Hash] claims or empty hash on error
+
       def decode_claims(token)
         return {} unless token
+        return {} if token.bytesize > Constants::MAX_TOKEN_BYTES
 
-        parts = token.split('.')
-        return {} unless parts.size >= 2
-
-        payload = JWT::Base64.url_decode(parts[1])
-        JSON.parse(payload)
+        JWT.decode(token, nil, false).first
       rescue StandardError
         {}
       end

data/lib/verikloak/bff/constants.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Verikloak
+  module BFF
+    module Constants
+      MAX_TOKEN_BYTES = 4096
+    end
+  end
+end

data/lib/verikloak/bff/forwarded_token.rb

@@ -45,7 +45,7 @@ module Verikloak
         return nil unless raw
 
         token = raw.to_s.strip
-        return ::Regexp.last_match(1) if token =~ /^Bearer\s+(.+)$/i
+        token = token.sub(/^Bearer\s+/i, '') if token =~ /^Bearer\s+/i
 
         token.empty? ? nil : token
       end
@@ -57,7 +57,7 @@ module Verikloak
       # @param token [String]
       # @return [String]
       def ensure_bearer(token)
-        s = token.to_s.strip
+        s = sanitize(token)
         # Case-insensitive 'Bearer' with spaces/tabs after
         if s =~ /\ABearer[ \t]+/i
           rest = s.sub(/\ABearer[ \t]+/i, '')
@@ -86,6 +86,14 @@ module Verikloak
         env[AUTH_HEADER] = ensure_bearer(token)
       end
 
+      # Remove CRLF and other control characters to prevent header injection.
+      #
+      # @param token [String]
+      # @return [String]
+      def sanitize(token)
+        token.to_s.gsub(/[[:cntrl:]]/, '').strip
+      end
+
       # Remove potentially forged X-Auth-Request-* headers before passing
       # downstream when not emitted by a trusted proxy.
       #

data/lib/verikloak/bff/header_guard.rb

@@ -11,16 +11,74 @@
 # headers against JWT claims, and normalizes the request into
 # `HTTP_AUTHORIZATION: Bearer <token>` for the downstream verifier.
 require 'rack'
+require 'rack/utils'
 require 'json'
 require 'jwt'
+require 'digest'
 require 'verikloak/bff/configuration'
 require 'verikloak/bff/errors'
 require 'verikloak/bff/proxy_trust'
 require 'verikloak/bff/forwarded_token'
 require 'verikloak/bff/consistency_checks'
+require 'verikloak/bff/constants'
 
 module Verikloak
   module BFF
+    # Internal helpers that sanitize tokens and log payloads for HeaderGuard.
+    module HeaderGuardSanitizer
+      LOG_CONTROL_CHARS = /[[:cntrl:]]/
+
+      module_function
+
+      def token_tags(token)
+        return {} unless token
+
+        payload, header = decode_unverified(token)
+        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)
+        }.compact
+      rescue StandardError
+        {}
+      end
+
+      def decode_unverified(token)
+        return [{}, {}] if token.nil? || token.bytesize > Constants::MAX_TOKEN_BYTES
+
+        JWT.decode(token, nil, false)
+      rescue StandardError
+        [{}, {}]
+      end
+
+      def sanitize_payload(payload)
+        payload.transform_values { |value| sanitize_log_field(value) }.compact
+      end
+
+      def sanitize_log_field(value)
+        case value
+        when nil
+          nil
+        when String
+          sanitized = sanitize_string(value)
+          sanitized.empty? ? nil : sanitized
+        when Array
+          sanitized = value.map { |item| item.is_a?(String) ? sanitize_string(item) : item }
+          sanitized.reject! { |item| item.nil? || (item.is_a?(String) && item.empty?) }
+          sanitized.empty? ? nil : sanitized
+        else
+          value
+        end
+      end
+
+      def sanitize_string(value)
+        value.to_s.encode('UTF-8', invalid: :replace, undef: :replace, replace: '').gsub(LOG_CONTROL_CHARS, '')
+      end
+    end
+
     # Rack middleware that enforces BFF boundary and header/claims consistency.
     class HeaderGuard
       # Accept both Rack 2 and Rack 3 builder call styles:
@@ -38,6 +96,10 @@ module Verikloak
         combined.merge!(opts) if opts.is_a?(Hash)
         combined.merge!(opts_kw) if opts_kw && !opts_kw.empty?
         apply_overrides!(combined)
+
+        return unless @config.trusted_proxies.nil? || @config.trusted_proxies.empty?
+
+        raise ArgumentError, 'trusted_proxies must be configured'
       end
 
       # Process a Rack request.
@@ -99,45 +161,6 @@ module Verikloak
         end
       end
 
-      # Extract selected JWT tags for audit logging (best-effort, unverified).
-      #
-      # @param token [String, nil]
-      # @return [Hash] subset of {sub, iss, aud, kid}
-      def token_tags(token)
-        return {} unless token
-
-        payload, header = decode_unverified(token)
-        {
-          sub: payload['sub'],
-          iss: payload['iss'],
-          aud: (payload['aud'].is_a?(Array) ? payload['aud'].join(' ') : payload['aud']).to_s,
-          kid: header['kid']
-        }.compact
-      rescue StandardError
-        {}
-      end
-
-      # Decode JWT header/payload without validation (for logging only).
-      #
-      # @param token [String]
-      # @return [Array(Hash, Hash)] [payload, header]
-      def decode_unverified(token)
-        parts = token.to_s.split('.')
-        return [{}, {}] unless parts.size >= 2
-
-        payload = begin
-          JSON.parse(::JWT::Base64.url_decode(parts[1]))
-        rescue StandardError
-          {}
-        end
-        header = begin
-          JSON.parse(::JWT::Base64.url_decode(parts[0]))
-        rescue StandardError
-          {}
-        end
-        [payload, header]
-      end
-
       # Extract request id for logging from common headers.
       #
       # @param env [Hash]
@@ -162,16 +185,17 @@ module Verikloak
       def log_event(env, kind, **attrs)
         lg = logger(env)
         payload = { event: 'bff.header_guard', kind: kind, rid: request_id(env) }.merge(attrs).compact
+        sanitized = HeaderGuardSanitizer.sanitize_payload(payload)
         if @config.log_with.respond_to?(:call)
           begin
-            @config.log_with.call(payload)
+            @config.log_with.call(sanitized)
           rescue StandardError
             # ignore log hook failures
           end
         end
         return unless lg
 
-        msg = payload.map { |k, v| v.nil? || v.to_s.empty? ? nil : "#{k}=#{v}" }.compact.join(' ')
+        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
@@ -203,7 +227,10 @@ module Verikloak
       def enforce_header_consistency!(env, auth_token, fwd_token)
         return unless @config.enforce_header_consistency
         return unless auth_token && fwd_token
-        return if auth_token == fwd_token
+
+        digest_a = ::Digest::SHA256.hexdigest(auth_token)
+        digest_b = ::Digest::SHA256.hexdigest(fwd_token)
+        return if Rack::Utils.secure_compare(digest_a, digest_b)
 
         log_event(env, :mismatch, reason: 'authorization_vs_forwarded')
         raise HeaderMismatchError
@@ -219,9 +246,21 @@ module Verikloak
 
         field = res.last
         log_event(env, :claims_mismatch, field: field.to_s)
+        return if claims_consistency_log_only?
+
         raise ClaimsMismatchError, field
       end
 
+      # Determine whether claims mismatches should only be logged.
+      #
+      # @return [Boolean]
+      def claims_consistency_log_only?
+        mode = @config.claims_consistency_mode || :enforce
+        mode = mode.to_sym if mode.is_a?(String)
+        mode = :enforce unless %i[enforce log_only].include?(mode)
+        mode == :log_only
+      end
+
       # Set normalized Authorization header and emit success log.
       #
       # @param env [Hash]
@@ -232,7 +271,7 @@ module Verikloak
         return unless chosen
 
         ForwardedToken.set_authorization!(env, chosen)
-        log_event(env, :ok, source: token_source(auth_token, fwd_token), **token_tags(chosen))
+        log_event(env, :ok, source: token_source(auth_token, fwd_token), **HeaderGuardSanitizer.token_tags(chosen))
       end
 
       # Build a minimal RFC6750-style error response.

data/lib/verikloak/bff/proxy_trust.rb

@@ -23,7 +23,7 @@ module Verikloak
       # @example CIDR + Regex allowlist
       #   ProxyTrust.trusted?(env, ["10.0.0.0/8", /^192\.168\./], :rightmost)
       def trusted?(env, trusted, strategy = :rightmost)
-        return true if trusted.nil? || trusted.empty?
+        return false if trusted.nil? || trusted.empty?
 
         # Rails-aligned: prefer REMOTE_ADDR; fallback to nearest XFF entry
         remote = (env['REMOTE_ADDR'] || '').to_s.strip
@@ -108,7 +108,7 @@ module Verikloak
       # @param trusted [Array<String, Regexp, Proc>, nil]
       # @return [Boolean]
       def self.from_trusted_proxy?(env, trusted)
-        return true if trusted.nil? || trusted.empty?
+        return false if trusted.nil? || trusted.empty?
 
         ip = (env['REMOTE_ADDR'] || '').to_s.strip
         ip = env['HTTP_X_FORWARDED_FOR'].to_s.split(',').last.to_s.strip if ip.empty? && env['HTTP_X_FORWARDED_FOR']

data/lib/verikloak/bff/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak-bff
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - taiyaky
@@ -13,16 +13,22 @@ 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'
 - !ruby/object:Gem::Dependency
   name: rack
   requirement: !ruby/object:Gem::Requirement
@@ -76,6 +82,7 @@ files:
 - lib/verikloak/bff.rb
 - lib/verikloak/bff/configuration.rb
 - lib/verikloak/bff/consistency_checks.rb
+- lib/verikloak/bff/constants.rb
 - lib/verikloak/bff/errors.rb
 - lib/verikloak/bff/forwarded_token.rb
 - lib/verikloak/bff/header_guard.rb
@@ -88,7 +95,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.1.0
+  documentation_uri: https://rubydoc.info/gems/verikloak-bff/0.1.2
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: