verikloak-rails 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7bac28bdf7982aa61a3512e8af5f213c550dd68556af1e96e0654a8033d8d0d
-  data.tar.gz: 926fe82895004cb6ee2dcc4c55fe3138dc879e08ef59bf94a31a6b634c379348
+  metadata.gz: f473cac2688d575650e3c483eac520fcb910ca7a9fd3c08620337386a705ca27
+  data.tar.gz: d76e49d03d27b336e6c8727f0cf3b82bb783bbe5153051be4ad4d0c1af5cfe7f
 SHA512:
-  metadata.gz: dc7cf3ca6c356a17d28744402b22b0e2118ab8ec0c33a2e230b34613db8b935ccae635fe11094916ae2a58bb255523162eccd1c93bb57f39498f977343a30348
-  data.tar.gz: ea2d296e2845db7d01b128ee573865279e89544b1068c0fd05d302e1f6618c62d6bf051c91fbf6eb05f629aa9ab224a86353c623f76114a962bedf321bb58e66
+  metadata.gz: 6326a2ca5a86a50898ebe00094139733e3295203ec050e9c471093c1d3b21f2d161251d6ecf97ce265267718e83b570f1b9d8d82b9288855f732b557d22ac5a4
+  data.tar.gz: 874c03abffe2470e4993b64e0afdcbe42f1b1f27e8b4bbd17aa457445deffce591907a46a62f0be24801786f3e339bfd43fd89deb3d2239defcd3ad37c8410ca

data/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.3.2] - 2026-01-01
+
+### Changed
+- **BFF HeaderGuard safe insertion**: Railtie now validates BFF configuration before inserting `HeaderGuard`. If `trusted_proxies` is not configured (and `disabled` is not set to `true`), insertion is skipped with a warning instead of raising an error.
+  - This allows applications to start during initial setup before BFF configuration is complete.
+  - A clear warning message guides users to configure `trusted_proxies` to enable header validation.
+  - When `disabled: true` is set, HeaderGuard is inserted but internally disabled.
+- **Railtie refactoring**: Extracted BFF configuration logic into `BffConfigurator` module and logging utilities into `RailtieLogger` module to improve maintainability.
+
+### Added
+- `BffConfigurator` module for BFF-related middleware configuration.
+- `RailtieLogger` module for consistent logging across Railtie operations.
+- Comprehensive test coverage for `BffConfigurator.configuration_valid?` method.
+
+---
+
 ## [0.3.1] - 2026-01-01
 
 ### Added

data/lib/verikloak/rails/bff_configurator.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Verikloak
+  module Rails
+    # Handles BFF (Backend-for-Frontend) middleware configuration.
+    # Extracted from Railtie to maintain class size limits.
+    module BffConfigurator
+      module_function
+
+      # Insert the optional HeaderGuard middleware when verikloak-bff is present.
+      # Skips insertion with a warning if trusted_proxies is not configured and
+      # disabled is not explicitly set to true.
+      #
+      # @param stack [ActionDispatch::MiddlewareStackProxy]
+      # @return [void]
+      def configure_bff_guard(stack)
+        return unless Verikloak::Rails.config.auto_insert_bff_header_guard
+        return unless defined?(::Verikloak::BFF::HeaderGuard)
+
+        unless configuration_valid?
+          RailtieLogger.warn(
+            '[verikloak] Skipping BFF::HeaderGuard insertion: trusted_proxies not configured. ' \
+            'Set trusted_proxies in bff_header_guard_options to enable header validation.'
+          )
+          return
+        end
+
+        insert_header_guard(stack)
+      end
+
+      # Configure the verikloak-bff library when options are supplied.
+      #
+      # @return [void]
+      def configure_library
+        options = Verikloak::Rails.config.bff_header_guard_options
+        return if options.nil? || (options.respond_to?(:empty?) && options.empty?)
+        return unless defined?(::Verikloak::BFF) && ::Verikloak::BFF.respond_to?(:configure)
+
+        apply_configuration(::Verikloak::BFF, options)
+      rescue StandardError => e
+        RailtieLogger.warn("[verikloak] Failed to apply BFF configuration: #{e.message}")
+      end
+
+      # Check if BFF configuration is valid for middleware insertion.
+      # Returns true if:
+      #   - disabled: true is set (HeaderGuard will be inserted but internally disabled), OR
+      #   - trusted_proxies is configured with at least one entry
+      #
+      # @return [Boolean]
+      def configuration_valid?
+        return true unless defined?(::Verikloak::BFF)
+        return true unless ::Verikloak::BFF.respond_to?(:config)
+
+        bff_config = ::Verikloak::BFF.config
+
+        # If disabled is explicitly set to true, allow insertion
+        # (HeaderGuard will be inserted but internally disabled)
+        return true if bff_config.respond_to?(:disabled) && bff_config.disabled
+
+        # For legacy versions without trusted_proxies method, allow insertion
+        return true unless bff_config.respond_to?(:trusted_proxies)
+
+        # Require trusted_proxies to be a non-empty Array
+        proxies = bff_config.trusted_proxies
+        proxies.is_a?(Array) && !proxies.empty?
+      end
+
+      # Insert HeaderGuard middleware into the stack.
+      #
+      # @param stack [ActionDispatch::MiddlewareStackProxy]
+      # @return [void]
+      def insert_header_guard(stack)
+        guard_before = Verikloak::Rails.config.bff_header_guard_insert_before
+        guard_after = Verikloak::Rails.config.bff_header_guard_insert_after
+
+        if guard_before
+          stack.insert_before guard_before, ::Verikloak::BFF::HeaderGuard
+        elsif guard_after
+          stack.insert_after guard_after, ::Verikloak::BFF::HeaderGuard
+        else
+          stack.insert_before ::Verikloak::Middleware, ::Verikloak::BFF::HeaderGuard
+        end
+      end
+
+      # Apply configuration options to the verikloak-bff namespace.
+      # Supports hash-like and callable inputs.
+      #
+      # @param target [Module] Verikloak::BFF namespace
+      # @param options [Hash, Proc, #to_h]
+      # @return [void]
+      def apply_configuration(target, options)
+        if options.respond_to?(:call)
+          target.configure(&options)
+          return
+        end
+
+        hash = options.respond_to?(:to_h) ? options.to_h : options
+        return unless hash.respond_to?(:each)
+
+        entries = hash.transform_keys(&:to_sym)
+        return if entries.empty?
+
+        target.configure do |config|
+          entries.each do |key, value|
+            writer = "#{key}="
+            config.public_send(writer, value) if config.respond_to?(writer)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/verikloak/rails/railtie.rb

@@ -2,6 +2,8 @@
 
 require 'rails/railtie'
 require 'verikloak/middleware'
+require_relative 'railtie_logger'
+require_relative 'bff_configurator'
 
 module Verikloak
   module Rails
@@ -53,7 +55,7 @@ module Verikloak
         # @return [ActionDispatch::MiddlewareStackProxy] configured middleware stack
         def configure_middleware(app)
           apply_configuration(app)
-          configure_bff_library
+          BffConfigurator.configure_library
 
           unless discovery_url_present?
             log_missing_discovery_url_warning
@@ -61,55 +63,31 @@ module Verikloak
           end
 
           stack = insert_base_middleware(app)
-          configure_bff_guard(stack) if stack
+          BffConfigurator.configure_bff_guard(stack) if stack
 
           stack
         end
 
-        # Insert the optional HeaderGuard middleware when verikloak-bff is present.
+        # Check if discovery_url is present and valid.
         #
-        # @param stack [ActionDispatch::MiddlewareStackProxy]
-        # @return [void]
-        def configure_bff_guard(stack)
-          return unless Verikloak::Rails.config.auto_insert_bff_header_guard
-          return unless defined?(::Verikloak::BFF::HeaderGuard)
+        # @return [Boolean] true if discovery_url is configured and not empty
+        def discovery_url_present?
+          discovery_url = Verikloak::Rails.config.discovery_url
+          return false unless discovery_url
 
-          guard_before = Verikloak::Rails.config.bff_header_guard_insert_before
-          guard_after = Verikloak::Rails.config.bff_header_guard_insert_after
-          if guard_before
-            stack.insert_before guard_before, ::Verikloak::BFF::HeaderGuard
-          elsif guard_after
-            stack.insert_after guard_after, ::Verikloak::BFF::HeaderGuard
-          else
-            stack.insert_before ::Verikloak::Middleware, ::Verikloak::BFF::HeaderGuard
-          end
+          return !discovery_url.blank? if discovery_url.respond_to?(:blank?)
+          return !discovery_url.empty? if discovery_url.respond_to?(:empty?)
+
+          true
         end
 
-        # Apply configuration options to the verikloak-bff namespace.
-        # Supports hash-like and callable inputs.
+        # Log a warning message when discovery_url is missing.
+        # Uses Rails.logger if available, falls back to warn.
         #
-        # @param target [Module] Verikloak::BFF or Verikloak::Bff namespace
-        # @param options [Hash, Proc, #to_h]
         # @return [void]
-        def apply_bff_configuration(target, options)
-          if options.respond_to?(:call)
-            target.configure(&options)
-            return
-          end
-
-          hash = options.respond_to?(:to_h) ? options.to_h : options
-          return unless hash.respond_to?(:each)
-
-          entries = hash.transform_keys(&:to_sym)
-
-          return if entries.empty?
-
-          target.configure do |config|
-            entries.each do |key, value|
-              writer = "#{key}="
-              config.public_send(writer, value) if config.respond_to?(writer)
-            end
-          end
+        def log_missing_discovery_url_warning
+          message = '[verikloak] discovery_url is not configured; skipping middleware insertion.'
+          RailtieLogger.warn(message)
         end
 
         # Sync configuration from the Rails application into Verikloak::Rails.
@@ -126,41 +104,6 @@ module Verikloak
           end
         end
 
-        # Configure the verikloak-bff library when options are supplied.
-        #
-        # @return [void]
-        def configure_bff_library
-          options = Verikloak::Rails.config.bff_header_guard_options
-          return if options.nil? || (options.respond_to?(:empty?) && options.empty?)
-          return unless defined?(::Verikloak::BFF) && ::Verikloak::BFF.respond_to?(:configure)
-
-          apply_bff_configuration(::Verikloak::BFF, options)
-        rescue StandardError => e
-          warn_with_fallback("[verikloak] Failed to apply BFF configuration: #{e.message}")
-        end
-
-        # Check if discovery_url is present and valid.
-        #
-        # @return [Boolean] true if discovery_url is configured and not empty
-        def discovery_url_present?
-          discovery_url = Verikloak::Rails.config.discovery_url
-          return false unless discovery_url
-
-          return !discovery_url.blank? if discovery_url.respond_to?(:blank?)
-          return !discovery_url.empty? if discovery_url.respond_to?(:empty?)
-
-          true
-        end
-
-        # Log a warning message when discovery_url is missing.
-        # Uses Rails.logger if available, falls back to warn.
-        #
-        # @return [void]
-        def log_missing_discovery_url_warning
-          message = '[verikloak] discovery_url is not configured; skipping middleware insertion.'
-          warn_with_fallback(message)
-        end
-
         # Insert the base Verikloak::Middleware into the application middleware stack.
         # Respects the configured insertion point (before or after specified middleware).
         #
@@ -243,26 +186,7 @@ module Verikloak
         def log_middleware_insertion_warning(candidate, error)
           candidate_name = candidate.is_a?(Class) ? candidate.name : candidate.class.name
           message = "[verikloak] Unable to insert after #{candidate_name}: #{error.message}"
-          warn_with_fallback(message)
-        end
-
-        # Resolve the logger instance used for warnings, if present.
-        # @return [Object, nil]
-        def rails_logger
-          return unless defined?(::Rails) && ::Rails.respond_to?(:logger)
-
-          ::Rails.logger
-        end
-
-        # Log a warning using Rails.logger when available, otherwise fall back to Kernel#warn.
-        # @param message [String]
-        # @return [void]
-        def warn_with_fallback(message)
-          if (logger = rails_logger)
-            logger.warn(message)
-          else
-            warn(message)
-          end
+          RailtieLogger.warn(message)
         end
       end
     end

data/lib/verikloak/rails/railtie_logger.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Verikloak
+  module Rails
+    # Logging utilities for Railtie operations.
+    # Provides consistent warning output across Rails versions.
+    module RailtieLogger
+      module_function
+
+      # Log a warning using Rails.logger when available, otherwise fall back to Kernel#warn.
+      # @param message [String]
+      # @return [void]
+      def warn(message)
+        if (logger = rails_logger)
+          logger.warn(message)
+        else
+          Kernel.warn(message)
+        end
+      end
+
+      # Resolve the logger instance used for warnings, if present.
+      # @return [Object, nil]
+      def rails_logger
+        return unless defined?(::Rails) && ::Rails.respond_to?(:logger)
+
+        ::Rails.logger
+      end
+    end
+  end
+end

data/lib/verikloak/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Verikloak
   module Rails
-    VERSION = '0.3.1'
+    VERSION = '0.3.2'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak-rails
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - taiyaky
@@ -82,10 +82,12 @@ files:
 - lib/generators/verikloak/install/templates/initializer.rb.erb
 - lib/verikloak-rails.rb
 - lib/verikloak/rails.rb
+- lib/verikloak/rails/bff_configurator.rb
 - lib/verikloak/rails/configuration.rb
 - lib/verikloak/rails/controller.rb
 - lib/verikloak/rails/error_renderer.rb
 - lib/verikloak/rails/railtie.rb
+- lib/verikloak/rails/railtie_logger.rb
 - lib/verikloak/rails/version.rb
 homepage: https://github.com/taiyaky/verikloak-rails
 licenses:
@@ -94,7 +96,7 @@ metadata:
   source_code_uri: https://github.com/taiyaky/verikloak-rails
   changelog_uri: https://github.com/taiyaky/verikloak-rails/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/taiyaky/verikloak-rails/issues
-  documentation_uri: https://rubydoc.info/gems/verikloak-rails/0.3.1
+  documentation_uri: https://rubydoc.info/gems/verikloak-rails/0.3.2
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: