permit 0.9.0 → 1.0.0

data/VERSION.yml

@@ -1,5 +1,5 @@
----
-:major: 0
-:minor: 9
+--- 
+:minor: 0
 :patch: 0
-:build:
+:major: 1
+:build: 

data/lib/models/association.rb

@@ -4,17 +4,19 @@ module Permit
     # associations to help with querying for common cases. Some of these methods
     # do not show up in the documentation because they are dynamically created
     # with class_eval so that they can be explicit to the models you use for the
-    # Person and Role models.
+    # Person and Role models. See the documentation for {#method_missing} for
+    # additionally created methods.
     module AssociationExtensions
       include Permit::Support
 
-      # Finds all authorizations for the given resource
+      # Finds all authorizations for the given resources
       #
-      # @param [permit_authorizable, nil, :any] resource the resource to find 
-      #   authorizations for. :any may be given to find matches for any resource.
+      # @param [permit_authorizable, nil, :any, <permit_authorizable, nil>] 
+      #   resource the resources to find authorizations for. :any may be given 
+      #   to find matches for any resource.
       # @return [<permit_authorization>] the authorizations found for the resource.
-      def for(resource)
-        conditions = authorization_conditions(nil, resource)
+      def for(resources)
+        conditions = authorization_conditions(nil, resources)
         find(:all, :conditions => conditions)
       end
 
@@ -35,8 +37,8 @@ module Permit
       # @param [permit_role, String, Symbol, <permit_role, String, Symbol>] 
       #   roles the roles to find authorizations for.
       # @return [<permit_authorization>] the authorizations found for the resource and role(s)
-      def for_resource_as(resource, roles)
-        conditions = authorization_conditions(roles, resource)
+      def for_resources_as(resources, roles)
+        conditions = authorization_conditions(roles, resources)
         find(:all, :conditions => conditions)
       end
 
@@ -50,38 +52,53 @@ module Permit
         as(roles).collect(&:resource).uniq
       end
 
+      # Defines three methods used for getting your subject models for a
+      # resource, or as various roles, as well as role models for a given
+      # resource.
+      #
+      # @overload people_for(resources)
+      #   Finds all of the subjects that have authorizations for the given
+      #   resources. Where "people" is the plural name of your subject model.
+      #
+      #   @param [permit_authorizable, nil, :any, <permit_authorizable, nil>] 
+      #     resource the resources to find authorizations for. :any may be given 
+      #     to find matches for any resource.
+      #   @return [<permit_person>] a unique list of the people with 
+      #     authorizations for the resource.
+      #
+      # @overload people_as(roles)
+      #   Finds all of the subjects that have authorizations for the given
+      #   role(s). Where "people" is the plural name of your subject model.
+      #
+      #   @param [permit_role, String, Symbol, <permit_role, String, Symbol>] 
+      #     roles the roles to find authorizations for.
+      #   @return [<permit_person>] a unique list of the people with 
+      #     authorizations for the role(s).
+      #
+      # @overload roles_for(resources)
+      #   Finds all of the roles authorized for the given resources. Where
+      #   "roles" is the plural name of your role model.
+      #
+      #   @param [permit_authorizable, nil, :any, <permit_authorizable, nil>] 
+      #     resource the resources to find authorizations for. :any may be given 
+      #     to find matches for any resource.
+      #   @return [<permit_role>] a unique list of roles authorized for the 
+      #     resource.
+      def method_missing(*args, &block); super; end
+
       def self.extended(klass)
         class_eval <<-END
-          # Finds all of the people that have authorizations for the given resource.
-          #
-          # @param [permit_authorizable, nil, :any] resource the resource to find 
-          #   authorizations for. :any may be given to find matches for any resource.
-          # @return [<permit_person>] a unique list of the people with 
-          #   authorizations for the resource.
-          def #{Permit::Config.person_class.plural_class_symbol.to_s}_for(resource)
-            self.for(resource).collect(&:#{Permit::Config.person_class.class_symbol.to_s}).uniq
+          def #{Permit::Config.person_class.plural_class_symbol.to_s}_for(resources)
+            self.for(resources).collect(&:#{Permit::Config.person_class.class_symbol.to_s}).uniq
           end
 
-          # Finds all of the people that have authorizations for the given role(s).
-          #
-          # @param [permit_role, String, Symbol, <permit_role, String, Symbol>] 
-          #   roles the roles to find authorizations for.
-          # @return [<permit_person>] a unique list of the people with 
-          #   authorizations for the role(s).
           def #{Permit::Config.person_class.plural_class_symbol.to_s}_as(roles)
             as(roles).collect(&:#{Permit::Config.person_class.class_symbol.to_s}).uniq
           end
 
-          # Finds all of the roles authorized for the given resource.
-          #
-          # @param [permit_authorizable, nil, :any] resource the resource to find 
-          #   authorizations for. :any may be given to find matches for any resource.
-          # @return [<permit_role>] a unique list of roles authorized for the 
-          #   resource.
-          def #{Permit::Config.role_class.plural_class_symbol.to_s}_for(resource)
-            self.for(resource).collect(&:#{Permit::Config.role_class.class_symbol.to_s}).uniq
+          def #{Permit::Config.role_class.plural_class_symbol.to_s}_for(resources)
+            self.for(resources).collect(&:#{Permit::Config.role_class.class_symbol.to_s}).uniq
           end
-
         END
       end
     end

data/lib/models/person.rb

@@ -24,15 +24,15 @@ module Permit
         #
         # @param [Role, String, Symbol, <Role, String, Symbol>] roles the roles 
         #   to check for authorization on.
-        # @param [Authorizable, nil, :any] resource the resource to check for 
+        # @param [Authorizable, nil, :any, <Authorizable, nil>] resources the resources to check for 
         #   authorization on.
         # @return [true, false] true if the person is authorized on any of the a  
         #   roles, false otherwise.
-        def authorized?(roles, resource)
+        def authorized?(roles, resources)
           permit_arrayify(roles).each do |r|
             role = get_role(r)
             next unless role
-            conditions = authorization_conditions(role, resource)
+            conditions = authorization_conditions(role, resources)
             return true if permit_authorizations_proxy.exists?(conditions)
           end
           return false
@@ -43,16 +43,22 @@ module Permit
         #
         # @param [permit_role, String, Symbol, <permit_role, String, Symbol>] 
         #   roles the roles to check for authorization on.
-        # @param [permit_authorizable, nil, :any] resource the resource to check for 
+        # @param [permit_authorizable, nil, :any, <permit_authorizable, nil>] resources the resources to check for 
         #   authorization on.
         # @return [true, false] true if the person is authorized on all of the a  
         #   roles, false otherwise.
-        def authorized_all?(roles, resource)
+        def authorized_all?(roles, resources)
           permit_arrayify(roles).each do |r|
             role = get_role(r)
             return false unless role
-            conditions = authorization_conditions(role, resource)
-            return false unless permit_authorizations_proxy.exists?(conditions)
+            conditions = authorization_conditions(role, resources)
+            if resources == :any
+              # No idea how many authz they should have. As long as they have 
+              # something, that's good enough.
+              return false unless permit_authorizations_proxy.exists?(conditions)
+            else
+              return false unless permit_authorizations_proxy.count(:conditions => conditions) == permit_arrayify(resources).size
+            end
           end
           return true
         end

data/lib/permit.rb

@@ -32,12 +32,12 @@ module Permit
   # of all classes that are authorizable to roles by having defined 
   # +permit_authorizable+.
   class Config
-    @@authorization_class, @@person_class, @@role_class = nil, nil, nil
-    @@models_defined = false
-    @@authorizable_classes = []
-    @@controller_subject_method = nil
+    @authorization_class, @person_class, @role_class = nil, nil, nil
+    @authorizable_classes = []
+    @controller_subject_method = nil
 
-    @@action_aliases = {
+
+    @action_aliases = {
       :create => [:new, :create], 
       :update => [:edit, :update], 
       :destroy => [:delete, :destroy],
@@ -48,44 +48,55 @@ module Permit
     # Indicates the response returned by {PermitRules#permitted?} when no rules 
     # match. If set to +:allow+ then the person will be granted access. If set 
     # to anything else, they will be denied.
-    @@default_access = :deny
+    @default_access = :deny
 
     class << self
+      # Actions that when given to {PermitRules#allow}, and {PermitRules#deny} 
+      # will be expanded into the actions given in the value array.
+      #
+      # Defaults to:
+      #   {
+      #     :create => [:new, :create], 
+      #     :update => [:edit, :update], 
+      #     :destroy => [:delete, :destroy],
+      #     :read => [:index, :show], 
+      #     :write => [:new, :create, :edit, :update]
+      #   }
+      attr_reader :action_aliases
+
       # The class that currently represents authorizations in the system, as set
       # by {set_core_models}.
-      def authorization_class; @@authorization_class; end
+      attr_reader :authorization_class
       # The class that currently represents authorization subjects in the
       # system, as set by {set_core_models}.
-      def person_class; @@person_class; end
+      attr_reader :person_class
       # The class that curretly represents roles in the system, as set by
       # {set_core_models}.
-      def role_class; @@role_class; end
+      attr_reader :role_class
       # Classes that are marked as authorizable resources using
       # {Permit::Models::AuthorizableExtensions::AuthorizableClassMethods#permit_authorizable permit_authorizable}.
-      def authorizable_classes; @@authorizable_classes; end
+      attr_reader :authorizable_classes
 
-      # Actions that when given to {PermitRules#allow}, and {PermitRules#deny} 
-      # will be expanded into the actions given in the value array.
-      def action_aliases; @@action_aliases; end
+      #def action_aliases; @@action_aliases; end
 
       # Indicates the response that PermitRules will take if no
       # authorizations match. If set to +:allow+ then a subject will be given
       # access unless denied. By default this is set to +:deny+
       #
       # @return the current default access.
-      def default_access; @@default_access; end
+      def default_access; @default_access; end
 
       # Sets the response that PermitRules will use when no rules match.
       #
       # @param [:allow, :deny] access the default response to use.
-      def default_access=(access); @@default_access = access; end
+      def default_access=(access); @default_access = access; end
 
       # The method to use to retrieve the current authorization subject when
       # rules are being evaluated. If nil, then the method will be inferred from
       # the subject set in the call to {set_core_models}.
       #
       # @return [Symbol, nil]
-      def controller_subject_method; @@controller_subject_method; end
+      def controller_subject_method; @controller_subject_method; end
 
       # Sets the name of the method to use to retrieve the current subject
       # while checking authorizations. Set to nil, to infer the value from the
@@ -93,7 +104,7 @@ module Permit
       # authorizations are not being used.
       #
       # @param [nil, Symbol] method a symbol representing the method to use.
-      def controller_subject_method=(method); @@controller_subject_method = method; end
+      def controller_subject_method=(method); @controller_subject_method = method; end
 
       # Sets the core authorization, person, and role models to be used for
       # named authorizations, and configures them with their respective permit_*
@@ -108,13 +119,13 @@ module Permit
       def set_core_models(authorization, person, role)
         #raise PermitConfigurationError, "Core models cannot be redefined." if @@models_defined
 
-        @@authorization_class = authorization
-        @@person_class = person
-        @@role_class = role
+        @authorization_class = authorization
+        @person_class = person
+        @role_class = role
 
-        @@authorization_class.send :permit_authorization
-        @@person_class.send :permit_person
-        @@role_class.send :permit_role
+        @authorization_class.send :permit_authorization
+        @person_class.send :permit_person
+        @role_class.send :permit_role
       end
 
       # Forces Permit to reload its core classes based off of those given in the

data/lib/permit/controller.rb

@@ -80,27 +80,78 @@ module Permit
         true
       end
 
-      # Creates a PermitRule with the arguments that are given, and attempts to 
-      # match it based on the current person and binding context.
+      # Determines if a person is allowed access by evaluating rules for a 
+      # controller/action, or for a custom rule.
       #
-      # For information on the parameters for this method see 
-      # {PermitRule#initialize}.
+      # @overload allowed?(roles, options = {}) 
+      #   Creates a PermitRule with the arguments that are given, and attempts 
+      #   to match it based on the current subject and binding context.
+      #
+      #   For information on the parameters for this method see 
+      #   {PermitRule#initialize}.
+      #
+      #   @return [Boolean] true if the rule matches, otherwise false.
+      #
+      # @overload allowed?(options)
+      #   Attempts to evaluate the rules for the given action against the 
+      #   specified controller using the current subject, and binding context.
       #
-      # @return [Boolean] true if the rule matches, otherwise false.
-      def allowed?(roles, options = {})
-        rule = PermitRule.new roles, options
-        rule.matches? permit_authorization_subject, binding
+      #   Keep in mind that the evaluation is performed using the binding of the 
+      #   current controller. Any instance variables that may normally be needed 
+      #   for the rules on another controller need to exist in the current 
+      #   controller.
+      #
+      #   @param [Hash] options the controller/action to evaluate rules for.
+      #   @option options [String, Symbol] controller the name of the controller to 
+      #     evaluate the rules from. If this is not given then the current 
+      #     controller is used. You may use the string syntax 'namespaced/teams' 
+      #     for a namespaced controller Namespaced::TeamsController.
+      #   @option options [Symbol] action the action to evaluate rules for.
+      #
+      #   @return [Boolean] true if the rule matches, otherwise false.
+      def allowed?(*args)
+        options = args.extract_options!
+        if options.has_key? :action
+          name = options[:controller]
+          klass = (name ? "#{name}_controller".camelize.constantize : self)
+          klass.permit_rules.permitted? permit_authorization_subject, options[:action], binding
+        else
+          rule = PermitRule.new args[0], options
+          rule.matches? permit_authorization_subject, binding
+        end
       end
 
-      # Creates a PermitRule with the arguments that are given, and attempts to 
-      # match it based on the current person and binding context.
+      # Determines if a person is denied access by evaluating rules for a 
+      # controller/action, or for a custom rule.
       #
-      # For information on the parameters for this method see 
-      # {PermitRule#initialize}.
+      # @overload denied?(roles, options = {}) 
+      #   Creates a PermitRule with the arguments that are given, and attempts 
+      #   to match it based on the current subject and binding context.
+      #
+      #   For information on the parameters for this method see 
+      #   {PermitRule#initialize}.
+      #
+      #   @return [Boolean] true if the rule does not match, otherwise false.
+      #
+      # @overload denied?(options)
+      #   Attempts to evaluate the rules for the given action against the 
+      #   specified controller using the current subject, and binding context.
+      #
+      #   Keep in mind that the evaluation is performed using the binding of the 
+      #   current controller. Any instance variables that may normally be needed 
+      #   for the rules on another controller need to exist in the current 
+      #   controller.
+      #
+      #   @param [Hash] options the controller/action to evaluate rules for.
+      #   @option options [String, Symbol] controller the name of the controller to 
+      #     evaluate the rules from. If this is not given then the current 
+      #     controller is used. You may use the string syntax 'namespaced/teams' 
+      #     for a namespaced controller Namespaced::TeamsController.
+      #   @option options [Symbol] action the action to evaluate rules for.
       #
-      # @return [Boolean] true if the rule does not match, otherwise false.
-      def denied?(roles, options = {})
-        !allowed? roles, options
+      #   @return [Boolean] true if the subject is denied, otherwise false.
+      def denied?(*args)
+        !allowed? *args
       end
 
       # Shortcut for +current_person#authorized?+. If the current person is a 
@@ -108,8 +159,8 @@ module Permit
       # 
       # For information on the parameters for this method see 
       # {Permit::Models::PersonExtensions::PersonInstanceMethods#authorized?}
-      def authorized?(roles, resource)
-        permit_authorization_subject.guest? ? false : permit_authorization_subject.authorized?(roles, resource)
+      def authorized?(roles, resources)
+        permit_authorization_subject.guest? ? false : permit_authorization_subject.authorized?(roles, resources)
       end
 
     private

data/lib/permit/permit_rule.rb

@@ -1,11 +1,12 @@
 module Permit
+  # Defines an authorization rule to match against.
   class PermitRule
     include Permit::Support
     
     VALID_OPTION_KEYS = [:who, :that, :of, :on, :if, :unless]
     BUILTIN_ROLES = [:person, :guest, :everyone]
 
-    attr_reader :roles, :target_var, :method, :if, :unless
+    attr_reader :roles, :target_vars, :method, :if, :unless
 
     # Creates a new PermitRule.
     #
@@ -35,8 +36,8 @@ module Permit
     #   +is_owner()+, +is_owner?()+, +owner()+, +owner+, +owners.exist?()+. If 
     #   this option is given +:of+/+:on+ must also be given.
     # @option options [Symbol] :that alias for +:who+
-    # @option options [Symbol] :of The name of the instance variable to use as 
-    #   the target resource.
+    # @option options [Symbol, nil, :any, <Symbol, nil>] :of The name of the 
+    #   instance variable(s) to use as the target resource(s).
     #
     #   In a dynamic authorization this is the object that will be tested using 
     #   the value of +:who+/+:that+.
@@ -46,12 +47,15 @@ module Permit
     #   indicate a match if the person has one of the roles for any resource. If 
     #   not given, or set to +nil+, then the match will apply to a person that 
     #   has a matching role authorization for a nil resource. 
-    # @option options [Symbol] :on alias for +:of+
+    # @option options [Symbol, nil, :any, <Symbol, nil>] :on alias for +:of+
     # @option options [Symbol, String, Proc] :if code to evaluate at the end of the 
-    #   match if it is still valid. If it returns false, the rule will not match.
-    # @option options [Symbol, String, Proc] :unless code to evaluate at the end 
-    #   of the match if it is still valid. If it returns true, the rule will not 
-    #   match.
+    #   match if it is still valid. If it returns false, the rule will not 
+    #   match. If a proc if given, it will be passed the current subject and 
+    #   binding. A method will be called without any arguments.    
+    # @option options [Symbol, String, Proc] :unless code to evaluate at the end of 
+    #   the match if it is still valid. If it returns true, the rule will not 
+    #   match. If a proc if given, it will be passed the current subject and 
+    #   binding. A method will be called without any arguments.    
     #
     # @raise [PermitConfigurationError] if the rule options are invalid.
     def initialize(roles, options = {})
@@ -62,7 +66,7 @@ module Permit
       validate_options options
 
       @method = options[:who] || options[:that]
-      @target_var = options[:of] || options[:on]
+      @target_vars = permit_arrayify(options[:of] || options[:on]).uniq.freeze
 
       @if = options[:if]
       @unless = options[:unless]
@@ -83,7 +87,7 @@ module Permit
         has_named_authorizations? person, context_binding
       end
 
-      passed_conditionals = matched ? passes_conditionals?(context_binding) : false
+      passed_conditionals = matched ? passes_conditionals?(person, context_binding) : false
       passed = matched && passed_conditionals
       return passed
     end
@@ -121,24 +125,36 @@ module Permit
 
     def has_named_authorizations?(person, context_binding)
       return false if person.guest?
-      resource = case @target_var
-                 when nil then nil
-                 when :any then :any
-                 else get_resource(context_binding)
-                 end
-      person.authorized? @roles, resource
+      resources = []
+      @target_vars.each do |var_name|
+        resources << case var_name
+          when nil then nil
+          when :any then (resources = :any and break)
+          else get_resource(var_name, context_binding)
+        end
+      end
+      person.authorized? @roles, resources
     end
 
     def has_dynamic_authorization?(person, context_binding)
       return false if person.guest?
-      return true if @target_var.nil?
 
-      resource = get_resource context_binding
       methods = determine_method_sequence @method
 
+      @target_vars.each do |var_name|
+        return true if var_name.nil?
+
+        resource = get_resource var_name, context_binding
+        return true if evaluate_dynamic_methods(var_name, resource, methods, person)
+      end
+
+      return false
+    end
+
+    def evaluate_dynamic_methods(var_name, resource, methods, person)
       methods.each do |name, type|
         next unless resource.respond_to? name
-        
+
         case type
         when :method then return resource.send name, person
         when :getter then return resource.send(name) == person
@@ -148,7 +164,7 @@ module Permit
       end
 
       # Target didn't respond to any attempts. This would be a problem.
-      raise PermitEvaluationError, "Target object ':#{@target_var}' evaluated as #{resource.inspect} did not respond to any of the following: #{methods.collect {|n,t| n}.join(', ')}"
+      raise PermitEvaluationError, "Target object ':#{var_name}' evaluated as #{resource.inspect} did not respond to any of the following: #{methods.collect {|n,t| n}.join(', ')}"
     end
 
     # is_owner - is_owner(), is_owner?(), owner?(), owner, owners.exists()
@@ -174,20 +190,25 @@ module Permit
       end      
     end
 
-    def get_resource(context_binding)
-      eval "@#{@target_var.to_s}", context_binding
+    def get_resource(var, context_binding)
+      var_name = "@#{var.to_s}"
+      if eval(%Q{instance_variables.include? "#{var_name}"}, context_binding)
+        eval var_name, context_binding
+      else
+        raise PermitEvaluationError, "Target resource '#{var_name}' did not exist in the given context."
+      end
     end
 
-    def passes_conditionals?(context_binding)
-      return false unless eval_conditional @if, true, context_binding
-      return false if eval_conditional @unless, false, context_binding
+    def passes_conditionals?(person, context_binding)
+      return false unless eval_conditional @if, true, person, context_binding
+      return false if eval_conditional @unless, false, person, context_binding
       true
     end
 
-    def eval_conditional(condition, default, context_binding)
+    def eval_conditional(condition, default, person, context_binding)
       if condition
         condition = condition.to_s if Symbol===condition
-        return (String===condition ? eval(condition, context_binding) : condition.call)
+        return (String===condition ? eval(condition, context_binding) : condition.call(person, context_binding))
       else
         return default
       end