verikloak-bff 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19452cfc021fd5ffde923f55f294aafb99c4b80506047d0ef195233d019c5adb
-  data.tar.gz: 3211ddb4779f6bbe1b079f6c83b018bb5b7b881bb267d253f94ffaaa20006711
+  metadata.gz: 91439a22efdb87206de07fbff74c284cba33a05cb1c7392070c0b9f7c837734f
+  data.tar.gz: be08bb99047e72502cad67dbea7c41b916aef6d49fb103e3dbf53ab79082f6db
 SHA512:
-  metadata.gz: '0890fcfe4ac2af3ce8bdbc34ee0753744a3a56459a90da3441247a7d36779b28db68ae7998b349968f5ecfd937121d3fad96e2f21a092662da2cbedeb61a358c'
-  data.tar.gz: 7a4e7888b2f2caafc0bd1345760d3ef5e049f860cc9f36dba028c2a2afebaf8625719b6b0dbad9f7a21c01db957368b5d10d73c3533f19ce8fdc9acb4513e3f0
+  metadata.gz: 135054bc3b1556597924c843a834d87c46c291da4d880ed63ef611cafb9705984694062f64d25a08f8d3f932f304cfb7277c4d25f25dfb3f35ad3d83f0768e47
+  data.tar.gz: 3358b1f9f3114e9a00a7d4edd283e5b2c81dd6166ec1a5718a581f5f83a7c1cf75d27f300da01d5dc25763f4569a50be2393203130c5a67adb00ffb1a42fc1d9

data/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.2.0] - 2025-09-22
+
+### Added
+- `Verikloak::HeaderSources` module for shared header normalization (consumable by verikloak-rails and other adapters).
+
+### Changed
+- `Configuration#token_header_priority=` now normalizes and deduplicates entries, reusing the shared helper and ignoring `HTTP_AUTHORIZATION` automatically.
+- `forwarded_header_name` assignments trigger re-normalization of token priority lists to keep middleware aligned across gems.
+
+## [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

data/README.md

@@ -47,12 +47,13 @@ See `examples/rack.ru` for a tiny Rack app demo.
 | `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]                        | `['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. |
+| `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. Values are normalized via `Verikloak::HeaderSources`; `HTTP_AUTHORIZATION` is ignored as a source. |
 | `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'`
@@ -78,12 +82,16 @@ For full reverse proxy examples (Nginx auth_request / oauth2-proxy), see [docs/r
 - Authorization seeding from priority headers
   - When no token is chosen and `HTTP_AUTHORIZATION` is empty, the middleware consults `token_header_priority` to seed Authorization.
   - `HTTP_AUTHORIZATION` itself is never used as a source; forwarded headers are considered only from trusted peers.
+  - Other gems can `require 'verikloak/header_sources'` to reuse the same normalization helpers when sharing configuration defaults.
 
 - 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

@@ -22,6 +22,8 @@
 # @!attribute [rw] logger
 #   @return [Logger, nil] optional logger for audit tags
 
+require 'verikloak/header_sources'
+
 module Verikloak
   module BFF
     # Configuration for Verikloak::BFF middleware (trusted proxies, header policies, logging, etc.).
@@ -29,24 +31,31 @@ module Verikloak
       attr_accessor :trusted_proxies, :prefer_forwarded, :require_forwarded_header,
                     :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
+                    :logger, :peer_preference, :auth_request_headers, :log_with,
+                    :claims_consistency_mode
+      attr_reader :token_header_priority, :forwarded_header_name
 
       # enforce_claims_consistency example:
       # { email: :email, user: :sub, groups: :realm_roles }
+      #
+      # Initialize configuration with secure defaults for proxy trust, token
+      # handling, and logging behavior.
+      #
+      # @return [void]
       def initialize
         @trusted_proxies = []
         @prefer_forwarded = true
         @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
         @clock_skew_leeway = 30
         @logger = nil
         @log_with = nil
-        @forwarded_header_name = 'HTTP_X_FORWARDED_ACCESS_TOKEN'
+        self.forwarded_header_name = Verikloak::HeaderSources::DEFAULT_FORWARDED_HEADER
         @auth_request_headers = {
           email: 'HTTP_X_AUTH_REQUEST_EMAIL',
           user: 'HTTP_X_AUTH_REQUEST_USER',
@@ -54,9 +63,37 @@ module Verikloak
         }
         # 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 always ignored as a source.
-        @token_header_priority = %w[
-          HTTP_X_FORWARDED_ACCESS_TOKEN
-        ]
+        self.token_header_priority = Verikloak::HeaderSources.default_priority(forwarded_header: @forwarded_header_name)
+      end
+
+      # Override forwarded header name while re-normalizing the token priority list.
+      # When the forwarded header changes, downstream priority normalization must
+      # be refreshed because the forwarded value participates in that list.
+      #
+      # @param header [String, Symbol]
+      # @return [void]
+      def forwarded_header_name=(header)
+        @forwarded_header_name = Verikloak::HeaderSources.normalize_env_key(header)
+        renormalize_token_priority!
+      end
+
+      # Assign token header priority list using shared normalization logic.
+      #
+      # @param priority [Array<String, Symbol>, String, Symbol, nil]
+      # @return [void]
+      def token_header_priority=(priority)
+        normalized, = Verikloak::HeaderSources.normalize_priority(priority, forwarded_header: @forwarded_header_name)
+        @token_header_priority = normalized
+      end
+
+      private
+
+      # Re-apply token header normalization so it reflects the current forwarded header.
+      #
+      # @return [void]
+      def renormalize_token_priority!
+        # Refresh the normalized list so it reflects the new forwarded header name.
+        self.token_header_priority = @token_header_priority
       end
     end
   end

data/lib/verikloak/bff/consistency_checks.rb

@@ -15,12 +15,11 @@ module Verikloak
     module ConsistencyChecks
       module_function
 
-      # Parse JWT payload without verifying (verikloak core will verify later).
-      # Decode JWT payload without verification.
+      # Decode the JWT payload without verifying the signature. Intended only
+      # for lightweight claim comparisons; full verification occurs downstream.
       #
       # @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
@@ -36,6 +35,7 @@ module Verikloak
       # @param env [Hash]
       # @param token [String, nil]
       # @param mapping [Hash] e.g., { email: :email, user: :sub, groups: :realm_roles }
+      # @param headers_map [Hash{Symbol=>String}, nil] overrides for header keys
       # @return [true, Array(:error, Symbol)] true or error tuple with failing field
       def enforce!(env, token, mapping, headers_map = nil)
         return true if mapping.nil? || mapping.empty?
@@ -63,6 +63,7 @@ module Verikloak
       #
       # @param env [Hash]
       # @param key [Symbol]
+      # @param headers_map [Hash{Symbol=>String}, nil]
       # @return [String, nil]
       def extract_header_value(env, key, headers_map = nil)
         return env[headers_map[key]] if headers_map && headers_map[key]

data/lib/verikloak/bff/errors.rb

@@ -12,6 +12,12 @@ module Verikloak
     class Error < StandardError
       attr_reader :code, :http_status
 
+      # Build a BFF error with a stable code and HTTP status.
+      #
+      # @param message [String, nil]
+      # @param code [String]
+      # @param http_status [Integer]
+      # @return [void]
       def initialize(message = nil, code: 'bff_error', http_status: 401)
         super(message || code)
         @code = code
@@ -21,6 +27,8 @@ module Verikloak
 
     # Raised when a request did not pass through a trusted proxy peer.
     class UntrustedProxyError < Error
+      # @param msg [String]
+      # @return [void]
       def initialize(msg = 'request did not pass through a trusted proxy')
         super(msg, code: 'untrusted_proxy', http_status: 401)
       end
@@ -28,6 +36,8 @@ module Verikloak
 
     # Raised when require_forwarded_header is enabled but the forwarded token is absent.
     class MissingForwardedTokenError < Error
+      # @param msg [String]
+      # @return [void]
       def initialize(msg = 'missing X-Forwarded-Access-Token')
         super(msg, code: 'missing_forwarded_token', http_status: 401)
       end
@@ -35,6 +45,8 @@ module Verikloak
 
     # Raised when Authorization and X-Forwarded-Access-Token both exist and differ.
     class HeaderMismatchError < Error
+      # @param msg [String]
+      # @return [void]
       def initialize(msg = 'authorization and forwarded token mismatch')
         super(msg, code: 'header_mismatch', http_status: 401)
       end
@@ -42,6 +54,9 @@ module Verikloak
 
     # Raised when X-Auth-Request-* headers conflict with JWT claims.
     class ClaimsMismatchError < Error
+      # @param field [Symbol, String]
+      # @param msg [String, nil]
+      # @return [void]
       def initialize(field, msg = nil)
         super(msg || "claims/header mismatch for #{field}", code: 'claims_mismatch', http_status: 403)
       end

data/lib/verikloak/bff/forwarded_token.rb

@@ -16,6 +16,8 @@ module Verikloak
       # Extract normalized tokens from the Rack env.
       #
       # @param env [Hash]
+      # @param forwarded_header_name [String] Rack env key for forwarded header
+      # @param auth_header_name [String] Rack env key for Authorization header
       # @return [Array(String, String)] [auth_token, forwarded_token]
       def extract(env, forwarded_header_name = FORWARDED_HEADER, auth_header_name = AUTH_HEADER)
         fwd_raw = env[forwarded_header_name]
@@ -54,6 +56,7 @@ module Verikloak
       # - Detects scheme case-insensitively
       # - Inserts a missing space (e.g., 'BearerXYZ' => 'Bearer XYZ')
       # - Collapses multiple spaces/tabs after the scheme to a single space
+      #
       # @param token [String]
       # @return [String]
       def ensure_bearer(token)
@@ -78,6 +81,7 @@ module Verikloak
       #
       # @param env [Hash]
       # @param token [String]
+      # @return [void]
       def set_authorization!(env, token)
         existing = env[AUTH_HEADER].to_s
         # Overwrite only if Authorization is empty or not a valid Bearer value
@@ -98,6 +102,8 @@ module Verikloak
       # downstream when not emitted by a trusted proxy.
       #
       # @param env [Hash]
+      # @param headers [Hash{Symbol=>String}, nil] explicit headers to strip
+      # @return [void]
       def strip_suspicious!(env, headers = nil)
         if headers.is_a?(Hash)
           headers.each_value { |h| env.delete(h) }

data/lib/verikloak/bff/header_guard.rb

@@ -15,6 +15,7 @@ require 'rack/utils'
 require 'json'
 require 'jwt'
 require 'digest'
+require 'verikloak/header_sources'
 require 'verikloak/bff/configuration'
 require 'verikloak/bff/errors'
 require 'verikloak/bff/proxy_trust'
@@ -24,6 +25,83 @@ 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
+
+      # Generate sanitized token metadata suitable for structured logging without
+      # verifying the signature.
+      #
+      # @param token [String, nil]
+      # @return [Hash{Symbol=>Object}] sanitized tags keyed by JWT claim/header
+      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
+
+      # Decode a JWT without verifying the signature while guarding against
+      # excessively large tokens.
+      #
+      # @param token [String, nil]
+      # @return [Array<Hash>] payload and header hashes
+      def decode_unverified(token)
+        return [{}, {}] if token.nil? || token.bytesize > Constants::MAX_TOKEN_BYTES
+
+        JWT.decode(token, nil, false)
+      rescue StandardError
+        [{}, {}]
+      end
+
+      # Remove unsafe characters from a structured logging payload.
+      #
+      # @param payload [Hash]
+      # @return [Hash] sanitized payload suitable for logging
+      def sanitize_payload(payload)
+        payload.transform_values { |value| sanitize_log_field(value) }.compact
+      end
+
+      # Sanitize an individual value destined for logs, pruning empty results.
+      #
+      # @param value [Object]
+      # @return [Object, nil] sanitized value or nil when the result is empty
+      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
+
+      # Remove control characters and invalid UTF-8 from a string.
+      #
+      # @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, '')
+      end
+    end
+
     # Rack middleware that enforces BFF boundary and header/claims consistency.
     class HeaderGuard
       # Accept both Rack 2 and Rack 3 builder call styles:
@@ -73,6 +151,7 @@ module Verikloak
       # Apply per-instance configuration overrides.
       #
       # @param opts [Hash]
+      # @return [void]
       def apply_overrides!(opts)
         cfg = @config
         opts.each do |k, v|
@@ -106,37 +185,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)
-        return [{}, {}] if token.nil? || token.bytesize > Constants::MAX_TOKEN_BYTES
-
-        JWT.decode(token, nil, false)
-      rescue StandardError
-        [{}, {}]
-      end
-
       # Extract request id for logging from common headers.
       #
       # @param env [Hash]
@@ -158,19 +206,21 @@ module Verikloak
       # @param env [Hash]
       # @param kind [Symbol] :ok, :mismatch, :claims_mismatch, :error
       # @param attrs [Hash]
+      # @return [void]
       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
@@ -180,6 +230,7 @@ module Verikloak
       # Raise when the request did not come through a trusted proxy.
       #
       # @param env [Hash]
+      # @raise [UntrustedProxyError]
       def ensure_trusted_proxy!(env)
         return if ProxyTrust.trusted?(env, @config.trusted_proxies, @config.xff_strategy)
 
@@ -189,6 +240,7 @@ module Verikloak
       # Enforce presence of forwarded token when required.
       #
       # @param fwd_token [String, nil]
+      # @raise [MissingForwardedTokenError]
       def ensure_forwarded_if_required!(fwd_token)
         return unless @config.require_forwarded_header
         raise MissingForwardedTokenError if fwd_token.nil? || fwd_token.to_s.strip.empty?
@@ -199,6 +251,7 @@ module Verikloak
       # @param env [Hash]
       # @param auth_token [String, nil]
       # @param fwd_token [String, nil]
+      # @raise [HeaderMismatchError]
       def enforce_header_consistency!(env, auth_token, fwd_token)
         return unless @config.enforce_header_consistency
         return unless auth_token && fwd_token
@@ -215,26 +268,41 @@ module Verikloak
       #
       # @param env [Hash]
       # @param chosen [String, nil]
+      # @return [void]
+      # @raise [ClaimsMismatchError]
       def enforce_claims_consistency!(env, chosen)
         res = ConsistencyChecks.enforce!(env, chosen, @config.enforce_claims_consistency, @config.auth_request_headers)
         return unless res.is_a?(Array) && res.first == :error
 
         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]
       # @param chosen [String, nil]
       # @param auth_token [String, nil]
       # @param fwd_token [String, nil]
+      # @return [void]
       def normalize_authorization!(env, chosen, auth_token, fwd_token)
         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.
@@ -252,19 +320,21 @@ module Verikloak
 
       # Resolve the first env header from which to source a bearer token.
       # Forwarded is considered only when the peer is trusted; HTTP_AUTHORIZATION is never a source.
+      #
       # @param env [Hash]
       # @return [String, nil]
       def resolve_first_token_header(env)
         candidates = Array(@config.token_header_priority).dup
-        candidates -= ['HTTP_AUTHORIZATION']
-        fwd_key = 'HTTP_X_FORWARDED_ACCESS_TOKEN'
+        candidates -= [Verikloak::HeaderSources::AUTHORIZATION_HEADER]
+        fwd_key = @config.forwarded_header_name || Verikloak::HeaderSources::DEFAULT_FORWARDED_HEADER
         if candidates.include?(fwd_key) && !ProxyTrust.from_trusted_proxy?(env, @config.trusted_proxies)
           candidates -= [fwd_key]
         end
         candidates.find { |k| (v = env[k]) && !v.to_s.empty? }
       end
 
-      # Seed Authorization from priority headers if nothing chosen and empty Authorization
+      # Seed Authorization from priority headers if nothing chosen and empty Authorization.
+      #
       # @param env [Hash]
       # @param chosen [String, nil]
       # @return [String, nil] possibly updated chosen token
@@ -280,9 +350,11 @@ module Verikloak
         chosen
       end
 
-      # Expose hints to downstream
+      # Expose hints to downstream middleware or apps.
+      #
       # @param env [Hash]
       # @param chosen [String, nil]
+      # @return [void]
       def expose_env_hints(env, chosen)
         env['verikloak.bff.token'] = chosen if chosen
         env['verikloak.bff.selected_peer'] =

data/lib/verikloak/bff/proxy_trust.rb

@@ -53,6 +53,7 @@ module Verikloak
       end
 
       # Return the selected peer IP according to preference and strategy.
+      #
       # @param env [Hash]
       # @param preference [Symbol] :remote_then_xff or :xff_only
       # @param strategy [Symbol] :rightmost or :leftmost
@@ -70,6 +71,7 @@ module Verikloak
       end
 
       # Parse string to IPAddr or nil on failure.
+      #
       # @param str [String]
       # @return [IPAddr, nil]
       def ip_or_nil(str)
@@ -79,6 +81,7 @@ module Verikloak
       end
 
       # Check whether a single rule trusts the selected remote.
+      #
       # @param rule [String, Regexp, Proc]
       # @param remote [String]
       # @param remote_ip [IPAddr, nil]
@@ -104,6 +107,7 @@ module Verikloak
 
       # Determine if the request originates from a trusted proxy subnet.
       # Rails-aligned behavior: prefer REMOTE_ADDR, fallback to nearest (rightmost) X-Forwarded-For.
+      #
       # @param env [Hash]
       # @param trusted [Array<String, Regexp, Proc>, nil]
       # @return [Boolean]

data/lib/verikloak/bff/version.rb

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

data/lib/verikloak/header_sources.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# Helpers shared across verikloak middleware for normalizing Rack env header
+# names and token source priority lists. Extracted to allow other gems (such as
+# verikloak-rails) to consume the same normalization logic.
+module Verikloak
+  # Provides normalization helpers for Rack env header keys and token priority lists.
+  module HeaderSources
+    module_function
+
+    DEFAULT_FORWARDED_HEADER = 'HTTP_X_FORWARDED_ACCESS_TOKEN'
+    AUTHORIZATION_HEADER     = 'HTTP_AUTHORIZATION'
+
+    # Normalize a Rack env header key, accepting symbols, mixed case, or dash
+    # separated names and returning an upper-case HTTP_* variant.
+    #
+    # @param header [String, Symbol, nil]
+    # @return [String] normalized env key or empty string when blank
+    def normalize_env_key(header)
+      key = header.to_s.strip
+      return '' if key.empty?
+
+      key = key.tr('-', '_').upcase
+      key = "HTTP_#{key}" unless key.start_with?('HTTP_')
+      key
+    end
+
+    # Normalize a token priority list by stripping blanks, rejecting
+    # Authorization as a source, and deduplicating entries while preserving
+    # order.
+    #
+    # @param priority [Array<String, Symbol>, String, Symbol, nil]
+    # @param forwarded_header [String, Symbol]
+    # @param drop_authorization [Boolean]
+    # @return [Array(Array<String>, String)] normalized priority and forwarded key
+    def normalize_priority(priority, forwarded_header: DEFAULT_FORWARDED_HEADER, drop_authorization: true)
+      forwarded_env = normalize_env_key(forwarded_header)
+      items = Array(priority).flatten
+
+      normalized = items.map { |value| normalize_env_key(value) }.reject(&:empty?)
+      normalized = [forwarded_env] if normalized.empty?
+      normalized = normalized.reject { |key| drop_authorization && key == AUTHORIZATION_HEADER }
+
+      deduped = []
+      normalized.each do |key|
+        deduped << key unless deduped.include?(key)
+      end
+
+      [deduped.freeze, forwarded_env]
+    end
+
+    # Default priority list using the provided forwarded header name.
+    #
+    # @param forwarded_header [String, Symbol]
+    # @return [Array<String>] normalized default priority
+    def default_priority(forwarded_header: DEFAULT_FORWARDED_HEADER)
+      normalize_priority([forwarded_header], forwarded_header: forwarded_header).first
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak-bff
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - taiyaky
@@ -55,20 +55,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.2
+        version: 0.1.5
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: 1.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.2
+        version: 0.1.5
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: 1.0.0
 description: Framework-agnostic Rack middleware that normalizes forwarded tokens,
   enforces trust boundaries, and checks header/claims consistency before verikloak.
 executables: []
@@ -88,6 +88,7 @@ files:
 - lib/verikloak/bff/header_guard.rb
 - lib/verikloak/bff/proxy_trust.rb
 - lib/verikloak/bff/version.rb
+- lib/verikloak/header_sources.rb
 homepage: https://github.com/taiyaky/verikloak-bff
 licenses:
 - MIT
@@ -95,7 +96,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.1
+  documentation_uri: https://rubydoc.info/gems/verikloak-bff/0.2.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: