verikloak-pundit 0.4.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89c932324252efb900c44575ab54dffb96e1d6300c958d267217e612952664bc
-  data.tar.gz: aa4409c08ff3af4e48960980c684988975054a6d5a574e209a64ad4889a58f61
+  metadata.gz: bf2182c6f85bdb89c0d109fcabc9fdcf0141b9b9dfef32dd4d953694e9f3d239
+  data.tar.gz: d93f6833adda5312d3485c9f9aa310777c35341207f0bda7fd54c1667f7fa18a
 SHA512:
-  metadata.gz: 34e87036e92f4c0af62a2238298bbafc0ed61337c44b92a4c0533dc142ebd4983ca8d2040caa4a3566f6ca9233cf14b26ebe19f3302e5e15805111bf222df0ee
-  data.tar.gz: 532af9d0e912a5fc23df9859ccc42cc5853d4da78a3a6349f45f8a200979588273306186f5a3532cbed50f3f8b1706ab3ebe7db38c3d508eeab6e704894dd9e1
+  metadata.gz: ba7e80788a77d28ba624e9c5b41da2427c9d42eecb44de665d6c88a6f21e1b42f7fe0b387964219182d35ba336cac664066b4be983068aa78cfb0f6855d0badb
+  data.tar.gz: e876d7ddf9c83469c6f9eb8423786392d4f45abd687c37d7e835d41d013aa2ee133a6d1840de8f171562908065d579a85f6dce7bb1eb9f9cb49648eba35e5c18

data/CHANGELOG.md

@@ -7,6 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.1.0] - 2026-07-03
+
+### Added
+- **`strict_permissions` configuration**: when enabled, `has_permission?` only grants permissions defined as `role_map` values; unmapped role names no longer act as implicit permissions. Recommended together with `permission_role_scope = :all_resources`
+
+### Changed
+- Minimum `verikloak` dependency raised to `~> 1.1`, aligned with the verikloak 1.1.0 release (compatibility with verikloak-rails 1.2.0 verified: default user env key and the `verikloak.configure` initializer ordering are unchanged)
+- **Helper exposure is evaluated at call time**: `verikloak_claims` is exposed to views through a helper module that consults `expose_helper_method` on each call, so the setting takes effect regardless of initializer ordering. When disabled, views receive `nil` instead of raising `NoMethodError`
+- **Reentrant configuration lock**: the internal config `Mutex` was replaced with a `Monitor`, so reading `Verikloak::Pundit.config` inside a `configure` block no longer raises `ThreadError`
+- `role_map` values are validated at assignment: Symbols, Strings, and `nil` are accepted; anything else raises `ArgumentError` so misconfiguration surfaces at boot (v1.0.0 silently coerced such values via `to_s`)
+- An explicit `nil` value in `role_map` now revokes the role's implicit permission even when `strict_permissions` is off (previously a `nil` mapping was treated as unmapped and the bare role name fell through as a permission)
+- Boolean configuration flags (`strict_permissions`, `expose_helper_method`) are coerced to strict `true`/`false` on finalize
+
+### Deprecated
+- `RoleMapper.map`: use `RoleMapper.permission_for` instead. `map` now delegates to it, so strict mode and explicit `nil` revocations are honored consistently by every caller
+
+### Security
+- Updated locked development/CI dependencies to resolve all known advisories (25 Dependabot alerts): rack 3.2.6, activesupport 8.1.3, concurrent-ruby 1.3.7, faraday 2.14.3, jwt 3.2.0, json 2.20.0. The `pundit ~> 2.3` runtime constraint is unchanged (the `verikloak` constraint bump is listed under Changed)
+
+### Removed
+- **Unused `rack` runtime dependency**: the gem only reads the Rack env Hash and uses no Rack APIs (`rack-test` was likewise removed from development dependencies)
+
+### Fixed
+- **Per-client `resource_role?` with the default configuration**: the default `resource_roles_path` lambda ignored the requested client, so `resource_role?(client, role)` always inspected the default resource client's roles — granting or denying based on the wrong client. The default path lambda now receives `(config, client)` and resolves the explicitly requested client
+- **Path lambdas with optional or variadic parameters**: custom `resource_roles_path` lambdas such as `->(cfg, client = nil) { ... }` (negative arity) never received the requested client and silently fell back to the default resource client. Zero-argument procs are now called as thunks, single-argument procs receive `(config)`, and every other signature receives `(config, client)`
+- ERRORS.md no longer claims configuration is not thread-safe (stale since the v1.0.0 thread-safety fix)
+
+### Internal
+- CI: added a Ruby compatibility matrix (3.1 / 3.2 / 3.3, mirroring the verikloak repo) that runs the suite against `gemfiles/compat.gemfile` with a fresh per-Ruby resolution; the docker-based job continues to cover the development Ruby (3.4)
+- Refactoring: unified deep-copy helpers in `Configuration` (removed the `dup_hash`/`dup_string`/`dup_array` wrappers and the redundant `dup` override), simplified `RoleMapper.map` and `UserContext#normalize_to_symbol`
+- Test coverage: added specs for `Delegations`, `ClaimUtils`, `Railtie.sync_with_verikloak_rails`, `UserContext.from_env`, the `KEYCLOAK_RESOURCE_CLIENT` ENV fallback, and strict permission mode. Spec files are now linted by RuboCop, and Rails-stubbing specs share a scoped `stub_require` helper instead of mutating `$LOADED_FEATURES`
+
+---
+
+## [1.0.0] - 2026-02-15
+
+### Fixed
+- **Thread-safety**: `config_mutex` is now eagerly initialized at load time. The previous `||= Mutex.new` pattern was racy — two threads could create separate Mutex instances, defeating mutual exclusion
+
+### Removed
+- **BREAKING**: `Verikloak::Pundit::Policy` and `Verikloak::Pundit::Helpers` deprecated modules have been removed as announced in their deprecation notices. Use `Verikloak::Pundit::Delegations` directly instead
+
+### Changed
+- **BREAKING**: Minimum `verikloak` dependency raised to `~> 1.0`
+- **v1.0.0 stable release**: Public API is now considered stable under Semantic Versioning
+
+---
+
 ## [0.4.0] - 2026-02-15
 
 ### Changed

data/README.md

@@ -90,6 +90,42 @@ Verikloak::Pundit.configure do |c|
 end
 ```
 
+The synchronization runs after your `config/initializers` have been applied
+(verikloak-rails registers its `verikloak.configure` initializer with
+`after: :load_config_initializers`), so a `user_env_key` customized in your
+verikloak-rails initializer is picked up automatically.
+
+### Strict permission mapping
+
+By default, `has_permission?` treats unmapped role names as permissions
+themselves: a bare Keycloak role `admin` satisfies `has_permission?(:admin)`
+even without a `role_map` entry. To only grant permissions that appear as
+`role_map` values, enable strict mode:
+
+```ruby
+Verikloak::Pundit.configure do |c|
+  c.role_map = { admin: :manage_all }
+  c.strict_permissions = true
+end
+```
+
+With strict mode on, roles without a `role_map` entry contribute no
+permissions. This is recommended when combining
+`permission_role_scope = :all_resources` with tokens shared across services,
+so role names minted for other clients cannot accidentally satisfy
+permission checks.
+
+`role_map` values must be Symbols, Strings, or `nil` — any other type raises
+an `ArgumentError` when assigned. Mapping a role to `nil` explicitly revokes
+its implicit permission even when strict mode is off:
+
+```ruby
+Verikloak::Pundit.configure do |c|
+  # `legacy_role` in a token no longer satisfies has_permission?(:legacy_role)
+  c.role_map = { legacy_role: nil }
+end
+```
+
 ### Working with other Verikloak gems
 
 - **verikloak-bff**: When your Rails application sits behind the BFF, the access
@@ -318,7 +354,8 @@ If you find a security vulnerability, please follow the instructions in [SECURIT
 
 - Enabling `permission_role_scope = :all_resources` pulls roles from every Keycloak client in `resource_access`. Review the granted roles carefully to ensure you are not expanding permissions beyond what the application expects.
 - Combine `permission_role_scope = :all_resources` with `permission_resource_clients` to explicitly opt-in the clients that may contribute permissions. Leaving the whitelist blank (the default) reverts to the legacy behavior of trusting every client in the token.
-- Leaving `expose_helper_method = true` exposes `verikloak_claims` to the Rails view layer. If the claims include personal or sensitive data, consider switching it to `false` and pass only the minimum required information through controller-provided helpers.
+- Enable `strict_permissions = true` so `has_permission?` only grants permissions defined as `role_map` values. Without it, any role name in the token doubles as a permission, which is convenient but broadens what a token can satisfy.
+- Leaving `expose_helper_method = true` exposes `verikloak_claims` to the Rails view layer. If the claims include personal or sensitive data, consider switching it to `false` and pass only the minimum required information through controller-provided helpers. The setting is consulted every time the view helper is called, so it can be changed in any initializer regardless of load order; when disabled, the view helper returns `nil`.
 
 ## License
 This project is licensed under the [MIT License](LICENSE).

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

@@ -13,16 +13,23 @@ Verikloak::Pundit.configure do |c|
   # Resource client (optional - falls back to ENV['KEYCLOAK_RESOURCE_CLIENT'] or 'rails-api')
   # c.resource_client = ENV.fetch('KEYCLOAK_RESOURCE_CLIENT', 'rails-api')
 
-  # Role to permission mapping (optional)
+  # Role to permission mapping (optional).
+  # Values must be Symbols or Strings; map a role to nil to explicitly
+  # revoke its implicit permission.
   # c.role_map = {
   #   admin:  :manage_all,
   #   editor: :write_notes,
   #   reader: :read_notes
   # }
 
+  # Only grant permissions defined as role_map values (optional, default: false).
+  # When true, bare role names no longer act as implicit permissions in
+  # has_permission?. Recommended with permission_role_scope = :all_resources.
+  # c.strict_permissions = true
+
   # Uncomment to customize JWT claims path and scope (usually not needed):
   # c.env_claims_key = 'verikloak.user'
   # c.realm_roles_path = %w[realm_access roles]
-  # c.resource_roles_path = ['resource_access', ->(cfg) { cfg.resource_client }, 'roles']
+  # c.resource_roles_path = ['resource_access', ->(cfg, client) { client || cfg.resource_client }, 'roles']
   # c.permission_role_scope = :default_resource  # or :all_resources
 end

data/lib/verikloak/pundit/configuration.rb

@@ -7,7 +7,9 @@ module Verikloak
     # @!attribute resource_client
     #   @return [String] default Keycloak resource client used for resource roles
     # @!attribute role_map
-    #   @return [Hash{Symbol=>Symbol,String}] mapping from roles to permissions
+    #   @return [Hash{Symbol=>Symbol,String,nil}] mapping from roles to
+    #     permissions; a nil value explicitly revokes the role's implicit
+    #     permission
     # @!attribute env_claims_key
     #   @return [String] Rack env key where claims are stored (when using verikloak/verikloak-rails)
     # @!attribute realm_roles_path
@@ -19,21 +21,30 @@ module Verikloak
     # @!attribute permission_resource_clients
     #   @return [Array<String>, nil] list of resource clients allowed when
     #     {#permission_role_scope} is `:all_resources`. `nil` permits every client.
+    # @!attribute strict_permissions
+    #   @return [Boolean] when true, `has_permission?` only grants permissions that
+    #     appear as values in {#role_map}; unmapped role names no longer act as
+    #     implicit permissions
     # @!attribute expose_helper_method
-    #   @return [Boolean] whether to register `verikloak_claims` as a Rails helper method
+    #   @return [Boolean] whether `verikloak_claims` is exposed to Rails views
     class Configuration
       attr_accessor :env_claims_key,
                     :realm_roles_path, :resource_roles_path,
                     :permission_role_scope, :permission_resource_clients,
-                    :expose_helper_method
+                    :strict_permissions, :expose_helper_method
 
       attr_reader :role_map
       attr_writer :resource_client
 
       # Set the role map, normalizing keys to symbols for consistent lookup.
+      # Values must be Symbols, Strings, or nil (an explicit nil revokes the
+      # role's implicit permission); anything else raises at assignment time
+      # so misconfiguration surfaces at boot instead of as silently missing
+      # permissions.
       #
       # @param value [Hash]
       # @return [void]
+      # @raise [ArgumentError] when a value is neither Symbol, String, nor nil
       def role_map=(value)
         @role_map = normalize_role_map(value)
       end
@@ -45,34 +56,37 @@ module Verikloak
         @resource_client || ENV.fetch('KEYCLOAK_RESOURCE_CLIENT', 'rails-api')
       end
 
-      # Build a new configuration, optionally copying values from another
-      # configuration so callers can mutate a safe duplicate.
+      # Build a new configuration populated with default values, optionally
+      # copying values from another configuration so callers can mutate a
+      # safe duplicate. The `copy_from` parameter is kept for backward
+      # compatibility with the v1.0.0 signature; `dup` is the idiomatic way
+      # to copy.
       #
       # @param copy_from [Configuration, nil]
       def initialize(copy_from = nil)
-        if copy_from
-          initialize_from(copy_from)
-        else
-          initialize_defaults
-        end
-      end
-
-      # Create a deep-ish copy that can be safely mutated without affecting the
-      # source configuration. `dup` is overridden so the object returned from
-      # `Verikloak::Pundit.config.dup` behaves as expected.
-      #
-      # @return [Configuration]
-      def dup
-        self.class.new(self)
+        @resource_client   = nil # Falls back to ENV['KEYCLOAK_RESOURCE_CLIENT'] or 'rails-api'
+        @role_map          = {} # e.g., { admin: :manage_all }
+        @env_claims_key    = 'verikloak.user'
+        @realm_roles_path  = %w[realm_access roles]
+        # The lambda receives (config, client) so that an explicitly requested
+        # client (e.g. resource_role?(:other, :role)) resolves to that client's
+        # entry instead of always falling back to the default resource client.
+        @resource_roles_path = ['resource_access', ->(cfg, client) { client || cfg.resource_client }, 'roles']
+        # :default_resource (realm + default client), :all_resources (realm + all clients)
+        @permission_role_scope = :default_resource
+        @permission_resource_clients = nil
+        @strict_permissions = false
+        @expose_helper_method = true
+        copy_state_from(copy_from) if copy_from
       end
 
-      # Duplicate the configuration via Ruby's `dup`, ensuring the new instance
-      # receives freshly-copied nested state.
+      # Duplicate the configuration via Ruby's `dup`/`clone`, ensuring the new
+      # instance receives freshly-copied (and unfrozen) nested state.
       #
       # @param other [Configuration]
       def initialize_copy(other)
         super
-        initialize_from(other)
+        copy_state_from(other)
       end
 
       # Freeze the configuration and its nested structures to prevent runtime
@@ -83,55 +97,53 @@ module Verikloak
       def finalize!
         @resource_client = freeze_string(@resource_client)
         @env_claims_key = freeze_string(@env_claims_key)
-        @role_map = dup_hash(@role_map).freeze
-        @realm_roles_path = dup_array(@realm_roles_path).freeze
-        @resource_roles_path = dup_array(@resource_roles_path).freeze
+        @role_map = deep_dup(@role_map).freeze
+        @realm_roles_path = deep_dup(@realm_roles_path).freeze
+        @resource_roles_path = deep_dup(@resource_roles_path).freeze
         @permission_resource_clients = freeze_permission_clients(@permission_resource_clients)
-        @expose_helper_method = !@expose_helper_method.nil? && @expose_helper_method
+        # Coerce flags to strict booleans based on truthiness
+        @strict_permissions = @strict_permissions ? true : false
+        @expose_helper_method = @expose_helper_method ? true : false
         freeze
       end
 
       private
 
-      # Populate default values that mirror the gem's out-of-the-box behavior.
-      def initialize_defaults
-        @resource_client   = nil # Falls back to ENV['KEYCLOAK_RESOURCE_CLIENT'] or 'rails-api'
-        @role_map          = {} # e.g., { admin: :manage_all }
-        @env_claims_key    = 'verikloak.user'
-        @realm_roles_path  = %w[realm_access roles]
-        # rubocop:disable Style/SymbolProc -- we need a Proc object here, not block pass
-        @resource_roles_path = ['resource_access', ->(cfg) { cfg.resource_client }, 'roles']
-        # rubocop:enable Style/SymbolProc
-        # :default_resource (realm + default client), :all_resources (realm + all clients)
-        @permission_role_scope = :default_resource
-        @permission_resource_clients = nil
-        @expose_helper_method = true
+      # Copy all configuration state from another instance, deep-duplicating
+      # nested structures (and reading the raw @resource_client rather than
+      # the getter, to preserve its ENV fallback behavior) so the copy can be
+      # mutated without affecting the source.
+      #
+      # @param other [Configuration]
+      # @return [void]
+      def copy_state_from(other)
+        @resource_client = deep_dup(other.instance_variable_get(:@resource_client))
+        @role_map = deep_dup(other.role_map)
+        @env_claims_key = deep_dup(other.env_claims_key)
+        @realm_roles_path = deep_dup(other.realm_roles_path)
+        @resource_roles_path = deep_dup(other.resource_roles_path)
+        @permission_role_scope = other.permission_role_scope
+        @permission_resource_clients = deep_dup(other.permission_resource_clients)
+        @strict_permissions = other.strict_permissions
+        @expose_helper_method = other.expose_helper_method
       end
 
-      # Normalize role_map keys to symbols for consistent lookup.
+      # Normalize role_map keys to symbols and validate value types.
       #
       # @param map [Hash, nil]
       # @return [Hash]
+      # @raise [ArgumentError] when a value is neither Symbol, String, nor nil
       def normalize_role_map(map)
         return {} unless map.is_a?(Hash)
 
-        map.transform_keys(&:to_sym)
-      end
+        map.each do |key, value|
+          next if value.nil? || value.is_a?(Symbol) || value.is_a?(String)
 
-      # Copy configuration fields from another instance, duplicating mutable
-      # structures so future writes do not leak across instances.
-      #
-      # @param other [Configuration]
-      def initialize_from(other)
-        # Copy the raw instance variable, not the getter, to preserve ENV fallback behavior
-        @resource_client = dup_string(other.instance_variable_get(:@resource_client))
-        @role_map = dup_hash(other.role_map)
-        @env_claims_key = dup_string(other.env_claims_key)
-        @realm_roles_path = dup_array(other.realm_roles_path)
-        @resource_roles_path = dup_array(other.resource_roles_path)
-        @permission_role_scope = other.permission_role_scope
-        @permission_resource_clients = dup_array(other.permission_resource_clients)
-        @expose_helper_method = other.expose_helper_method
+          raise ArgumentError,
+                "role_map value for #{key.inspect} must be a Symbol, a String, " \
+                "or nil (explicit revocation); got #{value.class}"
+        end
+        map.transform_keys(&:to_sym)
       end
 
       # Duplicate and freeze a string value, returning `nil` when appropriate.
@@ -141,7 +153,7 @@ module Verikloak
       def freeze_string(value)
         return nil if value.nil?
 
-        dup_string(value).freeze
+        deep_dup(value).freeze
       end
 
       # Deep duplicate any object, handling nested structures recursively.
@@ -165,30 +177,6 @@ module Verikloak
         end
       end
 
-      # Duplicate a hash using deep duplication.
-      #
-      # @param value [Hash, nil]
-      # @return [Hash, nil]
-      def dup_hash(value)
-        deep_dup(value)
-      end
-
-      # Duplicate a string guardingly, returning `nil` when no value is present.
-      #
-      # @param value [String, nil]
-      # @return [String, nil]
-      def dup_string(value)
-        deep_dup(value)
-      end
-
-      # Duplicate an array using deep duplication.
-      #
-      # @param value [Array, nil]
-      # @return [Array, nil]
-      def dup_array(value)
-        deep_dup(value)
-      end
-
       # Check whether a value can be safely duplicated using `dup`.
       #
       # @param value [Object]
@@ -206,7 +194,7 @@ module Verikloak
       # @param value [Array<String, Symbol>, nil]
       # @return [Array<String>, nil]
       def freeze_permission_clients(value)
-        array = dup_array(value)
+        array = deep_dup(value)
         return nil if array.nil?
 
         array.compact.map(&:to_s).uniq.freeze

data/lib/verikloak/pundit/controller.rb

@@ -4,13 +4,27 @@ module Verikloak
   module Pundit
     # Rails controller mixin providing `pundit_user` and claims accessor.
     module Controller
-      # Hook used by Rails to include helper methods in views when available.
+      # View-facing helpers registered on helper-capable controllers.
+      #
+      # Exposure is decided at call time (not include time) so that
+      # `expose_helper_method` set in `config/initializers` is honored even
+      # when ActionController loads before application initializers run.
+      module ViewHelpers
+        # Access raw Verikloak claims from the controller, or nil when
+        # exposure to views is disabled via configuration.
+        #
+        # @return [Hash, nil]
+        def verikloak_claims
+          return nil unless Verikloak::Pundit.config.expose_helper_method
+
+          controller&.verikloak_claims
+        end
+      end
+
+      # Hook used by Rails to register view helpers when available.
       # @param base [Class]
       def self.included(base)
-        return unless base.respond_to?(:helper_method)
-
-        config = Verikloak::Pundit.config
-        base.helper_method :verikloak_claims if config.expose_helper_method
+        base.helper(ViewHelpers) if base.respond_to?(:helper)
       end
 
       # Pundit hook returning the UserContext built from Rack env claims.

data/lib/verikloak/pundit/railtie.rb

@@ -14,7 +14,10 @@ module Verikloak
       end
 
       # Synchronize configuration with verikloak-rails when available.
-      # Runs after verikloak-rails configuration is applied.
+      # verikloak-rails defines `initializer 'verikloak.configure',
+      # after: :load_config_initializers`, so this hook runs after both
+      # verikloak-rails' configuration and the app's config/initializers
+      # have been applied.
       initializer 'verikloak_pundit.sync_configuration', after: 'verikloak.configure' do
         Verikloak::Pundit::Railtie.sync_with_verikloak_rails if defined?(Verikloak::Rails)
       end

data/lib/verikloak/pundit/role_mapper.rb

@@ -8,13 +8,30 @@ module Verikloak
 
       # Map a Keycloak role to a domain permission via configuration.
       #
+      # @deprecated Use {.permission_for} instead. This method now delegates
+      #   to it so that strict mode and explicit nil revocations are honored
+      #   consistently by every caller.
       # @param role [String, Symbol] Role name from JWT claims
       # @param config [Configuration] Configuration providing the role_map
-      # @return [String, Symbol] Mapped permission (or the role itself if unmapped)
+      # @return [String, Symbol, nil] see {.permission_for}
       def map(role, config)
-        return role unless config.role_map && !config.role_map.empty?
+        permission_for(role, config)
+      end
+
+      # Resolve the permission granted by a role, honoring strict mode.
+      # A role explicitly mapped to nil grants nothing even when strict mode
+      # is off — an explicit revocation of the role's implicit permission.
+      #
+      # @param role [String, Symbol] Role name from JWT claims
+      # @param config [Configuration] Configuration providing role_map and strict_permissions
+      # @return [String, Symbol, nil] Mapped permission, the role itself when
+      #   unmapped and strict mode is off, or nil when unmapped in strict mode
+      #   or explicitly mapped to nil
+      def permission_for(role, config)
+        key = role.to_sym
+        return config.role_map[key] if config.role_map.key?(key)
 
-        config.role_map[role.to_sym] || role
+        config.strict_permissions ? nil : role
       end
     end
   end

data/lib/verikloak/pundit/user_context.rb

@@ -124,11 +124,15 @@ module Verikloak
         Array(path_config).map do |seg|
           case seg
           when Proc
-            # Support lambdas that accept (config) or (config, client)
-            if seg.arity >= 2
-              seg.call(config, client).to_s
-            else
-              seg.call(config).to_s
+            # Zero-argument procs are called as thunks and single-argument
+            # procs receive (config). Every other signature — including
+            # optional/variadic ones such as ->(cfg, client = nil)
+            # (arity -2) — receives (config, client), so an explicitly
+            # requested client is never silently dropped.
+            case seg.arity
+            when 0 then seg.call.to_s
+            when 1 then seg.call(config).to_s
+            else seg.call(config, client).to_s
             end
           else
             seg.to_s
@@ -190,15 +194,18 @@ module Verikloak
         permissions = Set.new
 
         roles.each do |role|
-          mapped_permission = RoleMapper.map(role, config)
-          symbol_permission = normalize_to_symbol(mapped_permission)
+          permission = RoleMapper.permission_for(role, config)
+          symbol_permission = normalize_to_symbol(permission)
           permissions << symbol_permission if symbol_permission
         end
 
         permissions
       end
 
-      # Normalize a value to a symbol, handling various types safely.
+      # Normalize a value to a symbol. Only Symbols and non-empty Strings are
+      # convertible; nil (a strict-mode miss or an explicit role_map
+      # revocation) and any other type yield nil so no permission is granted.
+      #
       # @param value [Object] The value to convert to a symbol
       # @return [Symbol, nil] The symbol representation, or nil if not convertible
       def normalize_to_symbol(value)
@@ -206,21 +213,8 @@ module Verikloak
         when Symbol
           value
         when String
-          return nil if value.empty?
-
-          value.to_sym
-        else
-          if value.respond_to?(:to_sym)
-            value.to_sym
-          elsif value.respond_to?(:to_s)
-            text = value.to_s
-            return nil if text.empty?
-
-            text.to_sym
-          end
+          value.empty? ? nil : value.to_sym
         end
-      rescue StandardError
-        nil
       end
     end
   end

data/lib/verikloak/pundit/version.rb

@@ -5,6 +5,6 @@ module Verikloak
     # Gem version for verikloak-pundit.
     #
     # @return [String]
-    VERSION = '0.4.0'
+    VERSION = '1.1.0'
   end
 end

data/lib/verikloak/pundit.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'monitor'
+
 # Verikloak::Pundit provides Pundit integration over Keycloak claims.
 require_relative 'pundit/version'
 require_relative 'pundit/configuration'
@@ -7,14 +9,19 @@ require_relative 'pundit/role_mapper'
 require_relative 'pundit/delegations'
 require_relative 'pundit/claim_utils'
 require_relative 'pundit/user_context'
-require_relative 'pundit/helpers'
 require_relative 'pundit/controller'
-require_relative 'pundit/policy'
 require_relative 'pundit/railtie' if defined?(Rails::Railtie)
 
 module Verikloak
   # Pundit integration namespace
   module Pundit
+    # Eagerly-initialized lock to protect configuration reads/writes.
+    # Using ||= inside a method is NOT thread-safe — two threads can race
+    # past the nil-check and create separate lock instances. A reentrant
+    # Monitor (rather than Mutex) allows `config` to be read from within a
+    # `configure` block without raising ThreadError.
+    @config_lock = Monitor.new
+
     class << self
       # Configure the library at runtime.
       #
@@ -22,7 +29,7 @@ module Verikloak
       # @return [Configuration] the current configuration after applying changes
       def configure
         new_config = nil
-        config_mutex.synchronize do
+        config_lock.synchronize do
           current = @config&.dup || Configuration.new
           yield current if block_given?
           new_config = current.finalize!
@@ -35,7 +42,7 @@ module Verikloak
       #
       # @return [Configuration]
       def config
-        config_mutex.synchronize do
+        config_lock.synchronize do
           @config ||= Configuration.new.finalize!
         end
       end
@@ -44,19 +51,18 @@ module Verikloak
       #
       # @return [void]
       def reset!
-        config_mutex.synchronize do
+        config_lock.synchronize do
           @config = nil
         end
       end
 
       private
 
-      # Mutex protecting configuration reads/writes to maintain thread safety.
+      # Reentrant lock protecting configuration reads/writes.
+      # Eagerly initialized at load time (see module body above).
       #
-      # @return [Mutex]
-      def config_mutex
-        @config_mutex ||= Mutex.new
-      end
+      # @return [Monitor]
+      attr_reader :config_lock
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak-pundit
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 1.1.0
 platform: ruby
 authors:
 - taiyaky
@@ -23,46 +23,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.3'
-- !ruby/object:Gem::Dependency
-  name: rack
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '2.2'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '4.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '2.2'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: verikloak
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.4.0
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.0.0
+        version: '1.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.4.0
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.0.0
+        version: '1.1'
 description: Maps Keycloak JWT roles to a Pundit-friendly UserContext with helpers
   and a Rails generator.
 executables: []
@@ -81,8 +55,6 @@ files:
 - lib/verikloak/pundit/configuration.rb
 - lib/verikloak/pundit/controller.rb
 - lib/verikloak/pundit/delegations.rb
-- lib/verikloak/pundit/helpers.rb
-- lib/verikloak/pundit/policy.rb
 - lib/verikloak/pundit/railtie.rb
 - lib/verikloak/pundit/role_mapper.rb
 - lib/verikloak/pundit/user_context.rb
@@ -94,7 +66,7 @@ metadata:
   source_code_uri: https://github.com/taiyaky/verikloak-pundit
   changelog_uri: https://github.com/taiyaky/verikloak-pundit/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/taiyaky/verikloak-pundit/issues
-  documentation_uri: https://rubydoc.info/gems/verikloak-pundit/0.4.0
+  documentation_uri: https://rubydoc.info/gems/verikloak-pundit/1.1.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:

data/lib/verikloak/pundit/helpers.rb

@@ -1,23 +0,0 @@
-# frozen_string_literal: true
-
-module Verikloak
-  module Pundit
-    # Helpers expose convenient delegations to the policy `user`.
-    #
-    # @deprecated Use {Delegations} directly instead. This module will be removed in v1.0.0.
-    module Helpers
-      include Delegations
-
-      # Warn consumers when the deprecated helper module is included.
-      #
-      # @param base [Module] module or class including this helper
-      # @return [void]
-      def self.included(base)
-        warn '[DEPRECATED] Verikloak::Pundit::Helpers is deprecated. ' \
-             'Include Verikloak::Pundit::Delegations directly instead. ' \
-             'This will be removed in v1.0.0.'
-        super
-      end
-    end
-  end
-end

data/lib/verikloak/pundit/policy.rb

@@ -1,27 +0,0 @@
-# frozen_string_literal: true
-
-module Verikloak
-  module Pundit
-    # Policy mixin to delegate common helpers to the `user` context.
-    #
-    # @deprecated Use {Delegations} directly instead. This module will be removed in v1.0.0.
-    module Policy
-      # Warn consumers when the deprecated policy mixin is included.
-      #
-      # @param base [Module] module or class including this policy mixin
-      # @return [void]
-      def self.included(base)
-        warn '[DEPRECATED] Verikloak::Pundit::Policy is deprecated. ' \
-             'Include Verikloak::Pundit::Delegations directly instead. ' \
-             'This will be removed in v1.0.0.'
-        base.extend(ClassMethods)
-        super
-      end
-
-      # Placeholder for future class-level helpers
-      module ClassMethods; end
-
-      include Delegations
-    end
-  end
-end