verikloak-rails 0.2.6 → 0.2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6126b5013614bb5cb7c0594126c21456db9762a9e3d307108e5f8c1ce197155
-  data.tar.gz: e8504432260a732881946e72cb5551e00178108ba641b802b78c4ca42879e664
+  metadata.gz: cbc6aebdf72129720e402e9e90f168b311fa9718c704c86f67d68d9a560cf706
+  data.tar.gz: 10c488b6ac7dbe7c2e2951300f2a4f1b21ccfe3ea0f9517ec2537aee6e6fb0a1
 SHA512:
-  metadata.gz: ecaf3de303c489d429c6157232f3159333ddec36e87ac0499784181e944c9fe25f59aceb72452b69f297bc7ff0761c069df13cf78ab776c5311a04d6d6c0e9be
-  data.tar.gz: e335daefda43368d7c0b58b87372214a8e999bad0424c7e5e2e4e5d5f1ced49b51190e900865ff34d1a277a72eb6fd172b64fc559f0eb246fac4f1d114902bfc
+  metadata.gz: 50bf90d8935e1a402c71075f015f3fc113894171129ba510ef91164614cb636b99474ddb3ab7c18300d1c59d32f44de1d58e8fe8b2c3dc084419e65170094c09
+  data.tar.gz: 2e2510548db798e6295a4d36b0f655c4c802908a1842e82bb4680a814d5847de1c4eab60f20cb3d7219e24023c48b64a7ff745f3901de913fb4a7f4ac5808073

data/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.2.8] - 2025-01-03
+
+### Changed
+- Refactor controller helpers to use shared `_verikloak_fetch_request_context` method for consistent RequestStore fallback handling
+- Optimize configuration access by caching `Verikloak::Rails.config` in log tag building
+- Extract `auth_headers` method in ErrorRenderer for reusable WWW-Authenticate header generation
+- Streamline middleware configuration by inlining BFF guard insertion into main configuration flow
+- Improve middleware insertion error handling with `try_insert_after` and `warn_with_fallback` utilities
+
+### Added
+- Support for advanced middleware options: `token_verify_options`, `decoder_cache_limit`, `token_env_key`, `user_env_key`
+- `bff_header_guard_options` configuration for verikloak-bff library integration
+- Centralized `CONFIG_KEYS` constant in Railtie for consistent configuration management
+- Enhanced README documentation with RequestStore vs Rack environment priority examples
+
+### Fixed
+- Only call `configure_bff_guard` when middleware stack is successfully created
+- Replace `each_with_object` with `transform_keys` for better Ruby style compliance
+
+## [0.2.7] - 2025-09-23
+
+### Fixed
+- Handle `RuntimeError` exceptions from `ActionDispatch::MiddlewareStack#insert_after` in Rails 8+
+- Add `inserted` flag to prevent duplicate middleware insertion when fallback is used
+- Enhance error handling to gracefully handle all middleware insertion failures
+
+### Changed
+- Update middleware insertion candidates logic for better Rails version compatibility
+  - Rails 8+ now raises `RuntimeError` instead of the deprecated `ActionDispatch::MiddlewareStack::MiddlewareNotFound`
+  - Broaden exception handling to catch `StandardError` for robustness across Rails versions
+  - Improve logging and debugging information for middleware insertion failures
+
 ## [0.2.6] - 2025-09-23
 
 ### Fixed

data/README.md

@@ -48,6 +48,33 @@ Then configure `config/initializers/verikloak.rb`.
 | `current_user_claims` | `verikloak.user` | `:verikloak_user` | Uses RequestStore only when available |
 | `current_token` | `verikloak.token` | `:verikloak_token` | Uses RequestStore only when available |
 
+#### Priority and Behavior Details
+
+The helpers follow this priority order:
+
+1. **Primary**: `request.env` (Rack environment) - Set directly by `Verikloak::Middleware`
+2. **Fallback**: `RequestStore.store` (when available) - Thread-local storage for background jobs
+
+**Examples:**
+
+```ruby
+# In a controller action (normal case)
+current_user_claims  # reads from request.env['verikloak.user']
+current_token        # reads from request.env['verikloak.token']
+
+# In a background job triggered during request
+# (when RequestStore gem is present and middleware has mirrored values)
+current_user_claims  # falls back to RequestStore.store[:verikloak_user]
+current_token        # falls back to RequestStore.store[:verikloak_token]
+
+# When RequestStore is not available or disabled
+current_user_claims  # returns nil if not in request.env
+current_token        # returns nil if not in request.env
+```
+
+**Custom Environment Keys**: If you configure custom `token_env_key` or `user_env_key`,
+the helpers automatically adapt to use those keys instead of the defaults.
+
 ### Example Controller
 
 ```ruby
@@ -99,6 +126,12 @@ When `verikloak-bff` is on the load path, `verikloak-rails` automatically insert
 
 Use verikloak-bff alongside this gem when you front Rails with a BFF/proxy such as oauth2-proxy and need to enforce trusted forwarding and header consistency.
 
+Assign `config.verikloak.bff_header_guard_options` to customize the guard before
+it is inserted. Provide either a Hash (merged via attribute writers) or a block/
+callable that receives the `Verikloak::BFF.configure` object so you can set
+advanced options such as trusted proxies, forwarded header names, or custom log
+hooks directly from the Rails initializer.
+
 ## Configuration (initializer)
 ### Keys
 Keys under `config.verikloak`:
@@ -120,6 +153,11 @@ Keys under `config.verikloak`:
 | `auto_insert_bff_header_guard` | Boolean | Auto insert `Verikloak::Bff::HeaderGuard` when the gem is present | `true` |
 | `bff_header_guard_insert_before` | Object/String/Symbol | Insert the header guard before this middleware (`Verikloak::Middleware` when `nil`) | `nil` |
 | `bff_header_guard_insert_after` | Object/String/Symbol | Insert the header guard after this middleware | `nil` |
+| `token_verify_options` | Hash | Additional options forwarded to `Verikloak::TokenDecoder` (e.g. `{ verify_iat: false }`) | `{}` |
+| `decoder_cache_limit` | Integer or nil | Overrides the cached decoder count before eviction | `nil` (verikloak default `128`) |
+| `token_env_key` | String | Custom Rack env key that stores the Bearer token | `nil` (middleware default `verikloak.token`) |
+| `user_env_key` | String | Custom Rack env key that stores decoded claims | `nil` (middleware default `verikloak.user`) |
+| `bff_header_guard_options` | Hash or Proc | Forwarded to `Verikloak::BFF.configure` prior to middleware insertion | `{}` |
 
 Environment variable examples are in the generated initializer.
 

data/lib/verikloak/rails/configuration.rb

@@ -59,7 +59,9 @@ module Verikloak
                     :render_500_json, :rescue_pundit,
                     :middleware_insert_before, :middleware_insert_after,
                     :auto_insert_bff_header_guard,
-                    :bff_header_guard_insert_before, :bff_header_guard_insert_after
+                    :bff_header_guard_insert_before, :bff_header_guard_insert_after,
+                    :token_verify_options, :decoder_cache_limit,
+                    :token_env_key, :user_env_key, :bff_header_guard_options
 
       # Initialize configuration with sensible defaults for Rails apps.
       # @return [void]
@@ -79,6 +81,11 @@ module Verikloak
         @auto_insert_bff_header_guard = true
         @bff_header_guard_insert_before = nil
         @bff_header_guard_insert_after = nil
+        @token_verify_options = {}
+        @decoder_cache_limit = nil
+        @token_env_key = nil
+        @user_env_key = nil
+        @bff_header_guard_options = {}
       end
 
       # Options forwarded to the base Verikloak Rack middleware.
@@ -92,7 +99,11 @@ module Verikloak
           audience: audience,
           issuer: issuer,
           leeway: leeway,
-          skip_paths: skip_paths
+          skip_paths: skip_paths,
+          token_verify_options: token_verify_options,
+          decoder_cache_limit: decoder_cache_limit,
+          token_env_key: token_env_key,
+          user_env_key: user_env_key
         }.compact
       end
     end

data/lib/verikloak/rails/controller.rb

@@ -59,22 +59,14 @@ module Verikloak
       # Prefer Rack env; fall back to RequestStore when available.
       # @return [Hash, nil]
       def current_user_claims
-        env_claims = request.env['verikloak.user']
-        return env_claims unless env_claims.nil?
-        return ::RequestStore.store[:verikloak_user] if defined?(::RequestStore) && ::RequestStore.respond_to?(:store)
-
-        nil
+        _verikloak_fetch_request_context('verikloak.user', :verikloak_user)
       end
 
       # The raw bearer token used for the current request.
       # Prefer Rack env; fall back to RequestStore when available.
       # @return [String, nil]
       def current_token
-        env_token = request.env['verikloak.token']
-        return env_token unless env_token.nil?
-        return ::RequestStore.store[:verikloak_token] if defined?(::RequestStore) && ::RequestStore.respond_to?(:store)
-
-        nil
+        _verikloak_fetch_request_context('verikloak.token', :verikloak_token)
       end
 
       # The `sub` (subject) claim from the current user claims.
@@ -112,13 +104,14 @@ module Verikloak
       # Build log tags from request context with minimal branching and safe values.
       # @return [Array<String>]
       def _verikloak_build_log_tags
+        config = Verikloak::Rails.config
         tags = []
-        if Verikloak::Rails.config.logger_tags.include?(:request_id)
+        if config.logger_tags.include?(:request_id)
           rid = request.request_id || request.headers['X-Request-Id']
           rid = rid.to_s.gsub(/[\r\n]+/, ' ')
           tags << "req:#{rid}" unless rid.empty?
         end
-        if Verikloak::Rails.config.logger_tags.include?(:sub)
+        if config.logger_tags.include?(:sub)
           sub = current_subject
           if sub
             sanitized = sub.to_s.gsub(/[[:cntrl:]]+/, ' ').strip
@@ -128,6 +121,21 @@ module Verikloak
         tags
       end
 
+      # Retrieve request context from Rack env or RequestStore.
+      # @param env_key [String]
+      # @param store_key [Symbol]
+      # @return [Object, nil]
+      def _verikloak_fetch_request_context(env_key, store_key)
+        env_value = request.env[env_key]
+        return env_value unless env_value.nil?
+        return unless defined?(::RequestStore) && ::RequestStore.respond_to?(:store)
+
+        store = ::RequestStore.store
+        return unless store.respond_to?(:[])
+
+        store[store_key]
+      end
+
       # Write StandardError details to the controller or Rails logger when
       # rendering the generic 500 JSON response. Logging ensures the
       # underlying failure is still visible to operators even though the

data/lib/verikloak/rails/error_renderer.rb

@@ -34,14 +34,9 @@ module Verikloak
       def render(controller, error)
         code, message = extract_code_message(error)
         status = status_for(error, code)
-        headers = {}
-        if status == 401
-          hdr = +'Bearer'
-          hdr << %( error="#{sanitize_quoted(code)}") if code
-          hdr << %( error_description="#{sanitize_quoted(message)}") if message
-          headers['WWW-Authenticate'] = hdr
+        auth_headers(status, code, message).each do |header, value|
+          controller.response.set_header(header, value)
         end
-        headers.each { |k, v| controller.response.set_header(k, v) }
         controller.render json: { error: code || 'unauthorized', message: message }, status: status
       end
 
@@ -71,6 +66,20 @@ module Verikloak
         end
       end
 
+      # Build WWW-Authenticate headers when returning 401 responses.
+      # @param status [Integer]
+      # @param code [String, nil]
+      # @param message [String]
+      # @return [Hash<String, String>]
+      def auth_headers(status, code, message)
+        return {} unless status == 401
+
+        header = +'Bearer'
+        header << %( error="#{sanitize_quoted(code)}") if code
+        header << %( error_description="#{sanitize_quoted(message)}") if message
+        { 'WWW-Authenticate' => header }
+      end
+
       # Sanitize a value for inclusion inside a quoted HTTP header parameter.
       # Escapes quotes and backslashes, and strips CR/LF to prevent header injection.
       # Why block replacement? String replacements like '\\1' are parsed as

data/lib/verikloak/rails/railtie.rb

@@ -11,13 +11,22 @@ module Verikloak
     # - Inserts base `Verikloak::Middleware`
     # - Auto-includes controller concern when enabled
     class Railtie < ::Rails::Railtie
+      CONFIG_KEYS = %i[
+        discovery_url audience issuer leeway skip_paths
+        logger_tags error_renderer auto_include_controller
+        render_500_json rescue_pundit middleware_insert_before
+        middleware_insert_after auto_insert_bff_header_guard
+        bff_header_guard_insert_before bff_header_guard_insert_after
+        token_verify_options decoder_cache_limit token_env_key user_env_key
+        bff_header_guard_options
+      ].freeze
+
       config.verikloak = ActiveSupport::OrderedOptions.new
 
       # Apply configuration and insert middleware.
       # @return [void]
       initializer 'verikloak.configure' do |app|
-        stack = ::Verikloak::Rails::Railtie.send(:configure_middleware, app)
-        ::Verikloak::Rails::Railtie.send(:configure_bff_guard, stack) if stack
+        ::Verikloak::Rails::Railtie.send(:configure_middleware, app)
       end
 
       # Optionally include the controller concern when ActionController loads.
@@ -37,13 +46,17 @@ module Verikloak
         # @return [ActionDispatch::MiddlewareStackProxy] configured middleware stack
         def configure_middleware(app)
           apply_configuration(app)
+          configure_bff_library
 
           unless discovery_url_present?
             log_missing_discovery_url_warning
             return
           end
 
-          insert_base_middleware(app)
+          stack = insert_base_middleware(app)
+          configure_bff_guard(stack) if stack
+
+          stack
         end
 
         # Insert the optional HeaderGuard middleware when verikloak-bff is present.
@@ -65,6 +78,33 @@ module Verikloak
           end
         end
 
+        # Apply configuration options to the verikloak-bff namespace.
+        # Supports hash-like and callable inputs.
+        #
+        # @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
+        end
+
         # Sync configuration from the Rails application into Verikloak::Rails.
         #
         # @param app [Rails::Application]
@@ -72,17 +112,33 @@ module Verikloak
         def apply_configuration(app)
           Verikloak::Rails.configure do |c|
             rails_cfg = app.config.verikloak
-            %i[discovery_url audience issuer leeway skip_paths
-               logger_tags error_renderer auto_include_controller
-               render_500_json rescue_pundit middleware_insert_before
-               middleware_insert_after auto_insert_bff_header_guard
-               bff_header_guard_insert_before bff_header_guard_insert_after].each do |key|
+            CONFIG_KEYS.each do |key|
               c.send("#{key}=", rails_cfg[key]) if rails_cfg.key?(key)
             end
             c.rescue_pundit = false if !rails_cfg.key?(:rescue_pundit) && defined?(::Verikloak::Pundit)
           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?)
+
+          target = if defined?(::Verikloak::BFF) && ::Verikloak::BFF.respond_to?(:configure)
+                     ::Verikloak::BFF
+                   elsif defined?(::Verikloak::Bff) && ::Verikloak::Bff.respond_to?(:configure)
+                     ::Verikloak::Bff
+                   end
+
+          return unless target
+
+          apply_bff_configuration(target, 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
@@ -102,11 +158,7 @@ module Verikloak
         # @return [void]
         def log_missing_discovery_url_warning
           message = '[verikloak] discovery_url is not configured; skipping middleware insertion.'
-          if defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger
-            ::Rails.logger.warn(message)
-          else
-            warn(message)
-          end
+          warn_with_fallback(message)
         end
 
         # Insert the base Verikloak::Middleware into the application middleware stack.
@@ -136,13 +188,80 @@ module Verikloak
         # @param base_options [Hash] options to pass to the middleware
         # @return [void]
         def insert_middleware_after(stack, base_options)
-          after = Verikloak::Rails.config.middleware_insert_after || ::Rails::Rack::Logger
-          if after
-            stack.insert_after after,
-                               ::Verikloak::Middleware,
-                               **base_options
+          inserted = middleware_insert_after_candidates.any? do |candidate|
+            try_insert_after(stack, candidate, base_options)
+          end
+
+          # Only use as fallback if insertion after a specific middleware failed
+          stack.use ::Verikloak::Middleware, **base_options unless inserted
+        end
+
+        # Attempt to insert after a candidate middleware.
+        # Logs a warning and returns false when the candidate is not present.
+        #
+        # @param stack [ActionDispatch::MiddlewareStackProxy]
+        # @param candidate [Object, nil]
+        # @param base_options [Hash]
+        # @return [Boolean]
+        def try_insert_after(stack, candidate, base_options)
+          return false unless candidate
+
+          stack.insert_after candidate,
+                             ::Verikloak::Middleware,
+                             **base_options
+          true
+        rescue StandardError => e
+          # Handle middleware insertion failures:
+          # - Rails 8+: RuntimeError for missing middleware
+          # - Earlier versions: ActionDispatch::MiddlewareStack::MiddlewareNotFound
+          log_middleware_insertion_warning(candidate, e)
+          false
+        end
+
+        # Build list of middleware to try as insertion points.
+        # Starts with the configured value (if any) and falls back to defaults
+        # that exist across supported Rails versions.
+        #
+        # @return [Array<Object>] ordered list of potential middleware targets
+        def middleware_insert_after_candidates
+          configured = Verikloak::Rails.config.middleware_insert_after
+
+          defaults = []
+          defaults << ::Rails::Rack::Logger if defined?(::Rails::Rack::Logger)
+          defaults << ::ActionDispatch::Executor if defined?(::ActionDispatch::Executor)
+          defaults << ::Rack::Head if defined?(::Rack::Head)
+          defaults << ::Rack::Runtime if defined?(::Rack::Runtime)
+
+          ([configured] + defaults).compact.uniq
+        end
+
+        # Log when a middleware insertion target cannot be found.
+        #
+        # @param candidate [Object] middleware we attempted to insert after
+        # @param error [StandardError] the exception raised during insertion
+        # @return [void]
+        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
-            stack.use ::Verikloak::Middleware, **base_options
+            warn(message)
           end
         end
       end

data/lib/verikloak/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Verikloak
   module Rails
-    VERSION = '0.2.6'
+    VERSION = '0.2.8'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 0.2.8
 platform: ruby
 authors:
 - taiyaky
@@ -94,7 +94,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.2.6
+  documentation_uri: https://rubydoc.info/gems/verikloak-rails/0.2.8
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: