pundit 1.1.0 → 2.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: a2c188098c86ad5a0804044f80219014564501ef
-  data.tar.gz: 2ab7f79275d9ae66e5d04cf980c11e2c2983a4ef
+SHA256:
+  metadata.gz: 91c992d8bb2bc907e4c532fb868f0e6f4105d9f4a79f0871593ec374f6f173b0
+  data.tar.gz: a855c49b6ada65cd8d1309ed104d6d089236ec46fcade8e872b66be6b152a054
 SHA512:
-  metadata.gz: 55fbbf71ad514c0cfe4f8933dea59915314f749efa53ab5579f2da9dfcf2b4786343cefa53d3a35e26f4a346776c1c513884595a39561d280b259e6b6fb9b31a
-  data.tar.gz: bbcf9417801b22deac78afe2d5ea8a268193daf0e011f861006c25b1d0124d1f462aa37d4d38e623b9d438cb29ceb52b250575118e053862b74561795bbdd7a4
+  metadata.gz: 17b426b7b0a1410809be20410d20f2f291d26d3fde05bb333b68464f720c7824989f5063ba30c107459debaabb572f9a682738a74f35ebc08c4b3b6638350a3a
+  data.tar.gz: e28ba68e5f8c1a430a4cb1335b0ad95ff2d4dc35d5c2842e74321aad26e42cf8f1c383b217cbac8aab8449f20ef1d9faf10fe1432d27287fce961bea04e53b4e

data/.rubocop.yml

@@ -1,14 +1,22 @@
 AllCops:
+  DisplayCopNames: true
+  TargetRubyVersion: 2.1
   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
@@ -25,7 +33,7 @@ Metrics/PerceivedComplexity:
 Style/StructInheritance:
   Enabled: false
 
-Style/AlignParameters:
+Layout/AlignParameters:
   EnforcedStyle: with_fixed_indentation
 
 Style/StringLiterals:
@@ -34,7 +42,7 @@ Style/StringLiterals:
 Style/StringLiteralsInInterpolation:
   EnforcedStyle: double_quotes
 
-Style/ClosingParenthesisIndentation:
+Layout/ClosingParenthesisIndentation:
   Enabled: false
 
 Style/OneLineConditional:
@@ -49,8 +57,8 @@ Style/Not:
 Documentation:
   Enabled: false # TODO: Enable again once we have more docs
 
-Style/CaseIndentation:
-  IndentWhenRelativeTo: case
+Layout/CaseIndentation:
+  EnforcedStyle: case
   SupportedStyles:
     - case
     - end
@@ -61,22 +69,22 @@ Style/PercentLiteralDelimiters:
     '%w': "[]"
     '%W': "[]"
 
-Style/AccessModifierIndentation:
+Layout/AccessModifierIndentation:
   EnforcedStyle: outdent
 
 Style/SignalException:
   Enabled: false
 
-Style/IndentationWidth:
+Layout/IndentationWidth:
   Enabled: false
 
 Style/TrivialAccessors:
   ExactNameMatch: true
 
-Lint/EndAlignment:
-  AlignWith: variable
+Layout/EndAlignment:
+  EnforcedStyleAlignWith: variable
 
-Lint/DefEndAlignment:
+Layout/DefEndAlignment:
   Enabled: false
 
 Lint/HandleExceptions:
@@ -88,7 +96,7 @@ Style/SpecialGlobalVars:
 Style/TrivialAccessors:
   Enabled: false
 
-Style/IndentHash:
+Layout/IndentHash:
   Enabled: false
 
 Style/DoubleNegation:

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 update --system
+  - gem install bundler
+
+matrix:
+  include:
+    - rvm: 2.5.1
+      script: bundle exec rake rubocop # ONLY lint once, first
+    - rvm: 2.1
+    - rvm: 2.2.8
+    - rvm: 2.3.5
+    - rvm: 2.4.2
+    - rvm: 2.5.1
+    - rvm: jruby-9.1.8.0
+      env:
+        - JRUBY_OPTS="--debug"
+    - rvm: jruby-9.2.0.0
+      env:
+        - JRUBY_OPTS="--debug"

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Pundit
 
+## 2.0.0.beta1 (2018-07-04)
+
+- 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)
+- Only pass last element of "namespace array" to policy and scope. (#529)
+- Allow specification of a `NilClassPolicy`. (#525)
+- Make sure `policy_class` override is called when passed an array. (#475)
+- Raise `InvalidConstructorError` if a policy or policy scope with an invalid constructor is called. (#462)
+- Use `action_name` instead of `params[:action]`. (#419)
+- Add `pundit_params_for` method to make it easy to customize params fetching. (#502)
+- Return passed object from `#authorize` method to make chaining possible. (#385)
+
 ## 1.1.0 (2016-01-14)
 
 - Can retrieve policies via an array of symbols/objects.

data/Gemfile

@@ -1,4 +1,16 @@
 source "https://rubygems.org"
 
-gem "rspec", ENV["RSPEC_VERSION"] unless ENV["RSPEC_VERSION"].to_s.empty?
+ruby RUBY_VERSION
+
 gemspec
+
+group :development, :test do
+  gem "actionpack"
+  gem "activemodel"
+  gem "bundler"
+  gem "pry"
+  gem "rake"
+  gem "rspec"
+  gem "rubocop"
+  gem "yard"
+end

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:
@@ -184,54 +207,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 +233,7 @@ class PostPolicy < ApplicationPolicy
   end
 
   def update?
-    user.admin? or not post.published?
+    user.admin? or not record.published?
   end
 end
 ```
@@ -291,7 +266,7 @@ class PostPolicy < ApplicationPolicy
   end
 
   def update?
-    user.admin? or not post.published?
+    user.admin? or not record.published?
   end
 end
 ```
@@ -302,6 +277,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 +310,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 +414,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 +429,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 +486,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 +557,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 +694,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,12 +769,16 @@ 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/)
 
 # License