pundit 1.1.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: a2c188098c86ad5a0804044f80219014564501ef
-  data.tar.gz: 2ab7f79275d9ae66e5d04cf980c11e2c2983a4ef
+SHA256:
+  metadata.gz: 371516754ff155f90b2093a0ce80aacf097ab555027b19ea22b7c823de72a66a
+  data.tar.gz: 41e69a7d6a317b46ad35d1d1485d2119b443b8a430e5c78e62935ec502c7d08f
 SHA512:
-  metadata.gz: 55fbbf71ad514c0cfe4f8933dea59915314f749efa53ab5579f2da9dfcf2b4786343cefa53d3a35e26f4a346776c1c513884595a39561d280b259e6b6fb9b31a
-  data.tar.gz: bbcf9417801b22deac78afe2d5ea8a268193daf0e011f861006c25b1d0124d1f462aa37d4d38e623b9d438cb29ceb52b250575118e053862b74561795bbdd7a4
+  metadata.gz: c77a792bec5d87f487fd3ee419d00745dcab754bd1bd38504d9987b71d80be3bd32fb1aab8419a8e63ef3c3718e1bd8a255ff0117be8f8a5c743c221d87fccdd
+  data.tar.gz: 3086b4036cdbafb499f462f22405f185c83d12c8d8175136531dd053733320574b3d5d05c8379895940d854d54d7abb59d6a0958a9d0e6fdfc03f7691883c3ab

data/.rubocop.yml

@@ -1,14 +1,22 @@
 AllCops:
+  DisplayCopNames: true
+  TargetRubyVersion: 2.2
   Exclude:
     - "gemfiles/**/*"
     - "vendor/**/*"
     - "lib/generators/**/*"
 
+Metrics/BlockLength:
+  Exclude:
+    - "**/*_spec.rb"
+
 Metrics/MethodLength:
   Max: 40
 
 Metrics/ModuleLength:
   Max: 200
+  Exclude:
+    - "**/*_spec.rb"
 
 Metrics/LineLength:
   Max: 120
@@ -22,74 +30,47 @@ Metrics/CyclomaticComplexity:
 Metrics/PerceivedComplexity:
   Enabled: false
 
-Style/StructInheritance:
-  Enabled: false
-
-Style/AlignParameters:
+Layout/AlignParameters:
   EnforcedStyle: with_fixed_indentation
 
-Style/StringLiterals:
-  EnforcedStyle: double_quotes
-
-Style/StringLiteralsInInterpolation:
-  EnforcedStyle: double_quotes
-
-Style/ClosingParenthesisIndentation:
-  Enabled: false
-
-Style/OneLineConditional:
-  Enabled: false
-
-Style/AndOr:
-  Enabled: false
-
-Style/Not:
-  Enabled: false
-
-Documentation:
-  Enabled: false # TODO: Enable again once we have more docs
-
-Style/CaseIndentation:
-  IndentWhenRelativeTo: case
+Layout/CaseIndentation:
+  EnforcedStyle: case
   SupportedStyles:
     - case
     - end
   IndentOneStep: true
 
-Style/PercentLiteralDelimiters:
-  PreferredDelimiters:
-    '%w': "[]"
-    '%W': "[]"
-
-Style/AccessModifierIndentation:
+Layout/AccessModifierIndentation:
   EnforcedStyle: outdent
 
-Style/SignalException:
-  Enabled: false
-
-Style/IndentationWidth:
-  Enabled: false
+Layout/EndAlignment:
+  EnforcedStyleAlignWith: variable
 
-Style/TrivialAccessors:
-  ExactNameMatch: true
+Style/FrozenStringLiteralComment:
+  Enabled: true
 
-Lint/EndAlignment:
-  AlignWith: variable
+Style/PercentLiteralDelimiters:
+  PreferredDelimiters:
+    '%w': "[]"
+    '%W': "[]"
 
-Lint/DefEndAlignment:
-  Enabled: false
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
 
-Lint/HandleExceptions:
-  Enabled: false
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
 
-Style/SpecialGlobalVars:
+Style/StructInheritance:
   Enabled: false
 
-Style/TrivialAccessors:
+Style/AndOr:
   Enabled: false
 
-Style/IndentHash:
+Style/Not:
   Enabled: false
 
 Style/DoubleNegation:
   Enabled: false
+
+Documentation:
+  Enabled: false # TODO: Enable again once we have more docs

data/.travis.yml

@@ -1,11 +1,21 @@
 language: ruby
-sudo: false
-rvm:
-  - 2.0.0
-  - 2.1
-  - 2.2
-  - jruby-19mode
-  - rbx-2
-env:
-  - RSPEC_VERSION="<2.99"
-  - RSPEC_VERSION="~>3.0
+before_install:
+  - gem install bundler -v 1.17.3
+
+matrix:
+  include:
+    - rvm: 2.5.1 # Pre-installed Ruby version
+      script: bundle exec rake rubocop # ONLY lint once, first
+    - rvm: 2.1
+    - rvm: 2.2
+    - rvm: 2.3.5
+    - rvm: 2.4.6
+    - rvm: 2.5.5
+    - rvm: 2.6.3
+    - rvm: jruby-9.1.8.0
+      env:
+        - JRUBY_OPTS="--debug"
+      jdk: openjdk8
+    - rvm: jruby-9.2.8.0
+      env:
+        - JRUBY_OPTS="--debug"

data/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Pundit
 
+### Fixed
+
+- Avoid name clashes with the Error class. (#590)
+
+### Changed
+
+- Return a safer default NotAuthorizedError message. (#583)
+
+## 2.0.1 (2019-01-18)
+
+### Breaking changes
+
+None
+
+### Other changes
+
+- Improve exception handling for `#policy_scope` and `#policy_scope!`. (#550)
+- Add `:policy` metadata to RSpec template. (#566)
+
+## 2.0.0 (2018-07-21)
+
+No changes since beta1
+
+## 2.0.0.beta1 (2018-07-04)
+
+### Breaking changes
+
+- Only pass last element of "namespace array" to policy and scope. (#529)
+- Raise `InvalidConstructorError` if a policy or policy scope with an invalid constructor is called. (#462)
+- Return passed object from `#authorize` method to make chaining possible. (#385)
+
+### Other changes
+
+- Add `policy_class` option to `authorize` to be able to override the policy. (#441)
+- Add `policy_scope_class` option to `authorize` to be able to override the policy scope. (#441)
+- Fix `param_key` issue when passed an array. (#529)
+- Allow specification of a `NilClassPolicy`. (#525)
+- Make sure `policy_class` override is called when passed an array. (#475)
+
+- Use `action_name` instead of `params[:action]`. (#419)
+- Add `pundit_params_for` method to make it easy to customize params fetching. (#502)
+
 ## 1.1.0 (2016-01-14)
 
 - Can retrieve policies via an array of symbols/objects.

data/Gemfile

@@ -1,4 +1,7 @@
+# frozen_string_literal: true
+
 source "https://rubygems.org"
 
-gem "rspec", ENV["RSPEC_VERSION"] unless ENV["RSPEC_VERSION"].to_s.empty?
+ruby RUBY_VERSION
+
 gemspec

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2012 Jonas Nicklas, Elabs AB
+Copyright (c) 2019 Jonas Nicklas, Varvet AB
 
 MIT License
 

data/README.md

@@ -1,8 +1,8 @@
 # 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
@@ -12,13 +12,13 @@ scaleable 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)
+- [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
 
@@ -116,7 +116,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 +133,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 +165,15 @@ def admin_list
 end
 ```
 
+`authorize` returns the object passed to it, so you can chain it like this:
+
+Controller:
+```ruby
+def show
+  @user = authorize 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:
@@ -172,6 +195,10 @@ class DashboardPolicy < Struct.new(:user, :dashboard)
 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?
@@ -184,54 +211,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
@@ -258,7 +237,7 @@ class PostPolicy < ApplicationPolicy
   end
 
   def update?
-    user.admin? or not post.published?
+    user.admin? or not record.published?
   end
 end
 ```
@@ -291,7 +270,7 @@ class PostPolicy < ApplicationPolicy
   end
 
   def update?
-    user.admin? or not post.published?
+    user.admin? or not record.published?
   end
 end
 ```
@@ -302,6 +281,19 @@ 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
@@ -322,6 +314,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
+  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
+  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
@@ -362,7 +418,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 +433,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
 ```
 
@@ -402,6 +490,10 @@ class ApplicationController < ActionController::Base
 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
@@ -469,6 +561,48 @@ 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 = Post.find(params[:id])
+    authorize(post)
+  end
+end
+```
+
 ## Additional context
 
 Pundit strongly encourages you to model your application in such a way that the
@@ -564,6 +698,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 +773,22 @@ 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!
+
 # 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)
+- [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.