verikloak-pundit 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ece87ad9829b8123230d55d270c57bf399c3b16a5c8d38e7e89e3c2e31a3f63
-  data.tar.gz: 511d923d115ebe33105099ab61b0390e46288e013ecca8a455c9b896abf9d5e7
+  metadata.gz: 9062ddd03a6b118971608756c82d1299dc4b509d7219d289aefbeaf381c8e49e
+  data.tar.gz: f2c2a0e9a236c454aabd9316b04ee6e1e98860f6d2db3d8e3863fb826d92a29f
 SHA512:
-  metadata.gz: acf8d7d1a12e3b12ce152deb35c4c506adbb6a9002cbc30aa9293ed8c5577c838692795c27edc332802db689a5af9ae55dcf6e9b06abd18f8b3cf77e06f1a331
-  data.tar.gz: 9a514dcdd539c3a9e1ef7abbcfb858df7a8899ecb71985972b8a9199d2153efd434f06e3cbb798daf5ea9a990c7e41b750f189dbf01b0149208ead90b0f39072
+  metadata.gz: b2a830375513deb2e8d4b350ffb7960fb95a6c58d5b45af7c519b45cd6086ffd21230af26a89921fca57528e48275e4bf4be59d96a2c45794a11d262c7fe80c3
+  data.tar.gz: deebae419df84ced4bb9ff0a9181847155db0adeb08f6b8cfb8319c6b2f50cd99cbd8e2dc2fa89417d15f2ab198c8e262503be630ab9ec3daf1ca58c5de7aeef

data/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [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,7 +86,12 @@ 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
+
+  # Expose `verikloak_claims` to views via helper_method (Rails only)
+  c.expose_helper_method = true
 end
 ```
 
@@ -114,12 +117,33 @@ 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.
+- 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/verikloak/pundit/configuration.rb

@@ -16,13 +16,62 @@ 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 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, :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
+        @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 +81,102 @@ module Verikloak
         # rubocop:enable Style/SymbolProc
         # :default_resource (realm + default client), :all_resources (realm + all clients)
         @permission_role_scope = :default_resource
+        @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
+        @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
     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/version.rb

@@ -5,6 +5,6 @@ module Verikloak
     # Gem version for verikloak-pundit.
     #
     # @return [String]
-    VERSION = '0.1.0'
+    VERSION = '0.1.1'
   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.1.1
 platform: ruby
 authors:
 - taiyaky
@@ -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.1.1
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: