annotation_security 1.0.1

data/lib/annotation_security/exec.rb

@@ -0,0 +1,189 @@
+require 'optparse'
+require 'fileutils'
+
+# = lib/annotation_security/exec.rb
+# This file is borrowed heavily from HAML
+#
+
+module AnnotationSecurity
+  module Exec # :nodoc:
+
+    # An abstract class that encapsulates the executable
+    # code for all executables.
+    class Generic # :nodoc:
+
+      # Parsed options
+      def options
+        @options ||= {}
+      end
+
+      # @param args [Array<String>] The command-line arguments
+      def initialize(args)
+        @args = args
+      end
+      
+      # Parses the command-line arguments and runs the executable.
+      # Calls `Kernel#exit` at the end, so it never returns.
+      def parse!
+        begin
+          @opts = OptionParser.new(&method(:set_opts))
+          @opts.parse!(@args)
+
+          process_result
+
+          options
+        rescue Exception => e
+          raise e if e.is_a?(SystemExit) || options[:trace]
+
+          $stderr.puts e.message
+          exit 1
+        end
+        exit 0
+      end
+
+      # @return [String] A description of the executable
+      def to_s
+        @opts.to_s
+      end
+
+      protected
+
+      # Tells optparse how to parse the arguments
+      # available for all executables.
+      #
+      # This is meant to be overridden by subclasses
+      # so they can add their own options.
+      #
+      # @param opts [OptionParser]
+      def set_opts(opts)
+        opts.on("--force", "Force command execution, override assets without asking") do
+          options[:force] = true
+        end
+
+        opts.on("--trace", "Shows full stack trace in case of errors") do
+          options[:trace] = true
+        end
+
+        opts.on_tail("-?", "-h", "--help", "Show this message") do
+          puts opts
+          exit
+        end
+
+        opts.on_tail("-v", "--version", "Print version") do
+          puts("AnnotationSecurity 0.01")
+          exit
+        end
+      end
+
+      # Processes the options set by the command-line arguments.
+      # 
+      # This is meant to be overridden by subclasses
+      # so they can run their respective programs.
+      def process_result; end
+    end
+
+    # An abstrac class that encapsulates the code
+    # specific to executables.
+    class RailsInstaller < Generic # :nodoc:
+
+      ASSET_FILES = %w{
+        config/initializers/annotation_security.rb
+        config/security/relations.rb
+        config/security/rights.yml
+        app/helpers/annotation_security_helper.rb
+        vendor/plugins/annotation_security/init.rb
+      }
+      
+      # @param args [Array<String>] The command-line arguments
+      def initialize(args)
+        super
+        @name = "annosec"
+      end
+
+      protected
+
+      # Tells optparse how to parse the arguments.
+      #
+      # This is meant to be overridden by subclasses
+      # so they can add their own options.
+      #
+      # @param opts [OptionParser]
+      def set_opts(opts)
+        opts.banner = <<END
+Usage: #{@name.downcase} [options]
+
+Description:
+  Installs the AnnotationSecurity layer into a rails app
+
+Options:
+END
+        
+        opts.on('--rails RAILS_DIR', "Install AnnotationSecurity layer from the Gem to a Rails project") do |dir|
+          options[:rails_dir] = dir
+        end
+
+        super
+      end
+
+      # Processes the options set by the command-line arguments.
+      # In particular, sets `@options[:for_engine][:filename]` to the input filename
+      # and requires the appropriate file.
+      #
+      # This is meant to be overridden by subclasses
+      # so they can run their respective programs.
+      def process_result
+
+        unless options[:rails_dir]
+          puts @opts
+          exit
+        end
+
+        options[:cur_dir] = File.dirname(__FILE__)
+        options[:assets_dir] = File.join(options[:cur_dir], '..', '..', 'assets')
+
+        assert_exists('config')
+        assert_exists('vendor')
+        assert_exists('app/helpers')
+
+        ASSET_FILES.each { |f| install_file(f) }
+
+        puts "AnnotationSecurity plugin added to #{options[:rails_dir]}"
+        exit
+      end
+
+      private
+      
+      def assert_exists(dir)
+        dir = File.join(options[:rails_dir], dir)
+        unless File.exists?(dir)
+          if options[:force]
+            puts "Creating #{dir}"
+            FileUtils.mkdir_p dir
+          else
+            puts "Directory #{dir} does not exist"
+            exit
+          end
+        end
+      end
+      
+      def install_file(f)
+        orign = File.join(options[:assets_dir], f)
+        dest = File.join(options[:rails_dir], f)
+        
+        if File.exists?(dest) && !options[:force]
+          print "File #{dest} already exists, overwrite [y/N]? "
+          return if gets !~ /y/i
+        end
+
+        dir = File.dirname(dest)
+        unless File.exists?(dir)
+          puts "Creating #{dir}"
+          FileUtils.mkdir_p(dir)
+        end
+        
+        FileUtils.install(orign, dest)
+        puts "Installed #{dest}"
+      end
+    end
+  end
+end

data/lib/annotation_security/filters.rb

@@ -0,0 +1,38 @@
+#
+# = lib/annotation_security/filters.rb
+#
+
+require "active_record"
+
+module AnnotationSecurity # :nodoc:
+  
+  # Contains filters of the security layer which filter current requests,
+  # set up security context and apply security rules.
+  module Filters
+    # This filter is a before filter and is executed as the first filter in the
+    # filter chain. It initializes the security layer.
+    class InitializeSecurity
+      
+      # Initialize current security context depending on logged_in user
+      def self.filter(controller)
+        SecurityContext.initialize(controller)
+        yield
+      end
+    end
+
+    # This filter is an around filter and is executed as the last filter before
+    # execution of action. It applies the security mechanisms.
+    class ApplySecurity
+      # Applies security policies based on current user.
+      def self.filter(controller)
+        ::ActiveRecord::Base.transaction do
+          rules = controller.class.descriptions_of(controller.action_name)
+          SecurityContext.current.eval_with_security(rules){ yield }
+        end
+      rescue AnnotationSecurity::SecurityError
+        SecurityContext.security_exception = $!
+        raise $!
+      end
+    end
+  end
+end

data/lib/annotation_security/includes/action_controller.rb

@@ -0,0 +1,144 @@
+#
+# = lib/annotation_security/includes/action_controller.rb
+#
+
+# Provides security extensions for rails controllers.
+# Is included in ActionController::Base.
+#
+# See AnnotationSecurity::ActionController::ClassMethods.
+#
+module AnnotationSecurity::ActionController
+
+  def self.included(base) # :nodoc:
+    base.extend(ClassMethods)
+    base.send :include, InstanceMethods
+  end
+
+  # Provides security extensions for rails controllers on the class side.
+  # 
+  module ClassMethods
+
+    # Filters are not affected by the security settings of the action.
+    # If you want security checkings in your filters, activate them with
+    # +apply_security+.
+    #
+    #  apply_security :get_user
+    #
+    #  private
+    #
+    #  desc "shows a user"
+    #  def get_user
+    #    @user = User.find params[:id]
+    #  end
+    #
+    # You can use +apply_security+ to secure any methods, not only filters.
+    # Notice that these rules are *not* taken into account when evaluating
+    # AnnotationSecurity::Helper#link_to_if_allowed and similar methods.
+    #
+    def apply_security(*symbols)
+      symbols.each { |s| pending_security_wrappers << s.to_sym }
+    end
+
+    # Filters are not affected by the security settings of the action.
+    # If you want the security settings of the action applied to your filter,
+    # use this method. It can be combined with #apply_security
+    def apply_action_security(*symbols)
+      symbols.each { |s| pending_action_security_wrappers << s.to_sym }
+    end
+
+    # AnnotationSecurity is using the +method_added+ callback. If this method
+    # is overwritten without calling +super+, +apply_security+ will not work.
+    #
+    def method_added(method)
+      super(method)
+      if pending_security_wrappers.delete method
+        build_security_wrapper(method)
+      end
+      if pending_action_security_wrappers.delete method
+        build_action_security_wrapper(method)
+      end
+    end
+
+    # If no resource type is provided in a description, the default resource
+    # will be used. Once set the value cannot be changed.
+    #
+    # This is still experimental. You should not use it unless you have a
+    # reason. It might be usefull for inheritance.
+    #
+    def default_resource(value=nil)
+      @default_resource ||= value || compute_default_resource
+    end
+
+    # Creates a new security filter.
+    #
+    # Security filters are around filters that are evaluated before the first
+    # before filter. Use security filters to set the credentials and to react
+    # to security violations.
+    #  class ApplicationController < ActionController::Base
+    #
+    #    security_filter :security_filter
+    #
+    #    private
+    #
+    #    def security_filter
+    #      SecurityContext.current_credential = session[:user]
+    #      yield
+    #    rescue SecurityViolationError
+    #      if SecurityContext.is? :logged_in
+    #        render :template => "welcome/not_allowed"
+    #      else
+    #        render :template => "welcome/please_login"
+    #      end
+    #    end
+    #
+    # See SecurityContext#current_credential= and SecurityViolationError.
+    #
+    def security_filter(symbol, &block)
+      filter_chain.append_filter_to_chain([symbol], :security, &block)
+    end
+
+    private
+
+    def pending_security_wrappers
+      @pending_security_wrappers ||= []
+    end
+
+    def pending_action_security_wrappers
+      @pending_action_security_wrappers ||= []
+    end
+
+    def build_security_wrapper(method)
+      no_security = "#{method}_without_security".to_sym
+      class_eval %{
+        alias :#{no_security} :#{method}
+        def #{method}(*args, &proc)
+          rules = self.class.descriptions_of(:#{method})
+          SecurityContext.current.send_with_security(rules, self, :#{no_security}, *args, &proc)
+        end
+      }
+    end
+
+    def build_action_security_wrapper(method)
+      no_security = "#{method}_without_action_security".to_sym
+      class_eval %{
+        alias :#{no_security} :#{method}
+        def #{method}(*args, &proc)
+          rules = self.class.descriptions_of(action_name)
+          SecurityContext.current.send_with_security(rules, self, :#{no_security}, *args, &proc)
+        end
+      }
+    end
+
+    def compute_default_resource
+      name.first(-"Controller".length).singularize.underscore.to_sym
+    end
+
+  end
+
+  module InstanceMethods # :nodoc:
+
+    def security_exception=(ex)
+      @security_exception = ex
+    end
+  end
+end

data/lib/annotation_security/includes/active_record.rb

@@ -0,0 +1,28 @@
+#
+# = lib/annotation_security/includes/active_record.rb
+#
+
+# = AnnotationSecurity::ActiveRecord
+# 
+# Included by model classes if they are used as resources.
+# Includes AnnotationSecurity::Resource and sets up the model observer.
+#
+module AnnotationSecurity::ActiveRecord # :nodoc:
+
+  def self.included(base)
+    base.class_eval do
+      include ::AnnotationSecurity::Resource
+    end
+    base.extend(ClassMethods)
+    AnnotationSecurity::ModelObserver.observe base.name.underscore.to_sym
+    AnnotationSecurity::ModelObserver.instance.reload_model_observer
+  end
+  
+  module ClassMethods # :nodoc:
+    def get_resource(object)
+      return object if object.is_a? self
+      # Object.const_get(name) needed because of a bug in Rails
+      Object.const_get(name).find(object)
+    end
+  end
+end

data/lib/annotation_security/includes/helper.rb

@@ -0,0 +1,215 @@
+#
+# = lib/annotation_security/includes/helper.rb
+#
+
+# = AnnotationSecurity::Helper
+# 
+# This module adds some useful helper methods to your templates.
+#
+module AnnotationSecurity::Helper
+
+  # Returns true if the operation defined by +policy_args+ is allowed.
+  #
+  # The following calls to #allowed? are possible:
+  #
+  #   allowed? :show, :resource, @resource
+  #   # => true if the current user has the right to show @resource,
+  #   #    which belongs to the :resource resource-class
+  #
+  # In case of model objects or other classes which implement a #resource_type
+  # method the the second argument may be ommited
+  #
+  #   allowed? :show, @resource
+  #   # equivalent to the above call if @resource.resource_type == :resource
+  #
+  # A policy description used as a controller annotation may also be used 
+  # to check a right
+  #
+  #   allowed? "show resource", @resource
+  #   # => true if the current user has the right "show resource" for @resource
+  #
+  # A policy may also be applied without an object representing the context:
+  #
+  #   allowed? :show, :resource
+  #   # => true if the current may show resources.
+  #
+  # This will only check system and pretest rules. The result +true+ does not
+  # mean that the user may show all resources. However, a +false+ indicates
+  # that the user is not allowed to show any resources.
+  #
+  # If the resource class is omitted as well, only rules defined for all
+  # resources can be tested. See RelationLoader#all_resources for details.
+  #
+  #  allowed? :administrate
+  #  # => true if the user is allowed to administrate all resources.
+  #
+  # See SecurityContext#allowed?.
+  #
+  def allowed?(*args)
+    SecurityContext.allowed?(*args)
+  end
+
+  alias a? allowed?
+
+  # Equivalent to allowed?; is? is provided for better readability.
+  #
+  #  allowed? :logged_in
+  # vs
+  #  is? :logged_in
+  #
+  def is?(*args)
+    SecurityContext.is?(*args)
+  end
+
+  # Checks whether the user is allowed to access the action.
+  #
+  # Expects arguments like #link_to_if_allowed, just without name and block.
+  #
+  # Returns true if the action is allowed.
+  #
+  def action_allowed?(options, objects=nil, params=nil, html_options=nil)
+
+    options, objects, params, html_options =
+              parse_allow_action_args(options, objects, params, html_options)
+
+    controller = params.delete :controller
+    action = params.delete :action
+    SecurityContext.allow_action?(controller, action, objects, params)
+  end
+
+  # Returns a link tag with the specified name to the specified resource if
+  # the user is allowed to access it. See #link_to_unless and
+  # SecurityContext#action_allowed? for more documentation.
+  #
+  # There are two ways of using #link_to_if_allowed
+  #
+  # === As #link_to with alternative
+  # (or as #link_to_unless without explicit condition)
+  #  link_to_if_allowed(name, options={}, html_options=nil) { 'alternative' }
+  # +options+ either is a hash, like
+  #  { :controller => :comments, :action => edit, :id => @comment }
+  # a string, like
+  #  "comments/1/edit"
+  # or
+  #  edit_comment_path(@comment)
+  # or a single resource object.
+  #
+  # Notice that when providing a string, controller, action and parameters will
+  # be parsed. After that, the resource types of the parameters are *guessed*,
+  # the resources are retrieved and the rules of the action are evaluated.
+  #
+  # The block will be evaluated if the action is not allowed,
+  # like in #link_to_unless.
+  #
+  # === As #link_to with alternative and explicit objects
+  #  link_to_if_allowed(name, options={}, objects=[], params={}, html_options=nil) { 'alternative' }
+  # In this case, controller and action will be derived from +options+ unless
+  # they are specified in +params+.
+  # All items in +objects+ and all remaining items in +params+ will be used
+  # for evaluating the rules of the action.
+  #
+  # If you want to specify +html_options+, provide at least an empty hash
+  # for +params+.
+  #
+  # Unlike to #link_to, you can also provide a symbol as +options+ value.
+  # In this case, the target url will be determined by sending symbol as
+  # message, providing +objects+ and +params+ as arguments, e.g.
+  #  link_to_if_allowed("Show comment", :comment_path, [@article, @comment], {:details => true})
+  # will call
+  #  comment_path(@article, @comment, {:details => true})
+  #
+  # === Examples
+  #  <%= link_to_if_allowed("Show", @course) { } %>
+  #  <%= link_to_if_allowed("New", new_course_path) { "You may not create a new course." } %>
+  #
+  # These two are equivalent, however, the second approach is more efficient:
+  #  <%= link_to_if_allowed("Edit", edit_course_path(@course)) { } %>
+  #  <%= link_to_if_allowed("Edit", :edit_course_path, @course) { } %>
+  #
+  # The HTML-options are taken into account when choosing the action.
+  #  <%= link_to_if_allowed("Delete", @course, {:method => :delete}) { } %>
+  #
+  # You can also define all values explicitly
+  #  <%= link_to_if_allowed("Edit comment", "articles/1/comments/5/edit", [@comment], {:article => @comment.article, :action => :edit, :controller => :comments}) { } %>
+  # 
+  # === Parameters
+  # - +name+ Text of the link
+  # - +options+
+  # - +objects+
+  # - +params+
+  # - +html_options+
+  #
+  def link_to_if_allowed(name, options, objects=nil, params=nil, html_options=nil, &block)
+
+    options, objects, params, html_options =
+              parse_allow_action_args(options, objects, params, html_options)
+
+    controller = params.delete :controller
+    action = params.delete :action
+    allowed = SecurityContext.allow_action?(controller, action, objects, params)
+
+    link_to_if(allowed, name, options, html_options, &block)
+  end
+
+  alias link_if_a link_to_if_allowed
+
+  private
+
+  def parse_allow_action_args(*args)
+    if args.second && !(args.second.is_a? Hash)
+      # objects and params are specified
+      options, objects, params, html_options = args
+      objects = [objects] unless objects.is_a? Array
+      params ||= {}
+      html_options ||= {}
+      if options.is_a? Symbol
+        # options is a symbol, send the message to get the link path
+        path_args = objects + [params]
+        options = send(options, *path_args)
+      end
+    else
+      # retrieve objects and params from options
+      options = args.first
+      html_options = args.second || {}
+      objects = [] # everything will be in the params
+      if options.is_a? Hash
+        params = options.dup
+      else
+        params = parse_action_params(options, html_options)
+      end
+    end
+
+    unless params[:controller] && params[:action]
+      # if controller and action are not given, parse from options
+      params = parse_controller_action(options, params, html_options)
+    end
+    
+    [options, objects, params, html_options]
+  end
+
+  # uses options and html_options to retrieve controller and action,
+  # adds these values to params hash
+  def parse_controller_action(options, params, html_options)
+    path_info = get_path_info(options, html_options)
+    params[:controller] ||= path_info[:controller]
+    params[:action] ||= path_info[:action]
+    params
+  end
+
+  # uses options and html_options to retrieve controller, action
+  # and params
+  def parse_action_params(options, html_options)
+    get_path_info(options, html_options)
+  end
+
+  def get_path_info(options, html_options)
+    if options.is_a? String
+      path = options
+    else
+      path = url_for(options)
+    end
+    env = { :method => (html_options[:method] || :get ) }
+    ActionController::Routing::Routes.recognize_path(path, env)
+  end
+
+end

data/lib/annotation_security/includes/resource.rb

@@ -0,0 +1,85 @@
+#
+# = lib/annotation_security/includes/resource.rb
+#
+
+# Must be included by all classes that are resource classes and do not extend
+# ActiveRecord::Base.
+#
+#   class MailDispatcher
+#     include AnnotationSecurity::Resource
+#     resource_type = :email
+#     ...
+#
+# See AnnotationSecurity::Resource::ClassMethods.
+#
+module AnnotationSecurity::Resource
+
+  def self.included(base) # :nodoc:
+    base.extend(ClassMethods)
+    base.class_eval do
+      include InstanceMethods
+    end
+  end
+
+  # Provides class side methods for resource classes.
+  module ClassMethods
+
+    # Registers the class as a resource.
+    #
+    def resource_type=(symbol)
+      @resource_type = symbol
+      AnnotationSecurity::ResourceManager.add_resource_class(symbol,self)
+      symbol
+    end
+
+    def resource_type # :nodoc:
+      @resource_type || (self.resource_type = name.underscore.to_sym)
+    end
+
+    def policy_for(user,obj=nil) # :nodoc:
+      policy_factory.create_policy(user,obj)
+    end
+
+    # If required, overwrite this method to return a resource object identified
+    # by the argument.
+    #
+    # This might be necessary if you change the to_param method of an
+    # ActiveRecord class.
+    #
+    #  class Course < ActiveRecord::Base
+    #    ...
+    #    # each course has a unique name --> make better urls
+    #    def to_param
+    #      name
+    #    end
+    #
+    #    def self.get_resource(name)
+    #      find_by_name(name)
+    #    end
+    #
+    def get_resource(arg)
+      raise NoMethodError, "#{self} does not implement #get_resource"
+    end
+
+    private
+
+    def policy_factory # :nodoc:
+      @policy_factory ||= AnnotationSecurity::PolicyManager.policy_factory(resource_type)
+    end
+
+  end
+
+  module InstanceMethods # :nodoc:
+    def resource_type
+      self.class.resource_type
+    end
+
+    def __is_resource?
+      true
+    end
+
+    def policy_for(user)
+      self.class.policy_for(user,self)
+    end
+  end
+end