cancan 1.3.4 → 1.4.1

data/CHANGELOG.rdoc

@@ -1,3 +1,55 @@
+1.4.1 (November 12, 2010)
+
+* Renaming skip_authorization to skip_authorization_check - see issue #169
+
+* Adding :through_association option to load_resource (thanks hunterae) - see issue #171
+
+* The :shallow option now works with the :singleton option (thanks nandalopes) - see issue #187
+
+* Play nicely with quick_scopes gem (thanks ramontayag) - see issue #183
+
+* Fix odd behavior when "cache_classes = false" (thanks mphalliday) - see issue #174
+
+
+1.4.0 (October 5, 2010)
+
+* Adding Gemfile; to get specs running just +bundle+ and +rake+ - see issue #163
+
+* Stop at 'cannot' definition when there are no conditions - see issue #161
+
+* The :through option will now call a method with that name if instance variable doesn't exist - see issue #146
+
+* Adding :shallow option to load_resource to bring back old behavior of fetching a child without a parent
+
+* Raise AccessDenied error when loading a child and parent resource isn't found
+
+* Abilities defined on a module will apply to anything that includes that module - see issue #150 and #152
+
+* Abilities can be defined with a string of SQL in addition to a block so accessible_by works with a block - see issue #150
+
+* Adding better support for InheritedResource - see issue #23
+
+* Loading the collection instance variable (for index action) using accessible_by - see issue #137
+
+* Adding action and subject variables to I18n unauthorized message - closes #142
+
+* 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/Gemfile

@@ -0,0 +1,2 @@
+source "http://rubygems.org"
+gemspec

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2009 Ryan Bates
+Copyright (c) 2010 Ryan Bates
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -2,29 +2,29 @@
 
 Wiki[http://wiki.github.com/ryanb/cancan] | RDocs[http://rdoc.info/projects/ryanb/cancan] | Screencast[http://railscasts.com/episodes/192-authorization-with-cancan]
 
-CanCan is an authorization solution for Ruby on Rails for restricting what a given user is allowed to access throughout the application. It does not care how your user roles are defined, it simply focusses on keeping permission logic in a single location (the +Ability+ class) so it is not duplicated across controllers, views, and database queries.
-
-By default, the +current_user+ method is required, so if you have not already, set up some authentication (such as Authlogic[http://github.com/binarylogic/authlogic] or Devise[http://github.com/plataformatec/devise]). See {Changing Defaults}[http://wiki.github.com/ryanb/cancan/changing-defaults] if you need different behavior.
+CanCan is an authorization library for Ruby on Rails which restricts what resources a given user is allowed to access. All permissions are defined in a single location (the +Ability+ class) and not duplicated across controllers, views, and database queries.
 
 
 == Installation
 
-To install CanCan, include the gem in the environment.rb in Rails 2.3.
+In <b>Rails 3</b>, add this to your Gemfile.
 
-  config.gem "cancan"
+  gem "cancan"
 
-Or the Gemfile in Rails 3.
+In <b>Rails 2</b>, add this to your environment.rb file.
 
-  gem "cancan"
+  config.gem "cancan"
 
-Alternatively it can be installed as a plugin.
+Alternatively, you can install it as a plugin.
 
-  script/plugin install git://github.com/ryanb/cancan.git
+  rails plugin install git://github.com/ryanb/cancan.git
 
 
 == Getting Started
 
-First, define a class called +Ability+ in "models/ability.rb" or anywhere else in the load path. It should look something like this.
+CanCan expects a +current_user+ method to exist. If you have not already, set up some authentication (such as Authlogic[http://github.com/binarylogic/authlogic] or Devise[http://github.com/plataformatec/devise]). See {Changing Defaults}[http://wiki.github.com/ryanb/cancan/changing-defaults] if you need different behavior.
+
+Next create a class called +Ability+ in "models/ability.rb" or anywhere else in the load path. It should look similar to this.
 
   class Ability
     include CanCan::Ability
@@ -38,7 +38,7 @@ First, define a class called +Ability+ in "models/ability.rb" or anywhere else i
     end
   end
 
-This is where all permissions will go. See the "Defining Abilities" section below for more information.
+The +current_user+ is passed in to this method which is where the abilities are defined. See the "Defining Abilities" section below for more information.
 
 The current user's permissions can be accessed using the "can?" and "cannot?" methods in the view and controller.
 
@@ -67,11 +67,11 @@ Setting this for every action can be tedious, therefore the +load_and_authorize_
 
 See {Authorizing Controller Actions}[http://wiki.github.com/ryanb/cancan/authorizing-controller-actions] for more information
 
-If the user authorization fails, a CanCan::AccessDenied exception will be raised. You can catch this and modify its behavior in the +ApplicationController+.
+If the user authorization fails, a <tt>CanCan::AccessDenied</tt> exception will be raised. You can catch this and modify its behavior in the +ApplicationController+.
 
   class ApplicationController < ActionController::Base
     rescue_from CanCan::AccessDenied do |exception|
-      flash[:error] = exception.message
+      flash[:alert] = exception.message
       redirect_to root_url
     end
   end
@@ -81,7 +81,7 @@ See {Exception Handling}[http://wiki.github.com/ryanb/cancan/exception-handling]
 
 == Defining Abilities
 
-As shown above, the +Ability+ class is where all user permissions are defined. The user model is passed into the initialize method so the permissions can be modified based on any user attributes. CanCan makes no assumptions about how roles are handled in your application. See {Role Based Authorization}[http://wiki.github.com/ryanb/cancan/role-based-authorization] for an example.
+As shown above, the +Ability+ class is where all user permissions are defined. The current user model is passed into the initialize method so the permissions can be modified based on any user attributes. CanCan makes no assumption about how roles are handled in your application. See {Role Based Authorization}[http://wiki.github.com/ryanb/cancan/role-based-authorization] for an example.
 
 The +can+ method is used to define permissions and requires two arguments. The first one is the action you're setting the permission for, the second one is the class of object you're setting it on.
 
@@ -97,7 +97,7 @@ Use :+manage+ to represent any action and :+all+ to represent any class. Here ar
   can :read, :all        # has permission to read any model
   can :manage, :all      # has permission to do anything to any model
 
-You can pass a hash of conditions as the third argument to further restrict what the user is able to access. Here the user will only have permission to read active projects which he owns.
+You can pass a hash of conditions as the third argument to further define what the user is able to access. Here the user will only have permission to read active projects which he owns.
 
   can :read, Project, :active => true, :user_id => user.id
 
@@ -106,10 +106,10 @@ See {Defining Abilities with Hashes}[http://wiki.github.com/ryanb/cancan/definin
 Blocks can also be used if you need more control.
 
   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. See {Defining Abilities with Blocks}[http://wiki.github.com/ryanb/cancan/defining-abilities-with-blocks] for more information.
+If the block returns true then the user has that ability for that project, otherwise he will be denied access. See {Defining Abilities with Blocks}[http://wiki.github.com/ryanb/cancan/defining-abilities-with-blocks] for more information.
 
 
 == Aliasing Actions
@@ -120,33 +120,43 @@ You will usually be working with four actions when defining and checking permiss
   alias_action :new, :to => :create
   alias_action :edit, :to => :update
 
-Notice the +edit+ action is aliased to +update+. If the user is able to update a record he also has permission to edit it. You can define your own aliases in the +Ability+ class
+Notice the +edit+ action is aliased to +update+. This means if the user is able to update a record he also has permission to edit it. You can define your own aliases in the +Ability+ class.
 
   alias_action :update, :destroy, :to => :modify
   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
 
-In the controller +index+ action you may want to fetch only the records which the user has permission to read. You can do this with the +accessible_by+ scope.
+It is possible to fetch records which the user has permission to read using the +accessible_by+ scope in Active Record.
 
   @articles = Article.accessible_by(current_ability)
 
+Since version 1.4 this is done automatically when loading resources in the index action, so one rarely needs to do it manually.
+
 This will only work when abilities are defined using hash conditions, not blocks. See {Fetching Records}[http://wiki.github.com/ryanb/cancan/fetching-records] for more information.
 
 
 == Additional Docs
 
-* {Upgrading to 1.3}[http://wiki.github.com/ryanb/cancan/upgrading-to-13]
+* {Upgrading to 1.4}[http://github.com/ryanb/cancan/wiki/Upgrading-to-1.4]
 * {Nested Resources}[http://wiki.github.com/ryanb/cancan/nested-resources]
 * {Testing Abilities}[http://wiki.github.com/ryanb/cancan/testing-abilities]
 * {Accessing Request Data}[http://wiki.github.com/ryanb/cancan/accessing-request-data]
 * {Admin Namespace}[http://wiki.github.com/ryanb/cancan/admin-namespace]
 * {See more}[http://wiki.github.com/ryanb/cancan/]
 
+
+== Questions or Problems?
+
+If you have any issues with CanCan which you cannot find the solution to in the documentation, please add an {issue on GitHub}[http://github.com/ryanb/cancan/issues] or fork the project and send a pull request.
+
+To get the specs running you should call +bundle+ and then +rake+. Specs currently do not work in Ruby 1.9 due to the RR mocking framework.
+
+
 == Special Thanks
 
 CanCan was inspired by declarative_authorization[http://github.com/stffn/declarative_authorization/] and aegis[http://github.com/makandra/aegis]. Also many thanks to the CanCan contributors[http://github.com/ryanb/cancan/contributors]. See the CHANGELOG[http://github.com/ryanb/cancan/blob/master/CHANGELOG.rdoc] for the full list.

data/Rakefile

@@ -1,13 +1,10 @@
 require 'rubygems'
 require 'rake'
-require 'spec/rake/spectask'
+require 'rspec/core/rake_task'
 
-spec_files = Rake::FileList["spec/**/*_spec.rb"]
-
-desc "Run specs"
-Spec::Rake::SpecTask.new do |t|
-  t.spec_files = spec_files
-  t.spec_opts = ["-c"]
+desc "Run RSpec"
+RSpec::Core::RakeTask.new do |t|
+  t.verbose = false
 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,8 +54,7 @@ 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|
+      match = relevant_can_definitions_for_match(action, subject).detect do |can_definition|
         can_definition.matches_conditions?(action, subject, extra_args)
       end
       match ? match.base_behavior : false
@@ -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.
+    #
+    #   can :manage, :all
+    #   can :update, :all
+    #   can :manage, Project
     #
-    # You can pass a hash of conditions as the third argument.
+    # 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,54 @@ 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)
+      variables = {:action => action.to_s}
+      variables[:subject] = (subject.class == Class ? subject : subject.class).to_s.downcase
+      message = I18n.translate(nil, variables.merge(: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
+
+    def has_block?(action, subject)
+      relevant_can_definitions(action, subject).any?(&:only_block?)
+    end
+
+    def has_raw_sql?(action, subject)
+      relevant_can_definitions(action, subject).any?(&:only_raw_sql?)
+    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 +249,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
@@ -213,6 +272,14 @@ module CanCan
       end
     end
 
+    def relevant_can_definitions_for_match(action, subject)
+      relevant_can_definitions(action, subject).each do |can_definition|
+        if can_definition.only_raw_sql?
+          raise Error, "The can? and cannot? call cannot be used with a raw sql 'can' definition. The checking code cannot be determined for #{action.inspect} #{subject.inspect}"
+        end
+      end
+    end
+
     def relevant_can_definitions_for_query(action, subject)
       relevant_can_definitions(action, subject).each do |can_definition|
         if can_definition.only_block?

data/lib/cancan/active_record_additions.rb

@@ -21,7 +21,7 @@ module CanCan
       # internally uses Ability#conditions method, see that for more information.
       def accessible_by(ability, action = :read)
         query = ability.query(action, self)
-        if respond_to? :where
+        if respond_to?(:where) && respond_to?(:joins)
           where(query.conditions).joins(query.joins)
         else
           scoped(:conditions => query.conditions, :joins => query.joins)

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,21 +21,28 @@ 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
+        # Don't stop at "cannot" definitions when there are conditions.
+        @conditions.empty? ? true : @base_behavior
       end
     end
 
     def tableized_conditions(conditions = @conditions)
+      return conditions unless conditions.kind_of? Hash
       conditions.inject({}) do |result_hash, (name, value)|
         if value.kind_of? Hash
           name = name.to_s.tableize.to_sym
@@ -49,6 +57,10 @@ module CanCan
       conditions_empty? && !@block.nil?
     end
 
+    def only_raw_sql?
+      @block.nil? && !conditions_empty? && !@conditions.kind_of?(Hash)
+    end
+
     def conditions_empty?
       @conditions == {} || @conditions.nil?
     end
@@ -57,12 +69,25 @@ module CanCan
       hash = {}
       conditions.map do |name, value|
         hash[name] = associations_hash(value) if value.kind_of? Hash
-      end
+      end if conditions.kind_of? Hash
       hash
     end
 
+    def attributes_from_conditions
+      attributes = {}
+      @conditions.each do |key, value|
+        attributes[key] = value unless [Array, Range, Hash].include? value.class
+      end if @conditions.kind_of? Hash
+      attributes
+    end
+
     private
 
+    def subject_class?(subject)
+      klass = (subject.kind_of?(Hash) ? subject.values.first : subject).class
+      klass == Class || klass == Module
+    end
+
     def matches_action?(action)
       @expanded_actions.include?(:manage) || @expanded_actions.include?(action)
     end
@@ -72,7 +97,7 @@ module CanCan
     end
 
     def matches_subject_class?(subject)
-      @subjects.any? { |sub| sub.kind_of?(Class) && (subject.kind_of?(sub) || subject.kind_of?(Class) && subject.ancestors.include?(sub)) }
+      @subjects.any? { |sub| sub.kind_of?(Module) && (subject.kind_of?(sub) || subject.class.to_s == sub.to_s || subject.kind_of?(Module) && subject.ancestors.include?(sub)) }
     end
 
     def matches_conditions_hash?(subject, conditions = @conditions)
@@ -92,13 +117,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