verikloak-pundit 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40f6167b3a558b93b98bcabbe529acc50b4ffef682d9fc02375ea85c8f9ce26f
-  data.tar.gz: 31ca32b4215cc022474e5f385a56f3c6b189137665cdb76b5f748842c12cdce2
+  metadata.gz: a4618def320e58859e62b0562ac2d942a3e307a61b3c287bc3a748511c76a3d0
+  data.tar.gz: ce80df2707bf38a548ef51dc6ed68acd149e2c06b2ef02d2b0a20dc709040cbf
 SHA512:
-  metadata.gz: e7c270e29f9872f007ebd3863946cb665bc4d62973cfcf7e2f635533ae1e20eaba64511f474e7a33bb3dd6040a751fca2b25027db4457690bdafd9333c05cac1
-  data.tar.gz: 81887295612920fe124f1947e1ecc9a91143beda4097ece57015739bb1e28481d5027a2d75e1e77545f4e98c7b5c4cd5c2fab43e86c5a8b386c965dfbe0696ac
+  metadata.gz: 246e5840dc895ee184ef33d88ea92c5e73f58c6120217e2661e6757dd2539ee74f7ba2b2eb47502ca70115884a971ef11530458af6a8aa6f3900f96f70d1119e
+  data.tar.gz: 6d4762d24e1b90c71ea68a1642456a9b4f3132d6424ef9587bfc1f41d70c3f124ebb1c8e60ea49d273b3e73a1077ebaeac4106311e1244890a29d41af8169300

data/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [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

@@ -118,6 +118,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

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.3'
   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.3
 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.3
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: