verikloak-bff 0.2.3 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e2d5b0966fddd564dcd1b6e48fb871f3239542204176f0291f4249f5770b713
-  data.tar.gz: c1f1c43a58c7428263757d2f051c3f988921d84b30fc5fbdc8995f0c5d55ef4c
+  metadata.gz: b024a1e87d9a4cd895b0e052ba276cbf418b50d4f51b3f642d3916e7b713253e
+  data.tar.gz: 82bab8741e03c8b1f57bea89856b8811440c34778470c18a82c87c279a36c4a4
 SHA512:
-  metadata.gz: a4c8c80a0fccd793d93b2ef98374fd0bca253d5a36ff4d690dbd67de622bebd92ad27ef141d3c65c56ddd8c1934b9e9818a51eb3ef0a40b780ad0bc491263503
-  data.tar.gz: 339f5c58833ebb8ef19b511725c3f540e7506f097032235852088e0594dc917702723f8084f1abbdfd050b41f738486665d1c8b93891fb9fc7293c31d6e0483d
+  metadata.gz: c2e1f2587d253acd2ac1f3a26b33d701adbe7cce48a6646f95658bd503e5238033bd855ab39fe23dc8ebb85af5bbb449b6170acba6e5bb840e8878afcd9e9d79
+  data.tar.gz: ecf08756e3af68c6d199ff54e40f10aee69a0a5c62d49cde1c5b1bd732dc319510490131e9a0ea357c82b67af7710ba7bd4a7303549b842b7a78fcddba86ad49

data/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.2.5] - 2025-09-28
+
+### Changed
+- Align the install generator under `Verikloak::Bff::Generators` while retaining the `Verikloak::BFF::Generators` alias to avoid constant redefinition warnings during reloads.
+
+
+## [0.2.4] - 2025-09-27
+
+### Changed
+- Simplify BFF install generator by inlining configuration lookups and removing unnecessary helper methods.
+- Streamline generated initializer to use `Rails.configuration.middleware` and `Rails.logger` directly.
+- Extract JWT decoding logic into shared `JwtUtils` module to eliminate duplication between `HeaderGuard` and `ConsistencyChecks`.
+- Refactor `HeaderGuard#call` into clear pipeline stages with improved documentation.
+- Enhance middleware stack detection to handle wrapped entries, string names, and complex objects.
+- Remove duplicate proxy trust logic in `ProxyTrust` module by unifying `from_trusted_proxy?` and `trusted?` methods.
+
+### Fixed
+- Resolve RuboCop style violations including useless constant scoping and identical conditional branches.
+
 ## [0.2.3] - 2025-09-23
 
 ### Changed

data/lib/generators/verikloak/bff/install/install_generator.rb

@@ -1,57 +1,41 @@
 # frozen_string_literal: true
 
-require 'rails/generators/base'
+require 'rails/generators'
 
 module Verikloak
-  module BFF
-    # Namespace for Rails generators related to Verikloak BFF
+  module Bff
+    # Rails generators supporting verikloak-bff integration.
     module Generators
-      # Rails generator for installing Verikloak BFF middleware integration.
-      #
-      # This generator creates a Rails initializer that safely inserts the
-      # Verikloak::BFF::HeaderGuard middleware into the Rails middleware stack.
-      # It replaces automatic middleware insertion to avoid boot failures when
-      # core Verikloak middleware is not yet configured.
-      #
-      # @example Basic usage
-      #   rails g verikloak:bff:install
-      #
-      # @example Custom initializer path
-      #   rails g verikloak:bff:install --initializer=config/initializers/custom_bff.rb
+      # Generator to install the Verikloak BFF initializer into a Rails app.
       #
       # @see Verikloak::BFF::Rails::Middleware
+      # @example Default usage
+      #   rails g verikloak:bff:install
       class InstallGenerator < ::Rails::Generators::Base
         source_root File.expand_path('templates', __dir__)
+        desc 'Creates the Verikloak BFF initializer for Rails applications.'
 
-        # Configuration option for specifying the initializer file path.
-        #
         # @option options [String] :initializer ('config/initializers/verikloak_bff.rb')
-        #   The path where the initializer file will be created
+        #   Path for the generated initializer file.
         class_option :initializer, type: :string,
                                    default: 'config/initializers/verikloak_bff.rb',
                                    desc: 'Path for the generated initializer'
 
-        # Creates the Rails initializer file from template.
-        #
-        # Generates a Rails initializer that safely inserts the HeaderGuard
-        # middleware into the middleware stack with proper error handling.
-        # The initializer uses Verikloak::BFF::Rails::Middleware.insert_after_core
-        # to ensure graceful handling when core middleware is missing.
+        # Copies the initializer template to the desired location.
         #
         # @return [void]
         def create_initializer
-          template 'initializer.rb.tt', initializer_path
-        end
-
-        private
-
-        # Returns the path where the initializer should be created.
-        #
-        # @return [String] The initializer file path from options
-        def initializer_path
-          options[:initializer]
+          template 'initializer.rb.erb', options.fetch(:initializer)
         end
       end
     end
   end
 end
+
+# Maintain legacy constant path for consumers referencing Verikloak::BFF::Generators.
+module Verikloak
+  # Legacy namespace alias for backward compatibility.
+  module BFF
+    Generators = Bff::Generators unless defined?(Generators)
+  end
+end

data/lib/generators/verikloak/bff/install/templates/initializer.rb.erb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Configure verikloak-bff to insert its HeaderGuard middleware only after the
+# Verikloak core middleware is present. This avoids boot errors when the core
+# gem has not yet been installed.
+Rails.application.config.after_initialize do
+  Verikloak::BFF::Rails::Middleware.insert_after_core(
+    Rails.application.config.middleware,
+    logger: Rails.logger
+  )
+end

data/lib/verikloak/bff/consistency_checks.rb

@@ -6,8 +6,8 @@
 # @see .enforce!
 
 require 'json'
-require 'jwt' # used only to parse segments safely without verify
 require 'verikloak/bff/constants'
+require 'verikloak/bff/jwt_utils'
 
 module Verikloak
   module BFF
@@ -21,12 +21,7 @@ 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
-
-        JWT.decode(token, nil, false).first
-      rescue StandardError
-        {}
+        Verikloak::BFF::JwtUtils.decode_claims(token)
       end
 
       # mapping: { email: :email, user: :sub, groups: :realm_roles }

data/lib/verikloak/bff/header_guard.rb

@@ -13,7 +13,6 @@
 require 'rack'
 require 'rack/utils'
 require 'json'
-require 'jwt'
 require 'digest'
 require 'verikloak/header_sources'
 require 'verikloak/bff/configuration'
@@ -22,6 +21,7 @@ require 'verikloak/bff/proxy_trust'
 require 'verikloak/bff/forwarded_token'
 require 'verikloak/bff/consistency_checks'
 require 'verikloak/bff/constants'
+require 'verikloak/bff/jwt_utils'
 
 module Verikloak
   module BFF
@@ -58,11 +58,7 @@ module Verikloak
       # @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
-        [{}, {}]
+        Verikloak::BFF::JwtUtils.decode_unverified(token)
       end
 
       # Remove unsafe characters from a structured logging payload.
@@ -104,6 +100,8 @@ module Verikloak
 
     # Rack middleware that enforces BFF boundary and header/claims consistency.
     class HeaderGuard
+      RequestTokens = Struct.new(:auth, :forwarded, :chosen)
+
       # Accept both Rack 2 and Rack 3 builder call styles:
       # - new(app, key: val)
       # - new(app, { key: val })
@@ -125,22 +123,29 @@ module Verikloak
         raise ArgumentError, 'trusted_proxies must be configured'
       end
 
-      # Process a Rack request.
+      # Process a Rack request through the BFF header guard pipeline.
+      #
+      # Pipeline stages:
+      # 1. Proxy trust validation
+      # 2. Token extraction and state building
+      # 3. Policy enforcement (forwarded token requirements, consistency checks)
+      # 4. Request finalization (Authorization header normalization)
       #
       # @param env [Hash]
       # @return [Array(Integer, Hash, Array<#to_s>)] Rack response triple
       def call(env)
+        # Stage 1: Validate request comes from trusted proxy
         ensure_trusted_proxy!(env)
-        auth_token, fwd_token = ForwardedToken.extract(env, @config.forwarded_header_name)
-        ensure_forwarded_if_required!(fwd_token)
-        chosen = choose_token(auth_token, fwd_token)
-        chosen = seed_authorization_if_needed(env, chosen)
 
-        enforce_header_consistency!(env, auth_token, fwd_token)
-        enforce_claims_consistency!(env, chosen)
-        ForwardedToken.strip_suspicious!(env, @config.auth_request_headers) if @config.strip_suspicious_headers
-        normalize_authorization!(env, chosen, auth_token, fwd_token)
-        expose_env_hints(env, chosen)
+        # Stage 2: Extract and validate tokens, build request state
+        tokens = build_token_state(env)
+
+        # Stage 3: Enforce configured policies (forwarded requirements, consistency)
+        enforce_token_policies!(env, tokens)
+
+        # Stage 4: Finalize request with normalized Authorization header
+        finalize_request!(env, tokens)
+
         @app.call(env)
       rescue Verikloak::BFF::Error => e
         respond_with_error(env, e)
@@ -148,6 +153,41 @@ module Verikloak
 
       private
 
+      # Build token state by extracting, validating, and selecting the active token.
+      #
+      # @param env [Hash]
+      # @return [RequestTokens]
+      def build_token_state(env)
+        auth_token, fwd_token = ForwardedToken.extract(env, @config.forwarded_header_name)
+        ensure_forwarded_if_required!(fwd_token)
+
+        chosen = choose_token(auth_token, fwd_token)
+        chosen = seed_authorization_if_needed(env, chosen)
+
+        RequestTokens.new(auth_token, fwd_token, chosen)
+      end
+
+      # Apply header and claim consistency policies for the current request.
+      #
+      # @param env [Hash]
+      # @param tokens [RequestTokens]
+      # @return [void]
+      def enforce_token_policies!(env, tokens)
+        enforce_header_consistency!(env, tokens.auth, tokens.forwarded)
+        enforce_claims_consistency!(env, tokens.chosen)
+      end
+
+      # Mutate the Rack env with normalized headers and logging hints.
+      #
+      # @param env [Hash]
+      # @param tokens [RequestTokens]
+      # @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)
+        expose_env_hints(env, tokens.chosen)
+      end
+
       # Apply per-instance configuration overrides.
       #
       # @param opts [Hash]

data/lib/verikloak/bff/jwt_utils.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'jwt'
+require 'verikloak/bff/constants'
+
+module Verikloak
+  module BFF
+    # Lightweight helpers around JWT decoding without verification.
+    module JwtUtils
+      module_function
+
+      # Decode JWT header and payload without verification, guarding against oversized input.
+      #
+      # @param token [String, nil]
+      # @return [Array<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
+
+      # Return the decoded JWT payload without verification.
+      #
+      # @param token [String, nil]
+      # @return [Hash]
+      def decode_claims(token)
+        decode_unverified(token).first
+      end
+    end
+  end
+end

data/lib/verikloak/bff/proxy_trust.rb

@@ -23,17 +23,8 @@ module Verikloak
       # @example CIDR + Regex allowlist
       #   ProxyTrust.trusted?(env, ["10.0.0.0/8", /^192\.168\./], :rightmost)
       def trusted?(env, trusted, strategy = :rightmost)
-        return false if trusted.nil? || trusted.empty?
-
-        # Rails-aligned: prefer REMOTE_ADDR; fallback to nearest XFF entry
-        remote = (env['REMOTE_ADDR'] || '').to_s.strip
-        remote = extract_peer_ip(env, strategy) if remote.empty?
-        return false unless remote
-
-        remote_ip = ip_or_nil(remote)
-        trusted.any? { |rule| rule_trusts?(rule, remote, remote_ip, env) }
-      rescue StandardError
-        false
+        remote = resolve_peer(env, :remote_then_xff, strategy)
+        trusted_remote?(remote, trusted, env)
       end
 
       # Select the peer IP from X-Forwarded-For according to strategy or fall back to REMOTE_ADDR.
@@ -59,15 +50,7 @@ module Verikloak
       # @param strategy [Symbol] :rightmost or :leftmost
       # @return [String, nil]
       def selected_peer(env, preference, strategy)
-        case preference.to_s.to_sym
-        when :remote_then_xff
-          ip = (env['REMOTE_ADDR'] || '').to_s.strip
-          return ip unless ip.nil? || ip.empty?
-
-          extract_peer_ip(env, :rightmost) # nearest by default
-        else
-          extract_peer_ip(env, strategy)
-        end
+        resolve_peer(env, preference, strategy)
       end
 
       # Parse string to IPAddr or nil on failure.
@@ -112,16 +95,37 @@ module Verikloak
       # @param trusted [Array<String, Regexp, Proc>, nil]
       # @return [Boolean]
       def self.from_trusted_proxy?(env, trusted)
-        return false if trusted.nil? || trusted.empty?
+        trusted?(env, trusted, :rightmost)
+      end
 
-        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']
-        return false if ip.empty?
+      # Resolve the peer value based on preference and strategy.
+      #
+      # @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
+        extract_peer_ip(env, strategy)
+      end
 
-        remote_ip = ip_or_nil(ip)
-        return false unless remote_ip
+      # Determine whether a remote peer appears in the trusted list.
+      #
+      # @param remote [String, nil]
+      # @param trusted [Array<String, Regexp, Proc>, nil]
+      # @param env [Hash]
+      # @return [Boolean]
+      def trusted_remote?(remote, trusted, env)
+        return false if trusted.nil? || trusted.empty?
+        return false unless remote
 
-        trusted.any? { |rule| rule_trusts?(rule, ip, remote_ip, env) }
+        remote_ip = ip_or_nil(remote)
+        trusted.any? { |rule| rule_trusts?(rule, remote, remote_ip, env) }
       rescue StandardError
         false
       end

data/lib/verikloak/bff/rails.rb

@@ -4,14 +4,20 @@ module Verikloak
   module BFF
     # Rails-specific functionality for Verikloak BFF
     module Rails
-      # Middleware management utilities for Rails applications
+      # Middleware management utilities for Rails applications.
       #
-      # This module provides functionality to insert Verikloak BFF middleware
-      # into Rails middleware stack, with proper error handling for cases where
-      # the core Verikloak middleware is not present.
+      # 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.
       module Middleware
         module_function
 
+        CORE_NAME = 'Verikloak::Middleware'
+        HEADER_GUARD_NAME = 'Verikloak::BFF::HeaderGuard'
+        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
+
         # Inserts Verikloak::BFF::HeaderGuard middleware after Verikloak::Middleware
         #
         # Attempts to insert the HeaderGuard middleware into the Rails middleware stack
@@ -31,12 +37,15 @@ module Verikloak
         def insert_after_core(stack, logger: nil)
           return false unless auto_insert_enabled?
 
-          unless core_present?(stack)
+          core = core_middleware
+          header_guard = header_guard_middleware
+
+          unless stack && core && header_guard && core_present?(stack, core)
             log_skip(logger)
             return false
           end
 
-          stack.insert_after(::Verikloak::Middleware, ::Verikloak::BFF::HeaderGuard)
+          stack.insert_after(core, header_guard)
           true
         rescue RuntimeError => e
           raise unless missing_core?(e)
@@ -54,11 +63,9 @@ module Verikloak
         #
         # @return [Boolean]
         def auto_insert_enabled?
-          return true unless defined?(::Verikloak)
-          return true unless ::Verikloak.respond_to?(:config)
-
-          config = ::Verikloak.config
+          config = core_config
           return true unless config
+
           return config.auto_insert_bff_header_guard if config.respond_to?(:auto_insert_bff_header_guard)
 
           true
@@ -66,56 +73,60 @@ module Verikloak
           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
+        end
+
         # Detect whether the Verikloak core middleware is already present in the stack.
         #
         # @param stack [#include?, #each, nil]
         # @return [Boolean]
-        def core_present?(stack)
+        def core_present?(stack, core = core_middleware)
           return false unless stack
 
-          if stack.respond_to?(:include?)
-            begin
-              return true if stack.include?(::Verikloak::Middleware)
-            rescue StandardError
-              # Fall back to manual enumeration when include? is unsupported for this stack
-            end
+          begin
+            return true if core && stack.respond_to?(:include?) && stack.include?(core)
+          rescue StandardError
+            # Fall back to manual enumeration when include? is unsupported for this stack.
           end
 
           return false unless stack.respond_to?(:each)
 
-          stack.each do |middleware|
-            return true if middleware_matches_core?(middleware)
+          stack.each do |entry|
+            candidate = unwrap_middleware(entry)
+            return true if core && candidate == core
+            return true if middleware_name(candidate) == CORE_NAME
           end
 
           false
         end
 
-        # Check whether a middleware entry represents the Verikloak core middleware.
+        # Normalize raw stack entries to a comparable object.
         #
-        # @param middleware [Object]
-        # @return [Boolean]
-        def middleware_matches_core?(middleware)
-          candidate = middleware.is_a?(Array) ? middleware.first : middleware
-
-          klass = extract_middleware_class(candidate)
-
-          klass == ::Verikloak::Middleware ||
-            (klass.is_a?(String) && klass == 'Verikloak::Middleware') ||
-            (klass.respond_to?(:name) && klass.name == 'Verikloak::Middleware')
+        # @param entry [Object]
+        # @return [Object]
+        def unwrap_middleware(entry)
+          entry = entry.first if entry.is_a?(Array)
+          entry.respond_to?(:klass) ? entry.klass : entry
         end
 
-        # Extracts the class or class-like identifier from a middleware candidate.
-        #
-        # @param candidate [Object]
-        # @return [Class, String, Object]
-        def extract_middleware_class(candidate)
-          if candidate.respond_to?(:klass)
-            candidate.klass
-          elsif candidate.respond_to?(:name)
-            candidate.name
-          else
-            candidate
-          end
+        # Resolve a human-readable middleware name if possible.
+        #
+        # @param entry [Object]
+        # @return [String, nil]
+        def middleware_name(entry)
+          return entry if entry.is_a?(String)
+          return entry.to_s if entry.is_a?(Symbol)
+
+          entry.respond_to?(:name) ? entry.name : nil
         end
 
         # Checks if the error indicates missing core Verikloak middleware
@@ -134,7 +145,7 @@ module Verikloak
         #   end
         def missing_core?(error)
           error.message.include?('No such middleware') &&
-            error.message.include?('Verikloak::Middleware')
+            error.message.include?(CORE_NAME)
         end
 
         # Logs a warning message about skipping middleware insertion
@@ -151,11 +162,31 @@ module Verikloak
         # @example Logging without logger (uses warn)
         #   log_skip(nil)
         def log_skip(logger)
-          message = <<~MSG.chomp
-            [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
+          logger ? logger.warn(SKIP_MESSAGE) : warn(SKIP_MESSAGE)
+        end
 
-          logger ? logger.warn(message) : warn(message)
+        # Safely resolves the core middleware constant when available.
+        #
+        # @return [Class, nil]
+        def core_middleware
+          safe_const_get(CORE_NAME)
+        end
+
+        # Safely resolves the HeaderGuard middleware constant when available.
+        #
+        # @return [Class, nil]
+        def header_guard_middleware
+          safe_const_get(HEADER_GUARD_NAME)
+        end
+
+        # Attempts to constantize the provided class name, returning nil when undefined.
+        #
+        # @param name [String]
+        # @return [Module, Class, nil]
+        def safe_const_get(name)
+          Object.const_get(name)
+        rescue NameError
+          nil
         end
       end
     end

data/lib/verikloak/bff/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak-bff
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.5
 platform: ruby
 authors:
 - taiyaky
@@ -79,6 +79,7 @@ files:
 - LICENSE
 - README.md
 - lib/generators/verikloak/bff/install/install_generator.rb
+- lib/generators/verikloak/bff/install/templates/initializer.rb.erb
 - lib/verikloak-bff.rb
 - lib/verikloak/bff.rb
 - lib/verikloak/bff/configuration.rb
@@ -87,6 +88,7 @@ files:
 - lib/verikloak/bff/errors.rb
 - lib/verikloak/bff/forwarded_token.rb
 - lib/verikloak/bff/header_guard.rb
+- lib/verikloak/bff/jwt_utils.rb
 - lib/verikloak/bff/proxy_trust.rb
 - lib/verikloak/bff/rails.rb
 - lib/verikloak/bff/railtie.rb
@@ -99,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.2.3
+  documentation_uri: https://rubydoc.info/gems/verikloak-bff/0.2.5
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: