verikloak-pundit 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ece87ad9829b8123230d55d270c57bf399c3b16a5c8d38e7e89e3c2e31a3f63
-  data.tar.gz: 511d923d115ebe33105099ab61b0390e46288e013ecca8a455c9b896abf9d5e7
+  metadata.gz: 6936cd5efb5ccaecf789b427db2f7cd09f358604ba334f592f3e5079ac6501c4
+  data.tar.gz: 37db6dc08acd9918bebb15bd8dbb32320e00661ffc81b1b40c85850ec1c0822c
 SHA512:
-  metadata.gz: acf8d7d1a12e3b12ce152deb35c4c506adbb6a9002cbc30aa9293ed8c5577c838692795c27edc332802db689a5af9ae55dcf6e9b06abd18f8b3cf77e06f1a331
-  data.tar.gz: 9a514dcdd539c3a9e1ef7abbcfb858df7a8899ecb71985972b8a9199d2153efd434f06e3cbb798daf5ea9a990c7e41b750f189dbf01b0149208ead90b0f39072
+  metadata.gz: 120391c41f3f769ce49d7bddd83bed04b010ea367d8b63ddedb5de4610f9f8a6600f29f56f84c929b2209e4c26d6825a3d774ae1f32c20f16dd6d53378d5f9bf
+  data.tar.gz: a6d8babf7f27a842105fcc9ba44a42f9c73a21c45eeb486339c9afddca8aa1a6df97720c944407945ebd02a7918455bbb235b3e74de39025594d50d8babf0014

data/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.2.0] - 2025-09-21
+
+### Added
+- Allow `permission_role_scope = :all_resources` to respect the new
+  `permission_resource_clients` whitelist so only approved clients contribute
+  to permission checks.
+- Document verikloak-bff and verikloak-audience integration patterns,
+  including `env_claims_key` examples and role naming guidance.
+
+### Changed
+- `UserContext` now snapshots the configuration at initialization to keep
+  behavior consistent even if `Verikloak::Pundit.configure` runs mid-request.
+- Bump the minimum `verikloak` runtime dependency to `>= 0.1.5` to pick up
+  client whitelist support.
+
+## [0.1.1] - 2025-09-20
+
+### Added
+- Optional exposure flag for the Rails helper (`expose_helper_method`) so claims can stay hidden from views when not needed.
+- Continuous integration job that installs the latest `verikloak` and `verikloak-rails` releases and executes `integration/check.rb` to verify compatibility.
+- Detailed operational guidance in README/ERRORS explaining the risks of `permission_role_scope = :all_resources` and helper exposure.
+
+### Changed
+- Configuration publishing now duplicates nested structures and freezes them, reducing race conditions when reconfiguring at runtime.
+- `integration/check.rb` now exercises realm/resource roles, permission scopes, and helper exposure to catch regressions early.
+
 ## [0.1.0] - 2025-09-20
 
 ### Added

data/README.md

@@ -11,8 +11,6 @@ Pundit integration for the **Verikloak** family. This gem maps **Keycloak roles*
 - Provides a `pundit_user` hook so policies can use `user.has_role?(:admin)` etc.
 - Keeps role mapping **configurable** (project-specific mappings differ).
 
-
-
 ## Features
 
 - **UserContext**: lightweight wrapper around JWT claims
@@ -88,10 +86,38 @@ Verikloak::Pundit.configure do |c|
   # Permission mapping scope for `user.has_permission?`:
   #   :default_resource => realm roles + default client roles (recommended)
   #   :all_resources    => realm roles + roles from all clients in resource_access
+  #                         (enabling this broadens permissions to every resource client;
+  #                          review the upstream role assignments before turning it on)
   c.permission_role_scope = :default_resource
+  # Optional whitelist of resource clients when `permission_role_scope = :all_resources`.
+  # Leaving this as nil keeps the legacy "all clients" behavior, while providing
+  # an explicit list (e.g., %w[rails-api verikloak-bff]) limits which clients can
+  # contribute roles to permission checks.
+  c.permission_resource_clients = nil
+
+  # Expose `verikloak_claims` to views via helper_method (Rails only)
+  c.expose_helper_method = true
 end
 ```
 
+### Working with other Verikloak gems
+
+- **verikloak-bff**: When your Rails application sits behind the BFF, the access
+  token presented to verikloak-pundit typically originates from the BFF
+  (e.g. via the `x-verikloak-user` header). Make sure your Rack stack stores the
+  decoded claims under the same `env_claims_key` configured above (the default
+  `"verikloak.user"` works out of the box with `verikloak-bff >= 0.3`). If the
+  BFF issues tokens for multiple downstream services, set
+  `permission_resource_clients` to the limited list of clients whose roles should
+  affect Rails-side authorization to avoid accidentally inheriting permissions
+  meant for other services.
+- **verikloak-audience**: Audience services often mint resource roles with a
+  service-specific prefix (for example, `audience-service:editor`). Align your
+  `role_map` keys with that naming convention so `user.has_permission?` resolves
+  correctly. If Audience adds its own client entry inside `resource_access`, add
+  that client id to `permission_resource_clients` when you need to consume those
+  roles from Rails.
+
 ## Non-Rails / custom usage
 
 ```ruby
@@ -114,12 +140,37 @@ docker compose run --rm dev rspec
 docker compose run --rm dev rubocop -a
 ```
 
+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
+docker compose run --rm -e BUNDLE_FROZEN=0 dev bash -lc '
+  cd integration && \
+  apk add --no-cache --virtual .integration-build-deps \
+    build-base \
+    linux-headers \
+    openssl-dev \
+    yaml-dev && \
+  bundle config set --local path vendor/bundle && \
+  bundle install --jobs 4 --retry 3 && \
+  bundle exec ruby check.rb && \
+  apk del .integration-build-deps
+'
+```
+
 ## Contributing
 Bug reports and pull requests are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
 
 ## Security
 If you find a security vulnerability, please follow the instructions in [SECURITY.md](SECURITY.md).
 
+### Operational guidance
+- 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.
+
 ## License
 This project is licensed under the [MIT License](LICENSE).
 

data/lib/generators/verikloak/pundit/install/install_generator.rb

@@ -11,7 +11,6 @@ module Verikloak
         desc 'Creates Verikloak Pundit initializer and a base ApplicationPolicy (optional).'
 
         # Skip creating application_policy.rb
-        # @return [Boolean]
         class_option :skip_policy, type: :boolean, default: false, desc: 'Do not create application_policy.rb'
 
         # Create the initializer file under config/initializers.

data/lib/verikloak/pundit/configuration.rb

@@ -16,13 +16,67 @@ module Verikloak
     #   @return [Array<String,Proc>] path inside JWT claims to reach resource roles
     # @!attribute permission_role_scope
     #   @return [Symbol] :default_resource or :all_resources for permission mapping scope
+    # @!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 expose_helper_method
+    #   @return [Boolean] whether to register `verikloak_claims` as a Rails helper method
     class Configuration
       attr_accessor :resource_client, :role_map, :env_claims_key,
                     :realm_roles_path, :resource_roles_path,
-                    :permission_role_scope
+                    :permission_role_scope, :permission_resource_clients,
+                    :expose_helper_method
 
-      # Initialize default configuration values.
-      def initialize
+      # Build a new configuration, optionally copying values from another
+      # configuration so callers can mutate a safe duplicate.
+      #
+      # @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)
+      end
+
+      # Duplicate the configuration via Ruby's `dup`, ensuring the new instance
+      # receives freshly-copied nested state.
+      #
+      # @param other [Configuration]
+      def initialize_copy(other)
+        super
+        initialize_from(other)
+      end
+
+      # Freeze the configuration and its nested structures to prevent runtime
+      # mutations once it is published to the global state. Returns `self` to
+      # allow chaining inside callers.
+      #
+      # @return [Configuration]
+      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
+        @permission_resource_clients = freeze_permission_clients(@permission_resource_clients)
+        @expose_helper_method = !@expose_helper_method.nil? && @expose_helper_method
+        freeze
+      end
+
+      private
+
+      # Populate default values that mirror the gem's out-of-the-box behavior.
+      def initialize_defaults
         @resource_client   = 'rails-api'
         @role_map          = {} # e.g., { admin: :manage_all }
         @env_claims_key    = 'verikloak.user'
@@ -32,6 +86,115 @@ module Verikloak
         # 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
+      end
+
+      # Copy configuration fields from another instance, duplicating mutable
+      # structures so future writes do not leak across instances.
+      #
+      # @param other [Configuration]
+      def initialize_from(other)
+        @resource_client = dup_string(other.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
+      end
+
+      # Duplicate and freeze a string value, returning `nil` when appropriate.
+      #
+      # @param value [String, nil]
+      # @return [String, nil]
+      def freeze_string(value)
+        return nil if value.nil?
+
+        dup_string(value).freeze
+      end
+
+      # Recursively duplicate a hash, cloning nested structures so the copy can
+      # be mutated safely.
+      #
+      # @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
+      end
+
+      # Duplicate a string guardingly, returning `nil` when no value is present.
+      #
+      # @param value [String, nil]
+      # @return [String, nil]
+      def dup_string(value)
+        return nil if value.nil?
+
+        value.dup
+      end
+
+      # Recursively duplicate an array while copying nested structures.
+      #
+      # @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
+      end
+
+      # Check whether a value can be safely duplicated using `dup`.
+      #
+      # @param value [Object]
+      # @return [Boolean]
+      def duplicable?(value)
+        return false if value.nil?
+        return false if [true, false].include?(value)
+        return false if value.is_a?(Symbol) || value.is_a?(Numeric) || value.is_a?(Proc)
+
+        value.respond_to?(:dup)
+      end
+
+      # Normalize and freeze the configured permission clients list.
+      #
+      # @param value [Array<String, Symbol>, nil]
+      # @return [Array<String>, nil]
+      def freeze_permission_clients(value)
+        array = dup_array(value)
+        return nil if array.nil?
+
+        array.compact.map(&:to_s).uniq.freeze
       end
     end
   end

data/lib/verikloak/pundit/controller.rb

@@ -7,7 +7,10 @@ module Verikloak
       # Hook used by Rails to include helper methods in views when available.
       # @param base [Class]
       def self.included(base)
-        base.helper_method :verikloak_claims if base.respond_to?(:helper_method)
+        return unless base.respond_to?(:helper_method)
+
+        config = Verikloak::Pundit.config
+        base.helper_method :verikloak_claims if config.expose_helper_method
       end
 
       # Pundit hook returning the UserContext built from Rack env claims.

data/lib/verikloak/pundit/user_context.rb

@@ -4,15 +4,17 @@ module Verikloak
   module Pundit
     # Lightweight wrapper around Keycloak claims for Pundit policies.
     class UserContext
-      attr_reader :claims, :resource_client
+      attr_reader :claims, :resource_client, :config
 
       # Create a new user context from JWT claims.
       #
       # @param claims [Hash] JWT claims issued by Keycloak
       # @param resource_client [String] default resource client name for resource roles
-      def initialize(claims, resource_client: Verikloak::Pundit.config.resource_client)
+      # @param config [Verikloak::Pundit::Configuration] configuration snapshot to use
+      def initialize(claims, resource_client: nil, config: nil)
+        @config = config || Verikloak::Pundit.config
         @claims = claims || {}
-        @resource_client = resource_client.to_s
+        @resource_client = (resource_client || @config.resource_client).to_s
       end
 
       # Subject identifier from claims.
@@ -30,7 +32,7 @@ module Verikloak
       # Realm-level roles from claims based on configuration path.
       # @return [Array<String>]
       def realm_roles
-        path = resolve_path(Verikloak::Pundit.config.realm_roles_path)
+        path = resolve_path(config.realm_roles_path)
         Array(claims.dig(*path))
       end
 
@@ -40,7 +42,7 @@ module Verikloak
       # @return [Array<String>]
       def resource_roles(client = resource_client)
         client = client.to_s
-        path = resolve_path(Verikloak::Pundit.config.resource_roles_path, client: client)
+        path = resolve_path(config.resource_roles_path, client: client)
         Array(claims.dig(*path))
       end
 
@@ -82,7 +84,7 @@ module Verikloak
       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, Verikloak::Pundit.config) }
+        mapped = roles.map { |r| RoleMapper.map(r, config) }
         mapped.map(&:to_sym).include?(pr)
       end
 
@@ -91,8 +93,9 @@ module Verikloak
       # @param env [Hash] Rack environment
       # @return [UserContext]
       def self.from_env(env)
-        claims = env[Verikloak::Pundit.config.env_claims_key]
-        new(claims)
+        config = Verikloak::Pundit.config
+        claims = env[config.env_claims_key]
+        new(claims, config: config)
       end
 
       private
@@ -108,9 +111,9 @@ module Verikloak
           when Proc
             # Support lambdas that accept (config) or (config, client)
             if seg.arity >= 2
-              seg.call(Verikloak::Pundit.config, client).to_s
+              seg.call(config, client).to_s
             else
-              seg.call(Verikloak::Pundit.config).to_s
+              seg.call(config).to_s
             end
           else
             seg.to_s
@@ -121,7 +124,7 @@ module Verikloak
       # Resolve resource roles based on configured permission scope.
       # @return [Array<String>]
       def resource_roles_scope
-        case Verikloak::Pundit.config.permission_role_scope&.to_sym
+        case config.permission_role_scope&.to_sym
         when :all_resources
           resource_roles_all_clients
         else
@@ -137,7 +140,22 @@ module Verikloak
 
         # Bypass configured path lambda (which targets the default client)
         # and gather roles from all clients explicitly.
-        access.values.flat_map { |entry| Array(entry['roles']) }
+        access.each_with_object([]) do |(client_id, entry), roles|
+          next unless permission_client_allowed?(client_id)
+
+          roles.concat(Array(entry['roles']))
+        end
+      end
+
+      # Check whether the given client is allowed for permission scope.
+      #
+      # @param client_id [String]
+      # @return [Boolean]
+      def permission_client_allowed?(client_id)
+        whitelist = config.permission_resource_clients
+        return true if whitelist.nil?
+
+        whitelist.include?(client_id.to_s)
       end
     end
   end

data/lib/verikloak/pundit/version.rb

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

data/lib/verikloak/pundit.rb

@@ -19,16 +19,32 @@ module Verikloak
       # @yield [Configuration] Yields the configuration instance for mutation.
       # @return [Configuration] the current configuration after applying changes
       def configure
-        @config ||= Configuration.new
-        yield @config if block_given?
-        @config
+        new_config = nil
+        config_mutex.synchronize do
+          current = @config&.dup || Configuration.new
+          yield current if block_given?
+          new_config = current.finalize!
+          @config = new_config
+        end
+        new_config
       end
 
       # Access the current configuration without mutating it.
       #
       # @return [Configuration]
       def config
-        @config ||= Configuration.new
+        config_mutex.synchronize do
+          @config ||= Configuration.new.finalize!
+        end
+      end
+
+      private
+
+      # Mutex protecting configuration reads/writes to maintain thread safety.
+      #
+      # @return [Mutex]
+      def config_mutex
+        @config_mutex ||= Mutex.new
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak-pundit
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - taiyaky
@@ -49,20 +49,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.2
+        version: 0.1.5
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: 1.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.2
+        version: 0.1.5
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: 1.0.0
 description: Maps Keycloak JWT roles to a Pundit-friendly UserContext with helpers
   and a Rails generator.
 executables: []
@@ -92,7 +92,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.1.0
+  documentation_uri: https://rubydoc.info/gems/verikloak-pundit/0.2.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: