verikloak-bff 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9334e103b57c76a8723b73e30fd48f24e0eeb505a6b3d113ece410025b8f0f00
-  data.tar.gz: 9b6c0b661cc28b8061176c1c294f28d0e6577b4645bfc286db72ca952b9caf7f
+  metadata.gz: 7fc1c8dd0dd14c3ae72321e7265c572cd2c5437285325a5ab5ae2836205fc2e1
+  data.tar.gz: 51a5f52cf417750da1454bd0bf8ec8635cfa65b3df3b8ff634d7fe556b2b8498
 SHA512:
-  metadata.gz: 4c361c0afec931b6d5cbebfd76be1064362b4fb8eb7cb61d430029c6a10b9a42575973356657152f171ec15d9c0ad291a24db08006d9eb6bd503d791cbe2844a
-  data.tar.gz: f222b9c2718aead0b08ae8c1aaed235d62c880a046bf08c81a8f80cf9b6005435087d71262bcf53b7e115bdef0a7963c65a36a7c568c903daa2a96e91138fc29
+  metadata.gz: 92ff1528409857382e5530fc6de4c1f20d23deb8888a298b8f610c96cdb7ecf554545e3561ba0ffeada9001bc641fb8aea42f11b3eb595c85732136ff7e912ec
+  data.tar.gz: a6faf3c0282d56aa048d2176a213473d716fde00fedab97bd8d4a8fa1e4e811aea9f84d9e14ee6e9ac8a87a2f5f498cb9f1a66efe3c1bcb2882c29152b23d8f5

data/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.1.0] - 2026-07-03
+
+Verified against verikloak 1.1.0 (core) and verikloak-rails 1.2.0.
+
+### Fixed
+- **Empty Bearer Authorization**: `ForwardedToken.normalize_auth` now returns `nil` for a Bearer scheme without a token (e.g. `Authorization: Bearer`). Previously it returned an empty string, which caused a spurious `401 header_mismatch` when a valid forwarded token was present. `seed_authorization_if_needed` no longer re-inspects the raw `HTTP_AUTHORIZATION` value either, so a bare `Authorization: Bearer` no longer blocks seeding a valid token from `token_header_priority` headers
+- **Multi-line Authorization hardening**: `ForwardedToken.normalize_auth` is anchored with `\A`/`\z` (previously `^`/`$`) and only accepts space/tab between the scheme and token, so a multi-line value cannot smuggle a `Bearer <token>` line past a non-Bearer first line
+- **`peer_preference` honored in trust decisions**: `HeaderGuard` now passes the configured `peer_preference` (`:remote_then_xff` / `:xff_only`) to `ProxyTrust.trusted?`. Previously the preference only affected the `verikloak.bff.selected_peer` env hint and the trust decision always used `:remote_then_xff`, contradicting the documented behavior
+- **`peer_preference` fail-safe**: an unrecognized or `nil` `peer_preference` now resolves to the safe `REMOTE_ADDR`-first path instead of the client-controlled `X-Forwarded-For`, and `HeaderGuard` raises `ConfigurationError` at startup for an unrecognized value so a typo cannot silently weaken the trust decision
+- **Trusted proxy rule isolation**: a rule that raises (invalid CIDR string, failing Proc) no longer silently disables the remaining `trusted_proxies` rules; each rule is evaluated independently, and the failure is surfaced under `$DEBUG` instead of being swallowed without a trace
+- **Fail-fast IP/CIDR validation**: `HeaderGuard` raises `ConfigurationError` at startup when a `trusted_proxies` string cannot be parsed as an IP or CIDR (previously only CIDR strings containing `/` were checked, so a malformed plain IP such as `10.0.0.999` booted and then silently rejected every request)
+
+### Changed
+- Minimum `verikloak` dependency raised to `~> 1.1` (from `~> 1.0`), matching the coordinated 1.1.0 core / 1.2.0 verikloak-rails release; `verikloak-rails` 1.2.0 already requires `verikloak ~> 1.1`
+- **`Verikloak::BFF::Rails::Middleware.insert_before_core` added**: inserts HeaderGuard *before* `Verikloak::Middleware`, matching the documented stack order (`[HeaderGuard] → [Verikloak::Middleware] → [App]`) and the behavior of `verikloak-rails`
+- `ForwardedToken.strip_suspicious!` and `Configuration` now share the default `X-Auth-Request-*` header list via `Constants::DEFAULT_AUTH_REQUEST_HEADERS` (previously duplicated)
+- `HeaderGuard` no longer writes the `Authorization` header twice when seeding from `token_header_priority`; the header is written once during request finalization
+
+### Deprecated
+- **`Verikloak::BFF::Rails::Middleware.insert_after_core`**: deprecated in favor of `insert_before_core`. It now emits a deprecation warning and delegates to `insert_before_core`, because inserting HeaderGuard *after* the core middleware let core verification run on un-normalized tokens. The dead `auto_insert_enabled?` / `core_config` checks (which read a `Verikloak.config` that does not exist in the core gem — the real flag lives in `Verikloak::Rails.config`) were removed along the way
+
+### Removed
+- Internal helpers `HeaderGuardSanitizer.token_tags` and `HeaderGuardSanitizer.decode_unverified` (unused since token decoding was consolidated into `RequestTokens`; use `Verikloak::BFF::JwtUtils.decode_unverified` directly if needed)
+- `ProxyTrust.from_trusted_proxy?` (unused thin wrapper around `ProxyTrust.trusted?`; call `ProxyTrust.trusted?(env, trusted, :rightmost, preference: ...)` directly)
+
+---
+
 ## [1.0.0] - 2026-02-15
 
 ### Fixed

data/lib/verikloak/bff/configuration.rb

@@ -25,6 +25,7 @@
 #   @return [Logger, nil] optional logger for audit tags
 
 require 'verikloak/header_sources'
+require 'verikloak/bff/constants'
 
 module Verikloak
   module BFF
@@ -59,11 +60,7 @@ module Verikloak
         @logger = nil
         @log_with = nil
         self.forwarded_header_name = Verikloak::HeaderSources::DEFAULT_FORWARDED_HEADER
-        @auth_request_headers = {
-          email: 'HTTP_X_AUTH_REQUEST_EMAIL',
-          user: 'HTTP_X_AUTH_REQUEST_USER',
-          groups: 'HTTP_X_AUTH_REQUEST_GROUPS'
-        }
+        @auth_request_headers = Constants::DEFAULT_AUTH_REQUEST_HEADERS.dup
         # 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.
         self.token_header_priority = Verikloak::HeaderSources.default_priority(forwarded_header: @forwarded_header_name)

data/lib/verikloak/bff/constants.rb

@@ -16,6 +16,14 @@ module Verikloak
       # Maximum length for individual log field values to prevent log flooding
       # from oversized or malicious JWT claims.
       MAX_LOG_FIELD_LENGTH = 256
+
+      # Default X-Auth-Request-* env keys, shared by {Configuration} defaults
+      # and {ForwardedToken.strip_suspicious!} so both stay in sync.
+      DEFAULT_AUTH_REQUEST_HEADERS = {
+        email: 'HTTP_X_AUTH_REQUEST_EMAIL',
+        user: 'HTTP_X_AUTH_REQUEST_USER',
+        groups: 'HTTP_X_AUTH_REQUEST_GROUPS'
+      }.freeze
     end
   end
 end

data/lib/verikloak/bff/forwarded_token.rb

@@ -5,6 +5,7 @@
 # @see .extract
 
 require 'verikloak/header_sources'
+require 'verikloak/bff/constants'
 
 module Verikloak
   module BFF
@@ -28,17 +29,20 @@ module Verikloak
       end
 
       # Only accept Bearer scheme for Authorization header.
+      # A scheme without a token (e.g. "Bearer" or "Bearer ") is treated as
+      # absent so that an empty Authorization header never shadows a valid
+      # forwarded token.
+      #
+      # The pattern is anchored with \A/\z (not ^/$) so a multi-line value
+      # cannot smuggle a "Bearer <token>" line past a non-Bearer first line,
+      # and only space/tab may separate the scheme from the token.
       #
       # @param raw [String, nil]
-      # @return [String, nil] token or nil when not Bearer
+      # @return [String, nil] token or nil when not Bearer or token is empty
       def normalize_auth(raw)
         return nil unless raw
 
-        token = raw.to_s.strip
-        return ::Regexp.last_match(1) if token =~ /^Bearer\s+(.+)$/i
-        return token[6..] if token =~ /^Bearer(?!\s)/i
-
-        nil
+        raw.to_s.strip[/\ABearer[ \t]*(.+)\z/i, 1]
       end
 
       # Accept either bare token or Bearer for forwarded header.
@@ -105,13 +109,8 @@ module Verikloak
       # @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) }
-          return
-        end
-        env.delete('HTTP_X_AUTH_REQUEST_EMAIL')
-        env.delete('HTTP_X_AUTH_REQUEST_USER')
-        env.delete('HTTP_X_AUTH_REQUEST_GROUPS')
+        headers = Constants::DEFAULT_AUTH_REQUEST_HEADERS unless headers.is_a?(Hash)
+        headers.each_value { |h| env.delete(h) }
       end
     end
   end

data/lib/verikloak/bff/header_guard.rb

@@ -32,21 +32,6 @@ module Verikloak
 
       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)
-        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.
       #
@@ -69,15 +54,6 @@ module Verikloak
         {}
       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)
-        Verikloak::BFF::JwtUtils.decode_unverified(token)
-      end
-
       # Remove unsafe characters from a structured logging payload.
       #
       # @param payload [Hash]
@@ -212,6 +188,9 @@ module Verikloak
       # Error raised when trusted_proxies is not configured and disabled is not explicitly set.
       class ConfigurationError < StandardError; end
 
+      # Recognized values for the `peer_preference` setting.
+      VALID_PEER_PREFERENCES = %i[remote_then_xff xff_only].freeze
+
       RequestTokens = Struct.new(:auth, :forwarded, :chosen, :decoded_payload, :decoded_header)
 
       # Accept both Rack 2 and Rack 3 builder call styles:
@@ -277,8 +256,10 @@ module Verikloak
 
       private
 
-      # Validate that required configuration is present.
-      # Raises ConfigurationError if trusted_proxies is not configured and disabled is false.
+      # Validate that required configuration is present and well-formed.
+      # Raises ConfigurationError if trusted_proxies is not configured and disabled is false,
+      # when an IP/CIDR rule cannot be parsed, or when peer_preference is unrecognized
+      # (fail-fast instead of silently rejecting every request at runtime).
       #
       # @raise [ConfigurationError]
       # @return [void]
@@ -286,12 +267,53 @@ module Verikloak
         return if @config.disabled
 
         proxies = @config.trusted_proxies
-        return unless proxies.nil? || proxies.empty?
+        if proxies.nil? || proxies.empty?
+          raise ConfigurationError,
+                'trusted_proxies must be configured for Verikloak::BFF::HeaderGuard. ' \
+                'Set trusted_proxies to an array of allowed proxy addresses/CIDRs, ' \
+                'or set disabled: true to explicitly skip BFF protection.'
+        end
+
+        validate_trusted_proxy_rules!(proxies)
+        validate_peer_preference!
+      end
+
+      # Fail fast on unparsable IP/CIDR strings in trusted_proxies. Both plain
+      # IPs (exact-match rules) and CIDRs are checked, since a malformed plain
+      # IP would otherwise boot successfully and silently reject every request.
+      # Parsing is delegated to ProxyTrust.ip_or_nil so validation and runtime
+      # matching stay in lockstep.
+      #
+      # @param proxies [Array<String, Regexp, Proc>]
+      # @raise [ConfigurationError]
+      # @return [void]
+      def validate_trusted_proxy_rules!(proxies)
+        proxies.each do |rule|
+          next unless rule.is_a?(String)
+          next if ProxyTrust.ip_or_nil(rule)
+
+          kind = rule.include?('/') ? 'CIDR' : 'IP'
+          raise ConfigurationError,
+                "invalid #{kind} rule in trusted_proxies: #{rule.inspect}. " \
+                'Fix the rule so that proxy trust checks can match it.'
+        end
+      end
+
+      # Fail fast on an unrecognized peer_preference so a typo cannot silently
+      # change which peer the trust decision is based on (ProxyTrust treats any
+      # non-:xff_only value as the safe REMOTE_ADDR-first path, which would mask
+      # an intended :xff_only that was misspelled).
+      #
+      # @raise [ConfigurationError]
+      # @return [void]
+      def validate_peer_preference!
+        pref = @config.peer_preference
+        return if pref.nil?
+        return if VALID_PEER_PREFERENCES.include?(pref.to_s.to_sym)
 
         raise ConfigurationError,
-              'trusted_proxies must be configured for Verikloak::BFF::HeaderGuard. ' \
-              'Set trusted_proxies to an array of allowed proxy addresses/CIDRs, ' \
-              'or set disabled: true to explicitly skip BFF protection.'
+              "invalid peer_preference: #{pref.inspect}. " \
+              'Expected :remote_then_xff or :xff_only (or nil for the default).'
       end
 
       # Build token state by extracting, validating, and selecting the active token.
@@ -361,11 +383,14 @@ module Verikloak
       end
 
       # Raise when the request did not come through a trusted proxy.
+      # Honors the configured peer_preference (:remote_then_xff or :xff_only)
+      # when selecting the peer used for the trust decision.
       #
       # @param env [Hash]
       # @raise [UntrustedProxyError]
       def ensure_trusted_proxy!(env)
-        return if ProxyTrust.trusted?(env, @config.trusted_proxies, @config.xff_strategy)
+        return if ProxyTrust.trusted?(env, @config.trusted_proxies, @config.xff_strategy,
+                                      preference: @config.peer_preference)
 
         raise UntrustedProxyError
       end
@@ -444,35 +469,35 @@ module Verikloak
       end
 
       # 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.
+      # HTTP_AUTHORIZATION is never a source. Proxy trust is already guaranteed
+      # by stage 1 ({#ensure_trusted_proxy!}) before this is reached.
       #
       # @param env [Hash]
       # @return [String, nil]
       def resolve_first_token_header(env)
-        candidates = Array(@config.token_header_priority).dup
-        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 = Array(@config.token_header_priority) - [Verikloak::HeaderSources::AUTHORIZATION_HEADER]
         candidates.find { |k| (v = env[k]) && !v.to_s.empty? }
       end
 
-      # Seed Authorization from priority headers if nothing chosen and empty Authorization.
+      # Seed the chosen token from priority headers when no usable token was
+      # chosen. `chosen` is nil only when Authorization held no valid Bearer
+      # token (normalize_auth already treats a bare "Bearer" as absent) and no
+      # forwarded token was present, so inspecting the raw Authorization header
+      # here would re-introduce the empty-Bearer shadowing bug. The Authorization
+      # header itself is written once later by {#normalize_authorization!} from
+      # the chosen token.
       #
       # @param env [Hash]
       # @param chosen [String, nil]
       # @return [String, nil] possibly updated chosen token
       def seed_authorization_if_needed(env, chosen)
-        return chosen unless chosen.nil? && env['HTTP_AUTHORIZATION'].to_s.empty?
+        return chosen unless chosen.nil?
         return chosen unless Array(@config.token_header_priority).any?
 
         seeded = resolve_first_token_header(env)
-        if seeded
-          ForwardedToken.set_authorization!(env, env[seeded])
-          return ForwardedToken.normalize_forwarded(env[seeded]) || env[seeded].to_s
-        end
-        chosen
+        return chosen unless seeded
+
+        ForwardedToken.normalize_forwarded(env[seeded]) || env[seeded].to_s
       end
 
       # Expose hints to downstream middleware or apps.

data/lib/verikloak/bff/proxy_trust.rb

@@ -19,11 +19,13 @@ module Verikloak
       #   - Regexp: matched against the selected peer IP
       #   - Proc: called as `->(ip, env) { ... }` and returns truthy when trusted
       # @param strategy [Symbol, String] `:rightmost` (default) or `:leftmost` for XFF parsing
+      # @param preference [Symbol] `:remote_then_xff` (default) prefers REMOTE_ADDR,
+      #   `:xff_only` selects the peer from X-Forwarded-For first
       # @return [Boolean] true if the selected peer is trusted
       # @example CIDR + Regex allowlist
       #   ProxyTrust.trusted?(env, ["10.0.0.0/8", /^192\.168\./], :rightmost)
-      def trusted?(env, trusted, strategy = :rightmost)
-        remote = resolve_peer(env, :remote_then_xff, strategy)
+      def trusted?(env, trusted, strategy = :rightmost, preference: :remote_then_xff)
+        remote = resolve_peer(env, preference, strategy)
         trusted_remote?(remote, trusted, env)
       end
 
@@ -68,6 +70,9 @@ module Verikloak
       end
 
       # Check whether a single rule trusts the selected remote.
+      # A rule that raises (e.g. an invalid CIDR string or a failing Proc) is
+      # treated as non-matching so that one bad rule cannot disable the rest
+      # of the allowlist.
       #
       # @param rule [String, Regexp, Proc]
       # @param remote [String]
@@ -90,31 +95,33 @@ module Verikloak
         else
           false
         end
-      end
-
-      # 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]
-      def self.from_trusted_proxy?(env, trusted)
-        trusted?(env, trusted, :rightmost)
+      rescue StandardError => e
+        # Isolate a single failing rule without disabling the rest of the
+        # allowlist, but surface it under $DEBUG so a broken Proc/CIDR rule is
+        # observable instead of silently denying trust.
+        warn("[verikloak-bff] trusted_proxies rule raised and was skipped: #{e.class}: #{e.message}") if $DEBUG
+        false
       end
 
       # Resolve the peer value based on preference and strategy.
       #
+      # Only `:xff_only` selects the peer from X-Forwarded-For first. Every other
+      # value — the `:remote_then_xff` default, `nil`, or an unrecognized/typo'd
+      # preference — falls back to the safe REMOTE_ADDR-first path so a
+      # misconfiguration can never switch the trust decision onto the
+      # client-controlled X-Forwarded-For header.
+      #
       # @param env [Hash]
       # @param preference [Symbol]
       # @param strategy [Symbol]
       # @return [String, nil]
       def resolve_peer(env, preference, strategy)
-        case preference.to_s.to_sym
-        when :remote_then_xff
-          remote = (env['REMOTE_ADDR'] || '').to_s.strip
-          return remote unless remote.empty?
-          # Fall back to X-Forwarded-For when REMOTE_ADDR is empty
-        end
+        return extract_peer_ip(env, strategy) if preference.to_s.to_sym == :xff_only
+
+        remote = (env['REMOTE_ADDR'] || '').to_s.strip
+        return remote unless remote.empty?
+
+        # Fall back to X-Forwarded-For when REMOTE_ADDR is empty
         extract_peer_ip(env, strategy)
       end
 

data/lib/verikloak/bff/rails.rb

@@ -6,9 +6,14 @@ module Verikloak
     module Rails
       # Middleware management utilities for Rails applications.
       #
-      # This module focuses on inserting the HeaderGuard middleware right after
-      # the core Verikloak middleware while gracefully handling stacks that do
-      # not contain the core component.
+      # This module focuses on inserting the HeaderGuard middleware right before
+      # the core Verikloak middleware (so tokens are normalized before core
+      # verification) while gracefully handling stacks that do not contain the
+      # core component.
+      #
+      # NOTE: When `verikloak-rails` is installed, middleware insertion happens
+      # automatically via its railtie — these helpers are only needed for manual
+      # (non verikloak-rails) setups.
       module Middleware
         module_function
 
@@ -17,12 +22,17 @@ module Verikloak
         SKIP_MESSAGE = <<~MSG.chomp.freeze
           [verikloak-bff] Skipping Verikloak::BFF::HeaderGuard insertion because Verikloak::Middleware is not present. Configure verikloak-rails discovery settings and restart once core verification is enabled.
         MSG
+        DEPRECATION_MESSAGE = <<~MSG.chomp.freeze
+          [verikloak-bff] Verikloak::BFF::Rails::Middleware.insert_after_core is deprecated and will be removed in a future release. Use insert_before_core instead — HeaderGuard must run before Verikloak::Middleware so that tokens are normalized prior to verification. insert_after_core now delegates to insert_before_core.
+        MSG
 
-        # Inserts Verikloak::BFF::HeaderGuard middleware after Verikloak::Middleware
+        # Inserts Verikloak::BFF::HeaderGuard middleware before Verikloak::Middleware
         #
         # Attempts to insert the HeaderGuard middleware into the Rails middleware stack
-        # after the core Verikloak::Middleware. If the core middleware is not present,
-        # logs a warning and gracefully skips the insertion.
+        # before the core Verikloak::Middleware, matching the documented stack order:
+        #   [Verikloak::BFF::HeaderGuard] → [Verikloak::Middleware] → [Your App]
+        # If the core middleware is not present, logs a warning and gracefully skips
+        # the insertion.
         #
         # @param stack [ActionDispatch::MiddlewareStack] Rails middleware stack
         # @param logger [Logger, nil] Optional logger for warning messages
@@ -30,13 +40,11 @@ module Verikloak
         # @raise [RuntimeError] Re-raises non-middleware-related runtime errors
         #
         # @example Inserting middleware in Rails configuration
-        #   Verikloak::BFF::Rails::Middleware.insert_after_core(
+        #   Verikloak::BFF::Rails::Middleware.insert_before_core(
         #     Rails.application.config.middleware,
         #     logger: Rails.logger
         #   )
-        def insert_after_core(stack, logger: nil)
-          return false unless auto_insert_enabled?
-
+        def insert_before_core(stack, logger: nil)
           core = core_middleware
           header_guard = header_guard_middleware
 
@@ -45,7 +53,7 @@ module Verikloak
             return false
           end
 
-          stack.insert_after(core, header_guard)
+          stack.insert_before(core, header_guard)
           true
         rescue RuntimeError => e
           raise unless missing_core?(e)
@@ -54,35 +62,18 @@ module Verikloak
           false
         end
 
-        # Determine whether automatic insertion is enabled via Verikloak core configuration.
-        #
-        # When the core gem exposes +auto_insert_bff_header_guard+, respect that flag so
-        # consumers can opt out of automatic middleware wiring without triggering warnings.
-        # Any failures while reading configuration default to enabling insertion in order
-        # to preserve the previous behavior.
+        # @deprecated Use {.insert_before_core} instead. The previous behavior
+        #   (inserting HeaderGuard *after* the core middleware) contradicted the
+        #   documented stack order and let core verification see un-normalized
+        #   tokens. This method now delegates to {.insert_before_core} and emits
+        #   a deprecation warning.
         #
-        # @return [Boolean]
-        def auto_insert_enabled?
-          config = core_config
-          return true unless config
-
-          return config.auto_insert_bff_header_guard if config.respond_to?(:auto_insert_bff_header_guard)
-
-          true
-        rescue StandardError
-          true
-        end
-
-        # Returns the Verikloak configuration object when available.
-        #
-        # @return [Object, nil]
-        def core_config
-          return nil unless defined?(::Verikloak)
-          return nil unless ::Verikloak.respond_to?(:config)
-
-          ::Verikloak.config
-        rescue StandardError
-          nil
+        # @param stack [ActionDispatch::MiddlewareStack] Rails middleware stack
+        # @param logger [Logger, nil] Optional logger for warning messages
+        # @return [Boolean] true if insertion succeeded, false if skipped
+        def insert_after_core(stack, logger: nil)
+          logger ? logger.warn(DEPRECATION_MESSAGE) : warn(DEPRECATION_MESSAGE)
+          insert_before_core(stack, logger: logger)
         end
 
         # Detect whether the Verikloak core middleware is already present in the stack.
@@ -132,17 +123,10 @@ module Verikloak
         # Checks if the error indicates missing core Verikloak middleware
         #
         # Examines a RuntimeError to determine if it was caused by attempting
-        # to insert middleware after a non-existent Verikloak::Middleware.
+        # to insert middleware relative to a non-existent Verikloak::Middleware.
         #
         # @param error [RuntimeError] The error to examine
         # @return [Boolean] true if error indicates missing Verikloak::Middleware
-        #
-        # @example Checking for missing middleware error
-        #   begin
-        #     stack.insert_after(::Verikloak::Middleware, SomeMiddleware)
-        #   rescue RuntimeError => e
-        #     puts "Missing core!" if missing_core?(e)
-        #   end
         def missing_core?(error)
           error.message.include?('No such middleware') &&
             error.message.include?(CORE_NAME)
@@ -155,12 +139,6 @@ module Verikloak
         # Uses the provided logger if available, otherwise falls back to warn().
         #
         # @param logger [Logger, nil] Optional logger instance for structured logging
-        #
-        # @example Logging with Rails logger
-        #   log_skip(Rails.logger)
-        #
-        # @example Logging without logger (uses warn)
-        #   log_skip(nil)
         def log_skip(logger)
           logger ? logger.warn(SKIP_MESSAGE) : warn(SKIP_MESSAGE)
         end

data/lib/verikloak/bff/version.rb

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

data/lib/verikloak/header_sources.rb

@@ -1,8 +1,11 @@
 # 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.
+# names and token source priority lists.
+#
+# NOTE: This file lives under the shared `Verikloak::` namespace but is
+# currently shipped by verikloak-bff only. Moving it into the core `verikloak`
+# gem is planned so that sibling gems can share it without load-path conflicts.
 module Verikloak
   # Provides normalization helpers for Rack env header keys and token priority lists.
   module HeaderSources

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak-bff
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - taiyaky
@@ -55,14 +55,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.1'
 description: Framework-agnostic Rack middleware that normalizes forwarded tokens,
   enforces trust boundaries, and checks header/claims consistency before verikloak.
 executables: []
@@ -95,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/1.0.0
+  documentation_uri: https://rubydoc.info/gems/verikloak-bff/1.1.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: