verikloak-pundit 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4618def320e58859e62b0562ac2d942a3e307a61b3c287bc3a748511c76a3d0
-  data.tar.gz: ce80df2707bf38a548ef51dc6ed68acd149e2c06b2ef02d2b0a20dc709040cbf
+  metadata.gz: 8a9cbde30c7f580f43089a171707034fc1d476bdc63cf358ee00a7e2ceffe48c
+  data.tar.gz: 4bda6971e321a4a46045523f1dd01a610cb6a95b28e47a01c665d24a38bdaaf8
 SHA512:
-  metadata.gz: 246e5840dc895ee184ef33d88ea92c5e73f58c6120217e2661e6757dd2539ee74f7ba2b2eb47502ca70115884a971ef11530458af6a8aa6f3900f96f70d1119e
-  data.tar.gz: 6d4762d24e1b90c71ea68a1642456a9b4f3132d6424ef9587bfc1f41d70c3f124ebb1c8e60ea49d273b3e73a1077ebaeac4106311e1244890a29d41af8169300
+  metadata.gz: 26364d453900ef0bd915eedda4567343b65d8e9adfd7c61e02e926c954ad8bcc778042c7432ea4878a8fa1173a7f7eedccd5cea009f384b042044a65fadd53ca
+  data.tar.gz: 57494f3d1b8de679d2fb81b3a3ba7eff5d8635cadf0f4ef19110f8bd9d6bc70010629ed7c64b6584524c580e8968041d3c0581cc7d0468f067c13f45e4bdc254

data/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.3.0] - 2026-01-01
+
+### Fixed
+- **ENV fallback preservation**: `Configuration#dup` now correctly preserves the `nil` state of `resource_client`, allowing ENV fallback to remain dynamic after duplication. Previously, duplicating a config would freeze the resolved ENV value.
+- **Non-hash resource_access entries**: `resource_roles_all_clients` now guards against malformed `resource_access` entries that are not hashes, preventing potential `NoMethodError`.
+
+### Changed
+- **role_map key normalization**: `role_map` keys are now automatically normalized to symbols when set. This allows users to configure with string keys (e.g., from YAML) while maintaining consistent symbol-based lookup in `RoleMapper`.
+- **pundit_user memoization**: `Controller#pundit_user` is now memoized with `@pundit_user ||=` to avoid creating multiple `UserContext` instances per request.
+
+---
+
+## [0.2.4] - 2026-01-01
+
+### Added
+- **Environment variable fallback**: `resource_client` now falls back to `ENV['KEYCLOAK_RESOURCE_CLIENT']` when not explicitly configured, enabling environment-based configuration.
+- **Auto-sync with verikloak-rails**: When used alongside `verikloak-rails`, `env_claims_key` is automatically synchronized from `Verikloak::Rails.config.user_env_key` if not explicitly set.
+
+### Changed
+- **Simplified initializer template**: Generator now produces a minimal initializer with commented examples instead of explicit defaults. Most settings work out of the box.
+- **README improvements**: Updated Configuration section with environment variables table, auto-configuration documentation, and removed redundant examples.
+- **Consistent Pundit include**: Quick Start examples now use `Pundit::Authorization` consistently.
+
 ## [0.2.3] - 2025-12-31
 
 ### Added

data/README.md

@@ -43,7 +43,7 @@ For error-handling guidance, see [ERRORS.md](ERRORS.md).
 ```ruby
 # app/controllers/application_controller.rb
 class ApplicationController < ActionController::API
-  include Pundit
+  include Pundit::Authorization
   include Verikloak::Pundit::Controller  # provides pundit_user
 
   # If you're also using verikloak-rails:
@@ -65,38 +65,28 @@ Where `user` is the **UserContext** provided by `pundit_user`.
 
 ## Configuration
 
+Most settings have sensible defaults and can be auto-configured. You only need to customize what's different for your application.
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `KEYCLOAK_RESOURCE_CLIENT` | Default resource client ID for resource roles | `"rails-api"` |
+
+### Auto-configuration with verikloak-rails
+
+When used alongside `verikloak-rails`, the following settings are automatically synchronized:
+
+- **`env_claims_key`**: Inherits from `Verikloak::Rails.config.user_env_key` if you haven't explicitly set it. This ensures both gems read claims from the same Rack env key.
+
+This means in most cases you can use a minimal initializer:
+
 ```ruby
-# config/initializers/verikloak_pundit.rb
 Verikloak::Pundit.configure do |c|
-  c.resource_client = "rails-api"   # default client for resource roles
-  c.role_map = {                    # optional role → permission mapping
+  c.role_map = {
     admin:  :manage_all,
-    editor: :write_notes,
-    reader: :read_notes
+    editor: :write_notes
   }
-  # Where to find claims in Rack env (when using verikloak/verikloak-rails)
-  c.env_claims_key = "verikloak.user"
-
-  # How to traverse JWT for roles
-  c.realm_roles_path    = %w[realm_access roles]                      # => claims["realm_access"]["roles"]
-  # Lambdas in the path may accept (cfg) or (cfg, client)
-  # where `client` is the argument passed to `user.resource_roles(client)`
-  c.resource_roles_path = ["resource_access", ->(cfg){ cfg.resource_client }, "roles"]
-
-  # 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
 ```
 
@@ -105,12 +95,11 @@ end
 - **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.
+  decoded claims under the same `env_claims_key` (default: `"verikloak.user"`,
+  which 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
@@ -319,35 +308,16 @@ RSpec.configure do |config|
 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
-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
+## 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.
+- 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

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

@@ -1,24 +1,28 @@
 # frozen_string_literal: true
 
 # Verikloak::Pundit initializer
-# Configure how to read roles from Keycloak claims and how to map them
-# into application permissions.
+#
+# Most settings are auto-configured from environment variables and verikloak-rails.
+# Uncomment and customize only what you need to override.
+#
+# Environment variables supported:
+#   KEYCLOAK_RESOURCE_CLIENT - resource client ID (default: 'rails-api')
+#
+# When used with verikloak-rails, env_claims_key is automatically synchronized.
 Verikloak::Pundit.configure do |c|
-  c.resource_client = ENV.fetch('KEYCLOAK_RESOURCE_CLIENT', 'rails-api')
-  c.role_map = {
-    # admin:  :manage_all,
-    # editor: :write_notes,
-    # reader: :read_notes
-  }
-  c.env_claims_key = 'verikloak.user'
-  # claims['realm_access']['roles']
-  c.realm_roles_path    = %w[realm_access roles]
-  # rubocop:disable Style/SymbolProc -- we need a Proc object here, not block pass
-  # claims['resource_access'][resource_client]['roles']
-  c.resource_roles_path = ['resource_access', ->(cfg) { cfg.resource_client }, 'roles']
-  # rubocop:enable Style/SymbolProc
-  # Permission mapping scope:
-  #   :default_resource => realm roles + default client roles (recommended)
-  #   :all_resources    => realm roles + roles from all clients in resource_access
-  c.permission_role_scope = :default_resource
+  # 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)
+  # c.role_map = {
+  #   admin:  :manage_all,
+  #   editor: :write_notes,
+  #   reader: :read_notes
+  # }
+
+  # 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.permission_role_scope = :default_resource  # or :all_resources
 end

data/lib/verikloak/pundit/configuration.rb

@@ -22,11 +22,29 @@ module Verikloak
     # @!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,
+      attr_accessor :env_claims_key,
                     :realm_roles_path, :resource_roles_path,
                     :permission_role_scope, :permission_resource_clients,
                     :expose_helper_method
 
+      attr_reader :role_map
+      attr_writer :resource_client
+
+      # Set the role map, normalizing keys to symbols for consistent lookup.
+      #
+      # @param value [Hash]
+      # @return [void]
+      def role_map=(value)
+        @role_map = normalize_role_map(value)
+      end
+
+      # Returns the resource client, falling back to ENV['KEYCLOAK_RESOURCE_CLIENT'] if not set.
+      #
+      # @return [String]
+      def resource_client
+        @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.
       #
@@ -77,7 +95,7 @@ module Verikloak
 
       # Populate default values that mirror the gem's out-of-the-box behavior.
       def initialize_defaults
-        @resource_client   = 'rails-api'
+        @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]
@@ -90,12 +108,23 @@ module Verikloak
         @expose_helper_method = true
       end
 
+      # Normalize role_map keys to symbols for consistent lookup.
+      #
+      # @param map [Hash, nil]
+      # @return [Hash]
+      def normalize_role_map(map)
+        return {} unless map.is_a?(Hash)
+
+        map.transform_keys(&:to_sym)
+      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)
+        # 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)

data/lib/verikloak/pundit/controller.rb

@@ -14,9 +14,10 @@ module Verikloak
       end
 
       # Pundit hook returning the UserContext built from Rack env claims.
+      # Memoized to avoid creating multiple instances per request.
       # @return [UserContext]
       def pundit_user
-        Verikloak::Pundit::UserContext.from_env(request.env)
+        @pundit_user ||= Verikloak::Pundit::UserContext.from_env(request.env)
       end
 
       # Access raw Verikloak claims from Rack env.

data/lib/verikloak/pundit/railtie.rb

@@ -12,6 +12,35 @@ module Verikloak
           include Verikloak::Pundit::Controller
         end
       end
+
+      # Synchronize configuration with verikloak-rails when available.
+      # Runs after verikloak-rails configuration is applied.
+      initializer 'verikloak_pundit.sync_configuration', after: 'verikloak.configure' do
+        Verikloak::Pundit::Railtie.sync_with_verikloak_rails if defined?(Verikloak::Rails)
+      end
+
+      class << self
+        # Sync env_claims_key with verikloak-rails configuration.
+        # Only applies if env_claims_key has not been explicitly set.
+        #
+        # @return [void]
+        def sync_with_verikloak_rails
+          return unless Verikloak::Rails.respond_to?(:config)
+
+          rails_config = Verikloak::Rails.config
+          return unless rails_config.respond_to?(:user_env_key) && rails_config.user_env_key
+
+          current_key = Verikloak::Pundit.config.env_claims_key
+          return unless current_key == 'verikloak.user'
+
+          # Use configure to properly update frozen config
+          Verikloak::Pundit.configure do |c|
+            c.env_claims_key = rails_config.user_env_key
+          end
+        rescue StandardError => e
+          warn "[verikloak-pundit] Failed to sync with verikloak-rails: #{e.message}"
+        end
+      end
     end
   end
 end

data/lib/verikloak/pundit/user_context.rb

@@ -43,7 +43,7 @@ module Verikloak
       def realm_roles
         @realm_roles ||= begin
           path = resolve_path(config.realm_roles_path)
-          Array(claims.dig(*path)).map(&:to_s).uniq.freeze
+          extract_roles(path)
         end
       end
 
@@ -55,7 +55,7 @@ module Verikloak
         client = client.to_s
         (@resource_roles_cache ||= {})[client] ||= begin
           path = resolve_path(config.resource_roles_path, client: client)
-          Array(claims.dig(*path)).map(&:to_s).uniq.freeze
+          extract_roles(path)
         end
       end
 
@@ -107,6 +107,14 @@ module Verikloak
 
       private
 
+      # Extract roles from claims at the given path.
+      #
+      # @param path [Array<String>]
+      # @return [Array<String>]
+      def extract_roles(path)
+        Array(claims.dig(*path)).map(&:to_s).uniq.freeze
+      end
+
       # Resolve a configured path into concrete dig segments.
       #
       # @param path_config [Array<String, Proc>]
@@ -146,6 +154,7 @@ module Verikloak
           access = claims[CLAIM_RESOURCE_ACCESS]
           if access.is_a?(Hash)
             roles = access.each_with_object([]) do |(client_id, entry), acc|
+              next unless entry.is_a?(Hash)
               next unless permission_client_allowed?(client_id)
 
               acc.concat(Array(entry[CLAIM_ROLES]))

data/lib/verikloak/pundit/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak-pundit
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.0
 platform: ruby
 authors:
 - taiyaky
@@ -94,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.3
+  documentation_uri: https://rubydoc.info/gems/verikloak-pundit/0.3.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: