verikloak-pundit 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6936cd5efb5ccaecf789b427db2f7cd09f358604ba334f592f3e5079ac6501c4
-  data.tar.gz: 37db6dc08acd9918bebb15bd8dbb32320e00661ffc81b1b40c85850ec1c0822c
+  metadata.gz: 40f6167b3a558b93b98bcabbe529acc50b4ffef682d9fc02375ea85c8f9ce26f
+  data.tar.gz: 31ca32b4215cc022474e5f385a56f3c6b189137665cdb76b5f748842c12cdce2
 SHA512:
-  metadata.gz: 120391c41f3f769ce49d7bddd83bed04b010ea367d8b63ddedb5de4610f9f8a6600f29f56f84c929b2209e4c26d6825a3d774ae1f32c20f16dd6d53378d5f9bf
-  data.tar.gz: a6d8babf7f27a842105fcc9ba44a42f9c73a21c45eeb486339c9afddca8aa1a6df97720c944407945ebd02a7918455bbb235b3e74de39025594d50d8babf0014
+  metadata.gz: e7c270e29f9872f007ebd3863946cb665bc4d62973cfcf7e2f635533ae1e20eaba64511f474e7a33bb3dd6040a751fca2b25027db4457690bdafd9333c05cac1
+  data.tar.gz: 81887295612920fe124f1947e1ecc9a91143beda4097ece57015739bb1e28481d5027a2d75e1e77545f4e98c7b5c4cd5c2fab43e86c5a8b386c965dfbe0696ac

data/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.2.2] - 2025-09-28
+
+### Changed
+- Expanded generator specs to cover pre-existing `application_policy.rb` files and verify directory creation semantics, reinforcing the install generator contract.
+- Clarified the dummy generator base `desc` signature to mirror the Rails API and avoid warning noise in tests.
+- Stubbed helper and policy spec deprecation warnings so suite output stays clean while still asserting the message payload.
+
+## [0.2.1] - 2025-09-27
+
+### Added
+- `Verikloak::Pundit.reset!` helper to restore default configuration, easing test teardown.
+- `Verikloak::Pundit::Delegations` shared module consolidating role and permission helper methods.
+- `Verikloak::Pundit::ClaimUtils` for consistent claim normalization across entry points.
+
+### Changed
+- `UserContext` memoizes role lookups and caches mapped permissions to reduce repeated work inside policies.
+- `UserContext` now normalizes inputs via `ClaimUtils` and supports symbolized permission comparison for mixed role map values.
+- Configuration duplication derives from a unified `deep_dup`, ensuring hash keys are copied and nested structures remain isolated.
+- README documents the new delegations module, configuration reset helper, and deprecation guidance.
+
 ## [0.2.0] - 2025-09-21
 
 ### Added

data/README.md

@@ -14,7 +14,7 @@ Pundit integration for the **Verikloak** family. This gem maps **Keycloak roles*
 ## Features
 
 - **UserContext**: lightweight wrapper around JWT claims
-- **Helpers**: `has_role?`, `in_group?`, `resource_role?(client, role)`
+- **Delegations**: `has_role?`, `in_group?`, `resource_role?(client, role)` helpers for controllers and policies
 - **RoleMapper**: optional map from Keycloak roles → domain permissions
 - **Controller integration**: `pundit_user` provider for Rails controllers
 - **Generator**: `rails g verikloak:pundit:install` creates initializer + policy template (with `has_permission?` support for realm roles plus the configured resource scope)
@@ -140,6 +140,14 @@ docker compose run --rm dev rspec
 docker compose run --rm dev rubocop -a
 ```
 
+When writing specs, call `Verikloak::Pundit.reset!` in your test teardown to ensure configuration changes do not leak between examples:
+
+```ruby
+RSpec.configure do |config|
+  config.after { Verikloak::Pundit.reset! }
+end
+```
+
 An additional integration check exercises the gem together with the latest `verikloak` and `verikloak-rails` releases. This runs in CI automatically, and you can execute it locally with:
 
 ```bash

data/lib/verikloak/pundit/claim_utils.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Verikloak
+  module Pundit
+    # Helpers for coercing incoming claims payloads into safe Hashes.
+    module ClaimUtils
+      module_function
+
+      # Normalize incoming claims to a Hash to guard against odd payload types.
+      #
+      # @param claims [Object]
+      # @return [Hash]
+      def normalize(claims)
+        return {} if claims.nil?
+        return claims if claims.is_a?(Hash)
+
+        if claims.respond_to?(:to_hash)
+          coerced = claims.to_hash
+          return coerced if coerced.is_a?(Hash)
+        end
+
+        {}
+      rescue StandardError
+        {}
+      end
+    end
+  end
+end

data/lib/verikloak/pundit/configuration.rb

@@ -115,29 +115,33 @@ module Verikloak
         dup_string(value).freeze
       end
 
-      # Recursively duplicate a hash, cloning nested structures so the copy can
-      # be mutated safely.
+      # Deep duplicate any object, handling nested structures recursively.
+      #
+      # @param value [Object] The value to duplicate
+      # @return [Object] A deep copy of the value
+      def deep_dup(value)
+        case value
+        when nil
+          nil
+        when Hash
+          value.each_with_object({}) do |(key, element), copy|
+            copy[deep_dup(key)] = deep_dup(element)
+          end
+        when Array
+          value.map { |element| deep_dup(element) }
+        when String
+          value.dup
+        else
+          duplicable?(value) ? value.dup : value
+        end
+      end
+
+      # Duplicate a hash using deep duplication.
       #
       # @param value [Hash, nil]
       # @return [Hash, nil]
       def dup_hash(value)
-        return nil if value.nil?
-
-        copy = value.dup
-        copy.each do |key, element|
-          copy[key] =
-            case element
-            when Hash
-              dup_hash(element)
-            when Array
-              dup_array(element)
-            when String
-              dup_string(element)
-            else
-              duplicable?(element) ? element.dup : element
-            end
-        end
-        copy
+        deep_dup(value)
       end
 
       # Duplicate a string guardingly, returning `nil` when no value is present.
@@ -145,33 +149,15 @@ module Verikloak
       # @param value [String, nil]
       # @return [String, nil]
       def dup_string(value)
-        return nil if value.nil?
-
-        value.dup
+        deep_dup(value)
       end
 
-      # Recursively duplicate an array while copying nested structures.
+      # Duplicate an array using deep duplication.
       #
       # @param value [Array, nil]
       # @return [Array, nil]
       def dup_array(value)
-        return nil if value.nil?
-
-        copy = value.dup
-        return copy unless copy.respond_to?(:map)
-
-        copy.map do |element|
-          case element
-          when Hash
-            dup_hash(element)
-          when Array
-            dup_array(element)
-          when String
-            dup_string(element)
-          else
-            duplicable?(element) ? element.dup : element
-          end
-        end
+        deep_dup(value)
       end
 
       # Check whether a value can be safely duplicated using `dup`.

data/lib/verikloak/pundit/delegations.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Verikloak
+  module Pundit
+    # Shared role/permission delegations to expose consistent helpers.
+    module Delegations
+      # Check whether the user has a realm role.
+      # @param role [String, Symbol]
+      # @return [Boolean]
+      def has_role?(role) = user.has_role?(role) # rubocop:disable Naming/PredicatePrefix
+
+      # Check whether the user belongs to a group (alias to role).
+      # @param group [String, Symbol]
+      # @return [Boolean]
+      def in_group?(group) = user.in_group?(group)
+
+      # Check whether the user has a role for a specific resource client.
+      # @param client [String, Symbol]
+      # @param role [String, Symbol]
+      # @return [Boolean]
+      def resource_role?(client, role) = user.resource_role?(client, role)
+
+      # Check whether the user has a mapped permission.
+      # @param perm [String, Symbol]
+      # @return [Boolean]
+      def has_permission?(perm) = user.has_permission?(perm) # rubocop:disable Naming/PredicatePrefix
+    end
+  end
+end

data/lib/verikloak/pundit/helpers.rb

@@ -3,27 +3,21 @@
 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
-      # Check whether the user has a realm role.
-      # @param role [String, Symbol]
-      # @return [Boolean]
-      def has_role?(role) = user.has_role?(role) # rubocop:disable Naming/PredicatePrefix
+      include Delegations
 
-      # Check whether the user belongs to a group (alias to role).
-      # @param group [String, Symbol]
-      # @return [Boolean]
-      def in_group?(group) = user.in_group?(group)
-
-      # Check whether the user has a role for a specific resource client.
-      # @param client [String, Symbol]
-      # @param role [String, Symbol]
-      # @return [Boolean]
-      def resource_role?(client, role) = user.resource_role?(client, role)
-
-      # Check whether the user has a mapped permission.
-      # @param perm [String, Symbol]
-      # @return [Boolean]
-      def has_permission?(perm) = user.has_permission?(perm) # rubocop:disable Naming/PredicatePrefix
+      # 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

@@ -3,34 +3,25 @@
 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
 
-      # Check whether the user has a realm role.
-      # @param role [String, Symbol]
-      # @return [Boolean]
-      def has_role?(role) = user.has_role?(role) # rubocop:disable Naming/PredicatePrefix
-
-      # Check whether the user belongs to a group (alias to role).
-      # @param group [String, Symbol]
-      # @return [Boolean]
-      def in_group?(group) = user.in_group?(group)
-
-      # Check whether the user has a role for a specific resource client.
-      # @param client [String, Symbol]
-      # @param role [String, Symbol]
-      # @return [Boolean]
-      def resource_role?(client, role) = user.resource_role?(client, role)
-
-      # Check whether the user has a mapped permission.
-      # @param perm [String, Symbol]
-      # @return [Boolean]
-      def has_permission?(perm) = user.has_permission?(perm) # rubocop:disable Naming/PredicatePrefix
+      include Delegations
     end
   end
 end

data/lib/verikloak/pundit/user_context.rb

@@ -1,9 +1,18 @@
 # frozen_string_literal: true
 
+require 'set'
+
 module Verikloak
   module Pundit
     # Lightweight wrapper around Keycloak claims for Pundit policies.
     class UserContext
+      # JWT claim keys used internally
+      CLAIM_SUB = 'sub'
+      CLAIM_EMAIL = 'email'
+      CLAIM_PREFERRED_USERNAME = 'preferred_username'
+      CLAIM_RESOURCE_ACCESS = 'resource_access'
+      CLAIM_ROLES = 'roles'
+
       attr_reader :claims, :resource_client, :config
 
       # Create a new user context from JWT claims.
@@ -13,27 +22,29 @@ module Verikloak
       # @param config [Verikloak::Pundit::Configuration] configuration snapshot to use
       def initialize(claims, resource_client: nil, config: nil)
         @config = config || Verikloak::Pundit.config
-        @claims = claims || {}
+        @claims = ClaimUtils.normalize(claims)
         @resource_client = (resource_client || @config.resource_client).to_s
       end
 
       # Subject identifier from claims.
       # @return [String, nil]
       def sub
-        claims['sub']
+        claims[CLAIM_SUB]
       end
 
       # Email or preferred username from claims.
       # @return [String, nil]
       def email
-        claims['email'] || claims['preferred_username']
+        claims[CLAIM_EMAIL] || claims[CLAIM_PREFERRED_USERNAME]
       end
 
       # Realm-level roles from claims based on configuration path.
       # @return [Array<String>]
       def realm_roles
-        path = resolve_path(config.realm_roles_path)
-        Array(claims.dig(*path))
+        @realm_roles ||= begin
+          path = resolve_path(config.realm_roles_path)
+          Array(claims.dig(*path)).map(&:to_s).uniq.freeze
+        end
       end
 
       # Resource-level roles for a given client from claims based on configuration path.
@@ -42,8 +53,10 @@ module Verikloak
       # @return [Array<String>]
       def resource_roles(client = resource_client)
         client = client.to_s
-        path = resolve_path(config.resource_roles_path, client: client)
-        Array(claims.dig(*path))
+        (@resource_roles_cache ||= {})[client] ||= begin
+          path = resolve_path(config.resource_roles_path, client: client)
+          Array(claims.dig(*path)).map(&:to_s).uniq.freeze
+        end
       end
 
       # Check whether the user has a realm role.
@@ -51,8 +64,7 @@ module Verikloak
       # @param role [String, Symbol]
       # @return [Boolean]
       def has_role?(role) # rubocop:disable Naming/PredicatePrefix
-        r = role.to_s
-        realm_roles.include?(r)
+        realm_roles.include?(role.to_s)
       end
 
       # Alias to has_role? to align with group-based naming.
@@ -69,9 +81,7 @@ module Verikloak
       # @param role [String, Symbol]
       # @return [Boolean]
       def resource_role?(client, role)
-        client = client.to_s
-        r = role.to_s
-        resource_roles(client).include?(r)
+        resource_roles(client).include?(role.to_s)
       end
 
       # Check whether the user has a mapped permission.
@@ -82,10 +92,7 @@ module Verikloak
       # @param perm [String, Symbol] permission to check
       # @return [Boolean]
       def has_permission?(perm) # rubocop:disable Naming/PredicatePrefix
-        pr = perm.to_sym
-        roles = realm_roles + resource_roles_scope
-        mapped = roles.map { |r| RoleMapper.map(r, config) }
-        mapped.map(&:to_sym).include?(pr)
+        permission_set.include?(normalize_to_symbol(perm))
       end
 
       # Build a user context from Rack env using configured claims key.
@@ -94,7 +101,7 @@ module Verikloak
       # @return [UserContext]
       def self.from_env(env)
         config = Verikloak::Pundit.config
-        claims = env[config.env_claims_key]
+        claims = env&.fetch(config.env_claims_key, nil)
         new(claims, config: config)
       end
 
@@ -135,15 +142,18 @@ module Verikloak
       # Collect resource roles from all clients under resource_access.
       # @return [Array<String>]
       def resource_roles_all_clients
-        access = claims['resource_access']
-        return [] unless access.is_a?(Hash)
+        @resource_roles_all_clients ||= begin
+          access = claims[CLAIM_RESOURCE_ACCESS]
+          if access.is_a?(Hash)
+            roles = access.each_with_object([]) do |(client_id, entry), acc|
+              next unless permission_client_allowed?(client_id)
 
-        # Bypass configured path lambda (which targets the default client)
-        # and gather roles from all clients explicitly.
-        access.each_with_object([]) do |(client_id, entry), roles|
-          next unless permission_client_allowed?(client_id)
-
-          roles.concat(Array(entry['roles']))
+              acc.concat(Array(entry[CLAIM_ROLES]))
+            end
+            roles.map(&:to_s).uniq.freeze
+          else
+            [].freeze
+          end
         end
       end
 
@@ -157,6 +167,52 @@ module Verikloak
 
         whitelist.include?(client_id.to_s)
       end
+
+      # Cached permission lookup set combining realm and configured resource scopes.
+      # @return [Set<Symbol>]
+      def permission_set
+        @permission_set ||= build_permission_set.freeze
+      end
+
+      # Build the permission set from roles and role mappings.
+      # @return [Set<Symbol>]
+      def build_permission_set
+        roles = realm_roles + resource_roles_scope
+        permissions = Set.new
+
+        roles.each do |role|
+          mapped_permission = RoleMapper.map(role, config)
+          symbol_permission = normalize_to_symbol(mapped_permission)
+          permissions << symbol_permission if symbol_permission
+        end
+
+        permissions
+      end
+
+      # Normalize a value to a symbol, handling various types safely.
+      # @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)
+        case value
+        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
+        end
+      rescue StandardError
+        nil
+      end
     end
   end
 end

data/lib/verikloak/pundit/version.rb

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

data/lib/verikloak/pundit.rb

@@ -4,6 +4,8 @@
 require_relative 'pundit/version'
 require_relative 'pundit/configuration'
 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'
@@ -38,6 +40,15 @@ module Verikloak
         end
       end
 
+      # Reset configuration to defaults. Useful for test suites.
+      #
+      # @return [void]
+      def reset!
+        config_mutex.synchronize do
+          @config = nil
+        end
+      end
+
       private
 
       # Mutex protecting configuration reads/writes to maintain thread safety.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak-pundit
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - taiyaky
@@ -49,7 +49,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.5
+        version: 0.2.0
     - - "<"
       - !ruby/object:Gem::Version
         version: 1.0.0
@@ -59,7 +59,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.5
+        version: 0.2.0
     - - "<"
       - !ruby/object:Gem::Version
         version: 1.0.0
@@ -77,8 +77,10 @@ files:
 - lib/generators/verikloak/pundit/install/templates/initializer.rb
 - lib/verikloak-pundit.rb
 - lib/verikloak/pundit.rb
+- lib/verikloak/pundit/claim_utils.rb
 - 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
@@ -92,7 +94,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.2.0
+  documentation_uri: https://rubydoc.info/gems/verikloak-pundit/0.2.2
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: