verikloak-rails 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76efc055243284fee1fae95dac5e73f8a50bbc128310ea255f7fe224b3188c89
-  data.tar.gz: 0c5b906c0e406192e698454efd12f526021c3c26a8100da49ed9a1f3d71e9823
+  metadata.gz: f473cac2688d575650e3c483eac520fcb910ca7a9fd3c08620337386a705ca27
+  data.tar.gz: d76e49d03d27b336e6c8727f0cf3b82bb783bbe5153051be4ad4d0c1af5cfe7f
 SHA512:
-  metadata.gz: 52ae4d44b34d53dd247010d1af4371850ee811c92f38d505b0d775d99b7e3fb66a4c22471f4bc1ebf2c7634397c9da76c1aef811e11ecc2ad7745d95b6ef1070
-  data.tar.gz: a47b77285a47d8ce4092398d49d561586e874be1c4f98db2f6261bcd91b13e3bcfb3fd2283d8488a93be919321311c61f5e249ab758118f660fe04edd9e05d8b
+  metadata.gz: 6326a2ca5a86a50898ebe00094139733e3295203ec050e9c471093c1d3b21f2d161251d6ecf97ce265267718e83b570f1b9d8d82b9288855f732b557d22ac5a4
+  data.tar.gz: 874c03abffe2470e4993b64e0afdcbe42f1b1f27e8b4bbd17aa457445deffce591907a46a62f0be24801786f3e339bfd43fd89deb3d2239defcd3ad37c8410ca

data/CHANGELOG.md

@@ -7,6 +7,41 @@ 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
+- **API mode support**: `auto_include_controller` now automatically includes
+  `Verikloak::Rails::Controller` in both `ActionController::Base` and `ActionController::API`
+  - Rails API-only applications (`rails new myapp --api`) now work out of the box
+  - Skip logic prevents duplicate inclusion when controller already includes the concern
+
+### Changed
+- **Generator template improved**: `initializer.rb.erb` now includes:
+  - Descriptive comments for each configuration option
+  - ENV variable support for `auto_include_controller` (`VERIKLOAK_AUTO_INCLUDE`)
+  - ENV variable prefix changed from `VERIKLOAK_AUDIENCE` to `KEYCLOAK_AUDIENCE` for consistency
+
+### Documentation
+- README updated with API mode usage example
+
+---
+
 ## [0.3.0] - 2026-01-01
 
 ### Changed

data/README.md

@@ -108,6 +108,16 @@ class ApplicationController < ActionController::Base
 end
 ```
 
+### API Mode Support
+Both `ActionController::Base` and `ActionController::API` are supported. The controller concern is automatically included in both when `auto_include_controller` is enabled (default).
+
+```ruby
+# Works automatically with Rails API mode (rails new myapp --api)
+class ApplicationController < ActionController::API
+  # Verikloak::Rails::Controller is auto-included
+end
+```
+
 ## Middleware
 ### Inserted Middleware
 | Component | Inserted relative to | Purpose |

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

@@ -1,14 +1,29 @@
 # frozen_string_literal: true
 
 Rails.application.configure do
+  # Discovery URL (required)
   config.verikloak.discovery_url = ENV.fetch('KEYCLOAK_DISCOVERY_URL', nil)
-  config.verikloak.audience      = ENV.fetch('VERIKLOAK_AUDIENCE', 'rails-api')
-  config.verikloak.issuer        = ENV.fetch('VERIKLOAK_ISSUER', nil)
-  config.verikloak.leeway        = Integer(ENV.fetch('VERIKLOAK_LEEWAY', '60'))
-  config.verikloak.skip_paths    = %w[/up /health /rails/health]
 
+  # Audience validation (optional but recommended)
+  config.verikloak.audience = ENV.fetch('KEYCLOAK_AUDIENCE', 'rails-api')
+
+  # Issuer validation (optional, derived from discovery_url if not set)
+  config.verikloak.issuer = ENV.fetch('KEYCLOAK_ISSUER', nil)
+
+  # JWT clock skew tolerance in seconds
+  config.verikloak.leeway = Integer(ENV.fetch('VERIKLOAK_LEEWAY', '60'))
+
+  # Paths to skip authentication (health checks, etc.)
+  config.verikloak.skip_paths = %w[/up /health /rails/health]
+
+  # Request ID and subject in logs
   config.verikloak.logger_tags = %i[request_id sub]
-  config.verikloak.auto_include_controller = true
+
+  # Auto-include controller concern
+  # Set to false if you manually include Verikloak::Rails::Controller
+  config.verikloak.auto_include_controller = ENV.fetch('VERIKLOAK_AUTO_INCLUDE', 'true') == 'true'
+
+  # Render detailed 500 errors (development only recommended)
   config.verikloak.render_500_json = ENV.fetch('VERIKLOAK_RENDER_500', 'false') == 'true'
 
   # Optional Pundit rescue (403 JSON). Leave commented so `verikloak-pundit`

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
@@ -31,10 +33,16 @@ module Verikloak
       end
 
       # Optionally include the controller concern when ActionController loads.
+      # Supports both ActionController::Base and ActionController::API (API mode).
+      # Skips inclusion if the controller already includes the concern.
       # @return [void]
       initializer 'verikloak.controller' do |_app|
-        ActiveSupport.on_load(:action_controller_base) do
-          include Verikloak::Rails::Controller if Verikloak::Rails.config.auto_include_controller
+        %i[action_controller_base action_controller_api].each do |hook|
+          ActiveSupport.on_load(hook) do
+            next if include?(Verikloak::Rails::Controller) # Already included, skip
+
+            include Verikloak::Rails::Controller if Verikloak::Rails.config.auto_include_controller
+          end
         end
       end
 
@@ -47,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
@@ -55,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.
@@ -120,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).
         #
@@ -237,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.0'
+    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.0
+  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.0
+  documentation_uri: https://rubydoc.info/gems/verikloak-rails/0.3.2
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: