acl9 0.11.0

data/Rakefile

@@ -0,0 +1,40 @@
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
+
+desc 'Default: run tests.'
+task :default => :test
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "acl9"
+    s.summary = "Yet another role-based authorization system for Rails"
+    s.email = "olegdashevskii@gmail.com"
+    s.homepage = "http://github.com/be9/acl9"
+    s.description = "Role-based authorization system for Rails with a nice DSL for access control lists"
+    s.authors = ["oleg dashevskii"]
+    s.files = FileList["[A-Z]*", "{lib,test}/**/*.rb"]
+    s.add_development_dependency "jeremymcanally-context", ">= 0.5.5"
+    s.add_development_dependency "jnunemaker-matchy", ">= 0.4.0"
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install jeweler"
+end
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = false
+end
+
+begin
+  require 'yard'
+
+  YARD::Rake::YardocTask.new do |t|
+    t.files   = ['lib/**/*.rb']
+    #t.options = ['--any', '--extra', '--opts'] # optional
+  end
+rescue LoadError
+end

data/TODO

@@ -0,0 +1,42 @@
+* Complex roles with ANDing.
+
+  Something like:
+
+    access_control do
+      allow all, :except => :destroy
+      allow complex_role, :to => :destroy do
+        is :strong
+        is :decisive
+        is :owner, :of => :object
+        is_not :banned
+        is_not :fake
+      end
+    end
+
+* Acl9-based menu generator.
+
+  If you get Access Denied on /secrets/index, probably you shouldn't see "Secrets" item
+  in the menu at all.
+
+  It can be very DRY. Say, we introduce :menu => true option to access_control method which
+  will make it register a lambda (can see/cannot see) in some global hash (indexed by controller name).
+
+  Then, given an URL, you'll be able to check it against this hash. /secrets/index is mapped to
+  SecretsController#index, so you run access_control_hash['SecretsController'].call('index') and
+  show the link only if true is returned.
+
+  The problem here is with objects. SecretsController's access_control block can reference instance 
+  variables during the permission check, but we have only current instantiated controller which can be any.
+
+  Another option is to distinguish visible part from access control part.
+
+    menu do 
+      item 'Home', home_path
+      item 'Secrets', secrets_path do
+        allow :trusted
+      end
+
+      # ...
+    end
+
+  Here only "trusted" users will see "Secrets" item.

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:minor: 11
+:patch: 0
+:major: 0

data/lib/acl9.rb

@@ -0,0 +1,16 @@
+require File.join(File.dirname(__FILE__), 'acl9', 'config')
+
+if defined? ActiveRecord::Base
+  require File.join(File.dirname(__FILE__), 'acl9', 'model_extensions')
+
+  ActiveRecord::Base.send(:include, Acl9::ModelExtensions)
+end
+
+
+if defined? ActionController::Base
+  require File.join(File.dirname(__FILE__), 'acl9', 'controller_extensions')
+  require File.join(File.dirname(__FILE__), 'acl9', 'helpers')
+
+  ActionController::Base.send(:include, Acl9::ControllerExtensions)
+  Acl9Helpers = Acl9::Helpers unless defined?(Acl9Helpers)
+end

data/lib/acl9/config.rb

@@ -0,0 +1,10 @@
+module Acl9
+  @@config = {
+    :default_role_class_name => 'Role',
+    :default_subject_class_name => 'User',
+    :default_subject_method => :current_user,
+    :protect_global_roles => false,
+  }
+
+  mattr_reader :config
+end

data/lib/acl9/controller_extensions.rb

@@ -0,0 +1,85 @@
+require File.join(File.dirname(__FILE__), 'controller_extensions', 'generators')
+
+module Acl9
+  module ControllerExtensions
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def access_control(*args, &block)
+        opts = args.extract_options!
+
+        case args.size
+        when 0 then true
+        when 1
+          meth = args.first
+
+          if meth.is_a? Symbol
+            opts[:as_method] = meth
+          else
+            raise ArgumentError, "access_control argument must be a :symbol!"
+          end
+        else
+          raise ArgumentError, "Invalid arguments for access_control"
+        end
+
+        subject_method = opts[:subject_method] || Acl9::config[:default_subject_method]
+
+        raise ArgumentError, "Block must be supplied to access_control" unless block
+
+        filter = opts[:filter]
+        filter = true if filter.nil?
+
+        case helper = opts[:helper]
+        when true
+          raise ArgumentError, "you should specify :helper => :method_name" if !opts[:as_method]
+        when nil then nil
+        else
+          if opts[:as_method]
+            raise ArgumentError, "you can't specify both method name and helper name" 
+          else
+            opts[:as_method] = helper
+            filter = false
+          end
+        end
+
+        method = opts[:as_method]
+
+        query_method_available = true
+        generator = case
+                    when method && filter
+                      Acl9::Dsl::Generators::FilterMethod.new(subject_method, method)
+                    when method && !filter
+                      query_method_available = false
+                      Acl9::Dsl::Generators::BooleanMethod.new(subject_method, method)
+                    else
+                      Acl9::Dsl::Generators::FilterLambda.new(subject_method)
+                    end
+
+        generator.acl_block!(&block)
+
+        generator.install_on(self, opts)
+
+        if query_method_available && (query_method = opts.delete(:query_method))
+          case query_method
+          when true
+            if method
+              query_method = "#{method}?"
+            else
+              raise ArgumentError, "You must specify :query_method as Symbol"
+            end
+          when Symbol, String
+            # okay here
+          else
+            raise ArgumentError, "Invalid value for :query_method"
+          end
+
+          second_generator = Acl9::Dsl::Generators::BooleanMethod.new(subject_method, query_method)
+          second_generator.acl_block!(&block)
+          second_generator.install_on(self, opts)
+        end
+      end
+    end
+  end
+end

data/lib/acl9/controller_extensions/dsl_base.rb

@@ -0,0 +1,229 @@
+module Acl9
+  module Dsl
+    class Base
+      attr_reader :allows, :denys
+
+      def initialize(*args)
+        @default_action = nil
+
+        @allows = []
+        @denys = []
+
+        @original_args = args
+      end
+
+      def acl_block!(&acl_block)
+        instance_eval(&acl_block)
+      end
+
+      def default_action
+        if @default_action.nil? then :deny else @default_action end
+      end
+
+      def allowance_expression
+        allowed_expr = if @allows.size > 0
+                         @allows.map { |clause| "(#{clause})" }.join(' || ')
+                       else
+                         "false"
+                       end
+
+        not_denied_expr = if @denys.size > 0
+                            @denys.map { |clause| "!(#{clause})" }.join(' && ')
+                          else
+                            "true"
+                          end
+
+        [allowed_expr, not_denied_expr].
+          map { |expr| "(#{expr})" }.
+          join(default_action == :deny ? ' && ' : ' || ')
+      end
+
+      alias to_s allowance_expression
+
+      protected
+
+      def default(default_action)
+        raise ArgumentError, "default can only be called once in access_control block" if @default_action
+
+        unless [:allow, :deny].include? default_action
+          raise ArgumentError, "invalid value for default (can be :allow or :deny)"
+        end
+
+        @default_action = default_action
+      end
+
+      def allow(*args)
+        @current_rule = :allow
+        _parse_and_add_rule(*args)
+      end
+
+      def deny(*args)
+        @current_rule = :deny
+        _parse_and_add_rule(*args)
+      end
+
+      def actions(*args, &block)
+        raise ArgumentError, "actions should receive at least 1 action as argument" if args.size < 1
+
+        subsidiary = self.class.new(*@original_args)
+
+        class <<subsidiary
+          def actions(*args)
+            raise ArgumentError, "You cannot use actions inside another actions block"
+          end
+
+          def default(*args)
+            raise ArgumentError, "You cannot use default inside an actions block"
+          end
+
+          def _set_action_clause(to, except)
+            raise ArgumentError, "You cannot use :to/:except inside actions block" if to || except
+          end
+        end
+
+        subsidiary.acl_block!(&block)
+
+        action_check = _action_check_expression(args)
+
+        squash = lambda do |rules|
+          _either_of(rules) + ' && ' + action_check
+        end
+
+        @allows << squash.call(subsidiary.allows) if subsidiary.allows.size > 0
+        @denys  << squash.call(subsidiary.denys)  if subsidiary.denys.size > 0
+      end
+
+      alias action actions
+
+      def logged_in; false end
+      def anonymous; nil   end
+      def all;       true  end
+
+      alias everyone all
+      alias everybody all
+      alias anyone all
+
+      def _parse_and_add_rule(*args)
+        options = args.extract_options!
+
+        _set_action_clause(options.delete(:to), options.delete(:except))
+
+        object = _role_object(options)
+
+        role_checks = args.map do |who|
+          case who
+          when anonymous() then "#{_subject_ref}.nil?"
+          when logged_in() then "!#{_subject_ref}.nil?"
+          when all()       then "true"
+          else
+            "!#{_subject_ref}.nil? && #{_subject_ref}.has_role?('#{who.to_s.singularize}', #{object})"
+          end
+        end
+
+        [:if, :unless].each do |cond|
+          val = options[cond]
+          raise ArgumentError, "#{cond} option must be a Symbol" if val && !val.is_a?(Symbol)
+        end
+
+        condition = [
+          (_method_ref(options[:if]) if options[:if]),
+          ("!#{_method_ref(options[:unless])}" if options[:unless])
+        ].compact.join(' && ')
+
+        condition = nil if condition.blank?
+
+        _add_rule(case role_checks.size
+                  when 0
+                    raise ArgumentError, "allow/deny should have at least 1 argument"
+                  when 1 then role_checks.first
+                  else
+                    _either_of(role_checks)
+                  end, condition)
+      end
+
+      def _either_of(exprs)
+        exprs.map { |expr| "(#{expr})" }.join(' || ')
+      end
+
+      def _add_rule(what, condition)
+        anded = [what] + [@action_clause, condition].compact
+        anded[0] = "(#{anded[0]})" if anded.size > 1
+
+        (@current_rule == :allow ? @allows : @denys) << anded.join(' && ')
+      end
+
+      def _set_action_clause(to, except)
+        raise ArgumentError, "both :to and :except cannot be specified in the rule" if to && except
+
+        @action_clause = nil
+
+        action_list = to || except
+        return unless action_list
+
+        expr = _action_check_expression(action_list)
+
+        @action_clause = if to
+                           "#{expr}"
+                         else
+                           "!#{expr}"
+                         end
+      end
+
+      def _action_check_expression(action_list)
+        unless action_list.is_a?(Array)
+          action_list = [ action_list.to_s ]
+        end
+
+        case action_list.size
+        when 0 then "true"
+        when 1 then "(#{_action_ref} == '#{action_list.first}')"
+        else
+          set_of_actions = "Set.new([" + action_list.map { |act| "'#{act}'"}.join(',')  + "])"
+
+          "#{set_of_actions}.include?(#{_action_ref})"
+        end
+      end
+
+      VALID_PREPOSITIONS = %w(of for in on at by).freeze unless defined? VALID_PREPOSITIONS
+
+      def _role_object(options)
+        object = nil
+
+        VALID_PREPOSITIONS.each do |prep|
+          if options[prep.to_sym]
+            raise ArgumentError, "You may only use one preposition to specify object" if object
+
+            object = options[prep.to_sym]
+          end
+        end
+
+        case object
+        when Class
+          object.to_s
+        when Symbol
+          _object_ref object
+        when nil
+          "nil"
+        else
+          raise ArgumentError, "object specified by preposition can only be a Class or a Symbol"
+        end
+      end
+
+      def _subject_ref
+        raise
+      end
+
+      def _object_ref(object)
+        raise
+      end
+
+      def _action_ref
+        raise
+      end
+
+      def _method_ref(method)
+        raise
+      end
+    end
+  end
+end

data/lib/acl9/controller_extensions/generators.rb

@@ -0,0 +1,197 @@
+require File.join(File.dirname(__FILE__), 'dsl_base')
+
+module Acl9
+  ##
+  # This exception is raised whenever ACL block finds that the current user
+  # is not authorized for the controller action he wants to execute.
+  # @example How to catch this exception in ApplicationController
+  #   class ApplicationController < ActionController::Base
+  #     rescue_from 'Acl9::AccessDenied', :with => :access_denied
+  #
+  #     # ...other stuff...
+  #     private
+  #
+  #     def access_denied
+  #       if current_user
+  #         # It's presumed you have a template with words of pity and regret
+  #         # for unhappy user who is not authorized to do what he wanted
+  #         render :template => 'home/access_denied'
+  #       else
+  #         # In this case user has not even logged in. Might be OK after login.
+  #         flash[:notice] = 'Access denied. Try to log in first.'
+  #         redirect_to login_path
+  #       end
+  #     end
+  #   end
+  #
+  class AccessDenied < StandardError; end
+
+  ##
+  # This exception is raised when acl9 has generated invalid code for the
+  # filtering method or block. Should never happen, and it's a bug when it
+  # happens.
+  class FilterSyntaxError < StandardError; end
+
+  module Dsl
+    module Generators
+      class BaseGenerator < Acl9::Dsl::Base
+        def initialize(*args)
+          @subject_method = args[0]
+
+          super
+        end
+
+        protected
+
+        def _access_denied
+          "raise Acl9::AccessDenied"
+        end
+
+        def _subject_ref
+          "#{_controller_ref}send(:#{@subject_method})"
+        end
+
+        def _object_ref(object)
+          "#{_controller_ref}instance_variable_get('@#{object}')"
+        end
+
+        def _action_ref
+          "#{_controller_ref}action_name"
+        end
+
+        def _method_ref(method)
+          "#{_controller_ref}send(:#{method})"
+        end
+
+        def _controller_ref
+          @controller ? "#{@controller}." : ''
+        end
+
+        def install_on(controller_class, options)
+          debug_dump(controller_class) if options[:debug]
+        end
+
+        def debug_dump(klass)
+          return unless logger
+          logger.debug "=== Acl9 access_control expression dump (#{klass.to_s})"
+          logger.debug self.to_s
+          logger.debug "======"
+        end
+
+        def logger
+          ActionController::Base.logger
+        end
+      end
+
+      class FilterLambda < BaseGenerator
+        def initialize(subject_method)
+          super
+
+          @controller = 'controller'
+        end
+
+        def install_on(controller_class, options)
+          super
+
+          controller_class.send(:before_filter, options, &self.to_proc)
+        end
+
+        def to_proc
+          code = <<-RUBY
+            lambda do |controller|
+              unless #{allowance_expression}
+                #{_access_denied}
+              end
+            end
+          RUBY
+
+          self.instance_eval(code, __FILE__, __LINE__)
+        rescue SyntaxError
+          raise FilterSyntaxError, code
+        end
+      end
+
+      ################################################################
+
+      class FilterMethod < BaseGenerator
+        def initialize(subject_method, method_name)
+          super
+
+          @method_name = method_name
+          @controller = nil
+        end
+
+        def install_on(controller_class, options)
+          super
+          _add_method(controller_class)
+          controller_class.send(:before_filter, @method_name, options)
+        end
+
+        protected
+
+        def _add_method(controller_class)
+          code = self.to_method_code
+          controller_class.send(:class_eval, code, __FILE__, __LINE__)
+        rescue SyntaxError
+          raise FilterSyntaxError, code
+        end
+
+        def to_method_code
+          <<-RUBY
+            def #{@method_name}
+              unless #{allowance_expression}
+                #{_access_denied}
+              end
+            end
+          RUBY
+        end
+      end
+
+      ################################################################
+
+      class BooleanMethod < FilterMethod
+        def install_on(controller_class, opts)
+          debug_dump(controller_class) if opts[:debug]
+
+          _add_method(controller_class)
+
+          if opts[:helper]
+            controller_class.send(:helper_method, @method_name)
+          end
+        end
+
+        protected
+
+        def to_method_code
+          <<-RUBY
+            def #{@method_name}(*args)
+              options = args.extract_options!
+
+              unless args.size <= 1
+                raise ArgumentError, "call #{@method_name} with 0, 1 or 2 arguments"
+              end
+
+              action_name = args.empty? ? self.action_name : args.first.to_s
+
+              return #{allowance_expression}
+            end
+          RUBY
+        end
+
+        def _object_ref(object)
+          "(options[:#{object}] || #{super})"
+        end
+      end
+
+      ################################################################
+
+      class HelperMethod < BooleanMethod
+        def initialize(subject_method, method)
+          super
+
+          @controller = 'controller'
+        end
+      end
+    end
+  end
+end