cancan 1.3.4 → 1.4.0.beta1

data/CHANGELOG.rdoc

@@ -1,3 +1,22 @@
+1.4.0 (not yet released)
+
+* Adding check_authorization and skip_authorization controller class methods to ensure authorization is performed (thanks justinko) - see issue #135
+
+* Setting initial attributes based on ability conditions in new/create actions - see issue #114
+
+* Check parent attributes for nested association in index action - see issue #121
+
+* Supporting nesting in can? method using hash - see issue #121
+
+* Adding I18n support for Access Denied messages (thanks EppO) - see issue #103
+
+* Passing no arguments to +can+ definition will pass action, class, and object to block - see issue #129
+
+* Don't pass action to block in +can+ definition when using :+manage+ option - see issue #129
+
+* No longer calling block in +can+ definition when checking on class - see issue #116
+
+
 1.3.4 (August 31, 2010)
 
 * Don't stop at +cannot+ with hash conditions when checking class (thanks tamoya) - see issue #131

data/README.rdoc

@@ -126,7 +126,7 @@ Notice the +edit+ action is aliased to +update+. If the user is able to update a
   can :modify, Comment
   can? :update, Comment # => true
 
-See {Custom Actions}[http://wiki.github.com/ryanb/cancan/custom-actions] for information on adding other actions.
+The +alias_action+ method is an instance method and usually called in +initialize+. See {Custom Actions}[http://wiki.github.com/ryanb/cancan/custom-actions] for information on adding other actions.
 
 
 == Fetching Records

data/Rakefile

@@ -10,4 +10,4 @@ Spec::Rake::SpecTask.new do |t|
   t.spec_opts = ["-c"]
 end
 
-task :default => :spec
+task :default => :spec

data/lib/cancan/ability.rb

@@ -16,7 +16,7 @@ module CanCan
   #   end
   #
   module Ability
-    # Use to check if the user has permission to perform a given action on an object.
+    # Check if the user has permission to perform a given action on an object.
     #
     #   can? :destroy, @project
     #
@@ -24,6 +24,11 @@ module CanCan
     #
     #   can? :create, Project
     #
+    # Nested resources can be passed through a hash, this way conditions which are
+    # dependent upon the association will work when using a class.
+    #
+    #   can? :create, @category => Project
+    #
     # Any additional arguments will be passed into the "can" block definition. This
     # can be used to pass more information about the user's request for example.
     #
@@ -49,7 +54,6 @@ module CanCan
     #
     # Also see the RSpec Matchers to aid in testing.
     def can?(action, subject, *extra_args)
-      raise Error, "Nom nom nom. I eated it." if action == :has && subject == :cheezburger
       match = relevant_can_definitions(action, subject).detect do |can_definition|
         can_definition.matches_conditions?(action, subject, extra_args)
       end
@@ -70,54 +74,54 @@ module CanCan
     #   can :update, Article
     #
     # You can pass an array for either of these parameters to match any one.
+    # Here the user has the ability to update or destroy both articles and comments.
     #
     #   can [:update, :destroy], [Article, Comment]
     #
-    # In this case the user has the ability to update or destroy both articles and comments.
+    # You can pass :all to match any object and :manage to match any action. Here are some examples.
     #
-    # You can pass a hash of conditions as the third argument.
+    #   can :manage, :all
+    #   can :update, :all
+    #   can :manage, Project
+    #
+    # You can pass a hash of conditions as the third argument. Here the user can only see active projects which he owns.
     #
     #   can :read, Project, :active => true, :user_id => user.id
     #
-    # Here the user can only see active projects which he owns. See ActiveRecordAdditions#accessible_by
-    # for how to use this in database queries.
+    # See ActiveRecordAdditions#accessible_by for how to use this in database queries. These conditions
+    # are also used for initial attributes when building a record in ControllerAdditions#load_resource.
     #
-    # If the conditions hash does not give you enough control over defining abilities, you can use a block to
-    # write any Ruby code you want.
+    # If the conditions hash does not give you enough control over defining abilities, you can use a block
+    # along with any Ruby code you want.
     #
     #   can :update, Project do |project|
-    #     project && project.groups.include?(user.group)
+    #     project.groups.include?(user.group)
     #   end
     #
     # If the block returns true then the user has that :update ability for that project, otherwise he
-    # will be denied access. It's possible for the passed in model to be nil if one isn't specified,
-    # so be sure to take that into consideration.
+    # will be denied access. The downside to using a block is that it cannot be used to generate
+    # conditions for database queries.
     #
-    # The downside to using a block is that it cannot be used to generate conditions for database queries.
+    # You can pass custom objects into this "can" method, this is usually done with a symbol
+    # and is useful if a class isn't available to define permissions on.
     #
-    # You can pass :all to reference every type of object. In this case the object type will be passed
-    # into the block as well (just in case object is nil).
+    #   can :read, :stats
+    #   can? :read, :stats # => true
     #
-    #   can :read, :all do |object_class, object|
-    #     object_class != Order
-    #   end
+    # IMPORTANT: Neither a hash of conditions or a block will be used when checking permission on a class.
     #
-    # Here the user has permission to read all objects except orders.
+    #   can :update, Project, :priority => 3
+    #   can? :update, Project # => true
     #
-    # You can also pass :manage as the action which will match any action. In this case the action is
-    # passed to the block.
+    # If you pass no arguments to +can+, the action, class, and object will be passed to the block and the
+    # block will always be executed. This allows you to override the full behavior if the permissions are
+    # defined in an external source such as the database.
     #
-    #   can :manage, Comment do |action, comment|
-    #     action != :destroy
+    #   can do |action, object_class, object|
+    #     # check the database and return true/false
     #   end
     #
-    # You can pass custom objects into this "can" method, this is usually done through a symbol
-    # and is useful if a class isn't available to define permissions on.
-    #
-    #   can :read, :stats
-    #   can? :read, :stats # => true
-    #
-    def can(action, subject, conditions = nil, &block)
+    def can(action = nil, subject = nil, conditions = nil, &block)
       can_definitions << CanDefinition.new(true, action, subject, conditions, block)
     end
 
@@ -133,7 +137,7 @@ module CanCan
     #     product.invisible?
     #   end
     #
-    def cannot(action, subject, conditions = nil, &block)
+    def cannot(action = nil, subject = nil, conditions = nil, &block)
       can_definitions << CanDefinition.new(false, action, subject, conditions, block)
     end
 
@@ -189,9 +193,44 @@ module CanCan
       Query.new(subject, relevant_can_definitions_for_query(action, subject))
     end
 
+    # See ControllerAdditions#authorize! for documentation.
+    def authorize!(action, subject, *args)
+      message = nil
+      if args.last.kind_of?(Hash) && args.last.has_key?(:message)
+        message = args.pop[:message]
+      end
+      if cannot?(action, subject, *args)
+        message ||= unauthorized_message(action, subject)
+        raise AccessDenied.new(message, action, subject)
+      end
+    end
+
+    def unauthorized_message(action, subject)
+      keys = unauthorized_message_keys(action, subject)
+      message = I18n.translate(nil, :scope => :unauthorized, :default => keys + [""])
+      message.blank? ? nil : message
+    end
+
+    def attributes_for(action, subject)
+      attributes = {}
+      relevant_can_definitions(action, subject).map do |can_definition|
+        attributes.merge!(can_definition.attributes_from_conditions) if can_definition.base_behavior
+      end
+      attributes
+    end
+
     private
 
-    # Accepts a hash of aliased actions and returns an array of actions which match.
+    def unauthorized_message_keys(action, subject)
+      subject = (subject.class == Class ? subject : subject.class).name.underscore unless subject.kind_of? Symbol
+      [subject, :all].map do |try_subject|
+        [aliases_for_action(action), :manage].flatten.map do |try_action|
+          :"#{try_action}.#{try_subject}"
+        end
+      end.flatten
+    end
+
+    # Accepts an array of actions and returns an array of actions which match.
     # This should be called before "matches?" and other checking methods since they
     # rely on the actions to be expanded.
     def expand_actions(actions)
@@ -200,6 +239,16 @@ module CanCan
       end.flatten
     end
 
+    # Given an action, it will try to find all of the actions which are aliased to it.
+    # This does the opposite kind of lookup as expand_actions.
+    def aliases_for_action(action)
+      results = [action]
+      aliased_actions.each do |aliased_action, actions|
+        results += aliases_for_action(aliased_action) if actions.include? action
+      end
+      results
+    end
+
     def can_definitions
       @can_definitions ||= []
     end

data/lib/cancan/can_definition.rb

@@ -11,6 +11,7 @@ module CanCan
     # and subject respectively (such as :read, @project). The third argument is a hash
     # of conditions and the last one is the block passed to the "can" call.
     def initialize(base_behavior, action, subject, conditions, block)
+      @match_all = action.nil? && subject.nil?
       @base_behavior = base_behavior
       @actions = [action].flatten
       @subjects = [subject].flatten
@@ -20,14 +21,19 @@ module CanCan
 
     # Matches both the subject and action, not necessarily the conditions
     def relevant?(action, subject)
-      matches_action?(action) && matches_subject?(subject)
+      subject = subject.values.first if subject.kind_of? Hash
+      @match_all || (matches_action?(action) && matches_subject?(subject))
     end
 
     # Matches the block or conditions hash
     def matches_conditions?(action, subject, extra_args)
-      if @block
-        call_block(action, subject, extra_args)
-      elsif @conditions.kind_of?(Hash) && subject.class != Class
+      if @match_all
+        call_block_with_all(action, subject, extra_args)
+      elsif @block && !subject_class?(subject)
+        @block.call(subject, *extra_args)
+      elsif @conditions.kind_of?(Hash) && subject.kind_of?(Hash)
+        nested_subject_matches_conditions?(subject)
+      elsif @conditions.kind_of?(Hash) && !subject_class?(subject)
         matches_conditions_hash?(subject)
       else
         @base_behavior
@@ -61,8 +67,20 @@ module CanCan
       hash
     end
 
+    def attributes_from_conditions
+      attributes = {}
+      @conditions.each do |key, value|
+        attributes[key] = value unless [Array, Range, Hash].include? value.class
+      end
+      attributes
+    end
+
     private
 
+    def subject_class?(subject)
+      (subject.kind_of?(Hash) ? subject.values.first : subject).class == Class
+    end
+
     def matches_action?(action)
       @expanded_actions.include?(:manage) || @expanded_actions.include?(action)
     end
@@ -92,13 +110,17 @@ module CanCan
       end
     end
 
-    def call_block(action, subject, extra_args)
-      block_args = []
-      block_args << action if @expanded_actions.include?(:manage)
-      block_args << (subject.class == Class ? subject : subject.class) if @subjects.include?(:all)
-      block_args << (subject.class == Class ? nil : subject)
-      block_args += extra_args
-      @block.call(*block_args)
+    def nested_subject_matches_conditions?(subject_hash)
+      parent, child = subject_hash.shift
+      matches_conditions_hash?(parent, @conditions[parent.class.name.downcase.to_sym] || {})
+    end
+
+    def call_block_with_all(action, subject, extra_args)
+      if subject.class == Class
+        @block.call(action, subject, nil, *extra_args)
+      else
+        @block.call(action, subject.class, subject, *extra_args)
+      end
     end
   end
 end

data/lib/cancan/controller_additions.rb

@@ -21,6 +21,10 @@ module CanCan
       # Article.new(params[:article]) depending upon the action. It does nothing for the "index"
       # action.
       #
+      # If a conditions hash is used in the Ability, the +new+ and +create+ actions will set
+      # the initial attributes based on these conditions. This way these actions will satisfy
+      # the ability restrictions.
+      #
       # Call this method directly on the controller class.
       #
       #   class BooksController < ApplicationController
@@ -148,9 +152,44 @@ module CanCan
       # [:+instance_name+]
       #   The name of the instance variable for this resource.
       #
+      # [:+through+]
+      #   Authorize conditions on this parent resource when instance isn't available.
+      #
       def authorize_resource(*args)
         ControllerResource.add_before_filter(self, :authorize_resource, *args)
       end
+
+      # Add this to a controller to ensure it performs authorization through +authorized+! or +authorize_resource+ call.
+      # If neither of these authorization methods are called, a CanCan::AuthorizationNotPerformed exception will be raised.
+      # This is normally added to the ApplicationController to ensure all controller actions do authorization.
+      #
+      #   class ApplicationController < ActionController::Base
+      #     check_authorization
+      #   end
+      #
+      # Any arguments are passed to the +after_filter+ it triggers.
+      #
+      # See skip_authorization to bypass this check on specific controller actions.
+      def check_authorization(*args)
+        self.after_filter(*args) do |controller|
+          unless controller.instance_variable_defined?(:@_authorized)
+            raise AuthorizationNotPerformed, "This action failed the check_authorization because it does not authorize_resource. Add skip_authorization to bypass this check."
+          end
+        end
+      end
+
+      # Call this in the class of a controller to skip the check_authorization behavior on the actions.
+      #
+      #   class HomeController < ApplicationController
+      #     skip_authorization :only => :index
+      #   end
+      #
+      # Any arguments are passed to the +before_filter+ it triggers.
+      def skip_authorization(*args)
+        self.before_filter(*args) do |controller|
+          controller.instance_variable_set(:@_authorized, true)
+        end
+      end
     end
 
     def self.included(base)
@@ -171,6 +210,16 @@ module CanCan
     #
     #   authorize! :read, @article, :message => "Not authorized to read #{@article.name}"
     #
+    # You can also use I18n to customize the message. Action aliases defined in Ability work here.
+    #
+    #   en:
+    #     unauthorized:
+    #       manage:
+    #         all: "Not authorized to perform that action."
+    #         user: "Not allowed to manage other user accounts."
+    #       update:
+    #         project: "Not allowed to update this project."
+    #
     # You can rescue from the exception in the controller to customize how unauthorized
     # access is displayed to the user.
     #
@@ -185,12 +234,9 @@ module CanCan
     #
     # See the load_and_authorize_resource method to automatically add the authorize! behavior
     # to the default RESTful actions.
-    def authorize!(action, subject, *args)
-      message = nil
-      if args.last.kind_of?(Hash) && args.last.has_key?(:message)
-        message = args.pop[:message]
-      end
-      raise AccessDenied.new(message, action, subject) if cannot?(action, subject, *args)
+    def authorize!(*args)
+      @_authorized = true
+      current_ability.authorize!(*args)
     end
 
     def unauthorized!(message = nil)
@@ -223,6 +269,13 @@ module CanCan
     #     <%= link_to "New Project", new_project_path %>
     #   <% end %>
     #
+    # If it's a nested resource, you can pass the parent instance in a hash. This way it will
+    # check conditions which reach through that association.
+    #
+    #   <% if can? :create, @category => Project %>
+    #     <%= link_to "New Project", new_project_path %>
+    #   <% end %>
+    #
     # This simply calls "can?" on the current_ability. See Ability#can?.
     def can?(*args)
       current_ability.can?(*args)

data/lib/cancan/controller_resource.rb

@@ -32,7 +32,7 @@ module CanCan
     end
 
     def authorize_resource
-      @controller.authorize!(authorization_action, resource_instance || resource_class)
+      @controller.authorize!(authorization_action, resource_instance || resource_class_with_parent)
     end
 
     def parent?
@@ -50,8 +50,16 @@ module CanCan
     end
 
     def build_resource
-      method_name = @options[:singleton] ? "build_#{name}" : "new"
-      resource_base.send(*[method_name, @params[name]].compact)
+      resource = resource_base.send(@options[:singleton] ? "build_#{name}" : "new")
+      initial_attributes.each do |name, value|
+        resource.send("#{name}=", value)
+      end
+      resource.attributes = @params[name] if @params[name]
+      resource
+    end
+
+    def initial_attributes
+      @controller.current_ability.attributes_for(@params[:action].to_sym, resource_class)
     end
 
     def find_resource
@@ -86,6 +94,10 @@ module CanCan
       end
     end
 
+    def resource_class_with_parent
+      parent_resource ? {parent_resource => resource_class} : resource_class
+    end
+
     def resource_instance
       @controller.instance_variable_get("@#{instance_name}")
     end
@@ -94,15 +106,15 @@ module CanCan
     # If the :through option is passed it will go through an association on that instance.
     # If the :singleton option is passed it won't use the association because it needs to be handled later.
     def resource_base
-      if through_resource
-        @options[:singleton] ? through_resource : through_resource.send(name.to_s.pluralize)
+      if parent_resource
+        @options[:singleton] ? parent_resource : parent_resource.send(name.to_s.pluralize)
       else
         resource_class
       end
     end
 
     # The object to load this resource through.
-    def through_resource
+    def parent_resource
       @options[:through] && [@options[:through]].flatten.map { |i| @controller.instance_variable_get("@#{i}") }.compact.first
     end