verikloak-pundit 0.2.2 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40f6167b3a558b93b98bcabbe529acc50b4ffef682d9fc02375ea85c8f9ce26f
-  data.tar.gz: 31ca32b4215cc022474e5f385a56f3c6b189137665cdb76b5f748842c12cdce2
+  metadata.gz: 7a29b74665fc8bf023f1b6aeea48575b55227a5a4c0d8deae339b02651885814
+  data.tar.gz: fda84a30fa38d00819b5b00c4d72a2a8858355c4faaba2dcef8ec1a956df7753
 SHA512:
-  metadata.gz: e7c270e29f9872f007ebd3863946cb665bc4d62973cfcf7e2f635533ae1e20eaba64511f474e7a33bb3dd6040a751fca2b25027db4457690bdafd9333c05cac1
-  data.tar.gz: 81887295612920fe124f1947e1ecc9a91143beda4097ece57015739bb1e28481d5027a2d75e1e77545f4e98c7b5c4cd5c2fab43e86c5a8b386c965dfbe0696ac
+  metadata.gz: 928b8e33c892000b074a6c8fe12aece68a14140d5994b9f13640d074b39130f560a49e3fabc1a07917e0678d89e6f8a1b797a73dcb3f579b5ffeef622398050d
+  data.tar.gz: 7c418267c589a0a13a0aafdbb2cc48c4fa4cefb87a61d8051a3257e3250790b7be48ac79b7e3fc96421c4ad1a966d0ba511277d67e872d7e7c6f5e6fced09412

data/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [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
+- **Database User Integration Guide**: New README section documenting the custom `UserContext` pattern for combining JWT claims with database user models, including controller setup and policy examples.
+- **Delegations Module Documentation**: Comprehensive usage guide for `Verikloak::Pundit::Delegations`, covering requirements, custom `UserContext` compatibility, and nil user handling patterns.
+
+### Changed
+- Clarified controller setup examples to use `Verikloak::Pundit::Controller` (this gem) instead of `Verikloak::Rails::Controller` (verikloak-rails gem).
+- Added explicit notes about method origins (`verikloak_claims` vs `current_user_claims`) for users combining multiple Verikloak gems.
+- Enhanced nil user handling documentation with `safe_has_role?` helper pattern for public endpoints.
+- Bump minimum `verikloak` dependency from `>= 0.2.0` to `>= 0.3.0` to align with latest upstream releases.
+- Update Ruby version to 3.4.8 in development environment.
+
 ## [0.2.2] - 2025-09-28
 
 ### Changed

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
@@ -118,6 +107,177 @@ end
   that client id to `permission_resource_clients` when you need to consume those
   roles from Rails.
 
+## Integrating with Database User Models
+
+### Overview
+
+`Verikloak::Pundit::UserContext` wraps JWT claims for use in Pundit policies. However, real applications often need to access database User models for additional attributes (e.g., `user.admin?`, `user.organization_id`).
+
+### Custom UserContext Pattern
+
+Create a custom UserContext that holds both JWT claims and a database user reference:
+
+```ruby
+# app/lib/app_user_context.rb
+class AppUserContext < Verikloak::Pundit::UserContext
+  attr_reader :db_user
+
+  def initialize(claims, db_user: nil, resource_client: nil, config: nil)
+    super(claims, resource_client: resource_client, config: config)
+    @db_user = db_user
+  end
+
+  # Delegate database user methods
+  delegate :admin?, :organization_id, :active?, to: :db_user, allow_nil: true
+
+  # Custom authorization helpers
+  def owns?(record)
+    return false unless db_user && record
+    record.respond_to?(:user_id) && db_user.id == record.user_id
+  end
+
+  def same_organization?(record)
+    return false unless db_user && record
+    record.respond_to?(:organization_id) && db_user.organization_id == record.organization_id
+  end
+end
+```
+
+### Controller Setup
+
+Override `pundit_user` in your ApplicationController. This example assumes you are using `verikloak-rails`, which provides `current_user_claims` and related helpers:
+
+```ruby
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::API
+  include Pundit::Authorization
+  include Verikloak::Pundit::Controller  # Provides pundit_user and verikloak_claims
+
+  # If using verikloak-rails for JWT verification:
+  # include Verikloak::Rails::Controller  # Provides current_user_claims, current_subject, etc.
+
+  def pundit_user
+    @pundit_user ||= AppUserContext.new(
+      verikloak_claims,  # From Verikloak::Pundit::Controller
+      db_user: find_or_create_current_user,
+      config: Verikloak::Pundit.config
+    )
+  end
+
+  private
+
+  def find_or_create_current_user
+    # Extract subject from claims
+    sub = verikloak_claims&.dig('sub')
+    return nil unless sub
+
+    User.find_or_create_by(sub: sub) do |user|
+      user.email = verikloak_claims&.dig('email')
+      user.name = verikloak_claims&.dig('name')
+    end
+  end
+end
+```
+
+> **Note:** If you are also using `verikloak-rails`, you can use its `current_user_claims` method instead of `verikloak_claims`. Both provide access to the JWT claims from the Rack environment.
+
+### Policy Example
+
+Now your policies can use both JWT claims and database attributes:
+
+```ruby
+# app/policies/document_policy.rb
+class DocumentPolicy < ApplicationPolicy
+  def show?
+    # Combine JWT roles with database attributes
+    user.has_role?(:admin) || user.owns?(record) || user.same_organization?(record)
+  end
+
+  def update?
+    user.admin? || user.owns?(record)  # Uses delegated db_user.admin?
+  end
+
+  def destroy?
+    user.has_role?(:admin) && user.active?  # JWT role + DB attribute
+  end
+end
+```
+
+## Delegations Module
+
+### Overview
+
+`Verikloak::Pundit::Delegations` provides shortcut methods for role and permission checks in policies.
+
+### Usage
+
+Include in your ApplicationPolicy to access helpers directly:
+
+```ruby
+class ApplicationPolicy
+  include Verikloak::Pundit::Delegations
+
+  # Now you can use:
+  # - has_role?(:admin)        instead of user.has_role?(:admin)
+  # - in_group?(:editors)      instead of user.in_group?(:editors)
+  # - resource_role?(client, role)
+  # - has_permission?(:manage_all)
+end
+```
+
+### Requirements
+
+- The policy must have a `user` method that returns a `Verikloak::Pundit::UserContext` (or subclass)
+- If `user` is `nil`, delegation methods will raise `NoMethodError`
+
+### Compatibility with Custom UserContext
+
+Delegations work with any class that inherits from `Verikloak::Pundit::UserContext`:
+
+```ruby
+# Works with AppUserContext (shown above)
+class DocumentPolicy < ApplicationPolicy
+  include Verikloak::Pundit::Delegations
+
+  def update?
+    has_role?(:admin) || has_permission?(:write_documents)
+  end
+end
+```
+
+### Handling nil user
+
+For policies that may receive `nil` users (e.g., public endpoints), you **must** guard against nil before calling delegation methods:
+
+```ruby
+class PublicDocumentPolicy < ApplicationPolicy
+  def show?
+    return true if record.public?
+    return false unless user  # Guard against nil user before using delegations
+
+    has_role?(:viewer)
+  end
+end
+```
+
+Alternatively, create a helper method in your `ApplicationPolicy`:
+
+```ruby
+class ApplicationPolicy
+  include Verikloak::Pundit::Delegations
+
+  private
+
+  def authenticated?
+    !user.nil?
+  end
+
+  def safe_has_role?(role)
+    authenticated? && has_role?(role)
+  end
+end
+```
+
 ## Non-Rails / custom usage
 
 ```ruby
@@ -148,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,20 @@ 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 :role_map, :env_claims_key,
                     :realm_roles_path, :resource_roles_path,
                     :permission_role_scope, :permission_resource_clients,
                     :expose_helper_method
 
+      attr_writer :resource_client
+
+      # 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 +86,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]

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
+        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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak-pundit
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.4
 platform: ruby
 authors:
 - taiyaky
@@ -49,7 +49,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 0.3.0
     - - "<"
       - !ruby/object:Gem::Version
         version: 1.0.0
@@ -59,7 +59,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 0.3.0
     - - "<"
       - !ruby/object:Gem::Version
         version: 1.0.0
@@ -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.2
+  documentation_uri: https://rubydoc.info/gems/verikloak-pundit/0.2.4
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: