pundit 2.1.1 → 2.4.0

data/README.md

@@ -1,36 +1,36 @@
 # Pundit
 
-[![Build Status](https://secure.travis-ci.org/varvet/pundit.svg?branch=master)](https://travis-ci.org/varvet/pundit)
-[![Code Climate](https://codeclimate.com/github/varvet/pundit.svg)](https://codeclimate.com/github/varvet/pundit)
-[![Inline docs](http://inch-ci.org/github/varvet/pundit.svg?branch=master)](http://inch-ci.org/github/varvet/pundit)
-[![Gem Version](https://badge.fury.io/rb/pundit.svg)](http://badge.fury.io/rb/pundit)
+[![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](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 simple, robust and
+classes and object oriented design patterns to build a straightforward, robust, and
 scalable authorization system.
 
-Links:
+## Links:
 
-- [API documentation](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/master/CONTRIBUTING.md)
-- [Code of Conduct](https://github.com/varvet/pundit/blob/master/CODE_OF_CONDUCT.md)
+- [Contributing](https://github.com/varvet/pundit/blob/main/CONTRIBUTING.md)
+- [Code of Conduct](https://github.com/varvet/pundit/blob/main/CODE_OF_CONDUCT.md)
 
-Sponsored by:
-
-[<img src="https://www.varvet.com/images/wordmark-red.svg" alt="Varvet" height="50px"/>](https://www.varvet.com)
+<strong>Sponsored by:</strong> <a href="https://www.varvet.com">Varvet<br><br><img src="https://github.com/varvet/pundit/assets/99166/aa9efa0a-6903-4037-abee-1824edc57f1a" alt="Varvet logo" height="120"></div>
 
 ## Installation
 
-``` ruby
-gem "pundit"
+> **Please note** that the README on GitHub is accurate with the _latest code on GitHub_. You are most likely using a released version of Pundit, so please refer to the [documentation for the latest released version of Pundit](https://www.rubydoc.info/gems/pundit).
+
+``` sh
+bundle add pundit
 ```
 
-Include Pundit in your application controller:
+Include `Pundit::Authorization` in your application controller:
 
 ``` ruby
 class ApplicationController < ActionController::Base
-  include Pundit
+  include Pundit::Authorization
 end
 ```
 
@@ -47,8 +47,8 @@ can pick up any classes in the new `app/policies/` directory.
 ## Policies
 
 Pundit is focused around the notion of policy classes. We suggest that you put
-these classes in `app/policies`. This is a simple example that allows updating
-a post if the user is an admin, or if the post is unpublished:
+these classes in `app/policies`. This is an example that allows updating a post
+if the user is an admin, or if the post is unpublished:
 
 ``` ruby
 class PostPolicy
@@ -65,7 +65,7 @@ class PostPolicy
 end
 ```
 
-As you can see, this is just a plain Ruby class. Pundit makes the following
+As you can see, this is a plain Ruby class. Pundit makes the following
 assumptions about this class:
 
 - The class has the same name as some kind of model class, only suffixed
@@ -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
 ```
 
@@ -194,18 +194,30 @@ you can retrieve it by passing a symbol.
 
 ```ruby
 # app/policies/dashboard_policy.rb
-class DashboardPolicy < Struct.new(:user, :dashboard)
-  # ...
+class DashboardPolicy
+  attr_reader :user
+
+  # `_record` in this example will be :dashboard
+  def initialize(user, _record)
+    @user = user
+  end
+
+  def show?
+    user.admin?
+  end
 end
 ```
 
 Note that the headless policy still needs to accept two arguments. The
-second argument will just be the symbol `:dashboard` in this case which
+second argument will be the symbol `:dashboard` in this case, which
 is what is passed as the record to `authorize` below.
 
 ```ruby
 # In controllers
-authorize :dashboard, :show?
+def show
+  authorize :dashboard, :show?
+  ...
+end
 ```
 
 ```erb
@@ -265,7 +277,7 @@ generator, or create your own base class to inherit from:
 
 ``` ruby
 class PostPolicy < ApplicationPolicy
-  class Scope < Scope
+  class Scope < ApplicationPolicy::Scope
     def resolve
       if user.admin?
         scope.all
@@ -334,7 +346,7 @@ that you haven't forgotten to authorize the action. For example:
 
 ``` ruby
 class ApplicationController < ActionController::Base
-  include Pundit
+  include Pundit::Authorization
   after_action :verify_authorized
 end
 ```
@@ -347,9 +359,16 @@ authorize individual instances.
 
 ``` ruby
 class ApplicationController < ActionController::Base
-  include Pundit
-  after_action :verify_authorized, except: :index
-  after_action :verify_policy_scoped, only: :index
+  include Pundit::Authorization
+  after_action :verify_pundit_authorization
+
+  def verify_pundit_authorization
+    if action_name == "index"
+      verify_policy_scoped
+    else
+      verify_authorized
+    end
+  end
 end
 ```
 
@@ -360,7 +379,7 @@ these filters without affecting how your app works in any way.**
 
 Some people have found this feature confusing, while many others
 find it extremely helpful. If you fall into the category of people who find it
-confusing then you do not need to use it. Pundit will work just fine without
+confusing then you do not need to use it. Pundit will work fine without
 using `verify_authorized` and `verify_policy_scoped`.
 
 ### Conditional verification
@@ -405,20 +424,13 @@ class Post
 end
 ```
 
-## Just plain old Ruby
+## Plain old Ruby
+
+Pundit is a very small library on purpose, and it doesn't do anything you can't do yourself. There's no secret sauce here. It does as little as possible, and then gets out of your way.
 
-As you can see, Pundit doesn't do anything you couldn't have easily done
-yourself.  It's a very small library, it just provides a few neat helpers.
-Together these give you the power of building a well structured, fully working
-authorization system without using any special DSLs or funky syntax or
-anything.
+With the few but powerful helpers available in Pundit, you have the power to build a well structured, fully working authorization system without using any special DSLs or funky syntax.
 
-Remember that all of the policy and scope classes are just plain Ruby classes,
-which means you can use the same mechanisms you always use to DRY things up.
-Encapsulate a set of permissions into a module and include them in multiple
-policies. Use `alias_method` to make some permissions behave the same as
-others. Inherit from a base set of permissions. Use metaprogramming if you
-really have to.
+Remember that all of the policy and scope classes are plain Ruby classes, which means you can use the same mechanisms you always use to DRY things up. Encapsulate a set of permissions into a module and include them in multiple policies. Use `alias_method` to make some permissions behave the same as others. Inherit from a base set of permissions. Use metaprogramming if you really have to.
 
 ## Generator
 
@@ -469,7 +481,7 @@ example, associations which might be `nil`.
 
 ```ruby
 class NilClassPolicy < ApplicationPolicy
-  class Scope < Scope
+  class Scope < ApplicationPolicy::Scope
     def resolve
       raise Pundit::NotDefinedError, "Cannot scope NilClass"
     end
@@ -484,13 +496,13 @@ 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.
 
 ```ruby
 class ApplicationController < ActionController::Base
-  include Pundit
+  include Pundit::Authorization
 
   rescue_from Pundit::NotAuthorizedError, with: :user_not_authorized
 
@@ -498,7 +510,7 @@ class ApplicationController < ActionController::Base
 
   def user_not_authorized
     flash[:alert] = "You are not authorized to perform this action."
-    redirect_to(request.referrer || root_path)
+    redirect_back_or_to(root_path)
   end
 end
 ```
@@ -527,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_to(request.referrer || root_path)
+   redirect_back_or_to(root_path)
  end
 end
 ```
@@ -541,8 +553,7 @@ en:
      create?: 'You cannot create posts!'
 ```
 
-Of course, this is just an example. Pundit is agnostic as to how you implement
-your error messaging.
+This is an example. Pundit is agnostic as to how you implement your error messaging.
 
 ## Manually retrieving policies and scopes
 
@@ -564,9 +575,7 @@ those without the bang will return nil.
 
 ## Customize Pundit user
 
-In some cases your controller might not have access to `current_user`, or your
-`current_user` is not the method that should be invoked by Pundit. Simply
-define a method in your controller called `pundit_user`.
+On occasion, your controller may be unable to access `current_user`, or the method that should be invoked by Pundit may not be `current_user`. To address this, you can define a method in your controller named `pundit_user`.
 
 ```ruby
 def pundit_user
@@ -643,7 +652,7 @@ class UserContext
 end
 
 class ApplicationController
-  include Pundit
+  include Pundit::Authorization
 
   def pundit_user
     UserContext.new(current_user, request.ip)
@@ -678,7 +687,7 @@ You can now retrieve these attributes from the policy:
 class PostsController < ApplicationController
   def update
     @post = Post.find(params[:id])
-    if @post.update_attributes(post_params)
+    if @post.update(post_params)
       redirect_to @post
     else
       render :edit
@@ -700,7 +709,7 @@ However, this is a bit cumbersome, so Pundit provides a convenient helper method
 class PostsController < ApplicationController
   def update
     @post = Post.find(params[:id])
-    if @post.update_attributes(permitted_attributes(@post))
+    if @post.update(permitted_attributes(@post))
       redirect_to @post
     else
       render :edit
@@ -752,6 +761,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`:
 
@@ -781,25 +794,67 @@ 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/chrisalley/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
 
-Pundit does not provide a DSL for testing scopes. Just test it like a regular Ruby class!
+Pundit does not provide a DSL for testing scopes. Test them like you would a regular Ruby class!
+
+### Linting with RuboCop RSpec
+
+When you lint your RSpec spec files with `rubocop-rspec`, it will fail to properly detect RSpec constructs that Pundit defines, `permissions`.
+Make sure to use `rubocop-rspec` 2.0 or newer and add the following to your `.rubocop.yml`:
+
+```yaml
+inherit_gem:
+  pundit: config/rubocop-rspec.yml
+```
 
 # 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/SECURITY.md

@@ -0,0 +1,19 @@
+# Security Policy
+
+Please do not file an issue on GitHub, or send a PR addressing the issue.
+
+## Supported versions
+
+Most recent major version only.
+
+## Reporting a vulnerability
+
+Contact one of the maintainers directly:
+
+* [@Burgestrand](https://github.com/Burgestrand)
+* [@dgmstuart](https://github.com/dgmstuart)
+* [@varvet](https://github.com/varvet)
+
+You can report vulnerabilities on GitHub too: https://github.com/varvet/pundit/security
+
+Thank you!

data/config/rubocop-rspec.yml

@@ -0,0 +1,5 @@
+RSpec:
+  Language:
+    ExampleGroups:
+      Regular:
+        - permissions

data/lib/generators/pundit/install/templates/application_policy.rb

@@ -43,7 +43,7 @@ class ApplicationPolicy
     end
 
     def resolve
-      scope.all
+      raise NoMethodError, "You must define #resolve in #{self.class}"
     end
 
     private

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

@@ -1,9 +1,16 @@
 <% module_namespacing do -%>
 class <%= class_name %>Policy < ApplicationPolicy
-  class Scope < Scope
-    def resolve
-      scope.all
-    end
+  # NOTE: Up to Pundit v2.3.1, the inheritance was declared as
+  # `Scope < Scope` rather than `Scope < ApplicationPolicy::Scope`.
+  # In most cases the behavior will be identical, but if updating existing
+  # code, beware of possible changes to the ancestors:
+  # https://gist.github.com/Burgestrand/4b4bc22f31c8a95c425fc0e30d7ef1f5
+
+  class Scope < ApplicationPolicy::Scope
+    # NOTE: Be explicit about which records you allow access to!
+    # def resolve
+    #   scope.all
+    # end
   end
 end
 <% end -%>

data/lib/generators/rspec/templates/policy_spec.rb

@@ -1,4 +1,4 @@
-require '<%= File.exists?('spec/rails_helper.rb') ? 'rails_helper' : 'spec_helper' %>'
+require '<%= File.exist?('spec/rails_helper.rb') ? 'rails_helper' : 'spec_helper' %>'
 
 RSpec.describe <%= class_name %>Policy, type: :policy do
   let(:user) { User.new }

data/lib/pundit/authorization.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Pundit
+  module Authorization
+    extend ActiveSupport::Concern
+
+    included do
+      helper Helper if respond_to?(:helper)
+      if respond_to?(:helper_method)
+        helper_method :policy
+        helper_method :pundit_policy_scope
+        helper_method :pundit_user
+      end
+    end
+
+    protected
+
+    # @return [Pundit::Context] a new instance of {Pundit::Context} with the current user
+    def pundit
+      @pundit ||= Pundit::Context.new(
+        user: pundit_user,
+        policy_cache: Pundit::CacheStore::LegacyStore.new(policies)
+      )
+    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}.
+    #
+    # @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?
+    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]
+    def verify_policy_scoped
+      raise PolicyScopingNotPerformedError, self.class unless pundit_policy_scoped?
+    end
+
+    # 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.
+    #
+    # @param record [Object, Array] the object we're checking permissions of
+    # @param query [Symbol, String] the predicate method to check on the policy (e.g. `:show?`).
+    #   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
+    def authorize(record, query = nil, policy_class: nil)
+      query ||= "#{action_name}?"
+
+      @_pundit_policy_authorized = true
+
+      pundit.authorize(record, query: query, policy_class: policy_class)
+    end
+
+    # Allow this action not to perform authorization.
+    #
+    # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
+    # @return [void]
+    def skip_authorization
+      @_pundit_policy_authorized = :skipped
+    end
+
+    # Allow this action not to perform policy scoping.
+    #
+    # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
+    # @return [void]
+    def skip_policy_scope
+      @_pundit_policy_scoped = :skipped
+    end
+
+    # 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 [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)
+    end
+
+    # Retrieves the policy for the given record.
+    #
+    # @see https://github.com/varvet/pundit#policies
+    # @param record [Object] the object we're retrieving the policy for
+    # @return [Object] instance of policy class with query methods
+    def policy(record)
+      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.
+    #
+    # @see https://github.com/varvet/pundit#strong-parameters
+    # @param record [Object] the object we're retrieving permitted attributes for
+    # @param action [Symbol, String] the name of the action being performed on the record (e.g. `:update`).
+    #   If omitted then this defaults to the Rails controller action name.
+    # @return [Hash{String => Object}] the permitted attributes
+    def permitted_attributes(record, action = action_name)
+      policy = policy(record)
+      method_name = if policy.respond_to?("permitted_attributes_for_#{action}")
+        "permitted_attributes_for_#{action}"
+      else
+        "permitted_attributes"
+      end
+      pundit_params_for(record).permit(*policy.public_send(method_name))
+    end
+
+    # Retrieves the params for the given record.
+    #
+    # @param record [Object] the object we're retrieving params for
+    # @return [ActionController::Parameters] the params
+    def pundit_params_for(record)
+      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
+  end
+end

data/lib/pundit/cache_store/legacy_store.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Pundit
+  module CacheStore
+    # @api private
+    class LegacyStore
+      def initialize(hash = {})
+        @store = hash
+      end
+
+      def fetch(user:, record:)
+        _ = user
+        @store[record] ||= yield
+      end
+    end
+  end
+end

data/lib/pundit/cache_store/null_store.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Pundit
+  module CacheStore
+    # @api private
+    class NullStore
+      @instance = new
+
+      class << self
+        attr_reader :instance
+      end
+
+      def fetch(*, **)
+        yield
+      end
+    end
+  end
+end