constellation-authorization 2.0.0

data/lib/constellation/authorization.rb

@@ -0,0 +1,5 @@
+module Constellation
+  module Authorization
+    require 'constellation/authorization/engine' if defined?(Rails)
+  end
+end

data/lib/constellation/authorization/base.rb

@@ -0,0 +1,134 @@
+require 'constellation/authorization/exceptions'
+require 'constellation/authorization/parser'
+
+module Constellation
+  module Authorization
+    module Base
+      def self.included(recipient)
+        recipient.extend ControllerClassMethods
+        recipient.class_eval do
+          include ControllerInstanceMethods
+        end
+      end
+
+      module ControllerClassMethods
+
+        # Allow class-level authorization check.
+        # permit is used in a before_filter fashion and passes arguments to the before_filter.
+        def permit(authorization_expression, *args)
+          filter_keys = [:only, :except]
+          filter_args, eval_args = {}, {}
+          if args.last.is_a? Hash
+            filter_args.merge!(args.last.reject {|k,v| not filter_keys.include? k })
+            eval_args.merge!(args.last.reject {|k,v| filter_keys.include? k })
+          end
+          before_filter(filter_args) do |controller|
+            controller.permit(authorization_expression, eval_args)
+          end
+        end
+      end
+
+      module ControllerInstanceMethods
+        include Constellation::Authorization::Base::EvalParser  # RecursiveDescentParser is another option
+
+        # Permit? turns off redirection by default and takes no blocks
+        def permit?(authorization_expression, *args)
+          @options = { :allow_guests => false, :redirect => false }
+          @options.merge!(args.last.is_a?(Hash) ? args.last : {})
+
+          has_permission?(authorization_expression)
+        end
+
+        # Allow method-level authorization checks.
+        # permit (without a question mark ending) calls redirect on denial by default.
+        # Specify :redirect => false to turn off redirection.
+        def permit(authorization_expression, *args)
+          @options = { :allow_guests => false, :redirect => true }
+          @options.merge!(args.last.is_a?(Hash) ? args.last : {})
+
+          if has_permission?(authorization_expression)
+            yield if block_given?
+          elsif @options[:redirect]
+            handle_redirection
+          end
+        end
+
+        private
+
+        def has_permission?(authorization_expression)
+          @current_user = get_user
+          if not @options[:allow_guests]
+            # We aren't logged in, or an exception has already been raised.
+            # Test for both nil and :false symbol as restful_authentication plugin
+            # will set current user to ':false' on a failed login (patch by Ho-Sheng Hsiao).
+            # Latest incarnations of restful_authentication plugin set current user to false.
+            if @current_user.nil? || @current_user == :false || @current_user == false
+              return false
+            elsif not @current_user.respond_to? :id
+              raise(UserDoesntImplementID, "User doesn't implement #id")
+            elsif not @current_user.respond_to? :has_role?
+              raise(UserDoesntImplementRoles, "User doesn't implement #has_role?")
+            end
+          end
+          parse_authorization_expression(authorization_expression)
+        end
+
+        # Handle redirection within permit if authorization is denied.
+        def handle_redirection
+          return if not self.respond_to?(:redirect_to)
+
+          # Store url in session for return if this is available from
+          # authentication
+          send(Rails.application.config.constellation.authorization.store_location_method) if respond_to? Rails.application.config.constellation.authorization.store_location_method
+          if @current_user && @current_user != :false
+            flash[:notice] = @options[:permission_denied_message] || "Permission denied. You cannot access the requested page."
+            redirect_to @options[:permission_denied_redirection] || Rails.application.config.constellation.authorization.permission_denied_redirection
+          else
+            flash[:notice] = @options[:login_required_message] || "Login is required to access the requested page."
+            redirect_to @options[:login_required_redirection] || Rails.application.config.constellation.authorization.login_required_redirection
+          end
+          false  # Want to short-circuit the filters
+        end
+
+        # Try to find current user by checking options hash and instance method in that order.
+        def get_user
+          if @options[:user]
+            @options[:user]
+          elsif @options[:get_user_method]
+            send(@options[:get_user_method])
+          elsif self.respond_to? Rails.application.config.constellation.authorization.current_user_method
+            self.send Rails.application.config.constellation.authorization.current_user_method
+          elsif not @options[:allow_guests]
+            raise(CannotObtainUserObject, "Couldn't find ##{Rails.application.config.constellation.authorization.current_user_method} or @user, and nothing appropriate found in hash")
+          end
+        end
+
+        # Try to find a model to query for permissions
+        def get_model(str)
+          if str =~ /\s*([A-Z]+\w*)\s*/
+            # Handle model class
+            begin
+              Module.const_get(str)
+            rescue
+              raise CannotObtainModelClass, "Couldn't find model class: #{str}"
+            end
+          elsif str =~ /\s*:*(\w+)\s*/
+            # Handle model instances
+            model_name = $1
+            model_symbol = model_name.to_sym
+            if @options[model_symbol]
+              @options[model_symbol]
+            elsif instance_variables.include?('@'+model_name)
+              instance_variable_get('@'+model_name)
+            elsif respond_to?(model_symbol)
+              send(model_symbol)
+            else
+              raise CannotObtainModelObject, "Couldn't find model (#{str}) in hash or as an instance variable"
+            end
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/constellation/authorization/default.rb

@@ -0,0 +1,47 @@
+module Constellation
+  module Authorization
+    module Default
+      module UserExtensions
+        def self.included(recipient)
+          recipient.extend ClassMethods 
+        end
+
+        module ClassMethods
+          def acts_as_authorized_user
+            include Constellation::Authorization::Default::UserExtensions::InstanceMethods
+          end
+        end
+
+        module InstanceMethods
+          def has_role?(role)
+            self.send(:"#{role}?") if self.respond_to?(:"#{role}?")
+          end
+        end
+      end
+
+      module ModelExtensions
+        def self.included(recipient)
+          recipient.extend ClassMethods
+        end
+
+        module ClassMethods
+          def acts_as_authorizable
+            include Constellation::Authorization::Default::ModelExtensions::InstanceMethods
+          end
+        end
+
+        module InstanceMethods
+          def accepts_role?(role, user)
+            if self.respond_to? role
+              self.send(role) == user 
+            elsif self.respond_to? role.pluralize
+              self.send(role.pluralize).include?(user)
+            else
+              false
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/constellation/authorization/engine.rb

@@ -0,0 +1,27 @@
+require 'constellation/authorization'
+require 'rails'
+
+module Constellation
+  module Authorization
+    class Engine < Rails::Engine
+      config.constellation = ActiveSupport::OrderedOptions.new unless config.respond_to? :constellation
+      config.constellation.authorization = ActiveSupport::OrderedOptions.new
+      config.constellation.authorization.mixin = :default
+      config.constellation.authorization.login_required_redirection = { :controller => 'session', :action => 'new' }
+      config.constellation.authorization.permission_denied_redirection = ''
+      config.constellation.authorization.store_location_method = :store_location
+      config.constellation.authorization.current_user_method = :current_user
+      
+      
+      initializer "constellation.authorization.default" do |app|
+        ActionController::Base.send :include, Constellation::Authorization::Base
+        ActionView::Base.send :include, Constellation::Authorization::Base::ControllerInstanceMethods
+        if app.config.constellation.authorization.mixin == :default
+          ActiveRecord::Base.send :include, 
+            Constellation::Authorization::Default::UserExtensions, 
+            Constellation::Authorization::Default::ModelExtensions 
+        end
+      end
+    end
+  end
+end

data/lib/constellation/authorization/exceptions.rb

@@ -0,0 +1,45 @@
+module Constellation
+  module Authorization #:nodoc:
+    
+    # Base error class for Authorization module
+    class AuthorizationError < StandardError
+    end
+
+    # Raised when the authorization expression is invalid (cannot be parsed)
+    class AuthorizationExpressionInvalid < AuthorizationError
+    end
+
+    # Raised when we can't find the current user
+    class CannotObtainUserObject < AuthorizationError
+    end
+
+    # Raised when an authorization expression contains a model class that doesn't exist
+    class CannotObtainModelClass < AuthorizationError
+    end
+
+    # Raised when an authorization expression contains a model reference that doesn't exist
+    class CannotObtainModelObject < AuthorizationError
+    end
+
+    # Raised when the obtained user object doesn't implement #id
+    class UserDoesntImplementID < AuthorizationError
+    end
+
+    # Raised when the obtained user object doesn't implement #has_role?
+    class UserDoesntImplementRoles < AuthorizationError
+    end
+
+    # Raised when the obtained model doesn't implement #accepts_role?
+    class ModelDoesntImplementRoles < AuthorizationError
+    end
+
+    class CannotSetRoleWhenHardwired < AuthorizationError
+    end
+
+    class CannotSetObjectRoleWhenSimpleRoleTable < AuthorizationError
+    end
+
+    class CannotGetAuthorizables < AuthorizationError
+    end
+  end
+end

data/lib/constellation/authorization/parser.rb

@@ -0,0 +1,212 @@
+module Constellation
+  module Authorization
+    module Base
+
+      VALID_PREPOSITIONS = ['of', 'for', 'in', 'on', 'to', 'at', 'by']
+      BOOLEAN_OPS = ['not', 'or', 'and']
+      VALID_PREPOSITIONS_PATTERN = VALID_PREPOSITIONS.join('|')
+
+      module EvalParser
+        # Parses and evaluates an authorization expression and returns <tt>true</tt> or <tt>false</tt>.
+        #
+        # The authorization expression is defined by the following grammar:
+        #         <expr> ::= (<expr>) | not <expr> | <term> or <expr> | <term> and <expr> | <term>
+        #         <term> ::= <role> | <role> <preposition> <model>
+        #  <preposition> ::= of | for | in | on | to | at | by
+        #        <model> ::= /:*\w+/
+        #         <role> ::= /\w+/ | /'.*'/
+        #
+        # Instead of doing recursive descent parsing (not so fun when we support nested parentheses, etc),
+        # we let Ruby do the work for us by inserting the appropriate permission calls and using eval.
+        # This would not be a good idea if you were getting authorization expressions from the outside,
+        # so in that case (e.g. somehow letting users literally type in permission expressions) you'd
+        # be better off using the recursive descent parser in Module RecursiveDescentParser.
+        #
+        # We search for parts of our authorization evaluation that match <role> or <role> <preposition> <model>
+        # and we ignore anything terminal in our grammar.
+        #
+        # 1) Replace all <role> <preposition> <model> matches.
+        # 2) Replace all <role> matches that aren't one of our other terminals ('not', 'or', 'and', or preposition)
+        # 3) Eval
+
+        def parse_authorization_expression( str )
+          if str =~ /[^A-Za-z0-9_:'\(\)\s]/
+            raise AuthorizationExpressionInvalid, "Invalid authorization expression (#{str})"
+            return false
+          end
+          @replacements = []
+          expr = replace_temporarily_role_of_model( str )
+          expr = replace_role( expr )
+          expr = replace_role_of_model( expr )
+          begin
+            instance_eval( expr )
+          rescue Exception => error
+            raise AuthorizationExpressionInvalid, "Cannot parse authorization (#{str}): #{error.message}"
+          end
+        end
+
+        def replace_temporarily_role_of_model( str )
+          role_regex = '\s*(\'\s*(.+?)\s*\'|(\w+))\s+'
+          model_regex = '\s+(:*\w+)'
+          parse_regex = Regexp.new(role_regex + '(' + VALID_PREPOSITIONS.join('|') + ')' + model_regex)
+          str.gsub(parse_regex) do |match|
+            @replacements.push " process_role_of_model('#{$2 || $3}', '#{$5}') "
+            " <#{@replacements.length-1}> "
+          end
+        end
+
+        def replace_role( str )
+          role_regex = '\s*(\'\s*(.+?)\s*\'|([A-Za-z]\w*))\s*'
+          parse_regex = Regexp.new(role_regex)
+          str.gsub(parse_regex) do |match|
+            if BOOLEAN_OPS.include?($3)
+              " #{match} "
+            else
+              " process_role('#{$2 || $3}') "
+            end
+          end
+        end
+
+        def replace_role_of_model( str )
+          str.gsub(/<(\d+)>/) do |match|
+            @replacements[$1.to_i]
+          end
+        end
+
+        def process_role_of_model( role_name, model_name )
+          model = get_model( model_name )
+          raise( ModelDoesntImplementRoles, "Model (#{model_name}) doesn't implement #accepts_role?" ) if not model.respond_to? :accepts_role?
+          model.send( :accepts_role?, role_name, @current_user )
+        end
+
+        def process_role( role_name )
+          return false if @current_user.nil? || @current_user == :false
+          raise( UserDoesntImplementRoles, "User doesn't implement #has_role?" ) if not @current_user.respond_to? :has_role?
+          @current_user.has_role?( role_name )
+        end
+
+      end
+
+      # Parses and evaluates an authorization expression and returns <tt>true</tt> or <tt>false</tt>.
+      # This recursive descent parses uses two instance variables:
+      #  @stack --> a stack with the top holding the boolean expression resulting from the parsing
+      #
+      # The authorization expression is defined by the following grammar:
+      #         <expr> ::= (<expr>) | not <expr> | <term> or <expr> | <term> and <expr> | <term>
+      #         <term> ::= <role> | <role> <preposition> <model>
+      #  <preposition> ::= of | for | in | on | to | at | by
+      #        <model> ::= /:*\w+/
+      #         <role> ::= /\w+/ | /'.*'/
+      #
+      # There are really two values we must track:
+      # (1) whether the expression is valid according to the grammar
+      # (2) the evaluated results --> true/false on the permission queries
+      # The first is embedded in the control logic because we want short-circuiting. If an expression
+      # has been parsed and the permission is false, we don't want to try different ways of parsing.
+      # Note that this implementation of a recursive descent parser is meant to be simple
+      # and doesn't allow arbitrary nesting of parentheses. It supports up to 5 levels of nesting.
+      # It also won't handle some types of expressions (A or B) and C, which has to be rewritten as
+      # C and (A or B) so the parenthetical expressions are in the tail.
+      module RecursiveDescentParser
+
+        OPT_PARENTHESES_PATTERN = '(([^()]|\(([^()]|\(([^()]|\(([^()]|\(([^()]|\(([^()])*\))*\))*\))*\))*\))*)'
+        PARENTHESES_PATTERN = '\(' + OPT_PARENTHESES_PATTERN + '\)'
+        NOT_PATTERN = '^\s*not\s+' + OPT_PARENTHESES_PATTERN + '$'
+        AND_PATTERN = '^\s*' + OPT_PARENTHESES_PATTERN + '\s+and\s+' + OPT_PARENTHESES_PATTERN + '\s*$'
+        OR_PATTERN = '^\s*' + OPT_PARENTHESES_PATTERN + '\s+or\s+' + OPT_PARENTHESES_PATTERN + '\s*$'
+        ROLE_PATTERN = '(\'\s*(.+)\s*\'|(\w+))'
+        MODEL_PATTERN = '(:*\w+)'
+
+        PARENTHESES_REGEX = Regexp.new('^\s*' + PARENTHESES_PATTERN + '\s*$')
+        NOT_REGEX = Regexp.new(NOT_PATTERN)
+        AND_REGEX = Regexp.new(AND_PATTERN)
+        OR_REGEX = Regexp.new(OR_PATTERN)
+        ROLE_REGEX = Regexp.new('^\s*' + ROLE_PATTERN + '\s*$')
+        ROLE_OF_MODEL_REGEX = Regexp.new('^\s*' + ROLE_PATTERN + '\s+(' + VALID_PREPOSITIONS_PATTERN + ')\s+' + MODEL_PATTERN + '\s*$')
+
+        def parse_authorization_expression( str )
+          @stack = []
+          raise AuthorizationExpressionInvalid, "Cannot parse authorization (#{str})" if not parse_expr( str )
+          return @stack.pop
+        end
+
+        def parse_expr( str )
+          parse_parenthesis( str ) or
+          parse_not( str ) or
+          parse_or( str ) or
+          parse_and( str ) or
+          parse_term( str )
+        end
+
+        def parse_not( str )
+          if str =~ NOT_REGEX
+            can_parse = parse_expr( $1 )
+            @stack.push( !@stack.pop ) if can_parse
+          end
+          false
+        end
+
+        def parse_or( str )
+          if str =~ OR_REGEX
+            can_parse = parse_expr( $1 ) and parse_expr( $8 )
+            @stack.push( @stack.pop | @stack.pop ) if can_parse
+            return can_parse
+          end
+          false
+        end
+
+        def parse_and( str )
+          if str =~ AND_REGEX
+            can_parse = parse_expr( $1 ) and parse_expr( $8 )
+            @stack.push(@stack.pop & @stack.pop) if can_parse
+            return can_parse
+          end
+          false
+        end
+
+        # Descend down parenthesis (allow up to 5 levels of nesting)
+        def parse_parenthesis( str )
+          str =~ PARENTHESES_REGEX ? parse_expr( $1 ) : false
+        end
+
+        def parse_term( str )
+          parse_role_of_model( str ) or
+          parse_role( str )
+        end
+
+        # Parse <role> of <model>
+        def parse_role_of_model( str )
+          if str =~ ROLE_OF_MODEL_REGEX
+            role_name = $2 || $3
+            model_name = $5
+            model_obj = get_model( model_name )
+            raise( ModelDoesntImplementRoles, "Model (#{model_name}) doesn't implement #accepts_role?" ) if not model_obj.respond_to? :accepts_role?
+
+            has_permission = model_obj.send( :accepts_role?, role_name, @current_user )
+            @stack.push( has_permission )
+            true
+          else
+            false
+          end
+        end
+
+        # Parse <role> of the User-like object
+        def parse_role( str )
+          if str =~ ROLE_REGEX
+            role_name = $1
+            if @current_user.nil? || @current_user == :false
+              @stack.push(false)
+            else
+              raise( UserDoesntImplementRoles, "User doesn't implement #has_role?" ) if not @current_user.respond_to? :has_role?
+              @stack.push( @current_user.has_role?(role_name) )
+            end
+            true
+          else
+            false
+          end
+        end
+
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification 
+name: constellation-authorization
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 2
+  - 0
+  - 0
+  version: 2.0.0
+platform: ruby
+authors: 
+- Bill Katz
+- Ian Terrell
+- Jeff Bozek
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-04-28 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: A module for managing authorization.
+email: ian@constellationsoft.com;jeff@constellationsoft.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/constellation/authorization/base.rb
+- lib/constellation/authorization/default.rb
+- lib/constellation/authorization/engine.rb
+- lib/constellation/authorization/exceptions.rb
+- lib/constellation/authorization/parser.rb
+- lib/constellation/authorization.rb
+has_rdoc: true
+homepage: http://github.com/constellationsoft/authorization
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: A module for managing authorization.
+test_files: []
+