pundit 1.1.0 → 2.3.0

data/README.md

@@ -1,37 +1,38 @@
 # Pundit
 
-[![Build Status](https://secure.travis-ci.org/elabs/pundit.svg?branch=master)](https://travis-ci.org/elabs/pundit)
-[![Code Climate](https://codeclimate.com/github/elabs/pundit.svg)](https://codeclimate.com/github/elabs/pundit)
-[![Inline docs](http://inch-ci.org/github/elabs/pundit.svg?branch=master)](http://inch-ci.org/github/elabs/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)
 
 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
-scaleable authorization system.
+scalable authorization system.
 
 Links:
 
-- [API documentation](http://www.rubydoc.info/gems/pundit)
-- [Source Code](https://github.com/elabs/pundit)
-- [Contributing](https://github.com/elabs/pundit/blob/master/CONTRIBUTING.md)
-- [Code of Conduct](https://github.com/elabs/pundit/blob/master/CODE_OF_CONDUCT.md)
+- [API documentation for the most recent version](http://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)
 
 Sponsored by:
 
-[<img src="http://d3cv91luii1z1d.cloudfront.net/logo-gh.png" alt="Elabs" height="50px"/>](http://elabs.se)
+[<img src="https://www.varvet.com/images/wordmark-red.svg" alt="Varvet" height="50px"/>](https://www.varvet.com)
 
 ## 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
-  protect_from_forgery
+  include Pundit::Authorization
 end
 ```
 
@@ -61,7 +62,7 @@ class PostPolicy
   end
 
   def update?
-    user.admin? or not post.published?
+    user.admin? || !post.published?
   end
 end
 ```
@@ -116,7 +117,9 @@ and the given record. It then infers from the action name, that it should call
 `authorize` would have done something like this:
 
 ``` ruby
-raise "not authorized" unless PostPolicy.new(current_user, @post).update?
+unless PostPolicy.new(current_user, @post).update?
+  raise Pundit::NotAuthorizedError, "not allowed to update? this #{@post.inspect}"
+end
 ```
 
 You can pass a second argument to `authorize` if the name of the permission you
@@ -131,6 +134,18 @@ def publish
 end
 ```
 
+You can pass an argument to override the policy class if necessary. For example:
+
+```ruby
+def create
+  @publication = find_publication # assume this method returns any model that behaves like a publication
+  # @publication.class => Post
+  authorize @publication, policy_class: PublicationPolicy
+  @publication.publish!
+  redirect_to @publication
+end
+```
+
 If you don't have an instance for the first argument to `authorize`, then you can pass
 the class. For example:
 
@@ -151,6 +166,20 @@ def admin_list
 end
 ```
 
+`authorize` returns the instance passed to it, so you can chain it like this:
+
+Controller:
+```ruby
+def show
+  @user = authorize User.find(params[:id])
+end
+
+# return the record even for namespaced policies
+def show
+  @user = authorize [:admin, User.find(params[:id])]
+end
+```
+
 You can easily get a hold of an instance of the policy through the `policy`
 method in both the view and controller. This is especially useful for
 conditionally showing links or buttons in the view:
@@ -167,14 +196,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 just 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
+is what is passed as the record to `authorize` below.
+
 ```ruby
 # In controllers
-authorize :dashboard, :show?
+def show
+  authorize :dashboard, :show?
+  ...
+end
 ```
 
 ```erb
@@ -184,54 +229,6 @@ authorize :dashboard, :show?
 <% end %>
 ```
 
-## Ensuring policies are used
-
-Pundit adds a method called `verify_authorized` to your controllers. This
-method will raise an exception if `authorize` has not yet been called. You
-should run this method in an `after_action` to ensure that you haven't
-forgotten to authorize the action. For example:
-
-``` ruby
-class ApplicationController < ActionController::Base
-  after_action :verify_authorized
-end
-```
-
-Likewise, Pundit also adds `verify_policy_scoped` to your controller.  This
-will raise an exception in the vein of `verify_authorized`.  However, it tracks
-if `policy_scope` is used instead of `authorize`.  This is mostly useful for
-controller actions like `index` which find collections with a scope and don't
-authorize individual instances.
-
-``` ruby
-class ApplicationController < ActionController::Base
-  after_action :verify_authorized, except: :index
-  after_action :verify_policy_scoped, only: :index
-end
-```
-
-If you're using `verify_authorized` in your controllers but need to
-conditionally bypass verification, you can use `skip_authorization`. For
-bypassing `verify_policy_scoped`, use `skip_policy_scope`. These are useful
-in circumstances where you don't want to disable verification for the
-entire action, but have some cases where you intend to not authorize.
-
-```ruby
-def show
-  record = Record.find_by(attribute: "value")
-  if record.present?
-    authorize record
-  else
-    skip_authorization
-  end
-end
-```
-
-If you need to perform some more sophisticated logic or you want to raise a custom
-exception you can use the two lower level methods `pundit_policy_authorized?`
-and `pundit_policy_scoped?` which return `true` or `false` depending on whether
-`authorize` or `policy_scope` have been called, respectively.
-
 ## Scopes
 
 Often, you will want to have some kind of view listing records which a
@@ -241,8 +238,6 @@ define a class called a policy scope. It can look something like this:
 ``` ruby
 class PostPolicy < ApplicationPolicy
   class Scope
-    attr_reader :user, :scope
-
     def initialize(user, scope)
       @user  = user
       @scope = scope
@@ -255,10 +250,14 @@ class PostPolicy < ApplicationPolicy
         scope.where(published: true)
       end
     end
+
+    private
+
+    attr_reader :user, :scope
   end
 
   def update?
-    user.admin? or not post.published?
+    user.admin? or not record.published?
   end
 end
 ```
@@ -291,7 +290,7 @@ class PostPolicy < ApplicationPolicy
   end
 
   def update?
-    user.admin? or not post.published?
+    user.admin? or not record.published?
   end
 end
 ```
@@ -302,15 +301,26 @@ You can now use this class from your controller via the `policy_scope` method:
 def index
   @posts = policy_scope(Post)
 end
+
+def show
+  @post = policy_scope(Post).find(params[:id])
+end
+```
+
+Like with the authorize method, you can also override the policy scope class:
+
+``` ruby
+def index
+  # publication_class => Post
+  @publications = policy_scope(publication_class, policy_scope_class: PublicationPolicy::Scope)
+end
 ```
 
-Just as with your policy, this will automatically infer that you want to use
-the `PostPolicy::Scope` class, it will instantiate this class and call
-`resolve` on the instance. In this case it is a shortcut for doing:
+In this case it is a shortcut for doing:
 
 ``` ruby
 def index
-  @posts = PostPolicy::Scope.new(current_user, Post).resolve
+  @publications = PublicationPolicy::Scope.new(current_user, Post).resolve
 end
 ```
 
@@ -322,6 +332,70 @@ You can, and are encouraged to, use this method in views:
 <% end %>
 ```
 
+## Ensuring policies and scopes are used
+
+When you are developing an application with Pundit it can be easy to forget to
+authorize some action. People are forgetful after all. Since Pundit encourages
+you to add the `authorize` call manually to each controller action, it's really
+easy to miss one.
+
+Thankfully, Pundit has a handy feature which reminds you in case you forget.
+Pundit tracks whether you have called `authorize` anywhere in your controller
+action. Pundit also adds a method to your controllers called
+`verify_authorized`. This method will raise an exception if `authorize` has not
+yet been called. You should run this method in an `after_action` hook to ensure
+that you haven't forgotten to authorize the action. For example:
+
+``` ruby
+class ApplicationController < ActionController::Base
+  include Pundit::Authorization
+  after_action :verify_authorized
+end
+```
+
+Likewise, Pundit also adds `verify_policy_scoped` to your controller. This
+will raise an exception similar to `verify_authorized`. However, it tracks
+if `policy_scope` is used instead of `authorize`. This is mostly useful for
+controller actions like `index` which find collections with a scope and don't
+authorize individual instances.
+
+``` ruby
+class ApplicationController < ActionController::Base
+  include Pundit::Authorization
+  after_action :verify_authorized, except: :index
+  after_action :verify_policy_scoped, only: :index
+end
+```
+
+**This verification mechanism only exists to aid you while developing your
+application, so you don't forget to call `authorize`. It is not some kind of
+failsafe mechanism or authorization mechanism. You should be able to remove
+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
+using `verify_authorized` and `verify_policy_scoped`.
+
+### Conditional verification
+
+If you're using `verify_authorized` in your controllers but need to
+conditionally bypass verification, you can use `skip_authorization`. For
+bypassing `verify_policy_scoped`, use `skip_policy_scope`. These are useful
+in circumstances where you don't want to disable verification for the
+entire action, but have some cases where you intend to not authorize.
+
+```ruby
+def show
+  record = Record.find_by(attribute: "value")
+  if record.present?
+    authorize record
+  else
+    skip_authorization
+  end
+end
+```
+
 ## Manually specifying policy classes
 
 Sometimes you might want to explicitly declare which policy to use for a given
@@ -335,6 +409,16 @@ class Post
 end
 ```
 
+Alternatively, you can declare an instance method:
+
+``` ruby
+class Post
+  def policy_class
+    PostablePolicy
+  end
+end
+```
+
 ## Just plain old Ruby
 
 As you can see, Pundit doesn't do anything you couldn't have easily done
@@ -362,7 +446,8 @@ rails g pundit:policy post
 
 In many applications, only logged in users are really able to do anything. If
 you're building such a system, it can be kind of cumbersome to check that the
-user in a policy isn't `nil` for every single permission.
+user in a policy isn't `nil` for every single permission. Aside from policies,
+you can add this check to the base class for scopes.
 
 We suggest that you define a filter that redirects unauthenticated users to the
 login page. As a secondary defence, if you've defined an ApplicationPolicy, it
@@ -376,6 +461,37 @@ class ApplicationPolicy
     @user   = user
     @record = record
   end
+
+  class Scope
+    attr_reader :user, :scope
+
+    def initialize(user, scope)
+      raise Pundit::NotAuthorizedError, "must be logged in" unless user
+      @user = user
+      @scope = scope
+    end
+  end
+end
+```
+
+## NilClassPolicy
+
+To support a [null object pattern](https://en.wikipedia.org/wiki/Null_Object_pattern)
+you may find that you want to implement a `NilClassPolicy`. This might be useful
+where you want to extend your ApplicationPolicy to allow some tolerance of, for
+example, associations which might be `nil`.
+
+```ruby
+class NilClassPolicy < ApplicationPolicy
+  class Scope < Scope
+    def resolve
+      raise Pundit::NotDefinedError, "Cannot scope NilClass"
+    end
+  end
+
+  def show?
+    false # Nobody can see nothing
+  end
 end
 ```
 
@@ -388,8 +504,7 @@ method in every controller.
 
 ```ruby
 class ApplicationController < ActionController::Base
-  protect_from_forgery
-  include Pundit
+  include Pundit::Authorization
 
   rescue_from Pundit::NotAuthorizedError, with: :user_not_authorized
 
@@ -397,11 +512,15 @@ 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(fallback_location: root_path)
   end
 end
 ```
 
+Alternatively, you can globally handle Pundit::NotAuthorizedError's by having rails handle them as a 403 error and serving a 403 error page. Add the following to application.rb:
+
+```config.action_dispatch.rescue_responses["Pundit::NotAuthorizedError"] = :forbidden```
+
 ## Creating custom error messages
 
 `NotAuthorizedError`s provide information on what query (e.g. `:create?`), what
@@ -422,7 +541,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(fallback_url: root_path)
  end
 end
 ```
@@ -469,6 +588,47 @@ def pundit_user
 end
 ```
 
+## 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
+authorize with a namespaced policy, pass the namespace into the `authorize` helper in an array:
+
+```ruby
+authorize(post)                   # => will look for a PostPolicy
+authorize([:admin, post])         # => will look for an Admin::PostPolicy
+authorize([:foo, :bar, post])     # => will look for a Foo::Bar::PostPolicy
+
+policy_scope(Post)                # => will look for a PostPolicy::Scope
+policy_scope([:admin, Post])      # => will look for an Admin::PostPolicy::Scope
+policy_scope([:foo, :bar, Post])  # => will look for a Foo::Bar::PostPolicy::Scope
+```
+
+If you are using namespaced policies for something like Admin views, it can be useful to
+override the `policy_scope` and `authorize` helpers in your `AdminController` to automatically
+apply the namespacing:
+
+```ruby
+class AdminController < ApplicationController
+  def policy_scope(scope)
+    super([:admin, scope])
+  end
+
+  def authorize(record, query = nil)
+    super([:admin, record], query)
+  end
+end
+
+class Admin::PostController < AdminController
+  def index
+    policy_scope(Post)
+  end
+
+  def show
+    post = authorize Post.find(params[:id])
+  end
+end
+```
+
 ## Additional context
 
 Pundit strongly encourages you to model your application in such a way that the
@@ -497,7 +657,7 @@ class UserContext
 end
 
 class ApplicationController
-  include Pundit
+  include Pundit::Authorization
 
   def pundit_user
     UserContext.new(current_user, request.ip)
@@ -507,9 +667,8 @@ end
 
 ## Strong parameters
 
-In Rails 4 (or Rails 3.2 with the
-[strong_parameters](https://github.com/rails/strong_parameters) gem),
-mass-assignment protection is handled in the controller.  With Pundit you can
+In Rails,
+mass-assignment protection is handled in the controller. With Pundit you can
 control which attributes a user has access to update via your policies. You can
 set up a `permitted_attributes` method in your policy like this:
 
@@ -533,7 +692,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
@@ -555,7 +714,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
@@ -564,6 +723,45 @@ class PostsController < ApplicationController
 end
 ```
 
+If you want to permit different attributes based on the current action, you can define a `permitted_attributes_for_#{action}` method on your policy:
+
+```ruby
+# app/policies/post_policy.rb
+class PostPolicy < ApplicationPolicy
+  def permitted_attributes_for_create
+    [:title, :body]
+  end
+
+  def permitted_attributes_for_edit
+    [:body]
+  end
+end
+```
+
+If you have defined an action-specific method on your policy for the current action, the `permitted_attributes` helper will call it instead of calling `permitted_attributes` on your controller.
+
+If you need to fetch parameters based on namespaces different from the suggested one, override the below method, in your controller, and return an instance of `ActionController::Parameters`.
+
+```ruby
+def pundit_params_for(record)
+  params.require(PolicyFinder.new(record).param_key)
+end
+```
+
+For example:
+
+```ruby
+# If you don't want to use require
+def pundit_params_for(record)
+  params.fetch(PolicyFinder.new(record).param_key, {})
+end
+
+# If you are using something like the JSON API spec
+def pundit_params_for(_record)
+  params.fetch(:data, {}).fetch(:attributes, {})
+end
+```
+
 ## RSpec
 
 ### Policy Specs
@@ -600,14 +798,33 @@ 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.
 
+### Scope Specs
+
+Pundit does not provide a DSL for testing scopes. Just test it like 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/)
-- [Using Pundit outside of a Rails controller](https://github.com/elabs/pundit/pull/136)
+- [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/)
 
+## Other implementations
+
+- [Flask-Pundit](https://github.com/anurag90x/flask-pundit) (Python) is a [Flask](http://flask.pocoo.org/) extension "heavily inspired by" Pundit
+
 # License
 
 Licensed under the MIT license, see the separate LICENSE.txt file.

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "rubygems"
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
@@ -16,4 +18,3 @@ YARD::Rake::YardocTask.new do |t|
 end
 
 task default: :spec
-task default: :rubocop unless RUBY_ENGINE == "rbx"

data/config/rubocop-rspec.yml

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

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

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

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class ApplicationPolicy
   attr_reader :user, :record
 
@@ -11,7 +13,7 @@ class ApplicationPolicy
   end
 
   def show?
-    scope.where(:id => record.id).exists?
+    false
   end
 
   def create?
@@ -34,20 +36,18 @@ class ApplicationPolicy
     false
   end
 
-  def scope
-    Pundit.policy_scope!(user, record.class)
-  end
-
   class Scope
-    attr_reader :user, :scope
-
     def initialize(user, scope)
       @user = user
       @scope = scope
     end
 
     def resolve
-      scope
+      raise NotImplementedError, "You must define #resolve in #{self.class}"
     end
+
+    private
+
+    attr_reader :user, :scope
   end
 end

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

@@ -1,10 +1,12 @@
+# frozen_string_literal: true
+
 module Pundit
   module Generators
     class PolicyGenerator < ::Rails::Generators::NamedBase
-      source_root File.expand_path(File.join(File.dirname(__FILE__), 'templates'))
+      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", File.join("app/policies", class_path, "#{file_name}_policy.rb")
       end
 
       hook_for :test_framework