verikloak-rails 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b4d8e46a9c366b09726841773f09cbf54b44c3fbf2f0870b1994bb365ae9173
-  data.tar.gz: 31f3fdf2f6c9482f06a1a03bf0a4ecdc8109f24c814306e174ff582706659c4f
+  metadata.gz: 4ab889b6413e152dc2be695f2f4f738d7e2b90712b54559cc596e6d1c92166ed
+  data.tar.gz: b97dd2c56aca7b021daf781ffc2ad834bc0b42c4b72efdd9cdda1d609495f4a6
 SHA512:
-  metadata.gz: 6748be8631a59e8d1f0562c96ae6b53b01991d28a5fd094cf0117164d7597508c0d02e8be5ebdc28ad04c801686dac0492eb6f5242ea09e961a1814d4b0ff248
-  data.tar.gz: a41eb76616575e283c7ff139161fa18886b85ffea7f7d953eb4ed846b754fb1e15a93538d3f8ed51b04d92e68f302b3174d54ba881e600b2c58d9f8979687c6b
+  metadata.gz: 5bdf562dbadfbede90f0d2d32ab69f62072636abd5a7ff0a3580a1fe6a58cb2dd24ee35a0468b4d0b1d5fe91174e9e49dc481b2cfee862a9030a909b58742c78
+  data.tar.gz: 3ec0f43f095dd1002e6f612af4061beda81f29da93b2bc6e09d0fb37d67dfce477d4cc4194705441e11318ad11902f37fac2ab42768b4986eb0fcdc092a3bd66

data/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.2.0] - 2026-07-03
+
+### Fixed
+- **`Testing::Helpers#build_pundit_user_context` crashed against the real `verikloak-pundit` gem**: the helper called `UserContext.new(user, claims)`, but verikloak-pundit's constructor is `UserContext.new(claims, resource_client: nil, config: nil)` (a single positional argument), so `build_admin_user_context` / `build_user_user_context` always raised `ArgumentError`. The helper now takes the claims Hash (`build_pundit_user_context(claims, **options)`) and forwards keyword options such as `resource_client:` to the real constructor. The unit-spec fake was aligned with the real signature, and new contract specs (see below) guard against future drift.
+- **Controller helpers ignored custom `token_env_key` / `user_env_key`**: `current_user_claims` / `current_token` (and therefore `authenticate_user!`) always read the default `verikloak.user` / `verikloak.token` env keys, so configuring custom keys caused valid requests to be rejected with 401. The helpers and `Testing::MiddlewareStub` now resolve keys via the new `Configuration#effective_user_env_key` / `#effective_token_env_key`, matching what the middleware writes (and what `verikloak-pundit` already syncs to). Configured keys are whitespace-stripped exactly like the core middleware normalizes them before writing, so a padded value (e.g. an ENV var with a trailing newline) can no longer make the middleware write one env key while the helpers read another. `Testing::MiddlewareStub` resolves the keys when the stubbed call runs — not when the stub is installed — so configuration applied after `stub_verikloak_middleware` stays in sync with the helpers' request-time reads.
+- **`require 'verikloak/rails'` failed outside a booted Rails app**: the Railtie now requires the ActiveSupport core extensions it depends on (`delegate_missing_to`, `blank?`) before `rails/railtie`, so the gem can be loaded standalone (e.g. from contract specs or plain scripts).
+
+### Added
+- **`Verikloak::Rails::RequestStoreMirror` middleware**: when the `request_store` gem is on the load path, the Railtie inserts this middleware right after `Verikloak::Middleware` to mirror `verikloak.user` / `verikloak.token` (or the configured custom keys) into `RequestStore.store`. Previously the controller helpers' RequestStore fallback documented in the README had no writer — nothing ever mirrored the values — so it only worked if the application mirrored them by hand. **Upgrade note**: the mirror overwrites `RequestStore.store[:verikloak_user]` / `[:verikloak_token]` on every request (`nil` on unauthenticated/skipped paths) so stale context never leaks between requests — remove any hand-rolled mirroring of these keys when upgrading. Mirroring failures never break the request, but are logged once (per middleware instance) instead of being silently swallowed.
+- **`Configuration#effective_token_env_key` / `#effective_user_env_key`**: single source of truth for resolving the Rack env keys (custom value or core default), shared by the controller helpers, `RequestStoreMirror`, and `Testing::MiddlewareStub`.
+- **Contract specs against the real sibling gems** (`spec/contracts`): verify the constructor/config surfaces of `verikloak` core, `verikloak-pundit`, `verikloak-bff`, and `verikloak-audience` that this gem relies on. Tagged `:contract` and excluded from the default run; the new CI `contracts` job runs them with `gemfiles/contracts.Gemfile` so interface drift is caught even though the unit suite uses fakes.
+- **`jwks_refresh_interval` configuration option**: forwarded to the core `Verikloak::Middleware` (new in verikloak 1.1.0) to throttle JWKS/discovery revalidation on the request path. Left unset it is omitted from `middleware_options`, so the core default (`60` seconds) applies; `0` restores the pre-1.1 revalidate-on-every-request behavior, and numeric strings (e.g. from ENV) are coerced by the core. The keyword only exists in verikloak core `>= 1.1.0`, which this release now requires (see Changed).
+
+### Security
+- **Bumped locked dependencies to clear all Dependabot / bundler-audit advisories**: `jwt` 3.2.0 (GHSA-c32j-vqhx-rx3x, High), `faraday` 2.14.3 (GHSA-98m9-hrrm-r99r High, GHSA-5rv5-xj5j-3484 Medium), `net-imap` 0.6.4.1 (2 Medium, 1 Low), `nokogiri` 1.19.4 (9 advisories), `concurrent-ruby` 1.3.7 and `crass` 1.0.7 (3 + 4 advisories). All are transitive development/test dependencies pinned by `Gemfile.lock`; the gem's runtime requirements are unchanged.
+
+### Changed
+- **BREAKING**: `Testing::Helpers#build_pundit_user_context` now takes the claims Hash as its only positional argument (`build_pundit_user_context(claims, **options)` instead of `(user, claims)`). The old signature never worked against the real verikloak-pundit gem (it always raised `ArgumentError`), so only suites stubbing `UserContext` with a two-argument fake are affected; the `build_admin_user_context` / `build_user_user_context` wrappers are unchanged. See the Fixed entry above for details.
+- **Raised the minimum `verikloak` (core) runtime dependency to `~> 1.1`** (was `~> 1.0`): verikloak-rails 1.2.0 forwards the `jwks_refresh_interval` keyword, which only exists in verikloak core `>= 1.1.0`. Enforcing it in the gemspec turns a would-be boot-time `ArgumentError` (setting the option against a 1.0.x core) into a clear dependency-resolution error at `bundle install`. Apps that do not use the option are still subject to the new floor, but core 1.1.0 is backward-compatible with 1.0.x apart from the new default JWKS refresh throttle (60s).
+- **Error-handler registration hardened against boot-order issues**: `rescue_from StandardError` / `rescue_from Pundit::NotAuthorizedError` remain registered only when `render_500_json` / `rescue_pundit` are enabled — registering them unconditionally would suppress `ActiveSupport::Rescuable`'s `exception.cause` traversal (e.g. an app's `rescue_from ActiveRecord::RecordNotFound` no longer catching errors raised inside views and wrapped in `ActionView::Template::Error`) and shadow handlers registered earlier on the same class. Instead, the Railtie now fires the auto-include hook after `verikloak.configure`, so the include-time reads see the application's final configuration even when `ActionController::Base` is loaded early by another initializer. Handler bodies additionally re-check the flags at request time, so disabling them at runtime still takes effect. Note that Pundit must be loaded before the concern is included for the Pundit rescue to be registered.
+- **Log-tag sanitization extracted** to a shared `_verikloak_sanitize_tag` helper (same `[[:cntrl:]]` stripping, applied to both `request_id` and `sub` tags).
+- **Controller rescue handlers and 500-error logging extracted** to `Verikloak::Rails::Controller::ErrorHandling` (included by the concern automatically; behavior unchanged).
+- `Gemfile.lock` now includes the `x86_64-linux` / `aarch64-linux` (glibc) platforms so `bundle install` works outside the Alpine (musl) Docker image.
+
+---
+
 ## [1.1.0] - 2026-05-09
 
 ### Added

data/README.md

@@ -53,7 +53,9 @@ Then configure `config/initializers/verikloak.rb`.
 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
+2. **Fallback**: `RequestStore.store` (when available) - Thread-local storage for code running outside the controller
+
+When the [`request_store`](https://rubygems.org/gems/request_store) gem is on the load path, the Railtie automatically inserts `Verikloak::Rails::RequestStoreMirror` right after `Verikloak::Middleware`. It mirrors the claims/token from the Rack env into `RequestStore.store` on every request, so the fallback works out of the box (e.g. in service objects or jobs enqueued during the request). The mirror overwrites `RequestStore.store[:verikloak_user]` / `[:verikloak_token]` on every request — with `nil` on unauthenticated or skipped paths — so stale context never leaks between requests; if you previously mirrored these keys by hand, remove your own writer when upgrading. Mirroring failures never break the request and are logged once so a dead fallback does not go unnoticed.
 
 **Examples:**
 
@@ -62,8 +64,8 @@ The helpers follow this priority order:
 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)
+# Outside the controller during the same request
+# (when the request_store gem is present; mirrored automatically)
 current_user_claims  # falls back to RequestStore.store[:verikloak_user]
 current_token        # falls back to RequestStore.store[:verikloak_token]
 
@@ -124,6 +126,7 @@ end
 | --- | --- | --- |
 | `Verikloak::Bff::HeaderGuard` (optional) | Before `Verikloak::Middleware` by default when the gem is present | Normalize or enforce trusted proxy headers such as `X-Forwarded-Access-Token` |
 | `Verikloak::Middleware` | After `Rails::Rack::Logger` by default (configurable) | Validate Bearer JWT (OIDC discovery + JWKS), set `verikloak.user`/`verikloak.token`, and honor `skip_paths` |
+| `Verikloak::Rails::RequestStoreMirror` (optional) | After `Verikloak::Middleware`, when the `request_store` gem is present | Mirror `verikloak.user`/`verikloak.token` into `RequestStore.store` for the controller helpers' fallback |
 
 ### BFF Integration
 Support for BFF header handling (e.g., normalizing or enforcing `X-Forwarded-Access-Token`) now lives in a dedicated gem: verikloak-bff.
@@ -169,6 +172,7 @@ Keys under `config.verikloak`:
 | `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 | `{}` |
 | `allow_http` | Boolean | Allow `http://` discovery URLs (forwarded to core middleware). **Only for development/test.** | `false` |
+| `jwks_refresh_interval` | Numeric or nil | Minimum seconds between JWKS revalidations on the request path; `0` revalidates on every request (pre-verikloak-1.1 behavior). Key rotation within the window still forces an immediate refresh. Numeric strings are coerced. | `nil` (verikloak default `60`) |
 
 Environment variable examples are in the generated initializer.
 
@@ -220,6 +224,7 @@ end
 | `audience` | `VERIKLOAK_AUDIENCE` |
 | `issuer` | `VERIKLOAK_ISSUER` |
 | `leeway` | `VERIKLOAK_LEEWAY` |
+| `jwks_refresh_interval` | `VERIKLOAK_JWKS_REFRESH_INTERVAL` |
 | `render_500_json` | `VERIKLOAK_RENDER_500` |
 | `rescue_pundit` | `VERIKLOAK_RESCUE_PUNDIT` |
 
@@ -291,7 +296,8 @@ end
 `stub_verikloak_middleware` automatically also stubs
 `Verikloak::BFF::HeaderGuard` and `Verikloak::Audience::Middleware` when
 those gems are loaded, and sets `env['verikloak.token']` so controller
-helpers like `current_token` work.
+helpers like `current_token` work. Custom `user_env_key` / `token_env_key`
+settings are honored automatically.
 
 ### Policy specs (with `verikloak-pundit`)
 

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

@@ -13,6 +13,11 @@ Rails.application.configure do
   # JWT clock skew tolerance in seconds
   config.verikloak.leeway = Integer(ENV.fetch('VERIKLOAK_LEEWAY', '60'))
 
+  # Minimum seconds between JWKS refresh checks on the request path.
+  # Leave unset to keep the verikloak default (60); 0 revalidates on every
+  # request.
+  # config.verikloak.jwks_refresh_interval = Integer(ENV.fetch('VERIKLOAK_JWKS_REFRESH_INTERVAL', '60'))
+
   # Paths to skip authentication (health checks, etc.)
   config.verikloak.skip_paths = %w[/up /health /rails/health]
 

data/lib/verikloak/rails/configuration.rb

@@ -56,6 +56,12 @@ module Verikloak
     #   Rack middleware to insert the header guard after.
     #   @return [Object, String, Symbol, nil]
     class Configuration
+      # Default Rack env keys. These mirror the defaults used by the core
+      # `Verikloak::Middleware` and are the fallback when `token_env_key` /
+      # `user_env_key` are left unset.
+      DEFAULT_TOKEN_ENV_KEY = 'verikloak.token'
+      DEFAULT_USER_ENV_KEY  = 'verikloak.user'
+
       attr_accessor :discovery_url, :audience, :issuer, :leeway,
                     :logger_tags, :error_renderer, :auto_include_controller,
                     :render_500_json, :rescue_pundit,
@@ -64,7 +70,7 @@ module Verikloak
                     :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,
-                    :allow_http
+                    :allow_http, :jwks_refresh_interval
 
       attr_reader :skip_paths
 
@@ -92,6 +98,7 @@ module Verikloak
         @user_env_key = nil
         @bff_header_guard_options = {}
         @allow_http = false
+        @jwks_refresh_interval = nil
         @skip_path_matcher = nil
       end
 
@@ -107,6 +114,26 @@ module Verikloak
         @skip_path_matcher ||= SkipPathChecker.new(skip_paths)
       end
 
+      # Rack env key actually used for the bearer token: the configured
+      # `token_env_key`, or the core middleware default when unset/blank.
+      # The value is whitespace-stripped to match the normalization the core
+      # middleware applies before writing to the env, so readers and writer
+      # always agree on the key. Shared by the controller helpers,
+      # RequestStore mirroring, and the testing middleware stub so all
+      # layers stay in sync.
+      # @return [String]
+      def effective_token_env_key
+        presence_or_default(token_env_key, DEFAULT_TOKEN_ENV_KEY)
+      end
+
+      # Rack env key actually used for decoded claims: the configured
+      # `user_env_key`, or the core middleware default when unset/blank.
+      # Whitespace-stripped like {#effective_token_env_key}.
+      # @return [String]
+      def effective_user_env_key
+        presence_or_default(user_env_key, DEFAULT_USER_ENV_KEY)
+      end
+
       # Options forwarded to the base Verikloak Rack middleware.
       # @return [Hash]
       # @example
@@ -123,9 +150,23 @@ module Verikloak
           decoder_cache_limit: decoder_cache_limit,
           token_env_key: token_env_key,
           user_env_key: user_env_key,
-          allow_http: allow_http
+          allow_http: allow_http,
+          jwks_refresh_interval: jwks_refresh_interval
         }.compact
       end
+
+      private
+
+      # @param value [String, nil]
+      # @param default [String]
+      # @return [String] the stripped value, or the default when blank.
+      #   Stripping mirrors the core middleware's env-key normalization
+      #   (`value.to_s.strip`); without it a padded key would make the
+      #   middleware write one env key while the helpers read another.
+      def presence_or_default(value, default)
+        str = value.to_s.strip
+        str.empty? ? default : str
+      end
     end
   end
 end

data/lib/verikloak/rails/controller/error_handling.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Verikloak
+  module Rails
+    module Controller
+      # Rescue handlers and 500-error logging backing the Controller
+      # concern's `rescue_from` registrations. Turns uncaught exceptions
+      # into the standardized JSON responses while keeping the underlying
+      # failure visible to operators through the innermost logger.
+      module ErrorHandling
+        private
+
+        # Handle uncaught StandardError: render the generic JSON 500 when
+        # `render_500_json` is enabled, otherwise re-raise so Rails' default
+        # error handling applies. The handler is only registered when the flag
+        # is enabled at include time; this request-time check additionally lets
+        # a runtime opt-out take effect.
+        #
+        # @param exception [StandardError]
+        # @return [void]
+        # @raise [StandardError] the original exception when rendering is disabled
+        def _verikloak_handle_standard_error(exception)
+          raise exception unless Verikloak::Rails.config.render_500_json
+
+          _verikloak_render_internal_error(exception)
+        end
+
+        # Handle `Pundit::NotAuthorizedError`: render 403 JSON when
+        # `rescue_pundit` is enabled; otherwise fall through to the generic
+        # StandardError handling (500 JSON or re-raise).
+        #
+        # @param exception [StandardError]
+        # @return [void]
+        # @raise [StandardError] the original exception when both rescues are disabled
+        def _verikloak_handle_pundit_error(exception)
+          if Verikloak::Rails.config.rescue_pundit
+            render json: { error: 'forbidden', message: exception.message }, status: :forbidden
+          else
+            _verikloak_handle_standard_error(exception)
+          end
+        end
+
+        # Log the exception and render the static JSON 500 body.
+        #
+        # @param exception [Exception]
+        # @return [void]
+        def _verikloak_render_internal_error(exception)
+          _verikloak_log_internal_error(exception)
+          render json: { error: 'internal_server_error', message: 'An unexpected error occurred' },
+                 status: :internal_server_error
+        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
+        # response body is static.
+        #
+        # @param exception [Exception]
+        # @return [void]
+        def _verikloak_log_internal_error(exception)
+          target_logger = _verikloak_base_logger
+          return unless target_logger.respond_to?(:error)
+
+          target_logger.error("[Verikloak] #{exception.class}: #{exception.message}")
+          backtrace = exception.backtrace
+          target_logger.error(backtrace.join("\n")) if backtrace&.any?
+        rescue StandardError
+          # Never allow logging failures to interfere with request handling.
+          nil
+        end
+
+        # Locate the innermost logger that responds to `error`.
+        # @return [Object, nil]
+        def _verikloak_base_logger
+          root_logger = if defined?(::Rails) && ::Rails.respond_to?(:logger)
+                          ::Rails.logger
+                        elsif respond_to?(:logger)
+                          logger
+                        end
+          current = root_logger
+          seen = Set.new
+          while current.respond_to?(:logger)
+            break unless seen.add?(current.object_id)
+
+            next_logger = current.logger
+            break if next_logger.nil? || next_logger.equal?(current)
+
+            current = next_logger
+          end
+          current
+        end
+      end
+    end
+  end
+end

data/lib/verikloak/rails/controller.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require 'active_support/concern'
-require 'set'
+require_relative 'controller/error_handling'
 
 module Verikloak
   module Rails
@@ -13,20 +13,24 @@ module Verikloak
     module Controller
       extend ActiveSupport::Concern
 
+      # Rescue handlers and 500-error logging (kept in a separate module so
+      # the concern itself stays focused on wiring and public helpers).
+      include ErrorHandling
+
       included do
         before_action :authenticate_user!
-        # Register generic error handler first so specific handlers take precedence.
-        if Verikloak::Rails.config.render_500_json
-          rescue_from StandardError do |e|
-            _verikloak_log_internal_error(e)
-            render json: { error: 'internal_server_error', message: 'An unexpected error occurred' },
-                   status: :internal_server_error
-          end
-        end
+        # Handlers are only registered when enabled at include time: a
+        # registered-but-disabled `rescue_from StandardError` would suppress
+        # ActiveSupport::Rescuable's `exception.cause` traversal and shadow
+        # handlers registered earlier on the same class (re-raising from
+        # inside a handler consults no other handler). The Railtie fires the
+        # auto-include hook after `verikloak.configure`, so these flags are
+        # final here; the same applies to `defined?(::Pundit::NotAuthorizedError)`,
+        # which requires Pundit to be loaded before this concern is included.
+        # Generic handler first so specific handlers take precedence.
+        rescue_from StandardError, with: :_verikloak_handle_standard_error if Verikloak::Rails.config.render_500_json
         if defined?(::Pundit::NotAuthorizedError) && Verikloak::Rails.config.rescue_pundit
-          rescue_from ::Pundit::NotAuthorizedError do |e|
-            render json: { error: 'forbidden', message: e.message }, status: :forbidden
-          end
+          rescue_from ::Pundit::NotAuthorizedError, with: :_verikloak_handle_pundit_error
         end
         rescue_from ::Verikloak::Error do |e|
           Verikloak::Rails.config.error_renderer.render(self, e)
@@ -54,17 +58,19 @@ module Verikloak
       def authenticated? = current_user_claims.present?
 
       # The verified JWT claims for the current user.
-      # Prefer Rack env; fall back to RequestStore when available.
+      # Prefer Rack env (honoring a custom `user_env_key`); fall back to
+      # RequestStore when available.
       # @return [Hash, nil]
       def current_user_claims
-        _verikloak_fetch_request_context('verikloak.user', :verikloak_user)
+        _verikloak_fetch_request_context(Verikloak::Rails.config.effective_user_env_key, :verikloak_user)
       end
 
       # The raw bearer token used for the current request.
-      # Prefer Rack env; fall back to RequestStore when available.
+      # Prefer Rack env (honoring a custom `token_env_key`); fall back to
+      # RequestStore when available.
       # @return [String, nil]
       def current_token
-        _verikloak_fetch_request_context('verikloak.token', :verikloak_token)
+        _verikloak_fetch_request_context(Verikloak::Rails.config.effective_token_env_key, :verikloak_token)
       end
 
       # The `sub` (subject) claim from the current user claims.
@@ -105,20 +111,24 @@ module Verikloak
         config = Verikloak::Rails.config
         tags = []
         if config.logger_tags.include?(:request_id)
-          rid = request.request_id || request.headers['X-Request-Id']
-          rid = rid.to_s.gsub(/[[:cntrl:]]+/, ' ').strip
-          tags << "req:#{rid}" unless rid.empty?
+          rid = _verikloak_sanitize_tag(request.request_id || request.headers['X-Request-Id'])
+          tags << "req:#{rid}" if rid
         end
         if config.logger_tags.include?(:sub)
-          sub = current_subject
-          if sub
-            sanitized = sub.to_s.gsub(/[[:cntrl:]]+/, ' ').strip
-            tags << "sub:#{sanitized}" unless sanitized.empty?
-          end
+          sub = _verikloak_sanitize_tag(current_subject)
+          tags << "sub:#{sub}" if sub
         end
         tags
       end
 
+      # Strip control characters and surrounding whitespace from a log tag value.
+      # @param value [Object, nil]
+      # @return [String, nil] sanitized value, or nil when blank
+      def _verikloak_sanitize_tag(value)
+        sanitized = value.to_s.gsub(/[[:cntrl:]]+/, ' ').strip
+        sanitized.empty? ? nil : sanitized
+      end
+
       # Retrieve request context from Rack env or RequestStore.
       # @param env_key [String]
       # @param store_key [Symbol]
@@ -133,46 +143,6 @@ module Verikloak
 
         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
-      # response body is static.
-      #
-      # @param exception [Exception]
-      # @return [void]
-      def _verikloak_log_internal_error(exception)
-        target_logger = _verikloak_base_logger
-        return unless target_logger.respond_to?(:error)
-
-        target_logger.error("[Verikloak] #{exception.class}: #{exception.message}")
-        backtrace = exception.backtrace
-        target_logger.error(backtrace.join("\n")) if backtrace&.any?
-      rescue StandardError
-        # Never allow logging failures to interfere with request handling.
-        nil
-      end
-
-      # Locate the innermost logger that responds to `error`.
-      # @return [Object, nil]
-      def _verikloak_base_logger
-        root_logger = if defined?(::Rails) && ::Rails.respond_to?(:logger)
-                        ::Rails.logger
-                      elsif respond_to?(:logger)
-                        logger
-                      end
-        current = root_logger
-        seen = Set.new
-        while current.respond_to?(:logger)
-          break unless seen.add?(current.object_id)
-
-          next_logger = current.logger
-          break if next_logger.nil? || next_logger.equal?(current)
-
-          current = next_logger
-        end
-        current
-      end
     end
   end
 end

data/lib/verikloak/rails/railtie.rb

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
 
+require 'active_support'
+require 'active_support/core_ext/module/delegation'
+require 'active_support/core_ext/object/blank'
 require 'rails/railtie'
 require 'verikloak/middleware'
 require_relative 'railtie_logger'
 require_relative 'bff_configurator'
+require_relative 'request_store_mirror'
 
 module Verikloak
   module Rails
@@ -20,7 +24,7 @@ module Verikloak
         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 allow_http
+        bff_header_guard_options allow_http jwks_refresh_interval
       ].freeze
 
       config.verikloak = ActiveSupport::OrderedOptions.new
@@ -35,8 +39,13 @@ module Verikloak
       # 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.
+      #
+      # Registered after `verikloak.configure` so that when ActionController
+      # is already loaded (and the on_load hook therefore fires immediately),
+      # the concern's include-time reads of `render_500_json` / `rescue_pundit`
+      # see the application's final configuration instead of defaults.
       # @return [void]
-      initializer 'verikloak.controller' do |_app|
+      initializer 'verikloak.controller', after: 'verikloak.configure' do |_app|
         %i[action_controller_base action_controller_api].each do |hook|
           ActiveSupport.on_load(hook) do
             next if include?(Verikloak::Rails::Controller) # Already included, skip
@@ -63,22 +72,33 @@ module Verikloak
           end
 
           stack = insert_base_middleware(app)
-          BffConfigurator.configure_bff_guard(stack) if stack
+          if stack
+            insert_request_store_mirror(stack)
+            BffConfigurator.configure_bff_guard(stack)
+          end
 
           stack
         end
 
-        # Check if discovery_url is present and valid.
+        # Check if discovery_url is configured (non-blank).
         #
-        # @return [Boolean] true if discovery_url is configured and not empty
+        # @return [Boolean]
         def discovery_url_present?
-          discovery_url = Verikloak::Rails.config.discovery_url
-          return false unless discovery_url
+          Verikloak::Rails.config.discovery_url.present?
+        end
 
-          return !discovery_url.blank? if discovery_url.respond_to?(:blank?)
-          return !discovery_url.empty? if discovery_url.respond_to?(:empty?)
+        # Mirror Verikloak env values into RequestStore when the gem is
+        # present, so the controller helpers' RequestStore fallback works
+        # outside the request cycle (e.g. jobs enqueued during a request).
+        #
+        # @param stack [ActionDispatch::MiddlewareStackProxy]
+        # @return [void]
+        def insert_request_store_mirror(stack)
+          return unless defined?(::RequestStore)
 
-          true
+          stack.insert_after ::Verikloak::Middleware, RequestStoreMirror
+        rescue StandardError => e
+          RailtieLogger.warn("[verikloak] Unable to insert RequestStoreMirror: #{e.message}")
         end
 
         # Log a warning message when discovery_url is missing.

data/lib/verikloak/rails/request_store_mirror.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative 'railtie_logger'
+
+module Verikloak
+  module Rails
+    # Rack middleware that mirrors the Verikloak request context from the
+    # Rack env into +RequestStore+, so code running outside the controller
+    # (service objects, jobs enqueued during the request) can read the same
+    # values through the controller helpers' RequestStore fallback.
+    #
+    # The Railtie inserts this middleware right after +Verikloak::Middleware+
+    # and only when the +request_store+ gem is loaded. Values are written on
+    # every request (including +nil+ on skipped/unauthenticated paths) so no
+    # stale context leaks between requests even before request_store's own
+    # cleanup middleware runs. Applications that mirrored these keys by hand
+    # before this middleware existed should remove their own writer — it
+    # would otherwise be overwritten here.
+    #
+    # Mirroring is best-effort: a failure never breaks the request, but it
+    # is logged (once per middleware instance) so a silently dead fallback
+    # does not go unnoticed.
+    class RequestStoreMirror
+      # @param app [#call] next Rack application
+      def initialize(app)
+        @app = app
+        @failure_warned = false
+      end
+
+      # Mirror claims/token into RequestStore, then call downstream.
+      #
+      # @param env [Hash] Rack environment
+      # @return [Array] Rack response triple
+      def call(env)
+        mirror(env)
+        @app.call(env)
+      end
+
+      private
+
+      # Best-effort mirroring; never breaks the request.
+      #
+      # @param env [Hash]
+      # @return [void]
+      def mirror(env)
+        return unless defined?(::RequestStore)
+
+        config = Verikloak::Rails.config
+        store = ::RequestStore.store
+        store[:verikloak_user]  = env[config.effective_user_env_key]
+        store[:verikloak_token] = env[config.effective_token_env_key]
+      rescue StandardError => e
+        warn_mirror_failure(e)
+      end
+
+      # Log the first mirroring failure so the RequestStore fallback does not
+      # die silently; stay quiet afterwards to avoid flooding the log on
+      # every request.
+      #
+      # @param error [StandardError]
+      # @return [void]
+      def warn_mirror_failure(error)
+        return if @failure_warned
+
+        @failure_warned = true
+        RailtieLogger.warn(
+          "[verikloak] RequestStoreMirror could not mirror the request context: #{error.class}: #{error.message}"
+        )
+      end
+    end
+  end
+end

data/lib/verikloak/rails/testing/helpers.rb

@@ -16,34 +16,42 @@ module Verikloak
 
         # Build a `Verikloak::Pundit::UserContext` for policy specs.
         #
-        # @param user [Object] application user
+        # Matches verikloak-pundit's constructor
+        # (`UserContext.new(claims, resource_client: nil, config: nil)`),
+        # which wraps the JWT claims only — the application user object is
+        # not part of the context.
+        #
         # @param claims [Hash] JWT claims (string keys)
+        # @param options [Hash] keyword options forwarded to `UserContext.new`
+        #   (e.g. `resource_client:`, `config:`)
         # @return [Verikloak::Pundit::UserContext]
         # @raise [RuntimeError] if `verikloak-pundit` is not loaded
-        def build_pundit_user_context(user, claims)
+        def build_pundit_user_context(claims, **options)
           unless defined?(::Verikloak::Pundit::UserContext)
             raise 'verikloak-pundit gem is not loaded; cannot build a UserContext'
           end
 
-          ::Verikloak::Pundit::UserContext.new(user, claims)
+          ::Verikloak::Pundit::UserContext.new(claims, **options)
         end
 
         # Convenience wrapper: admin claims + UserContext.
         #
-        # @param user [Object]
+        # @param user [Object] user-like object used to build the claims
         # @param admin_group [String]
+        # @param options [Hash] forwarded to {#build_pundit_user_context}
         # @return [Verikloak::Pundit::UserContext]
-        def build_admin_user_context(user, admin_group: '/admin')
-          build_pundit_user_context(user, build_admin_claims(user, admin_group: admin_group))
+        def build_admin_user_context(user, admin_group: '/admin', **options)
+          build_pundit_user_context(build_admin_claims(user, admin_group: admin_group), **options)
         end
 
         # Convenience wrapper: user claims + UserContext.
         #
-        # @param user [Object]
+        # @param user [Object] user-like object used to build the claims
         # @param user_group [String]
+        # @param options [Hash] forwarded to {#build_pundit_user_context}
         # @return [Verikloak::Pundit::UserContext]
-        def build_user_user_context(user, user_group: '/user')
-          build_pundit_user_context(user, build_user_claims(user, user_group: user_group))
+        def build_user_user_context(user, user_group: '/user', **options)
+          build_pundit_user_context(build_user_claims(user, user_group: user_group), **options)
         end
       end
     end

data/lib/verikloak/rails/testing/middleware_stub.rb

@@ -11,6 +11,8 @@ module Verikloak
       # `env['verikloak.user']` and pass through to the next middleware.
       # The companion `verikloak.token` env key is also set when
       # available so controller helpers like `current_token` work.
+      # Custom `user_env_key` / `token_env_key` settings on
+      # `Verikloak::Rails.config` are honored automatically.
       #
       # Requires RSpec-style mocks (`allow_any_instance_of`). Load
       # `verikloak/rails/testing/rspec` to wire things up automatically,
@@ -47,14 +49,39 @@ module Verikloak
         end
 
         def install_passthrough_stub(middleware_class, claims, token)
+          # Env keys are resolved inside the stubbed call — i.e. when the
+          # request runs, not when the stub is installed — so configuration
+          # applied after `stub_verikloak_middleware` (an inner context or a
+          # lazily booted app setting custom env keys) still lines up with
+          # the controller helpers' request-time key resolution.
           allow_any_instance_of(middleware_class).to receive(:call) do |instance, env|
-            env['verikloak.user']  = claims
-            env['verikloak.token'] = token if token
+            env[stub_user_env_key]  = claims
+            env[stub_token_env_key] = token if token
             inner_app = instance.instance_variable_get(:@app)
             inner_app.call(env)
           end
         end
 
+        # Resolve env keys from the live configuration so the stub follows
+        # custom `user_env_key` / `token_env_key` settings. Falls back to the
+        # core defaults when verikloak-rails is not fully loaded.
+        def stub_user_env_key
+          return ::Verikloak::Rails.config.effective_user_env_key if verikloak_rails_config?
+
+          'verikloak.user'
+        end
+
+        def stub_token_env_key
+          return ::Verikloak::Rails.config.effective_token_env_key if verikloak_rails_config?
+
+          'verikloak.token'
+        end
+
+        def verikloak_rails_config?
+          ::Verikloak::Rails.respond_to?(:config) &&
+            ::Verikloak::Rails.config.respond_to?(:effective_user_env_key)
+        end
+
         def bff_middleware_loaded?
           defined?(::Verikloak::BFF::HeaderGuard)
         end

data/lib/verikloak/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Verikloak
   module Rails
-    VERSION = '1.1.0'
+    VERSION = '1.2.0'
   end
 end

data/lib/verikloak/rails.rb

@@ -5,6 +5,7 @@ require 'verikloak/rails/skip_path_checker'
 require 'verikloak/rails/configuration'
 require 'verikloak/rails/error_renderer'
 require 'verikloak/rails/controller'
+require 'verikloak/rails/request_store_mirror'
 require 'verikloak/rails/railtie'
 
 module Verikloak

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak-rails
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.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: 'Rails integration for Verikloak: auto middleware, helpers, and standardized
   JSON errors.'
 executables: []
@@ -79,9 +79,11 @@ files:
 - lib/verikloak/rails/bff_configurator.rb
 - lib/verikloak/rails/configuration.rb
 - lib/verikloak/rails/controller.rb
+- lib/verikloak/rails/controller/error_handling.rb
 - lib/verikloak/rails/error_renderer.rb
 - lib/verikloak/rails/railtie.rb
 - lib/verikloak/rails/railtie_logger.rb
+- lib/verikloak/rails/request_store_mirror.rb
 - lib/verikloak/rails/skip_path_checker.rb
 - lib/verikloak/rails/testing.rb
 - lib/verikloak/rails/testing/claims_builder.rb
@@ -96,7 +98,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/1.1.0
+  documentation_uri: https://rubydoc.info/gems/verikloak-rails/1.2.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: