annotation_security 1.0.1

data/lib/annotation_security/includes/role.rb

@@ -0,0 +1,31 @@
+#
+# = lib/annotation_security/includes/role.rb
+#
+
+# = AnnotationSecurity::Role
+# 
+# This module should be included by all role classes
+# to enable full support of all features.
+#
+# A role class is a domain class that represents user roles
+# and does not extend the user class. It should have the method #user that
+# returns the user object it belongs to.
+#
+module AnnotationSecurity::Role
+
+  # Returns true if this belongs to the user given as parameter.
+  #
+  # Required to have a common interface with AnnotationSecurity::User.
+  #
+  def is_user?(user)
+    self.user == user
+  end
+
+  # If +obj+ is a UserWrapper, extract the role before comparing
+  #
+  def ==(obj)
+    obj = obj.__role__ if obj.is_a? AnnotationSecurity::UserWrapper
+    super(obj)
+  end
+
+end

data/lib/annotation_security/includes/user.rb

@@ -0,0 +1,27 @@
+#
+# = lib/annotation_security/includes/user.rb
+#
+
+# = AnnotationSecurity::User
+# 
+# This module should be included by the user domain class to
+# enable full support of all features.
+#
+module AnnotationSecurity::User
+
+  # Returns true if this is the user given as parameter.
+  #
+  # Required to have a common interface with AnnotationSecurity::Role.
+  #
+  def is_user?(user)
+    self == user
+  end
+
+  # If +obj+ is a UserWrapper, extract the user before comparing
+  #
+  def ==(obj)
+    obj = obj.__user__ if obj.is_a? AnnotationSecurity::UserWrapper
+    super(obj)
+  end
+
+end

data/lib/annotation_security/manager/policy_factory.rb

@@ -0,0 +1,30 @@
+#
+# = lib/annotation_security/manager/policy_factory.rb
+#
+
+# = AnnotationSecurity::PolicyFactory
+# Builds the policy classes.
+#
+class AnnotationSecurity::PolicyFactory # :nodoc:
+
+  def initialize(resource_class)
+    @klass = AnnotationSecurity::AbstractPolicy.new_subclass(resource_class)
+  end
+
+  def policy_class
+    @klass
+  end
+
+  def add_rule(symbol,*args,&block)
+    @klass.add_rule(symbol,*args,&block)
+  end
+
+  def create_policy(*args)
+    @klass.new(*args)
+  end
+
+  def reset
+    @klass.reset
+  end
+
+end

data/lib/annotation_security/manager/policy_manager.rb

@@ -0,0 +1,80 @@
+#
+# = lib/annotation_security/manager/policy_manager.rb
+#
+require 'yaml'
+
+# = AnnotationSecurity::PolicyManager
+#
+# Manages loading and creation of all policy classes.
+#
+class AnnotationSecurity::PolicyManager # :nodoc:
+
+  # Get the policy factory for a resource class
+  def self.policy_factory(resource_type) # :nodoc:
+    policy_factories[resource_type.to_sym]
+  end
+
+  # Creates a policy object for a user and a resource type
+  #
+  # ==== Example
+  #
+  #  picture = Picture.find_by_id(params[:picture])
+  #  policy = PolicyManager.get_policy(:picture,@current_user)
+  #  policy.allowed? :show, picture # => true or false
+  #
+  def self.create_policy(resource_type,*args)
+    policy_factory(resource_type).create_policy(*args)
+  end
+
+  def self.policy_class(resource_class) # :nodoc:
+    policy_factory(resource_class).policy_class
+  end
+
+  def self.config_files # :nodoc:
+    @files ||= []
+  end
+
+  # Adds a file that contains security configurations
+  # * +f+ file name
+  # * +ext+ 'yml' or 'rb'
+  def self.add_file(f,ext) # :nodoc:
+    unless config_files.include? [f,ext]
+      config_files.push [f,ext]
+      load_file(f,ext)
+    end
+  end
+
+  def self.reset
+    policy_factories.each_value(&:reset)
+    config_files.each { |f,ext| load_file(f,ext) }
+  end
+
+  private
+
+  def self.load_file(f,ext)
+    fname = get_file_name(f,ext)
+    case ext
+    when 'yml'
+      AnnotationSecurity::RightLoader.define_rights(YAML.load_file(fname))
+    when 'rb'
+      load fname
+    end
+  end
+
+  SEARCH_PATH = ['', RAILS_ROOT, RAILS_ROOT + '/config/security/',
+                 RAILS_ROOT + '/config/', RAILS_ROOT + '/security/']
+
+  def self.get_file_name(f,ext)
+    SEARCH_PATH.each do |fname1|
+      [f, f+'.'+ext].each do |fname2|
+        return (fname1 + fname2) if File.exist?(fname1 + fname2)
+      end
+    end
+    raise "File not found: '#{f+'.'+ext}'"
+  end
+
+  def self.policy_factories
+    # Create a new factory if it is needed
+    @factories ||= Hash.new { |h,k| h[k] = AnnotationSecurity::PolicyFactory.new(k) }
+  end
+end

data/lib/annotation_security/manager/relation_loader.rb

@@ -0,0 +1,273 @@
+#
+# = lib/annotation_security/manager/relation_loader.rb
+#
+
+# Class responsible for loading the relation definitions for resources.
+#
+# == Defining a relation for a resource
+#
+# This example defines the owner relation between a picture and a user.
+# A relation definition is a proc that returns true if the relation exists.
+# All three examples are equivalent. However, in most cases the first way is
+# the way you want to use.
+#  AnnotationSecurity.define_relations do
+#    resource :picture do
+#      owner { |user,picture| picture.user == user }
+#    end
+#  end
+#
+# If you need only one relation for a resource class, use this example:
+#  AnnotationSecurity.define_relations do
+#    picture.owner { |user,picture| picture.user == user }
+#  end
+#
+# If the entire file contains definitions for only one resource class,
+# you might try this:
+#  AnnotationSecurity.define_relations :picture do
+#    owner { |user,picture| picture.user == user }
+#  end
+#
+# === Defining a relation for many resources
+#
+# Use +resources+ to define a relation once for more than one resource class.
+#  AnnotationSecurity.define_relations do
+#    resources(:picture, :comment) do
+#      owner { |user,res| res.user == user }
+#    end
+#  end
+# As for one resource, you can also use
+#  AnnotationSecurity.define_relations do
+#    resources(:picture, :comment).owner { |user,res| res.user == user }
+#  end
+# or
+#  AnnotationSecurity.define_relations(:picture, :comment) do
+#    owner { |user,res| res.user == user }
+#  end
+# 
+# It is also possible to define relations for all resources:
+#  AnnotationSecurity.define_relations do
+#    all_resources do
+#      related { owner or friend_of_owner }
+#    end
+#  end
+# or
+#  AnnotationSecurity.define_relations do
+#    all_resources.related { owner or friend_of_owner }
+#  end
+#
+# Notice that +owner+ and +friend_of_owner+ are relations that can be defined
+# individually for each resource. The 2 parameters +user+ and +resource_object+
+# dont need to be specified if they are not used.
+#
+# == Details on defining a relation
+#
+# As you have seen, the default way to define a relation is using a proc,
+# like
+#  owner { |user,picture| picture.user == user }
+#  related { owner or friend_of_owner }
+#
+# If the condition is simple and uses only other relations,
+# it also can be specified by a string:
+#  related 'if owner or friend_of_owner'
+#
+# === Implicit conditions
+# Besides a string or a proc, a rule definition can contain a list of flags
+# and an options-hash.
+#
+# ==== The :is option
+#
+# A Relation to which the <tt>:is => symbol</tt> option is passed as a parameter
+# only exists if the relation exists and <tt>is_symbol?</tt> invoked on the
+# current user evaluates to true.
+#
+# Let the user class have a method <tt>is_super_user?</tt>, which returns true
+# or false, depending on wheter the user is a super user. This method can be
+# used for defining a relation +super_owner+, that is true if the user is the
+# owner and a super user.
+# 
+#  owner { |user,picture| picture.user == user }
+#  super_owner(:is => :super_user) "if owner"
+# 
+#  super_user(:system, :is => :super_user)
+#
+# ==== The :as option
+# 
+# For a relation to which the <tt>:as => symbol</tt> option is passed as a
+# parameter the current user is replaced by the invocation of
+# <tt>current_credential.as_[symbol]</tt>. The method invocation may return +nil+
+# indicating that the transformation failed. In this case the relation for
+# which <tt>:as => ..</tt> was specified does not exist.
+# 
+# ==== :require_credential
+# By default, a relation requires a user to be executed. Therefore, rights will
+# always fail if the user is nil. To enable rights like 'unless logged_in', the
+# :require_credential option can be set to false.
+#  logged_in(:system, :require_credential => false) { |user| not user.nil? }
+#
+# === Evaluation time
+# While most relations are between the user and a resource object, some are
+# beween the user and an entire class of objects. This means that no instance of
+# a resource is required to tell whether the user has that relation or not.
+#
+# ==== The :resource flag
+# This flag is set by default. It is set for relations that need a resource.
+# 
+#  owner { |user,picture| picture.user == user }
+#  # is short for
+#  # owner(:resource) { |user,picture| picture.user == user }
+#
+# ==== The :system flag
+# You can use the :system flag to denote that a relation does not
+# require a resource object.
+#
+#  all_resources do
+#    super_user(:system, :is => :super_user)
+#  end
+#
+# It is possible to define system relations only for certain resources, and they
+# do not conflict with resource relations.
+#
+#  resource :present do
+#    receiver(:system) { |user| user.was_good? }
+#    receiver { |user,present| present.receiver == user }
+#  end
+#
+# The advantage of system relations is that they improve the rights evaluation.
+# Consider the right
+#  present:
+#    receive: if receiver
+#
+# If an action is invoked requiring the receive-present right,
+# AnnotationSecurity will evaluate the system relation before even entering the
+# action, thus improving the fail fast behavior and avoiding unnecessary
+# operations.
+#
+# Once a present object is observed during the action, the resource relation
+# will be evaluated as well.
+#
+# ==== The :pretest flag
+#
+# Using the :pretest flag, it is possible to define both resource and system
+# relations in one block.
+#
+#  resource :present do
+#    receiver(:pretest) do |user, present|
+#      if present
+#        present.receiver == user
+#      else
+#        user.was_good?
+#      end
+#    end
+#  end
+#
+# This can be helpfull if your relation depends on other relations, where a
+# resource and a system version is available.
+#
+#  all_resources do
+#    responsible(:pretest) { lecturer or corrector }
+#    lecturer(:system, :as => :lecturer)
+#    corrector(:system, :as => :corrector)
+#  end
+#
+#  resource :course do
+#    lecturer(:as => :lecturer) { |lecturer, course| course.lecturers.include? lecturer }
+#    corrector(:as => :corrector) { |corrector, course| course.correctors.include? corrector }
+#  end
+#  # For other resources, lecturer and corrector are defined differently
+#
+# === Defining relations as strings
+#
+# Instead of a block, a string can be used to define the relation.
+#  responsible :pretest, "if lecturer or corrector"
+#
+# The string syntax provides more simplifications, like referring to relations
+# of other resources.
+#
+# This example will evaluate the course-correction relation for the course
+# property of an assignment resource.
+#  resource :assignment do
+#    corrector "if course.corrector: course"
+#  end
+#
+# As the course class includes AnnotationSecurity::Resource, the resource type
+# is not explicitly needed.
+#  resource :assignment_result do
+#    corrector "if corrector: assignment.course"
+#  end
+#
+#
+class AnnotationSecurity::RelationLoader
+
+  # Load relations of the +block+
+  # * +resources+ (optional) list of resources
+  # * +block+ block with relation definitions
+  def self.define_relations(*resources, &block)
+    if resources.blank?
+      class_eval(&block)
+    else
+      resources(*resources,&block)
+    end
+  end
+
+  #
+  def self.method_missing(symbol,*args,&block) #:nodoc:
+    return super unless args.empty?
+    resources(symbol,&block)
+  end
+
+  # Defines relations for a resource
+  # * +block+ (optional) proc with relation definitions
+  def self.resource(resource,&block)
+    resources(resource,&block)
+  end
+
+  # Defines relations for a list of resources
+  # * +block+ (optional) proc with relation definitions
+  def self.resources(*resources,&block)
+    new(resources,&block)
+  end
+
+  # Defines relations for all resources
+  # * +block+ (optional) proc with relation definitions
+  def self.all_resources(&block)
+    resources(:all_resources,&block)
+  end
+
+  ## ===========================================================================
+  ## Instance
+
+  # An instance of RelationLoader is responsible for loading the relations
+  # for a set of resources.
+  def initialize(resources,&block) #:nodoc:
+    @factories = get_factories_for(resources)
+    instance_eval(&block) if block
+  end
+
+  # if a method is missing this will be a new relation for the resource class
+  def method_missing(symbol,*args,&block) #:nodoc:
+    define_relation(symbol,*args,&block)
+  end
+
+  # Defines a new relation for the current resources. However, instead of using
+  #  define_relation(:relation_name,args) { |user,res| some_condition }
+  # it is recommended to use
+  #  relation_name(args) { |user,res| some_condition }
+  #
+  # ==== Parameters
+  # * +symbol+ name of the relation
+  # * +args+ additonal arguments, see AnnotationSecurity::Rule for details
+  # * +block+ (optional) The condition can be passed either as string or as proc
+  #
+  def define_relation(symbol,*args,&block)
+    @factories.each do |factory|
+      factory.add_rule(symbol,*args,&block)
+    end
+  end
+
+  private
+
+  def get_factories_for(resources)
+    resources.collect{ |res| AnnotationSecurity::PolicyManager.policy_factory(res) }
+  end
+
+end

data/lib/annotation_security/manager/resource_manager.rb

@@ -0,0 +1,36 @@
+#
+# = lib/annotation_security/manager/resource_manager.rb
+#
+
+# Needed to find resource objects when only their id is known
+#
+class AnnotationSecurity::ResourceManager # :nodoc:
+
+  @classes = {}
+
+  def self.add_resource_class(res_type,klass)
+    @classes.delete_if { |k,v| v == klass }
+    @classes[res_type] = klass
+  end
+
+  def self.get_resource_class(res_type)
+    @classes[res_type]
+  end
+
+  unless RAILS_ENV == 'production'
+    def self.get_resource_class(res_type)
+      c = @classes[res_type]
+      unless c
+        res_type.to_s.camelize.constantize # load the class
+        c = @classes[res_type]
+      end
+      c
+    end
+  end
+
+  # Call get_resource of the class that is registered for +res_type+
+  def self.get_resource(res_type,object)
+    c = get_resource_class(res_type)
+    c ? c.get_resource(object) : object
+  end
+end

data/lib/annotation_security/manager/right_loader.rb

@@ -0,0 +1,88 @@
+#
+# = lib/annotation_security/manager/right_loader.rb
+#
+
+# = AnnotationSecurity::RightLoader
+# Contains the right loader class, which is responsible for loading
+# right definitions for resources. Load rights from a yaml file or a hash.
+#
+# == Example YAML
+#
+# The file <tt>config/security/rights.yml</tt> inside a rails app
+# might look like this:
+#  picture:
+#    # a user may show a picture if he fulfils the 'related'-relation
+#    show: if related
+#  comment:
+#    # you have to be logged in to view comments
+#    show: if logged_in
+#  user:
+#    # like in ruby, 'unless' is equivalent to 'if not'
+#    register: unless logged_in
+#    delete: if administrator # comments are also possible behind a line
+#  user_content:
+#    # all rights of 'user_content' are defined for 'picture' and 'comment' too
+#    applies_to: picture, comment
+#    create: if logged_in
+#    edit: if owner
+#    delete: if owner or administrator
+# The file can be loaded via <code>AnnotationSecurity#load_rights('rights')</code>.
+#
+# A right's condition can use the keywords +if+, +unless+, +and+, +or+ and
+# +not+, brackets, other rights and all of the resource's relations
+# (see AnnotationSecurity::RelationLoader). For better readability you may
+# add the prefixes +may+, +is+, +can+ or +has+,
+# or append one of the suffixes +for+, +in+, +of+ or +to+.
+#
+#  user_content:
+#    edit: if is_owner_of
+#    delete: if may_edit or is_administrator
+#
+# However, it is recommended to use this feature sparingly.
+#
+class AnnotationSecurity::RightLoader
+
+  # Goes through all resources of +hash+ and load the defined rights.
+  #
+  def self.define_rights(hash) # :nodoc:
+    if hash
+      hash.each_pair do |resource_class, rights|
+        new(resource_class).define_rights(rights)
+      end
+    end
+  end
+
+  # An instance of RightLoader is responsible for loading the rights of a
+  # resource class.
+  #
+  def initialize(resource) # :nodoc:
+    @factory = AnnotationSecurity::PolicyManager.policy_factory(resource)
+  end
+
+  # Goes through all rights in +hash+ and creates rules for all policies these
+  # rights apply to.
+  #
+  def define_rights(hash) # :nodoc:
+    factories = extract_applies_to(hash) << @factory
+    hash.each_pair do |right,condition|
+      # Important: set the :right-flag to activate automatic detection of
+      # the other flags (static,dynamic,require_user)
+      factories.each { |f| f.add_rule(right,:right,condition) }
+    end
+  end
+
+  private
+
+  # Looks for the key 'applies_to', which is no right but a command to apply
+  # all rights of the current resource class to the resource classes listed
+  # in the value.
+  #
+  def extract_applies_to(hash)
+    applies_to = hash.delete('applies_to') || hash.delete(:applies_to)
+    return [] if applies_to.blank?
+    applies_to = [applies_to] if applies_to.is_a? String
+    applies_to.collect{ |r| r.split(',') }.flatten.
+               collect{ |r| AnnotationSecurity::PolicyManager.policy_factory(r.strip) }
+  end
+
+end

data/lib/annotation_security/model_observer.rb

@@ -0,0 +1,61 @@
+#
+# = lib/annotation_security/model_observer.rb
+#
+# Contains SecurityObserver which implements constraint checking for model
+# classes.
+#
+
+module AnnotationSecurity
+
+  # Observes changes in models and applies security policy to them
+  #
+  class ModelObserver < ::ActiveRecord::Observer # :nodoc:
+
+    # Sets the observed model classes
+    #
+    observe # will be set automatically. However, observe must not be removed
+    
+    def before_validation_on_create(record)
+      SecurityContext.observe record
+    end
+    
+    def before_validation_on_update(record)
+      SecurityContext.observe record
+    end
+
+    # after_find is removed in favour of after_initialize
+
+    def after_initialize(record)      
+      if record.new_record?
+        # The record is new
+      else
+        # The record came out of database
+        SecurityContext.observe record
+      end
+    end
+
+    def before_destroy(record)
+      SecurityContext.observe record
+    end
+
+    # Re-register on classes you are observing
+    # See http://riotprojects.com/2009/1/18/active-record-observers-in-gems-plugins
+    #
+    def reload_model_observer
+      observed_classes.each do |klass|
+        add_observer!(klass.name.constantize)
+      end
+    end
+
+    protected
+
+    def add_observer!(klass)
+      klass.delete_observer(self)      
+      super
+      
+      if respond_to?(:after_initialize) && !klass.method_defined?(:after_initialize)
+        klass.class_eval 'def after_initialize() end'
+      end
+    end
+  end
+end