rails-action-authorization 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8d8a18e02c7cba715ff6d0369b2bc1463545d45062e58408ec8384d1dcbd316
-  data.tar.gz: 04ecdf2bae106d9cee8d4601f8693a7634a311a5cd12b905631954ed7e4d2be4
+  metadata.gz: 338c7a7bb0cbcb557f5797bc1c7c277d23f920495fd7045ce89b2c05b7c19667
+  data.tar.gz: 4a34a09a6089495f5987f6ac3e57937fdc5b03281345c8145ae64ec39e331df2
 SHA512:
-  metadata.gz: 81053e97cbf237ac0cf489a370d2f3c13b057838c99fecbed411e814e7d884d2f18faf73a8cd2705e2e39fa1d5bcb8555f7626dbabe5933b3fc0a8e878912709
-  data.tar.gz: 6d02f17442c5276e29de19ce8d6ba4599841847ee52b39660cdadafdbc96400801878daa4b02ca842021d3c6c6be8e0fc6cd9d351d5025b3fd5f27653e8ba41a
+  metadata.gz: e5609c9f4957b9e1371993b28293c534ebd78f45efe1076e131b8a8eebf6095af501a417ebe794b73786f2c539c4a1eb06590c435a99cf75fc01326f3bf4141c
+  data.tar.gz: 8eb2ac294e8cf13b17f5706153a7c1c09ffc180fa4b93c85a01d994fbee0b1e2a01cd51cf39f095d9ad0ba03a12a1291800275a7dca5ce936b0b18f0c580ce52

data/lib/authorizer.rb

@@ -1,5 +1,7 @@
 require "authorizer/railtie"
 
+##
+# The main module which contains all the code of +rails-action-authorization+.
 module ActionAuthorization
   # Your code goes here...
 end

data/lib/authorizer/action_controller_patch.rb

@@ -3,7 +3,31 @@ module ActionAuthorization
 
     POSSIBILITIES = [:allow_all, :deny_all, :filter]
 
+    ##
+    # This class adds instance methods to base controller to increase the ease
+    # with which authorization may be checked from controllers.
     class ActionController::Metal
+
+        ##
+        # This method checks the authorization of a given actor (authorizee) to 
+        # complete the controller action for the specified resource.
+        #
+        # The resource can be a single model or a List of models. In the case of
+        # a list of models, there are several options for dealing with list members
+        # that fail authorization checks. The default option is +behavior: :filter+ which
+        # will authorize the list but will hide all members of the list which fail
+        # the authorization check. Other options are +:allow_all+ and +:deny_all+.
+        # +:allow_all+ will permit the entire list and include even list members which
+        # fail the authorization test. +:deny_all+, on the other, authorizes the list only
+        # if all of its members pass the authorization check. Therefore, if any list member fails
+        # the authorization check, the actor is forbidden from completing the action on the entire
+        # list.
+        #
+        # @param resource either a model or a list of models for which the actor (authorizee) is 
+        #   attempting to complete the controller action.
+        # @param authorizee [Model] The actor (usually a +User+ model) attempting authorization.
+        # @param **options An unspecified number of options. Currently the only supported key is
+        #   +:behavior+ and the only supported actions are +:filter+, +:allow_all+, and +:deny_all+.
         def check_authorization(resource, authorizee, **options)
             action = "#{params[:controller]}##{action_name}"
 

data/lib/authorizer/active_record_patch.rb

@@ -1,5 +1,15 @@
 module ActionAuthorization
+  ##
+  # This class contains all the patches to +ActiveRecord::Base+ that
+  # make this library function on the model side. You should only
+  # have to interact with these methods on concrete models and not by
+  # interacting with +ActiveRecord::Base+ directly. 
   class ActiveRecord::Base
+
+    ##
+    # returns the hash mapping permission rules to executable actions.
+    # This is used internally and should not need to be called directly
+    # by the user.
     def self.get_perms
       unless (self.class_variables.include?(:'@@perms'))
         @@perms = {}
@@ -8,25 +18,59 @@ module ActionAuthorization
       return @@perms
     end
     
+    ##
+    # Ensures that the +fallback_rule+ class variable is defined.
+    # Used internally. There should be no need for users to call this method directly.
     def self.init_fallback_rule
       @@fallback_rule = nil unless (self.class_variable_defined?(:@@fallback_rule))
     end
-
+    
+    ##
+    # Defines an authorization rule for the specified
+    # action names. If multiple names are passed, then the same rule
+    # will be used for all of them.
+    # 
+    # Action names should take the following format "controller_name#action_name".
+    # E.G. To specify a rule for the update action on the posts controller, you would write
+    # 'posts#update'.
+    #
+    # names can also be symbols.
+    #
+    # @param *names [String, Symbol] The names of the actions which will use 
+    #   the given block for authorization.
+    # @param &block [Proc] The code to run on an authorization check.
     def self.define_rule(*names, &block)
       perms = self.get_perms
       names.each {|name| perms[name.to_sym] = block}
     end
-
+    
+    ##
+    # Defines a fallback rule. The fallback rule defined by this
+    # class method will be used in every case where a permission rule is not
+    # specified. This is intended to be used in situations where 
+    # users wish to define some generic authorization check that will be run for
+    # every action that doesn't have its own rule specified.
+    #
+    # @param &rule [Proc] The code to run when a rule is not defined for any action.
     def self.set_fallback_rule(&rule)
       @@fallback_rule = rule
     end
 
+    ##
+    # Checks whether the given actor (authorizee) is permitted to perform the given
+    # action on this instance of a model. Generally, this method is called by
+    # other parts of +rails-action-authorization+ and need not be invoked
+    # directly. It can be invoked directly if users need more precise control
+    # over a permission than is available using the default authorization flow.
+    # 
+    # Returns the model instance it is invoked on unless the actor (authorizee) is
+    # forbidden from performing the action, in which case it will raise a +ForbiddenError+.
     def is_authorized(action, authorizee)
       symbol = action.to_sym
       perms = self.class.get_perms
 
       authorized = false
-      authorized = perms[symbol].(self, authorizee) if perms[symbol]
+      authorized = perms[symbol].(self, authorizee, symbol) if perms[symbol]
       authorized = @@fallback_rule.(self, authorizee) if @@fallback_rule && !perms[symbol]
 
       raise ForbiddenError.new(

data/lib/authorizer/resource.rb

@@ -1,7 +1,32 @@
 module ActionAuthorization
+
+    ##
+    # This class represents a generic list of models that are about to
+    # authorized.
+    #
+    # It is instantiated automatically by +ActionController::Metal#check_authorization+ and there
+    # should be little need to instantiate it directly.
     class Resource
-        attr_reader :action, :actor, :resources, :options
-  
+        ##
+        # @return [String, Symbol] The action which +:actor+ is attempting to complete.
+        attr_reader :action
+        
+        # @return [Model] The model attempting authorization (usually a +User+).
+        attr_reader :actor
+        
+        # @return The list of models being authorized.
+        attr_reader :resources
+        
+        # @return The options which are being used for authorization.
+        attr_reader :options
+        
+        ##
+        # Creates a new instance of +Resource+.
+        #
+        # @param action [String, Symbol] The name of the action being performed.
+        # @param actor [Model] The model attempting authorization.
+        # @param *resources [Model] The list of models being authorized.
+        # @param **options Any additional options regarding the authorization options.
         def initialize(action, actor, *resources, **options)
             @action = action
             @actor = actor
@@ -9,6 +34,11 @@ module ActionAuthorization
             @options = options
         end
   
+        ##
+        # Returns the list of models passed into the constructor
+        # if the list passes authorization, otherwise raises
+        # +ForbiddenError+.
+        # @returns The list of models being authorized.
         def get
           return @resources if @resources.nil?
           return @resources if @resources.length == 0
@@ -25,6 +55,8 @@ module ActionAuthorization
               collect_permitted {|results| results.length == @resources.length}
           when :filter
               collect_permitted {|results| results.length > 0}
+          else
+            collect_permitted {|results| results.length > 0}
           end
         end
   

data/lib/authorizer/version.rb

@@ -1,3 +1,3 @@
 module ActionAuthorization
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails-action-authorization
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Andrew Luchuk
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-04-01 00:00:00.000000000 Z
+date: 2020-04-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -84,7 +84,8 @@ files:
 homepage: https://github.com/speratus/rails-action-authorization
 licenses:
 - MIT
-metadata: {}
+metadata:
+  allowed_push_host: http://rubygems.org
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -100,7 +101,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.6
+rubyforge_project: 
+rubygems_version: 2.7.7
 signing_key: 
 specification_version: 4
 summary: Rails Action Authorization adds an authorization framework for controller