pundit 2.3.2 → 2.5.0

data/README.md

@@ -2,8 +2,8 @@
 
 [![Main](https://github.com/varvet/pundit/actions/workflows/main.yml/badge.svg)](https://github.com/varvet/pundit/actions/workflows/main.yml)
 [![Code Climate](https://api.codeclimate.com/v1/badges/a940030f96c9fb43046a/maintainability)](https://codeclimate.com/github/varvet/pundit/maintainability)
-[![Inline docs](http://inch-ci.org/github/varvet/pundit.svg?branch=main)](http://inch-ci.org/github/varvet/pundit)
-[![Gem Version](https://badge.fury.io/rb/pundit.svg)](http://badge.fury.io/rb/pundit)
+[![Inline docs](https://inch-ci.org/github/varvet/pundit.svg?branch=main)](https://inch-ci.org/github/varvet/pundit)
+[![Gem Version](https://badge.fury.io/rb/pundit.svg)](https://badge.fury.io/rb/pundit)
 
 Pundit provides a set of helpers which guide you in leveraging regular Ruby
 classes and object oriented design patterns to build a straightforward, robust, and
@@ -11,7 +11,7 @@ scalable authorization system.
 
 ## Links:
 
-- [API documentation for the most recent version](http://www.rubydoc.info/gems/pundit)
+- [API documentation for the most recent version](https://www.rubydoc.info/gems/pundit)
 - [Source Code](https://github.com/varvet/pundit)
 - [Contributing](https://github.com/varvet/pundit/blob/main/CONTRIBUTING.md)
 - [Code of Conduct](https://github.com/varvet/pundit/blob/main/CODE_OF_CONDUCT.md)
@@ -116,7 +116,7 @@ and the given record. It then infers from the action name, that it should call
 
 ``` ruby
 unless PostPolicy.new(current_user, @post).update?
-  raise Pundit::NotAuthorizedError, "not allowed to update? this #{@post.inspect}"
+  raise Pundit::NotAuthorizedError, "not allowed to PostPolicy#update? this Post"
 end
 ```
 
@@ -360,8 +360,15 @@ authorize individual instances.
 ``` ruby
 class ApplicationController < ActionController::Base
   include Pundit::Authorization
-  after_action :verify_authorized, except: :index
-  after_action :verify_policy_scoped, only: :index
+  after_action :verify_pundit_authorization
+
+  def verify_pundit_authorization
+    if action_name == "index"
+      verify_policy_scoped
+    else
+      verify_authorized
+    end
+  end
 end
 ```
 
@@ -489,7 +496,7 @@ end
 ## Rescuing a denied Authorization in Rails
 
 Pundit raises a `Pundit::NotAuthorizedError` you can
-[rescue_from](http://guides.rubyonrails.org/action_controller_overview.html#rescue-from)
+[rescue_from](https://guides.rubyonrails.org/action_controller_overview.html#rescue-from)
 in your `ApplicationController`. You can customize the `user_not_authorized`
 method in every controller.
 
@@ -503,7 +510,7 @@ class ApplicationController < ActionController::Base
 
   def user_not_authorized
     flash[:alert] = "You are not authorized to perform this action."
-    redirect_back(fallback_location: root_path)
+    redirect_back_or_to(root_path)
   end
 end
 ```
@@ -532,7 +539,7 @@ class ApplicationController < ActionController::Base
    policy_name = exception.policy.class.to_s.underscore
 
    flash[:error] = t "#{policy_name}.#{exception.query}", scope: "pundit", default: :default
-   redirect_back(fallback_location: root_path)
+   redirect_back_or_to(root_path)
  end
 end
 ```
@@ -576,6 +583,36 @@ def pundit_user
 end
 ```
 
+For instance, Rails 8 includes a built-in [authentication generator](https://github.com/rails/rails/tree/8-0-stable/railties/lib/rails/generators/rails/authentication). If you choose to use it, the currently logged-in user is accessed via `Current.user` instead of `current_user`.
+
+To ensure compatibility with Pundit, define a `pundit_user` method in `application_controller.rb` (or another suitable location) as follows:
+
+```ruby
+def pundit_user
+  Current.user
+end
+```
+
+### Handling User Switching in Pundit
+
+When switching users in your application, it's important to reset the Pundit user context to ensure that authorization policies are applied correctly for the new user. Pundit caches the user context, so failing to reset it could result in incorrect permissions being applied.
+
+To handle user switching, you can use the following pattern in your controller:
+
+```ruby
+class ApplicationController
+  include Pundit::Authorization
+
+  def switch_user_to(user)
+    terminate_session if authenticated?
+    start_new_session_for user
+    pundit_reset!
+  end
+end
+```
+
+Make sure to invoke `pundit_reset!` whenever changing the user. This ensures the cached authorization context is reset, preventing any incorrect permissions from being applied.
+
 ## Policy Namespacing
 In some cases it might be helpful to have multiple policies that serve different contexts for a
 resource. A prime example of this is the case where User policies differ from Admin policies. To
@@ -754,6 +791,10 @@ end
 
 ### Policy Specs
 
+> [!TIP]
+> An alternative approach to Pundit policy specs is scoping them to a user context as outlined in this
+[excellent post](https://thunderboltlabs.com/blog/2013/03/27/testing-pundit-policies-with-rspec/) and implemented in the third party [pundit-matchers](https://github.com/punditcommunity/pundit-matchers) gem.
+
 Pundit includes a mini-DSL for writing expressive tests for your policies in RSpec.
 Require `pundit/rspec` in your `spec_helper.rb`:
 
@@ -783,8 +824,40 @@ describe PostPolicy do
 end
 ```
 
-An alternative approach to Pundit policy specs is scoping them to a user context as outlined in this
-[excellent post](http://thunderboltlabs.com/blog/2013/03/27/testing-pundit-policies-with-rspec/) and implemented in the third party [pundit-matchers](https://github.com/punditcommunity/pundit-matchers) gem.
+### Custom matcher description
+
+By default rspec includes an inspected `user` and `record` in the matcher description, which might become overly verbose:
+
+```
+PostPolicy
+  update? and show?
+    is expected to permit #<User:0x0000000104aefd80> and #<Post:0x0000000104aef8d0 @user=#<User:0x0000000104aefd80>>
+```
+
+You can override the default description with a static string, or a block:
+
+```ruby
+# static alternative: Pundit::RSpec::Matchers.description = "permit the user"
+Pundit::RSpec::Matchers.description = ->(user, record) do
+  "permit user with role #{user.role} to access record with ID #{record.id}"
+end
+```
+
+Which would make for a less chatty output:
+
+```
+PostPolicy
+  update? and show?
+    is expected to permit user with role admin to access record with ID 130
+```
+
+### Focus Support
+
+If your RSpec config has `filter_run_when_matching :focus`, you may tag the `permissions` helper like so:
+
+```
+permissions :show?, :focus do
+```
 
 ### Scope Specs
 
@@ -803,15 +876,15 @@ inherit_gem:
 # External Resources
 
 - [RailsApps Example Application: Pundit and Devise](https://github.com/RailsApps/rails-devise-pundit)
-- [Migrating to Pundit from CanCan](http://blog.carbonfive.com/2013/10/21/migrating-to-pundit-from-cancan/)
-- [Testing Pundit Policies with RSpec](http://thunderboltlabs.com/blog/2013/03/27/testing-pundit-policies-with-rspec/)
+- [Migrating to Pundit from CanCan](https://blog.carbonfive.com/2013/10/21/migrating-to-pundit-from-cancan/)
+- [Testing Pundit Policies with RSpec](https://thunderboltlabs.com/blog/2013/03/27/testing-pundit-policies-with-rspec/)
 - [Testing Pundit with Minitest](https://github.com/varvet/pundit/issues/204#issuecomment-60166450)
 - [Using Pundit outside of a Rails controller](https://github.com/varvet/pundit/pull/136)
-- [Straightforward Rails Authorization with Pundit](http://www.sitepoint.com/straightforward-rails-authorization-with-pundit/)
+- [Straightforward Rails Authorization with Pundit](https://www.sitepoint.com/straightforward-rails-authorization-with-pundit/)
 
 ## Other implementations
 
-- [Flask-Pundit](https://github.com/anurag90x/flask-pundit) (Python) is a [Flask](http://flask.pocoo.org/) extension "heavily inspired by" Pundit
+- [Flask-Pundit](https://github.com/anurag90x/flask-pundit) (Python) is a [Flask](https://flask.pocoo.org/) extension "heavily inspired by" Pundit
 
 # License
 

data/Rakefile

@@ -15,6 +15,7 @@ end
 
 YARD::Rake::YardocTask.new do |t|
   t.files = ["lib/**/*.rb"]
+  t.stats_options = ["--list-undoc"]
 end
 
 task default: :spec

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

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
 module Pundit
+  # @private
   module Generators
+    # @private
     class InstallGenerator < ::Rails::Generators::Base
       source_root File.expand_path("templates", __dir__)
 
       def copy_application_policy
-        template "application_policy.rb", "app/policies/application_policy.rb"
+        template "application_policy.rb.tt", "app/policies/application_policy.rb"
       end
     end
   end

data/lib/generators/pundit/policy/policy_generator.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
 module Pundit
+  # @private
   module Generators
+    # @private
     class PolicyGenerator < ::Rails::Generators::NamedBase
       source_root File.expand_path("templates", __dir__)
 
       def create_policy
-        template "policy.rb", File.join("app/policies", class_path, "#{file_name}_policy.rb")
+        template "policy.rb.tt", File.join("app/policies", class_path, "#{file_name}_policy.rb")
       end
 
       hook_for :test_framework

data/lib/generators/rspec/policy_generator.rb

@@ -1,12 +1,15 @@
 # frozen_string_literal: true
 
+# @private
 module Rspec
+  # @private
   module Generators
+    # @private
     class PolicyGenerator < ::Rails::Generators::NamedBase
       source_root File.expand_path("templates", __dir__)
 
       def create_policy_spec
-        template "policy_spec.rb", File.join("spec/policies", class_path, "#{file_name}_policy_spec.rb")
+        template "policy_spec.rb.tt", File.join("spec/policies", class_path, "#{file_name}_policy_spec.rb")
       end
     end
   end

data/lib/generators/test_unit/policy_generator.rb

@@ -1,12 +1,15 @@
 # frozen_string_literal: true
 
+# @private
 module TestUnit
+  # @private
   module Generators
+    # @private
     class PolicyGenerator < ::Rails::Generators::NamedBase
       source_root File.expand_path("templates", __dir__)
 
       def create_policy_test
-        template "policy_test.rb", File.join("test/policies", class_path, "#{file_name}_policy_test.rb")
+        template "policy_test.rb.tt", File.join("test/policies", class_path, "#{file_name}_policy_test.rb")
       end
     end
   end

data/lib/pundit/authorization.rb

@@ -1,6 +1,14 @@
 # frozen_string_literal: true
 
 module Pundit
+  # Pundit DSL to include in your controllers to provide authorization helpers.
+  #
+  # @example
+  #   class ApplicationController < ActionController::Base
+  #     include Pundit::Authorization
+  #   end
+  # @see #pundit
+  # @api public
   module Authorization
     extend ActiveSupport::Concern
 
@@ -15,7 +23,13 @@ module Pundit
 
     protected
 
-    # @return [Pundit::Context] a new instance of {Pundit::Context} with the current user
+    # An instance of {Pundit::Context} initialized with the current user.
+    #
+    # @note this method is memoized and will return the same instance during the request.
+    # @api public
+    # @return [Pundit::Context]
+    # @see #pundit_user
+    # @see #policies
     def pundit
       @pundit ||= Pundit::Context.new(
         user: pundit_user,
@@ -23,40 +37,38 @@ module Pundit
       )
     end
 
-    # @return [Boolean] whether authorization has been performed, i.e. whether
-    #                   one {#authorize} or {#skip_authorization} has been called
-    def pundit_policy_authorized?
-      !!@_pundit_policy_authorized
-    end
-
-    # @return [Boolean] whether policy scoping has been performed, i.e. whether
-    #                   one {#policy_scope} or {#skip_policy_scope} has been called
-    def pundit_policy_scoped?
-      !!@_pundit_policy_scoped
-    end
-
-    # Raises an error if authorization has not been performed, usually used as an
-    # `after_action` filter to prevent programmer error in forgetting to call
-    # {#authorize} or {#skip_authorization}.
+    # Hook method which allows customizing which user is passed to policies and
+    # scopes initialized by {#authorize}, {#policy} and {#policy_scope}.
     #
-    # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
-    # @raise [AuthorizationNotPerformedError] if authorization has not been performed
-    # @return [void]
-    def verify_authorized
-      raise AuthorizationNotPerformedError, self.class unless pundit_policy_authorized?
+    # @note Make sure to call `pundit_reset!` if this changes during a request.
+    # @see https://github.com/varvet/pundit#customize-pundit-user
+    # @see #pundit
+    # @see #pundit_reset!
+    # @return [Object] the user object to be used with pundit
+    def pundit_user
+      current_user
     end
 
-    # Raises an error if policy scoping has not been performed, usually used as an
-    # `after_action` filter to prevent programmer error in forgetting to call
-    # {#policy_scope} or {#skip_policy_scope} in index actions.
+    # Clears the cached Pundit authorization data.
+    #
+    # This method should be called when the pundit_user is changed,
+    # such as during user switching, to ensure that stale authorization
+    # data is not used. Pundit caches authorization policies and scopes
+    # for the pundit_user, so calling this method will reset those
+    # caches and ensure that the next authorization checks are performed
+    # with the correct context for the new pundit_user.
     #
-    # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
-    # @raise [AuthorizationNotPerformedError] if policy scoping has not been performed
     # @return [void]
-    def verify_policy_scoped
-      raise PolicyScopingNotPerformedError, self.class unless pundit_policy_scoped?
+    def pundit_reset!
+      @pundit = nil
+      @_pundit_policies = nil
+      @_pundit_policy_scopes = nil
+      @_pundit_policy_authorized = nil
+      @_pundit_policy_scoped = nil
     end
 
+    # @!group Policies
+
     # Retrieves the policy for the given record, initializing it with the record
     # and current user and finally throwing an error if the user is not
     # authorized to perform the given action.
@@ -66,7 +78,9 @@ module Pundit
     #   If omitted then this defaults to the Rails controller action name.
     # @param policy_class [Class] the policy class we want to force use of
     # @raise [NotAuthorizedError] if the given query method returned false
-    # @return [Object] Always returns the passed object record
+    # @return [record] Always returns the passed object record
+    # @see Pundit::Context#authorize
+    # @see #verify_authorized
     def authorize(record, query = nil, policy_class: nil)
       query ||= "#{action_name}?"
 
@@ -79,29 +93,45 @@ module Pundit
     #
     # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
     # @return [void]
+    # @see #verify_authorized
     def skip_authorization
       @_pundit_policy_authorized = :skipped
     end
 
-    # Allow this action not to perform policy scoping.
+    # @return [Boolean] wether or not authorization has been performed
+    # @see #authorize
+    # @see #skip_authorization
+    def pundit_policy_authorized?
+      !!@_pundit_policy_authorized
+    end
+
+    # Raises an error if authorization has not been performed.
+    #
+    # Usually used as an `after_action` filter to prevent programmer error in
+    # forgetting to call {#authorize} or {#skip_authorization}.
     #
     # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
+    # @raise [AuthorizationNotPerformedError] if authorization has not been performed
     # @return [void]
-    def skip_policy_scope
-      @_pundit_policy_scoped = :skipped
+    # @see #authorize
+    # @see #skip_authorization
+    def verify_authorized
+      raise AuthorizationNotPerformedError, self.class unless pundit_policy_authorized?
     end
 
-    # Retrieves the policy scope for the given record.
+    # rubocop:disable Naming/MemoizedInstanceVariableName
+
+    # Cache of policies. You should not rely on this method.
     #
-    # @see https://github.com/varvet/pundit#scopes
-    # @param scope [Object] the object we're retrieving the policy scope for
-    # @param policy_scope_class [Class] the policy scope class we want to force use of
-    # @return [Scope{#resolve}, nil] instance of scope class which can resolve to a scope
-    def policy_scope(scope, policy_scope_class: nil)
-      @_pundit_policy_scoped = true
-      policy_scope_class ? policy_scope_class.new(pundit_user, scope).resolve : pundit_policy_scope(scope)
+    # @api private
+    def policies
+      @_pundit_policies ||= {}
     end
 
+    # rubocop:enable Naming/MemoizedInstanceVariableName
+
+    # @!endgroup
+
     # Retrieves the policy for the given record.
     #
     # @see https://github.com/varvet/pundit#policies
@@ -111,11 +141,87 @@ module Pundit
       pundit.policy!(record)
     end
 
-    # Retrieves a set of permitted attributes from the policy by instantiating
-    # the policy class for the given record and calling `permitted_attributes` on
-    # it, or `permitted_attributes_for_{action}` if `action` is defined. It then infers
-    # what key the record should have in the params hash and retrieves the
-    # permitted attributes from the params hash under that key.
+    # @!group Policy Scopes
+
+    # Retrieves the policy scope for the given record.
+    #
+    # @see https://github.com/varvet/pundit#scopes
+    # @param scope [Object] the object we're retrieving the policy scope for
+    # @param policy_scope_class [#resolve] the policy scope class we want to force use of
+    # @return [#resolve, nil] instance of scope class which can resolve to a scope
+    def policy_scope(scope, policy_scope_class: nil)
+      @_pundit_policy_scoped = true
+      policy_scope_class ? policy_scope_class.new(pundit_user, scope).resolve : pundit_policy_scope(scope)
+    end
+
+    # Allow this action not to perform policy scoping.
+    #
+    # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
+    # @return [void]
+    # @see #verify_policy_scoped
+    def skip_policy_scope
+      @_pundit_policy_scoped = :skipped
+    end
+
+    # @return [Boolean] wether or not policy scoping has been performed
+    # @see #policy_scope
+    # @see #skip_policy_scope
+    def pundit_policy_scoped?
+      !!@_pundit_policy_scoped
+    end
+
+    # Raises an error if policy scoping has not been performed.
+    #
+    # Usually used as an `after_action` filter to prevent programmer error in
+    # forgetting to call {#policy_scope} or {#skip_policy_scope} in index
+    # actions.
+    #
+    # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
+    # @raise [AuthorizationNotPerformedError] if policy scoping has not been performed
+    # @return [void]
+    # @see #policy_scope
+    # @see #skip_policy_scope
+    def verify_policy_scoped
+      raise PolicyScopingNotPerformedError, self.class unless pundit_policy_scoped?
+    end
+
+    # rubocop:disable Naming/MemoizedInstanceVariableName
+
+    # Cache of policy scope. You should not rely on this method.
+    #
+    # @api private
+    def policy_scopes
+      @_pundit_policy_scopes ||= {}
+    end
+
+    # rubocop:enable Naming/MemoizedInstanceVariableName
+
+    # This was added to allow calling `policy_scope!` without flipping the
+    # `pundit_policy_scoped?` flag.
+    #
+    # It's used internally by `policy_scope`, as well as from the views
+    # when they call `policy_scope`. It works because views get their helper
+    # from {Pundit::Helper}.
+    #
+    # @note This also memoizes the instance with `scope` as the key.
+    # @see Pundit::Helper#policy_scope
+    # @api private
+    def pundit_policy_scope(scope)
+      policy_scopes[scope] ||= pundit.policy_scope!(scope)
+    end
+    private :pundit_policy_scope
+
+    # @!endgroup
+
+    # @!group Strong Parameters
+
+    # Retrieves a set of permitted attributes from the policy.
+    #
+    # Done by instantiating the policy class for the given record and calling
+    # `permitted_attributes` on it, or `permitted_attributes_for_{action}` if
+    # `action` is defined. It then infers what key the record should have in the
+    # params hash and retrieves the permitted attributes from the params hash
+    # under that key.
     #
     # @see https://github.com/varvet/pundit#strong-parameters
     # @param record [Object] the object we're retrieving permitted attributes for
@@ -140,37 +246,6 @@ module Pundit
       params.require(PolicyFinder.new(record).param_key)
     end
 
-    # Cache of policies. You should not rely on this method.
-    #
-    # @api private
-    # rubocop:disable Naming/MemoizedInstanceVariableName
-    def policies
-      @_pundit_policies ||= {}
-    end
-    # rubocop:enable Naming/MemoizedInstanceVariableName
-
-    # Cache of policy scope. You should not rely on this method.
-    #
-    # @api private
-    # rubocop:disable Naming/MemoizedInstanceVariableName
-    def policy_scopes
-      @_pundit_policy_scopes ||= {}
-    end
-    # rubocop:enable Naming/MemoizedInstanceVariableName
-
-    # Hook method which allows customizing which user is passed to policies and
-    # scopes initialized by {#authorize}, {#policy} and {#policy_scope}.
-    #
-    # @see https://github.com/varvet/pundit#customize-pundit-user
-    # @return [Object] the user object to be used with pundit
-    def pundit_user
-      current_user
-    end
-
-    private
-
-    def pundit_policy_scope(scope)
-      policy_scopes[scope] ||= pundit.policy_scope!(scope)
-    end
+    # @!endgroup
   end
 end

data/lib/pundit/cache_store/legacy_store.rb

@@ -2,12 +2,19 @@
 
 module Pundit
   module CacheStore
+    # A cache store that uses only the record as a cache key, and ignores the user.
+    #
+    # The original cache mechanism used by Pundit.
+    #
     # @api private
     class LegacyStore
       def initialize(hash = {})
         @store = hash
       end
 
+      # A cache store that uses only the record as a cache key, and ignores the user.
+      #
+      # @note `nil` results are not cached.
       def fetch(user:, record:)
         _ = user
         @store[record] ||= yield

data/lib/pundit/cache_store/null_store.rb

@@ -2,14 +2,23 @@
 
 module Pundit
   module CacheStore
+    # A cache store that does not cache anything.
+    #
+    # Use `NullStore.instance` to get the singleton instance, it is thread-safe.
+    #
+    # @see Pundit::Context#initialize
     # @api private
     class NullStore
       @instance = new
 
       class << self
+        # @return [NullStore] the singleton instance
         attr_reader :instance
       end
 
+      # Always yields, does not cache anything.
+      # @yield
+      # @return [any] whatever the block returns.
       def fetch(*, **)
         yield
       end

data/lib/pundit/cache_store.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Pundit
+  # Namespace for cache store implementations.
+  #
+  # Cache stores are used to cache policy lookups, so you get the same policy
+  # instance for the same record.
+  module CacheStore
+    # @!group Cache Store Interface
+
+    # @!method fetch(user:, record:, &block)
+    #   Looks up a stored policy or generate a new one.
+    #
+    #   @note This is a method template, but the method does not exist in this module.
+    #   @param user [Object]  the user that initiated the action
+    #   @param record [Object] the object being accessed
+    #   @param block [Proc] the block to execute if missing
+    #   @return [Object] the policy
+
+    # @!endgroup
+  end
+end