pragma-policy 0.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3558b9e18dec8f44921f49f1390ac27ec81d0633
-  data.tar.gz: ae90ff0b36bbd2ba93c66af2f33f540727517140
+  metadata.gz: 92f9cd653b6f54508780a68f79ccaa83c923780c
+  data.tar.gz: 12813e8504acfcade966bf450a4bd0c3f76db4be
 SHA512:
-  metadata.gz: e3dfe25ea37762ef45e30d474a5176d38f558d528f0352b3cc342a4f18c1508e9c8fe8f6605b67082ef5a8fa06f352bad19a6df420b8d42b2f5d8aa2acfdbeac
-  data.tar.gz: 3d15e2cceb67dc0236f0d9204d3938f0e248946688d07346e4f19bb572ae68b2767987fd1c34a8210659e681f1ee2e29d748164d57a46b487f813cf546d1f6bd
+  metadata.gz: 45f33ffbbc876b4a386841e819e8ce85d315039bad4d5644e999d527c88fa97153217f689c99dfb987481a0b6f1483775c7e0bb75ab568a8af4f0fe58caddcea
+  data.tar.gz: f7cd7b953b894075e7fe636c314509c3d8d9972b865312aa7afc758cce36180eda3ed1f30bb710e7d8ea763521e7a9cda0ee401f9786483940b8d5c9c0d740e2

data/.rubocop.yml

@@ -15,6 +15,7 @@ AllCops:
    - 'config/**/*'
    - '**/Rakefile'
    - '**/Gemfile'
+   - 'pragma-policy.gemspec'
 
 RSpec/DescribeClass:
   Exclude:
@@ -24,26 +25,26 @@ Style/BlockDelimiters:
   Exclude:
     - 'spec/**/*'
 
-Style/AlignParameters:
+Layout/AlignParameters:
   EnforcedStyle: with_fixed_indentation
 
-Style/ClosingParenthesisIndentation:
+Layout/ClosingParenthesisIndentation:
   Enabled: false
 
 Metrics/LineLength:
   Max: 100
   AllowURI: true
 
-Style/FirstParameterIndentation:
+Layout/FirstParameterIndentation:
   Enabled: false
 
-Style/MultilineMethodCallIndentation:
+Layout/MultilineMethodCallIndentation:
   EnforcedStyle: indented
 
-Style/IndentArray:
+Layout/IndentArray:
   EnforcedStyle: consistent
 
-Style/IndentHash:
+Layout/IndentHash:
   EnforcedStyle: consistent
 
 Style/SignalException:
@@ -53,7 +54,7 @@ Style/BracesAroundHashParameters:
   EnforcedStyle: context_dependent
 
 Lint/EndAlignment:
-  AlignWith: variable
+  EnforcedStyleAlignWith: variable
   AutoCorrect: true
 
 Style/AndOr:
@@ -68,7 +69,7 @@ RSpec/NamedSubject:
 RSpec/ExampleLength:
   Enabled: false
 
-Style/MultilineMethodCallBraceLayout:
+Layout/MultilineMethodCallBraceLayout:
   Enabled: false
 
 Metrics/MethodLength:
@@ -82,3 +83,6 @@ Metrics/PerceivedComplexity:
 
 Metrics/CyclomaticComplexity:
   Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false

data/README.md

@@ -7,7 +7,7 @@
 
 Policies provide fine-grained access control for your API resources.
 
-They are built on top of [Reform](https://github.com/apotonick/reform).
+They are built on top of the [Pundit](https://github.com/elabs/pundit) gem.
 
 ## Installation
 
@@ -36,7 +36,7 @@ To create a policy, simply inherit from `Pragma::Policy::Base`:
 ```ruby
 module API
   module V1
-    module Post
+    module Article
       class Policy < Pragma::Policy::Base
       end
     end
@@ -44,29 +44,31 @@ module API
 end
 ```
 
-By default, the policy does not return any objects and forbids all operations.
+By default, the policy does not return any objects when scoping and forbids all operations.
 
 You can start customizing your policy by defining a scope and operation predicates:
 
 ```ruby
 module API
   module V1
-    module Post
+    module Article
       class Policy < Pragma::Policy::Base
-        def self.accessible_by(user:, scope:)
-          scope.where('published = ? OR author_id = ?', true, user.id)
+        class Scope < Pragma::Policy::Base::Scope
+          def resolve
+            scope.where('published = ? OR author_id = ?', true, user.id)
+          end
         end
 
         def show?
-          resource.published? || resource.author_id == user.id
+          record.published? || record.author_id == user.id
         end
 
         def update?
-          resource.author_id == user.id
+          record.author_id == user.id
         end
 
         def destroy?
-          resource.author_id == user.id
+          record.author_id == user.id
         end
       end
     end
@@ -76,103 +78,31 @@ end
 
 You are ready to use your policy!
 
-### Retrieving records
+### Retrieving Records
 
 To retrieve all the records accessible by a user, use the `.accessible_by` class method:
 
 ```ruby
-posts = API::V1::Post::Policy.accessible_by(user: user, scope: Post.all)
+posts = API::V1::Article::Policy::Scope.new(user, Article.all).resolve
 ```
 
-### Authorizing operations
+### Authorizing Operations
 
 To authorize an operation, first instantiate the policy, then use the predicate methods:
 
 ```ruby
-policy = API::V1::Post::Policy.new(user: user, resource: post)
+policy = API::V1::Article::Policy.new(user, post)
 fail 'You cannot update this post!' unless policy.update?
 ```
 
 Since raising when the operation is forbidden is so common, we provide bang methods a shorthand
-syntax. `Pragma::Policy::ForbiddenError` is raised if the predicate method returns `false`:
+syntax. `Pragma::Policy::NotAuthorizedError` is raised if the predicate method returns `false`:
 
 ```ruby
-policy = API::V1::Post::Policy.new(user: user, resource: post)
+policy = API::V1::Article::Policy.new(user, post)
 policy.update! # raises if the user cannot update the post
 ```
 
-### Attribute-level authorization
-
-In some cases, you'll want to prevent a user from updating a certain attribute. You can do that with
-the `#authorize_attr` method:
-
-```ruby
-module API
-  module V1
-    module Post
-      class Policy < Pragma::Policy::Base
-        def update?
-          # admins can do whatever they want
-          return true if user.admin?
-
-          (
-            resource.author_id == user.id &&
-            # regular users cannot change the 'featured' attribute
-            authorize_attr(:featured)
-          )
-        end
-      end
-    end
-  end
-end
-```
-
-You can also allow specific values for an enumerated attribute:
-
-```ruby
-module API
-  module V1
-    module Post
-      class Policy < Pragma::Policy::Base
-        def update?
-          # admins can do whatever they want
-          return true if user.admin?
-
-          (
-            resource.author_id == user.id &&
-            # regular users can only set status to 'draft' or 'published'
-            authorize_attr(:status, only: ['draft', 'published'])
-          )
-        end
-      end
-    end
-  end
-end
-```
-
-Or you can invert the condition and specify the forbidden attributes:
-
-```ruby
-module API
-  module V1
-    module Post
-      class Policy < Pragma::Policy::Base
-        def update?
-          # admins can do whatever they want
-          return true if user.admin?
-
-          (
-            resource.author_id == user.id &&
-            # regular users cannot set the status to 'rejected'
-            authorize_attr(:status, except: ['rejected'])
-          )
-        end
-      end
-    end
-  end
-end
-```
-
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/pragmarb/pragma-policy.

data/lib/pragma/policy.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
+
+require 'pundit'
+
 require 'pragma/policy/version'
 require 'pragma/policy/base'
-require 'pragma/policy/attribute_authorizer'
+require 'pragma/policy/errors'
 
 module Pragma
   # Fine-grained access control for your API resources.

data/lib/pragma/policy/base.rb

@@ -1,41 +1,61 @@
 # frozen_string_literal: true
+
 module Pragma
   module Policy
-    # This is the base policy class that all your resource-specific policies should inherit from.
+    # This is the base policy class that all your record-specific policies should inherit from.
     #
     # A policy provides predicate methods for determining whether a user can perform a specific
-    # action on a resource.
+    # action on a record.
     #
     # @author Alessandro Desantis
     #
     # @abstract Subclass and implement action methods to create a policy.
     class Base
-      # @!attribute [r] user
-      #   @return [Object] the user operating on the resource
-      #
-      # @!attribute [r] resource
-      #   @return [Object] the resource being operated on
-      attr_reader :user, :resource
+      # Authorizes AR scopes and other relations by only returning the records accessible by the
+      # current user. Used, for instance, in index operations.
+      #
+      # @author Alessandro Desantis
+      class Scope
+        # @!attribute [r] user
+        #   @return [Object] the user accessing the records
+        #
+        # @!attribute [r] scope
+        #   @return [Object] the relation to use as a base
+        attr_reader :user, :scope
 
-      # Returns the records accessible by the given user.
-      #
-      # @param user [Object] the user accessing the records
-      # @param relation [Object] the relation to use as a base
-      #
-      # @return [Object]
-      #
-      # @abstract Override to implement retrieving the accessible records
-      def self.accessible_by(user, relation:) # rubocop:disable Lint/UnusedMethodArgument
-        fail NotImplementedError
+        # Initializes the scope.
+        #
+        # @param user [Object] the user accessing the records
+        # @param scope [Object] the relation to use as a base
+        def initialize(user, scope)
+          @user = user
+          @scope = scope
+        end
+
+        # Returns the records accessible by the given user.
+        #
+        # @return [Object]
+        #
+        # @abstract Override to implement retrieving the accessible records
+        def resolve
+          fail NotImplementedError
+        end
       end
 
+      # @!attribute [r] user
+      #   @return [Object] the user operating on the record
+      #
+      # @!attribute [r] record
+      #   @return [Object] the record being operated on
+      attr_reader :user, :record
+
       # Initializes the policy.
       #
-      # @param user [Object] the user operating on the resource
-      # @param resource [Object] the resource being operated on
-      def initialize(user:, resource:)
+      # @param user [Object] the user operating on the record
+      # @param record [Object] the record being operated on
+      def initialize(user, record)
         @user = user
-        @resource = resource
+        @record = record
       end
 
       # Returns whether the policy responds to the provided missing method.
@@ -71,67 +91,18 @@ module Pragma
       # @raise [ForbiddenError] if the user is not authorized to perform the action
       def authorize(action)
         unless respond_to?("#{action}?")
-          fail(
-            ArgumentError,
-            "'#{action}' is not a valid action for this policy."
-          )
+          fail(ArgumentError, "'#{action}' is not a valid action for this policy.")
         end
 
         return if send("#{action}?")
 
         fail(
-          ForbiddenError,
+          NotAuthorizedError,
           user: user,
           action: action,
-          resource: resource
+          record: record
         )
       end
-
-      protected
-
-      # Authorizes a resource attribute.
-      #
-      # @param attribute [Symbol] the name of the attribute
-      # @param options [Hash] options (see {AttributeAuthorizer#authorize} for allowed options)
-      #
-      # @return [Boolean] whether the attribute's value is allowed
-      def authorize_attr(attribute, options = {})
-        AttributeAuthorizer.new(
-          resource: resource,
-          attribute: attribute
-        ).authorize(options)
-      end
-    end
-
-    # This error is raised when a user attempts to perform an unauthorized operation on a
-    # resource.
-    #
-    # @author Alessandro Desantis
-    class ForbiddenError < StandardError
-      MESSAGE = "User is not authorized to perform the '%{action}' action on this resource."
-
-      # @!attribtue [r] user
-      #   @return [Object] the user operating on the resource
-      #
-      # @!attribute [r] action
-      #   @return [Symbol] the attempted action
-      #
-      # @!attribute [r] resource
-      #   @return [Object] the resource being operated on
-      attr_reader :user, :action, :resource
-
-      # Initializes the error.
-      #
-      # @param user [Object] the user operating on the resource
-      # @param action [Symbol] the attempted action
-      # @param resource [Object] the resource being operated on
-      def initialize(user:, action:, resource:)
-        @user = user
-        @action = action.to_sym
-        @resource = resource
-
-        super MESSAGE.gsub('%{action}', action.to_s)
-      end
     end
   end
 end

data/lib/pragma/policy/errors.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Pragma
+  module Policy
+    class NotAuthorizedError < Pundit::NotAuthorizedError
+    end
+  end
+end

data/lib/pragma/policy/version.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
+
 module Pragma
   module Policy
-    VERSION = '0.1.0'
+    VERSION = '2.0.0'
   end
 end

data/pragma-policy.gemspec

@@ -1,29 +1,32 @@
-# coding: utf-8
+# frozen_string_literal: true
+
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'pragma/policy/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "pragma-policy"
+  spec.name          = 'pragma-policy'
   spec.version       = Pragma::Policy::VERSION
-  spec.authors       = ["Alessandro Desantis"]
-  spec.email         = ["desa.alessandro@gmail.com"]
+  spec.authors       = ['Alessandro Desantis']
+  spec.email         = ['desa.alessandro@gmail.com']
 
   spec.summary       = 'Fine-grained access control for your API resources.'
-  spec.homepage      = "https://github.com/pragmarb/pragma-policy"
-  spec.license       = "MIT"
+  spec.homepage      = 'https://github.com/pragmarb/pragma-policy'
+  spec.license       = 'MIT'
 
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})
   end
-  spec.bindir        = "exe"
+  spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'pundit', '~> 1.1'
 
-  spec.add_development_dependency "bundler"
-  spec.add_development_dependency "rake"
-  spec.add_development_dependency "rspec"
-  spec.add_development_dependency "rubocop"
-  spec.add_development_dependency "rubocop-rspec"
-  spec.add_development_dependency "coveralls"
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'rubocop-rspec'
+  spec.add_development_dependency 'coveralls'
 end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: pragma-policy
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Alessandro Desantis
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-12-26 00:00:00.000000000 Z
+date: 2017-09-27 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: pundit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -112,8 +126,8 @@ files:
 - bin/console
 - bin/setup
 - lib/pragma/policy.rb
-- lib/pragma/policy/attribute_authorizer.rb
 - lib/pragma/policy/base.rb
+- lib/pragma/policy/errors.rb
 - lib/pragma/policy/version.rb
 - pragma-policy.gemspec
 homepage: https://github.com/pragmarb/pragma-policy
@@ -136,7 +150,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.2
+rubygems_version: 2.6.13
 signing_key: 
 specification_version: 4
 summary: Fine-grained access control for your API resources.

data/lib/pragma/policy/attribute_authorizer.rb

@@ -1,142 +0,0 @@
-# frozen_string_literal: true
-module Pragma
-  module Policy
-    # The attribute authorizer provides attribute-level authorization for resource updates.
-    #
-    # It allows you to specify whether a resource attribute can be changed and, if you want, what
-    # values should be allowed.
-    #
-    # If you want, you can subclass this base authorizer to avoid repeating code.
-    #
-    # @author Alessandro Desantis
-    class AttributeAuthorizer
-      # @!attribute [r] resource
-      #   @return [ActiveRecord::Base|Reform::Form] the resource being authorized
-      #
-      # @!attribute [r] attribute
-      #   @return [Symbol] the attribute being authorized
-      attr_reader :resource, :attribute
-
-      # Initializes the authorizer.
-      #
-      # @param resource [ActiveRecord::Base|Reform::Form] the resource being authorized
-      # @param attribute [Symbol] the attribute being authorized
-      #
-      # @raise [UnknownEngineError] if the resource is not based on Reform or ActiveRecord
-      def initialize(resource:, attribute:)
-        @resource = resource
-        @attribute = attribute
-
-        validate_resource
-      end
-
-      # Returns the old value of the attribute (if any).
-      #
-      # For Reform, this retrieves the current value of the attribute from the model. For
-      # ActiveRecord, uses the +<attribute>_was+ method.
-      #
-      # @return [Object|NilClass]
-      def old_value
-        case resource_engine
-        when :reform
-          resource.model.send(attribute)
-        when :active_record
-          resource.send("#{attribute}_was")
-        end
-      end
-
-      # Returns the new (i.e. current) value of the attribute.
-      #
-      # Simply sends the attribute name to the resource.
-      #
-      # @return [Object]
-      def new_value
-        resource.send(attribute)
-      end
-
-      # Returns whether the attribute has changed, by comparing the new and the old value.
-      #
-      # @return [Boolean]
-      def changed?
-        old_value != new_value
-      end
-
-      # Returns the engine used for the resource being authorized (Reform or ActiveRecord).
-      #
-      # @return [Symbol] +:reform+ or +:active_record+
-      #
-      # @raise [UnknownEngineError] if the engine cannot be detected
-      def resource_engine
-        if defined?(Reform::Form) && resource.is_a?(Reform::Form)
-          :reform
-        elsif defined?(ActiveRecord::Base) && resource.is_a?(ActiveRecord::Base)
-          :active_record
-        else
-          fail UnknownEngineError(resource: resource, attribute: attribute)
-        end
-      end
-
-      # Ensures that the attribute was changed according to the provided options.
-      #
-      # When neither +only+ nor +except+ are passed, simply ensures that the attribute was not
-      # changed.
-      #
-      # When +only+ is passed and is not empty, ensures that the value is part of the given array.
-      #
-      # When +except+ is passed and not empty, also ensures that the value is NOT part of the given
-      # array.
-      #
-      # @param options [Hash] a hash of options
-      #
-      # @option options [Array<String>] :only an optional list of allowed values
-      # @option options [Array<String>] :except an optional list of forbidden values
-      #
-      # @return [Boolean] whether the attribute has an authorized value
-      def authorize(options = {})
-        options[:only] = ([options[:only]] || []).flatten.map(&:to_s).reject(&:empty?)
-        options[:except] = ([options[:except]] || []).flatten.map(&:to_s).reject(&:empty?)
-
-        if options[:only].any? && options[:except].any?
-          fail(
-            ArgumentError,
-            'The :only and :except options cannot be used at the same time.'
-          )
-        end
-
-        return true unless changed?
-
-        if options[:only].any?
-          options[:only].include?(new_value.to_s)
-        elsif options[:except].any?
-          !options[:except].include?(new_value.to_s)
-        end || false
-      end
-
-      private
-
-      def validate_resource
-        resource_engine
-      end
-
-      # This error when the engine behind a resource cannot be detected for attribute authorization.
-      #
-      # @author Alessanro Desantis
-      class UnknownEngineError < StandardError
-        MESSAGE = 'Attribute authorization only works with Reform forms and ActiveRecord models.'
-
-        # @!attribute [r] resource
-        #   @return [Object] the resource
-        attr_reader :resource
-
-        # Initializes the error.
-        #
-        # @param resource [Object] the resource
-        def initialize(resource:)
-          @resource = resource
-
-          super MESSAGE
-        end
-      end
-    end
-  end
-end