pundit 2.0.0 → 2.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b973703e2b1653c804d138fb24c204807e41885a81f5b172656d032d7c2a75a
-  data.tar.gz: 01211cab222a4c16f274e041c074b2d2a1763a4943ab26b6dba938272297a48d
+  metadata.gz: b5c9e118c59bc3a683734817ac6fb9036a2b909df7abce2dbbdc00fc16aebdf7
+  data.tar.gz: 843cc1b7652e88d598a37a28f93bf13c41710bf3dddefeb96acf74e659279581
 SHA512:
-  metadata.gz: 812528978ec4e8d3322af071c3ebd5b31f4123be449d3fe9bfea1e1fd2845704e0fee308d4cdd6e787636987b1d7a03527f8eae5fe5968483a1f4c5f751b40ef
-  data.tar.gz: c433160a559102336b9a268ec1311a47e8f54e427ad8618b048634435259612a92d9b9187fefb6d7cc4a1ce5576a37f3e51b7adad1e3773d21c2bb6e9827c26f
+  metadata.gz: f2430ece33471f7a321a124aeafab7dbc3be4688fbda581b758d90649f4ae06d0cbaf86df768e881d0a2f1c0ab55581cb5dc0f1d3012ab7611b2fd81b8a0f321
+  data.tar.gz: 3432cc545ca5139cfcd7e1fc26a17d0882c11de71a3c6949c1d1da232183eba495de18aa06b64462c1233b820099788b43feeb0e9b439911bc9761dc7bd1e141

data/.github/pull_request_template.md

@@ -0,0 +1,9 @@
+## To do
+
+- [ ] I have read the [contributing guidelines](https://github.com/varvet/pundit/contribute).
+- [ ] I have added relevant tests.
+- [ ] I have adjusted relevant documentation.
+- [ ] I have made sure the individual commits are meaningful.
+- [ ] I have added relevant lines to the CHANGELOG.
+
+PS: Thank you for contributing to Pundit ❤️

data/.gitignore

@@ -2,6 +2,7 @@
 *.rbc
 .bundle
 .config
+.coverage
 .yardoc
 Gemfile.lock
 InstalledFiles

data/.rubocop.yml

@@ -1,10 +1,9 @@
 AllCops:
-  DisplayCopNames: true
-  TargetRubyVersion: 2.1
+  TargetRubyVersion: 2.6
   Exclude:
-    - "gemfiles/**/*"
-    - "vendor/**/*"
-    - "lib/generators/**/*"
+    - "lib/generators/**/templates/**/*"
+  SuggestExtensions: false
+  NewCops: disable
 
 Metrics/BlockLength:
   Exclude:
@@ -18,7 +17,7 @@ Metrics/ModuleLength:
   Exclude:
     - "**/*_spec.rb"
 
-Metrics/LineLength:
+Layout/LineLength:
   Max: 120
 
 Metrics/AbcSize:
@@ -30,33 +29,12 @@ Metrics/CyclomaticComplexity:
 Metrics/PerceivedComplexity:
   Enabled: false
 
-Style/StructInheritance:
-  Enabled: false
+Gemspec/RequiredRubyVersion:
+ Enabled: false
 
-Layout/AlignParameters:
+Layout/ParameterAlignment:
   EnforcedStyle: with_fixed_indentation
 
-Style/StringLiterals:
-  EnforcedStyle: double_quotes
-
-Style/StringLiteralsInInterpolation:
-  EnforcedStyle: double_quotes
-
-Layout/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
-
 Layout/CaseIndentation:
   EnforcedStyle: case
   SupportedStyles:
@@ -64,40 +42,31 @@ Layout/CaseIndentation:
     - end
   IndentOneStep: true
 
+Layout/EndAlignment:
+  EnforcedStyleAlignWith: variable
+
 Style/PercentLiteralDelimiters:
   PreferredDelimiters:
     '%w': "[]"
     '%W': "[]"
 
-Layout/AccessModifierIndentation:
-  EnforcedStyle: outdent
-
-Style/SignalException:
-  Enabled: false
-
-Layout/IndentationWidth:
-  Enabled: false
-
-Style/TrivialAccessors:
-  ExactNameMatch: true
-
-Layout/EndAlignment:
-  EnforcedStyleAlignWith: variable
-
-Layout/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
 
-Layout/IndentHash:
+Style/Not:
   Enabled: false
 
 Style/DoubleNegation:
   Enabled: false
+
+Style/Documentation:
+  Enabled: false # TODO: Enable again once we have more docs

data/.travis.yml

@@ -1,21 +1,27 @@
 language: ruby
-sudo: false
-before_install:
-  - gem update --system
-  - gem install bundler
+dist: focal
 
 matrix:
   include:
-    - rvm: 2.5.1
+    - name: "RuboCop lint on pre-installed Ruby version"
+      rvm: 2.7.1 # Pre-installed Ruby version
+      before_install:
+        - gem install bundler
       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
+    - rvm: 2.6.7
+      before_script:
+        - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+        - chmod +x ./cc-test-reporter
+        - ./cc-test-reporter before-build
+      after_script:
+        - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT
+    - rvm: 2.7.3
+    - rvm: 3.0.1
+    - rvm: 3.1.0
+    - rvm: 3.2.0
+    - rvm: jruby-9.3.10.0
       env:
         - JRUBY_OPTS="--debug"
+    - rvm: truffleruby-head
+  allow_failures:
+    - rvm: truffleruby-head

data/CHANGELOG.md

@@ -1,21 +1,103 @@
 # Pundit
 
+## Unreleased
+
+Nothing.
+
+## 2.3.1 (2023-07-17)
+
+### Fixed
+
+- Use `Kernel.warn` instead of `ActiveSupport::Deprecation.warn` for deprecations (#764)
+- Policy generator now works on Ruby 3.2 (#754)
+
+## 2.3.0 (2022-12-19)
+
+### Added
+
+- add support for rubocop-rspec syntax extensions (#745)
+
+## 2.2.0 (2022-02-11)
+
+### Fixed
+
+- Using `policy_class` and a namespaced record now passes only the record when instantiating the policy. (#697, #689, #694, #666)
+
+### Changed
+
+- Require users to explicitly define Scope#resolve in generated policies (#711, #722)
+
+### Deprecated
+
+- Deprecate `include Pundit` in favor of `include Pundit::Authorization` (#621)
+
+## 2.1.1 (2021-08-13)
+
+Friday 13th-release!
+
+Careful! The bugfix below (#626) could break existing code. If you rely on the
+return value for `authorize` and namespaced policies you might need to do some
+changes.
+
+### Fixed
+
+- `.authorize` and `#authorize` return the instance, even for namespaced
+  policies (#626)
+
+### Changed
+
+- Generate application scope with `protected` attr_readers. (#616)
+
+### Removed
+
+- Dropped support for Ruby end-of-life versions: 2.1 and 2.2. (#604)
+- Dropped support for Ruby end-of-life versions: 2.3 (#633)
+- Dropped support for Ruby end-of-life versions: 2.4, 2.5 and JRuby 9.1 (#676)
+- Dropped support for RSpec 2 (#615)
+
+## 2.1.0 (2019-08-14)
+
+### 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)
-- 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)
 

data/CONTRIBUTING.md

@@ -1,9 +1,6 @@
 ## Security issues
 
-If you have found a security related issue, please do not file an issue on
-GitHub or send a PR addressing the issue. Contact
-[Jonas](mailto:jonas.nicklas@gmail.com) directly. You will be given public
-credit for your disclosure.
+If you have found a security related issue, please do not file an issue on GitHub or send a PR addressing the issue. Refer to [SECURITY.md](./SECURITY.md) for instructions.
 
 ## Reporting issues
 

data/Gemfile

@@ -1,16 +1,7 @@
+# frozen_string_literal: true
+
 source "https://rubygems.org"
 
 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/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,17 +1,17 @@
 # Pundit
 
-[![Build Status](https://secure.travis-ci.org/varvet/pundit.svg?branch=master)](https://travis-ci.org/varvet/pundit)
+[![Build Status](https://app.travis-ci.com/varvet/pundit.svg?branch=main)](https://app.travis-ci.com/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.
+classes and object oriented design patterns to build a straightforward, robust, and
+scalable authorization system.
 
 Links:
 
-- [API documentation](http://www.rubydoc.info/gems/pundit)
+- [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)
@@ -22,16 +22,17 @@ Sponsored by:
 
 ## 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
 ```
 
@@ -48,8 +49,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
@@ -61,12 +62,12 @@ class PostPolicy
   end
 
   def update?
-    user.admin? or not post.published?
+    user.admin? || !post.published?
   end
 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
@@ -165,13 +166,18 @@ def admin_list
 end
 ```
 
-`authorize` returns the object passed to it, so you can chain it like this:
+`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`
@@ -190,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 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 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
@@ -216,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
@@ -230,6 +250,10 @@ class PostPolicy < ApplicationPolicy
         scope.where(published: true)
       end
     end
+
+    private
+
+    attr_reader :user, :scope
   end
 
   def update?
@@ -292,13 +316,11 @@ def index
 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
 ```
 
@@ -326,7 +348,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
 ```
@@ -339,7 +361,7 @@ authorize individual instances.
 
 ``` ruby
 class ApplicationController < ActionController::Base
-  include Pundit
+  include Pundit::Authorization
   after_action :verify_authorized, except: :index
   after_action :verify_policy_scoped, only: :index
 end
@@ -352,7 +374,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
@@ -387,20 +409,23 @@ class Post
 end
 ```
 
-## Just plain old Ruby
+Alternatively, you can declare an instance method:
+
+``` ruby
+class Post
+  def policy_class
+    PostablePolicy
+  end
+end
+```
+
+## 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
 
@@ -472,8 +497,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
 
@@ -481,7 +505,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(fallback_location: root_path)
   end
 end
 ```
@@ -510,7 +534,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_location: root_path)
  end
 end
 ```
@@ -524,8 +548,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
 
@@ -547,9 +570,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
@@ -593,8 +614,7 @@ class Admin::PostController < AdminController
   end
 
   def show
-    post = Post.find(params[:id])
-    authorize(post)
+    post = authorize Post.find(params[:id])
   end
 end
 ```
@@ -627,7 +647,7 @@ class UserContext
 end
 
 class ApplicationController
-  include Pundit
+  include Pundit::Authorization
 
   def pundit_user
     UserContext.new(current_user, request.ip)
@@ -637,9 +657,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:
 
@@ -663,7 +682,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
@@ -685,7 +704,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
@@ -767,20 +786,35 @@ 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.
+[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.
 
 ### 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/)
+- [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.