uhees-declarative_authorization 0.3.1

data/lib/declarative_authorization/in_model.rb

@@ -0,0 +1,150 @@
+# Authorization::AuthorizationInModel
+require File.dirname(__FILE__) + '/authorization.rb'
+require File.dirname(__FILE__) + '/obligation_scope.rb'
+
+module Authorization
+  
+  module AuthorizationInModel
+
+    # If the user meets the given privilege, permitted_to? returns true
+    # and yields to the optional block.
+    def permitted_to? (privilege, options = {} )
+      options = {
+        :user =>  Authorization.current_user,
+        :object => self
+      }.merge(options)
+      Authorization::Engine.instance.permit?(privilege,
+          {:user => options[:user],
+           :object => options[:object]},
+          &block)
+    end
+
+    # Works similar to the permitted_to? method, but doesn't accept a block
+    # and throws the authorization exceptions, just like Engine#permit!
+    def permitted_to! (privilege, options = {} )
+      options = {
+        :user =>  Authorization.current_user,
+        :object => self
+      }.merge(options)
+      Authorization::Engine.instance.permit!(privilege,
+          {:user => options[:user],
+           :object => options[:object]})
+    end
+    
+    def self.included(base) # :nodoc:
+      #base.extend(ClassMethods)
+      base.module_eval do
+        scopes[:with_permissions_to] = lambda do |parent_scope, *args|
+          options = args.last.is_a?(Hash) ? args.pop : {}
+          privilege = (args[0] || :read).to_sym
+          privileges = [privilege]
+          context = options[:context] || :"#{parent_scope.table_name}"
+          
+          user = options[:user] || Authorization.current_user
+
+          engine = options[:engine] || Authorization::Engine.instance
+          engine.permit!(privileges, :user => user, :skip_attribute_test => true,
+                         :context => context)
+
+          obligation_scope_for( privileges, :user => user,
+              :context => context, :engine => engine, :model => parent_scope)
+        end
+        
+        # Builds and returns a scope with joins and conditions satisfying all obligations.
+        def self.obligation_scope_for( privileges, options = {} )
+          options = {
+            :user => Authorization.current_user,
+            :context => nil,
+            :model => self,
+            :engine => nil,
+          }.merge(options)
+          engine = options[:engine] || Authorization::Engine.instance
+
+          scope = ObligationScope.new( options[:model], {} )
+          engine.obligations( privileges, :user => options[:user], :context => options[:context] ).each do |obligation|
+            scope.parse!( obligation )
+          end
+          scope
+        end
+
+        # Named scope for limiting query results according to the authorization
+        # of the current user.  If no privilege is given, :+read+ is assumed.
+        # 
+        #   User.with_permissions_to
+        #   User.with_permissions_to(:update)
+        #   User.with_permissions_to(:update, :context => :users)
+        #   
+        # As in the case of other named scopes, this one may be chained:
+        #   User.with_permission_to.find(:all, :conditions...)
+        # 
+        # Options
+        # [:+context+]
+        #   Context for the privilege to be evaluated in; defaults to the
+        #   model's table name.
+        # [:+user+]
+        #   User to be used for gathering obligations; defaults to the
+        #   current user.
+        #
+        def self.with_permissions_to (*args)
+          scopes[:with_permissions_to].call(self, *args)
+        end
+        
+        # Activates model security for the current model.  Then, CRUD operations
+        # are checked against the authorization of the current user.  The
+        # privileges are :+create+, :+read+, :+update+ and :+delete+ in the
+        # context of the model.  By default, :+read+ is not checked because of
+        # performance impacts, especially with large result sets.
+        # 
+        #   class User < ActiveRecord::Base
+        #     using_access_control
+        #   end
+        #   
+        # If an operation is not permitted, a Authorization::AuthorizationError
+        # is raised.
+        #
+        # To activate model security on all models, call using_access_control
+        # on ActiveRecord::Base
+        #   ActiveRecord::Base.using_access_control
+        # 
+        # Available options
+        # [:+context+] Specify context different from the models table name.
+        # [:+include_read+] Also check for :+read+ privilege after find.
+        #
+        def self.using_access_control (options = {})
+          options = {
+            :context => nil,
+            :include_read => false
+          }.merge(options)
+
+          class_eval do
+            [:create, :update, [:destroy, :delete]].each do |action, privilege|
+              send(:"before_#{action}") do |object|
+                Authorization::Engine.instance.permit!(privilege || action,
+                  :object => object, :context => options[:context])
+              end
+            end
+
+            # after_find is only called if after_find is implemented
+            after_find do |object|
+              Authorization::Engine.instance.permit!(:read, :object => object,
+                :context => options[:context])
+            end
+            
+            if options[:include_read]
+              def after_find; end
+            end
+
+            def self.using_access_control?
+              true
+            end
+          end
+        end
+
+        # Returns true if the model is using model security.
+        def self.using_access_control?
+          false
+        end
+      end
+    end
+  end
+end

data/lib/declarative_authorization/maintenance.rb

@@ -0,0 +1,188 @@
+# Authorization::Maintenance
+require File.dirname(__FILE__) + '/authorization.rb'
+
+module Authorization
+  
+  def self.ignore_access_control (state = nil) # :nodoc:
+    Thread.current["ignore_access_control"] = state unless state.nil?
+    Thread.current["ignore_access_control"] || false
+  end
+  
+  # Provides a few maintenance methods for modifying data without enforcing
+  # authorization.
+  module Maintenance
+    # Disables access control for the given block.  Appropriate for
+    # maintenance operation at the Rails console or in test case setup.
+    # 
+    # For use in the Rails console:
+    #  require "vendor/plugins/declarative_authorization/lib/maintenance"
+    #  include Authorization::Maintenance
+    #
+    #  without_access_control do
+    #    SomeModel.find(:first).save
+    #  end
+    def without_access_control
+      self.class.without_access_control
+    end
+
+    # A class method variant of without_access_control.  Thus, one can call
+    #  Authorization::Maintenance::without_access_control do
+    #    ...
+    #  end
+    def self.without_access_control
+      previous_state = Authorization.ignore_access_control
+      begin
+        Authorization.ignore_access_control(true)
+        yield
+      ensure
+        Authorization.ignore_access_control(previous_state)
+      end
+    end
+
+    # Sets the current user for the declarative authorization plugin to the
+    # given one for the execution of the supplied block.  Suitable for tests
+    # on certain users.
+    def with_user (user)
+      prev_user = Authorization.current_user
+      Authorization.current_user = user
+      yield
+    ensure
+      Authorization.current_user = prev_user
+    end
+
+    # Module for grouping usage-related helper methods
+    module Usage
+      # Delivers a hash of {ControllerClass => usage_info_hash},
+      # where usage_info_hash has the form of
+      def self.usages_by_controller
+        # load each application controller
+        begin
+          Dir.foreach(File.join(RAILS_ROOT, %w{app controllers})) do |entry|
+            if entry =~ /^\w+_controller\.rb$/
+              require File.join(RAILS_ROOT, %w{app controllers}, entry)
+            end
+          end
+        rescue Errno::ENOENT
+        end
+        controllers = []
+        ObjectSpace.each_object(Class) do |obj|
+          controllers << obj if obj.ancestors.include?(ActionController::Base) and
+                                !%w{ActionController::Base ApplicationController}.include?(obj.name)
+        end
+
+        controllers.inject({}) do |memo, controller|
+          catchall_permissions = []
+          permission_by_action = {}
+          controller.all_filter_access_permissions.each do |controller_permissions|
+            catchall_permissions << controller_permissions if controller_permissions.actions.include?(:all)
+            controller_permissions.actions.reject {|action| action == :all}.each do |action|
+              permission_by_action[action] = controller_permissions
+            end
+          end
+
+          actions = controller.public_instance_methods(false) - controller.hidden_actions
+          memo[controller] = actions.inject({}) do |actions_memo, action|
+            action_sym = action.to_sym
+            actions_memo[action_sym] =
+              if permission_by_action[action_sym]
+                {
+                  :privilege => permission_by_action[action_sym].privilege,
+                  :context   => permission_by_action[action_sym].context,
+                  :controller_permissions => [permission_by_action[action_sym]]
+                }
+              elsif !catchall_permissions.empty?
+                {
+                  :privilege => catchall_permissions[0].privilege,
+                  :context   => catchall_permissions[0].context,
+                  :controller_permissions => catchall_permissions
+                }
+              else
+                {}
+              end
+            actions_memo
+          end
+          memo
+        end
+      end
+    end
+  end
+  
+  # TestHelper provides assert methods and controller request methods which
+  # take authorization into account and set the current user to a specific
+  # one.
+  #
+  # Defines get_with, post_with, get_by_xhr_with etc. for methods 
+  # get, post, put, delete each with the signature
+  #   get_with(user, action, params = {}, session = {}, flash = {})
+  #
+  # Use it by including it in your TestHelper:
+  #  require File.expand_path(File.dirname(__FILE__) + 
+  #    "/../vendor/plugins/declarative_authorization/lib/maintenance")
+  #  class Test::Unit::TestCase 
+  #    include Authorization::TestHelper
+  #    ...
+  #    
+  #    def admin
+  #      # create admin user
+  #    end
+  #  end
+  # 
+  #  class SomeControllerTest < ActionController::TestCase
+  #    def test_should_get_index
+  #      ...
+  #      get_with admin, :index, :param_1 => "param value"
+  #      ...
+  #    end
+  #  end
+  module TestHelper
+    include Authorization::Maintenance
+    
+    # Analogue to the Ruby's assert_raise method, only executing the block
+    # in the context of the given user.
+    def assert_raise_with_user (user, *args, &block)
+      assert_raise(*args) do
+        with_user(user, &block)
+      end
+    end
+    
+    def should_be_allowed_to (privilege, object_or_context)
+      options = {}
+      options[object_or_context.is_a?(Symbol) ? :context : :object] = object_or_context
+      assert_nothing_raised do
+        Authorization::Engine.instance.permit!(privilege, options)
+      end
+    end
+
+    def should_not_be_allowed_to (privilege, object_or_context)
+      options = {}
+      options[object_or_context.is_a?(Symbol) ? :context : :object] = object_or_context
+      assert !Authorization::Engine.instance.permit?(privilege, options)
+    end
+    
+    def request_with (user, method, xhr, action, params = {}, 
+        session = {}, flash = {})
+      session = session.merge({:user => user, :user_id => user.id})
+      with_user(user) do
+        if xhr
+          xhr method, action, params, session, flash
+        else
+          send method, action, params, session, flash
+        end
+      end
+    end
+  
+    def self.included (base)
+      [:get, :post, :put, :delete].each do |method|
+        base.class_eval <<-EOV, __FILE__, __LINE__
+          def #{method}_with (user, *args)
+            request_with(user, #{method.inspect}, false, *args)
+          end
+
+          def #{method}_by_xhr_with (user, *args)
+            request_with(user, #{method.inspect}, true, *args)
+          end
+        EOV
+      end
+    end
+  end
+end

data/lib/declarative_authorization/obligation_scope.rb

@@ -0,0 +1,297 @@
+module Authorization
+  # The +ObligationScope+ class parses any number of obligations into joins and conditions.
+  #
+  # In +ObligationScope+ parlance, "association paths" are one-dimensional arrays in which each
+  # element represents an attribute or association (or "step"), and "leads" to the next step in the
+  # association path.
+  #
+  # Suppose we have this path defined in the context of model Foo:
+  # +{ :bar => { :baz => { :foo => { :attr => is { user } } } } }+
+  #
+  # To parse this path, +ObligationScope+ evaluates each step in the context of the preceding step.
+  # The first step is evaluated in the context of the parent scope, the second step is evaluated in
+  # the context of the first, and so forth.  Every time we encounter a step representing an
+  # association, we make note of the fact by storing the path (up to that point), assigning it a
+  # table alias intended to match the one that will eventually be chosen by ActiveRecord when
+  # executing the +find+ method on the scope.
+  #
+  # +@table_aliases = {
+  #   [] => 'foos',
+  #   [:bar] => 'bars',
+  #   [:bar, :baz] => 'bazzes',
+  #   [:bar, :baz, :foo] => 'foos_bazzes' # Alias avoids collisions with 'foos' (already used)
+  # }+
+  #
+  # At the "end" of each path, we expect to find a comparison operation of some kind, generally
+  # comparing an attribute of the most recent association with some other value (such as an ID,
+  # constant, or array of values).  When we encounter a step representing a comparison, we make
+  # note of the fact by storing the path (up to that point) and the comparison operation together.
+  # (Note that individual obligations' conditions are kept separate, to allow their conditions to
+  # be OR'ed together in the generated scope options.)
+  #
+  # +@obligation_conditions[<obligation>][[:bar, :baz, :foo]] = [
+  #   [ :attr, :is, <user.id> ]
+  # ]+
+  #
+  # After successfully parsing an obligation, all of the stored paths and conditions are converted
+  # into scope options (stored in +proxy_options+ as +:joins+ and +:conditions+).  The resulting
+  # scope may then be used to find all scoped objects for which at least one of the parsed
+  # obligations is fully met.
+  #
+  # +@proxy_options[:joins] = { :bar => { :baz => :foo } }
+  # @proxy_options[:conditions] = [ 'foos_bazzes.attr = :foos_bazzes__id_0', { :foos_bazzes__id_0 => 1 } ]+
+  #
+  class ObligationScope < ActiveRecord::NamedScope::Scope
+    
+    # Consumes the given obligation, converting it into scope join and condition options.
+    def parse!( obligation )
+      @current_obligation = obligation
+      obligation_conditions[@current_obligation] ||= {}
+      follow_path( obligation )
+
+      rebuild_condition_options!
+      rebuild_join_options!
+    end
+    
+    protected
+    
+    # Parses the next step in the association path.  If it's an association, we advance down the
+    # path.  Otherwise, it's an attribute, and we need to evaluate it as a comparison operation.
+    def follow_path( steps, past_steps = [] )
+      if steps.is_a?( Hash )
+        steps.each do |step, next_steps|
+          path_to_this_point = [past_steps, step].flatten
+          reflection = reflection_for( path_to_this_point ) rescue nil
+          if reflection
+            follow_path( next_steps, path_to_this_point )
+          else
+            follow_comparison( next_steps, past_steps, step )
+          end
+        end
+      elsif steps.is_a?( Array ) && steps.length == 2
+        if reflection_for( past_steps )
+          follow_comparison( steps, past_steps, :id )
+        else
+          follow_comparison( steps, past_steps[0..-2], past_steps[-1] )
+        end
+      else
+        raise "invalid obligation path #{[past_steps, steps].flatten}"
+      end
+    end
+    
+    # At the end of every association path, we expect to see a comparison of some kind; for
+    # example, +:attr => [ :is, :value ]+.
+    #
+    # This method parses the comparison and creates an obligation condition from it.
+    def follow_comparison( steps, past_steps, attribute )
+      operator = steps[0]
+      value = steps[1..-1]
+      value = value[0] if value.length == 1
+
+      add_obligation_condition_for( past_steps, [attribute, operator, value] )
+    end
+    
+    # Adds the given expression to the current obligation's indicated path's conditions.
+    #
+    # Condition expressions must follow the format +[ <attribute>, <operator>, <value> ]+.
+    def add_obligation_condition_for( path, expression )
+      raise "invalid expression #{expression.inspect}" unless expression.is_a?( Array ) && expression.length == 3
+      add_obligation_join_for( path )
+      obligation_conditions[@current_obligation] ||= {}
+      ( obligation_conditions[@current_obligation][path] ||= Set.new ) << expression
+    end
+    
+    # Adds the given path to the list of obligation joins, if we haven't seen it before.
+    def add_obligation_join_for( path )
+      map_reflection_for( path ) if reflections[path].nil?
+    end
+    
+    # Returns the model associated with the given path.
+    def model_for( path )
+      reflection = reflection_for( path )
+      reflection.respond_to?( :klass ) ? reflection.klass : reflection
+    end
+    
+    # Returns the reflection corresponding to the given path.
+    def reflection_for( path )
+      reflections[path] ||= map_reflection_for( path )
+    end
+    
+    # Returns a proper table alias for the given path.  This alias may be used in SQL statements.
+    def table_alias_for( path )
+      table_aliases[path] ||= map_table_alias_for( path )
+    end
+
+    # Attempts to map a reflection for the given path.  Raises if already defined.
+    def map_reflection_for( path )
+      raise "reflection for #{path.inspect} already exists" unless reflections[path].nil?
+      
+      reflection = path.empty? ? @proxy_scope : begin
+        parent = reflection_for( path[0..-2] )
+        parent.klass.reflect_on_association( path.last )
+      rescue
+        parent.reflect_on_association( path.last )
+      end
+      raise "invalid path #{path.inspect}" if reflection.nil?
+
+      reflections[path] = reflection
+      map_table_alias_for( path )  # Claim a table alias for the path.
+      
+      reflection
+    end
+
+    # Attempts to map a table alias for the given path.  Raises if already defined.
+    def map_table_alias_for( path )
+      return "table alias for #{path.inspect} already exists" unless table_aliases[path].nil?
+      
+      reflection = reflection_for( path )
+      table_alias = reflection.table_name
+      if table_aliases.values.include?( table_alias )
+        max_length = reflection.active_record.connection.table_alias_length
+        # Rails seems to pluralize reflection names
+        table_alias = "#{reflection.name.to_s.pluralize}_#{reflection.active_record.table_name}".to(max_length-1)
+      end            
+      while table_aliases.values.include?( table_alias )
+        if table_alias =~ /\w(_\d+?)$/
+          table_index = $1.succ
+          table_alias = "#{table_alias[0..-(table_index.length+1)]}_#{table_index}"
+        else
+          table_alias = "#{table_alias[0..(max_length-3)]}_2" 
+        end
+      end
+      table_aliases[path] = table_alias
+    end
+
+    # Returns a hash mapping obligations to zero or more condition path sets.
+    def obligation_conditions
+      @obligation_conditions ||= {}
+    end
+
+    # Returns a hash mapping paths to reflections.
+    def reflections
+      # lets try to get the order of joins right
+      @reflections ||= ActiveSupport::OrderedHash.new
+    end
+    
+    # Returns a hash mapping paths to proper table aliases to use in SQL statements.
+    def table_aliases
+      @table_aliases ||= {}
+    end
+    
+    # Parses all of the defined obligation conditions and defines the scope's :conditions option.
+    def rebuild_condition_options!
+      conds = []
+      binds = {}
+      used_paths = Set.new
+      delete_paths = Set.new
+      obligation_conditions.each_with_index do |array, obligation_index|
+        obligation, conditions = array
+        obligation_conds = []
+        conditions.each do |path, expressions|
+          model = model_for( path )
+          table_alias = table_alias_for(path)
+          parent_model = (path.length > 1 ? model_for(path[0..-2]) : @proxy_scope)
+          expressions.each do |expression|
+            attribute, operator, value = expression
+            # prevent unnecessary joins:
+            if attribute == :id and operator == :is and parent_model.columns_hash["#{path.last}_id"]
+              attribute_name = :"#{path.last}_id"
+              attribute_table_alias = table_alias_for(path[0..-2])
+              used_paths << path[0..-2]
+              delete_paths << path
+            else
+              attribute_name = model.columns_hash["#{attribute}_id"] && :"#{attribute}_id" ||
+                               model.columns_hash[attribute.to_s]    && attribute ||
+                               :id
+              attribute_table_alias = table_alias
+              used_paths << path
+            end
+            bindvar = "#{attribute_table_alias}__#{attribute_name}_#{obligation_index}".to_sym
+
+            sql_attribute = "#{connection.quote_table_name(attribute_table_alias)}.#{connection.quote_table_name(attribute_name)}"
+            if value.nil? and [:is, :is_not].include?(operator)
+              obligation_conds << "#{sql_attribute} IS #{[:contains, :is].include?(operator) ? '' : 'NOT '}NULL"
+            else
+              attribute_operator = case operator
+                                   when :contains, :is             then "= :#{bindvar}"
+                                   when :does_not_contain, :is_not then "<> :#{bindvar}"
+                                   when :is_in, :intersects_with   then "IN (:#{bindvar})"
+                                   when :is_not_in                 then "NOT IN (:#{bindvar})"
+                                   else raise AuthorizationUsageError, "Unknown operator: #{operator}"
+                                   end
+              obligation_conds << "#{sql_attribute} #{attribute_operator}"
+              binds[bindvar] = attribute_value(value)
+            end
+          end
+        end
+        obligation_conds << "1=1" if obligation_conds.empty?
+        conds << "(#{obligation_conds.join(' AND ')})"
+      end
+      (delete_paths - used_paths).each {|path| reflections.delete(path)}
+      @proxy_options[:conditions] = [ conds.join( " OR " ), binds ]
+    end
+
+    def attribute_value (value)
+      value.respond_to?( :descends_from_active_record? ) && value.descends_from_active_record? && value.id ||
+        value.is_a?( Array ) && value[0].respond_to?( :descends_from_active_record? ) && value[0].descends_from_active_record? && value.map( &:id ) ||
+        value
+    end
+    
+    # Parses all of the defined obligation joins and defines the scope's :joins or :includes option.
+    # TODO: Support non-linear association paths.  Right now, we just break down the longest path parsed.
+    def rebuild_join_options!
+      joins = (@proxy_options[:joins] || []) + (@proxy_options[:includes] || [])
+
+      reflections.keys.each do |path|
+        next if path.empty?
+
+        existing_join = joins.find do |join|
+          existing_path = join_to_path(join)
+          min_length = [existing_path.length, path.length].min
+          existing_path.first(min_length) == path.first(min_length)
+        end
+
+        if existing_join
+          if join_to_path(existing_join).length < path.length
+            joins[joins.index(existing_join)] = path_to_join(path)
+          end
+        else
+          joins << path_to_join(path)
+        end
+      end
+
+      case obligation_conditions.length
+      when 0 then
+        # No obligation conditions means we don't have to mess with joins or includes at all.
+      when 1 then
+        @proxy_options[:joins] = joins
+        @proxy_options.delete( :include )
+      else
+        @proxy_options.delete( :joins )
+        @proxy_options[:include] = joins
+      end
+    end
+
+    def path_to_join (path)
+      case path.length
+      when 0 then nil
+      when 1 then path[0]
+      else
+        hash = { path[-2] => path[-1] }
+        path[0..-3].reverse.each do |elem|
+          hash = { elem => hash }
+        end
+        hash
+      end
+    end
+
+    def join_to_path (join)
+      case join
+      when Symbol
+        [join]
+      when Hash
+        [join.keys.first] + join_to_path(join[join.keys.first])
+      end
+    end
+  end
+end