walruz 0.0.3

data/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2009 Roman Gonzalez <romanandreg@gmail.com>. 
+Copyright (c) 2009 Noomii inc. <http://www.noomii.com>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,265 @@
+= Walruz: Simple but Powerful Authorization Framework
+
+== Basic and Terminology
+
+Walruz facilitates the separation between the authorization process on the business logic and the actions executed after the validation of the authorizations. To understand how it works, we will follow the following terminology:
+
+  - Subject: Object that is going to be managed (Profile, Posts)
+  - Actor: Entity that wants to perform an action on a subject (User, Admin)
+  - Policy: A set of rules that tells if the Actor can perform the desired action on the Subject
+
+== Walruz Architecture 
+
+Walruz provides modules and classes that helps on the implementation of the concepts given previously, this are:
+  
+  - Walruz::Subject 
+    Module that provides the interface to associate policies to an action in the subject
+  
+  - Walruz::Actor
+    Module that provides the interface to perform queries to validate if an action can be done between the
+    actor and the subject
+    
+  - Walruz::Policy
+    Class that provides the interface to implement authorization logic
+
+== Subjects specify which policies are related to which actions
+
+Subject classes may specify a set of actions that can be performed to them using the check_authorization method
+
+  class ASubject
+    include Walruz::Subject
+    
+    check_authorization :show => Policy1,
+                        :edit => Policy2
+  end
+
+If there is just one policy to every possible action performed to the subject, you may specify the :default action, or just specify the Policy class.
+
+Example:
+
+  class ASubject
+    include Walruz::Subject
+  
+    check_authorization PolicyClazz
+  end
+
+or
+
+  class AnotherSubject
+    include Walruz::Subject
+  
+    check_authorization :default => PolicyClazz
+  end
+  
+You can also specify other flags with the default flag.
+
+  class ASubject
+    include Walruz::Subject
+
+    check_authorization :show => Policy1,
+                        :edit => Policy2,
+                        :default => DefaultPolicy
+  end
+
+== Actors verify if they are able to perform an action on a subject
+
+Actor classes can use several methods to check if the actor instance can perform the given action on the subject. This are:
+
+- `can?(action, subject)`
+  Returns boolean that says if the actor can execute or not the action on the subject, if a block is given, this will be executed when the authorization is true, and a parameters hash from the policy will be passed to the block.
+
+- `can!(action, subject)`
+  In case the actor can execute the action on the subject, it returns the parameters hash from the policy, otherwise it will raise a Walruz::NotAuthorized.
+
+- `satisfies?(policy_class, subject)`
+  It behaves just like the `can?` method, but instead of giving an action to be executed to the subject, it gives a policy
+
+In case the given action is not assigned to any policy, a default Policy will be executed (if given), if no default policy is given then a Walruz::FlagNotFound exception will be raised.
+
+Examples:
+  
+  current_user.can?(:read, friends_profile) do |policy_params|
+    # code to be executed if current user can read a friends profile
+  end
+  
+  current_user.satisfies?(ActorIsAdmin, nil) do
+    # execute some admin logic
+  end
+  
+  policy_params = current_user.can!(:read, friends_profile)
+  # all the code executed bellow will be executed when the actor is authorized
+
+== Implementing Policies
+
+To implement a Policy, its necessary that the Policy class inherits from the Walruz::Policy class. This class provides a method called `authorized?` that return either a Boolean, or an Array of two items, the first one being a Boolean, and the second being a Hash of parameters returned from the Policy.
+
+Examples:
+  
+  class ActorIsAdmin < Walruz::Policy
+  
+    def authorized?(actor, _)
+      actor.is_admin?
+    end
+  
+  end
+  
+  class UserIsFriend < Walruz::Policy
+  
+    def authorized?(current_user, friend)
+      friendship = Friendship.first(:conditions => { :friend_id => current_user.id, :owner_id => friend.id})
+      if !friendship.nil?
+        [true, {
+          :friendship => friendship
+        }]
+      else
+        false
+      end
+    end
+  
+  end
+
+== Composing basic policies to create complex ones
+
+Sometimes policies can turn really messy, specially when you have a complex business model. The good news is that, normally this complex policies are a composition of more simple policies (eg. ActorCanSeeUserPictures). Instead of creating this new classes that replicates the same logic of basic policies, we could merge them together in the following way:
+
+ActorCanSeeUserPictures = Walruz::Utils.andP(UserIsFriend, UserAllowsDisclosureOfPictures)
+
+There is also the utility methods `orP` and `notP`, to create combinations of policies. 
+
+If your policy returns a parameters hash, and you are using the `andP` method, the parameters will be merged on each policy invocation, if you are using the `orP` method, the parameters of the first policy that returns true will be returned.
+
+One other thing that the utility methods do for you is leave its track on the returned policy parameters, when you invoke a composite policy, every policy will leave a symbol with the name of the policy underscored and a question mark at the end, that way you can know which policies were successful or not. 
+
+Example:
+  
+  class ActorIsAdmin < Walruz::Policy 
+    # code from above here ...
+  end
+  
+  class ActorIsSubject < Walruz::Policy
+    def authorized?(actor, subject); actor == subject; end
+  end
+  
+  UserReadPolicy = orP(ActorIsSubject, ActorIsAdmin)
+  
+  class User < AbstractORM
+    include Walruz::Subject
+    
+    check_authorizations :read => UserReadPolicy
+  end
+  
+  current_user.can?(:read, other_user) do |policy_params|
+    if policy_params[:actor_is_subject?]
+      # do logic of the user interacting with herself
+    elsif policy_params[:actor_is_admin?]
+      # do logic of the admin user interacting with other user
+    else
+      # do other logic here...
+    end
+  end
+
+== Dependencies between Policies
+
+Sometimes you would like to have a Policy that strictly depends in other ones, on the previous example `UserAllowsDisclosureOfPictures` could have a dependency that says that only the User allows the disclosure of pictures if and only if there is a friend relationship, so we could re-implement this policy as:
+
+Example:
+
+  class UserAllowsDisclosureOfPictures < Walruz::Policy
+    depends_on UserIsFriend
+    # ...
+  end
+
+Suppose you need the parameters returned by the previous Policy, you can have them with the params method, it works just like a request.params from any Web Framework in Ruby.
+
+Example:
+
+  class UserAllowsDisclosureOfPictures < Walruz::Policy
+    depends_on UserIsFriend
+    
+    def authorized?(_, _)
+      params[:friendship].allows_disclosure_of_images?
+    end
+    
+  end
+  
+== Policy combinators, Lifting to the rescue! 
+
+Sometimes you would like to execute policies that are not directly related to a subject, but to the association of a subject. Given the example above of the friendship relationship and the disclosure of pictures, sometimes you would like to check if a user can see a picture directly on the picture model.
+
+Suppose we have the following model in our system:
+
+  class Picture < AbstractORM
+    belongs_to :owner
+  end
+
+and we would like to check if the current_user can see (read) the picture using:
+
+  current_user.can(:read, picture_instance)
+  
+If you may recall, we already implemented the logic that checks that authorization in UserAllowsDisclosureOfPictures, but that policy only works when the subject is of class User; given that you have a subject of class Picture you can not re-use this policy.
+
+You could solve this issue doing the following:
+
+  class PictureReadPolicy < Walruz::Policy
+    
+    def authorized?(user, image)
+      user.satisfies?(UserAllowsDisclosureOfPictures, image.owner)
+    end
+    
+  end
+
+But as you may see, we are just creating new policies to handle old ones, we are not combining the policies effectively. To avoid this caveat, you can use the `lift_subject` method:
+
+  PictureReadPolicy = lift_subject(:owner, UserAllowsDisclosureOfPictures)
+  
+  class Picture < AbstractORM
+    include Walruz::Subject
+    belongs_to :owner
+    
+    check_authorizations :read => PictureReadPolicy
+  end
+  
+The first parameter of `lift_subject` is the name of the method that will return a new subject, this new subject is then passed through the policy specified on the second parameter and then executes the Policy checking. Pretty neat eh?
+
+== Returning custom errors
+
+Suppose you want to add an error to the authorization failure that is a more descriptive, you can do so on the `authorized?` method passing a hash with a :error_message key on the false return. If you use the `can!` method on the actor model, this will become the `Walruz::NotAuthorized` error message.
+
+Example:
+  
+  class SomePolicy < Walruz::Policy
+  
+    def authorized?(actor, subject)
+      # some complex logic here
+      return [false, {
+        :error_message => 'More descriptive error message'
+      }]
+    end
+  end
+
+
+== Conventions
+
+You'll notice that once you start implementing policies for your system, you'll be lost soon enough asking yourself which type of subject a Policy receives; to avoid such confusions, we suggest that you apply the following rules:
+
+- The first name of the policy should be the Subject class (e.g. UserIsFriend)
+- If the policy only applies to the actor, the policy class name should start with the Actor word (e.g. ActorIsAdmin)
+- You should always have the compositions of policies in just one place in your library folder (e.g. in policies.rb file).
+- The result of policy compositions should finish with the word Policy (e.g `UserDeletePolicy = orP(ActorIsSubject, ActorIsAdmin`))
+- Use `lift_subject` when you are combining the lifted policy with other policies, if you are not doing this, consider checking authorizations on parents of the subject instead of the subject (e.g. current_user.can?(:see_pictures_of, picture.owner))
+
+If you follow this rules, it will be much easier for you to merge policies together in an efficient way.
+
+== Rails Integration
+
+See the "walruz-rails":http://github.com/noomii/walruz-rails gem
+
+== More examples
+
+You may check the project in the examples/ directory for more info; on the rails project, take a look on the spec/models/beatle_spec.rb file, it's really illustrating.
+
+== Copyright
+
+Copyright (c) 2009 Roman Gonzalez <romanandreg@gmail.com>. 
+Copyright (c) 2009 Noomii inc. <http://www.noomii.com>
+All rights reserved.

data/Rakefile

@@ -0,0 +1,75 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "walruz"
+    gem.summary = %Q{Walruz is a gem that provides an easy but powerful way to implement authorization policies in a system, relying on the composition of simple policies to create more complex ones.}
+    gem.email = "roman@noomi.com"
+    gem.homepage = "http://github.com/roman/walruz"
+    gem.authors = ["Roman Gonzalez"]
+    gem.rubyforge_project = "walruz"
+  
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+  spec.spec_opts = ['--options', "\"%s/spec/spec.opts\"" % File.dirname(__FILE__)]
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "walruz #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+begin
+  require 'rake/contrib/sshpublisher'
+  namespace :rubyforge do
+    
+    desc "Release gem and RDoc documentation to RubyForge"
+    task :release => ["rubyforge:release:gem", "rubyforge:release:docs"]
+    
+    namespace :release do
+      desc "Publish RDoc to RubyForge."
+      task :docs => [:rdoc] do
+        config = YAML.load(
+            File.read(File.expand_path('~/.rubyforge/user-config.yml'))
+        )
+
+        host = "#{config['username']}@rubyforge.org"
+        remote_dir = "/var/www/gforge-projects/walruz/"
+        local_dir = 'rdoc'
+
+        Rake::SshDirPublisher.new(host, remote_dir, local_dir).upload
+      end
+    end
+  end
+rescue LoadError
+  puts "Rake SshDirPublisher is unavailable or your rubyforge environment is not configured."
+end

data/VERSION.yml

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

data/lib/walruz/actor.rb

@@ -0,0 +1,104 @@
+module Walruz
+  
+  #
+  # Actors have the role to use subjects, so they are the ones
+  # who can or cannot do something with a given subject
+  # 
+  module Actor
+    
+    #
+    # Allows an actor to check if he can do some action on a given
+    # subject. It is normally used with a block that get's executed if the
+    # actor can execute the given action on the subject.
+    #
+    # Params: 
+    #   - label: The label of the action
+    #   - subject: The subject which the actor wants to interact with
+    #
+    # Returns:
+    #   It returns a boolean indicating that the actor is authorized to 
+    #   access (or not) the subject
+    #
+    # Notes:
+    #   Because this method is probably going to be called multiple times on
+    #   a same action, the result of the first invocation is cached, if you 
+    #   want to uncache just pass true as a third parameter.
+    #   
+    # 
+    def can?(*args)
+      if args.size == 2
+        cached_values_for_can[args] ||= can_without_caching?(*args)
+      elsif args.size == 3 
+        if args.pop
+          cached_values_for_can[args] = can_without_caching?(*args)
+        else
+          cached_values_for_can[args] ||= can_without_caching?(*args)
+        end
+      else
+        raise ArgumentError.new("wrong number of arguments (%d for 2)" % args.size) 
+      end
+    end
+    
+    def can_without_caching?(label, subject)
+      subject.can_be?(label, self)[0]
+    end
+    
+    def cached_values_for_can
+      @_cached_values_for_can ||= {}
+    end
+    
+    #
+    # Allows an actor to check if he can do some action on a given
+    # subject.
+    #
+    # Params: 
+    #   - label: The label of the action
+    #   - subject: The subject which the actor wants to interact with
+    #
+    # Returns:
+    #   It can return either a Boolean or an Array of the form [Boolean, Hash].
+    #   When is an Array, the second parameter is a Hash with parameters given from
+    #   the policy.
+    #
+    # Raises: 
+    #   Walruz::NotAuthorized error if the actor can't interact with the subject
+    #    
+    def can!(label, subject)
+      result = subject.can_be?(label, self)
+      if result[0]
+        cached_values_for_can[[label, subject]] = result[0]
+        result[1]
+      else
+        response_params = result[1]
+        error_message = response_params[:error_message] || "You are not authorized to access this content"
+        raise NotAuthorized.new(error_message) 
+      end
+    end
+    
+    #
+    # Allows an actor to check if he the given policy applies to him and the given subject.
+    # 
+    # Params:
+    #   - policy: label of the Policy the actor wants to check
+    #   - subject: The subject which the actor wants to interact with
+    #
+    # block |policy_hash|: 
+    #   If the actor can access the subject, then the block will be executed;
+    #   this will receive the policy hash as a parameter.
+    #
+    # Returns:
+    #   It returns a boolean indicating that the actor is authorized to 
+    #   access (or not) the subject with the given Policy.
+    #
+    def satisfies?(policy_label, subject, &block)
+      policy_clz = Walruz.policies[policy_label]
+      raise ActionNotFound.new(:policy_label, :label => policy_label) if policy_clz.nil?
+      result = policy_clz.return_policy.new.safe_authorized?(self, subject)
+      if result[0]
+        block.call(result[1]) if block_given?
+      end
+      result[0]
+    end
+    
+  end
+end

data/lib/walruz/policy.rb

@@ -0,0 +1,160 @@
+module Walruz
+  
+  #
+  # One of the cores of the framework, it's purpuse is to encapsulate
+  # some authorization logic with a given actor and subject.
+  # It's main method `authorized?(actor, subject)` verifies that 
+  # an actor is actually authorized to manage the subject. 
+  #
+  class Policy
+    extend Walruz::Utils
+    
+    attr_reader :params
+    
+    # @private
+    def self.inherited(child)
+      @policies ||= {}
+      unless child.policy_label.nil?
+        @policies[child.policy_label] = child
+      end
+    end
+    
+    #
+    # See Walruz.policies
+    #
+    def self.policies
+      @policies || {}
+    end
+    
+    #
+    # Returns a Proc with a curried actor, making it easier
+    # to perform validations of a policy in an Array of subjects
+    # Params:
+    #   - actor: The actor who checks if it is authorized
+    #
+    # Returns: (subject -> [Bool, Hash])
+    #
+    # Example:
+    #   subjects.filter(&PolicyXYZ.with_actor(some_user))
+    #
+    def self.with_actor(actor)
+      policy_instance = self.new
+      lambda do |subject|
+        policy_instance.safe_authorized?(actor, subject)[0]
+      end
+    end
+    
+    #
+    # Stablish other Policy dependencies, so that they are executed
+    # before the current one, giving chances to receive the previous 
+    # policies return parameters
+    #
+    # Example: 
+    #   class FriendEditProfilePolicy
+    #     depends_on FriendPolicy
+    #     
+    #     def authorized?(actor, subject)
+    #       params[:friend_relationship].can_edit? # for friend metadata
+    #     end
+    #
+    #   end
+    #
+    def self.depends_on(*other_policies)
+      self.policy_dependencies = (other_policies << self)
+    end
+    
+    # Utility for depends_on macro
+    # @private
+    def self.policy_dependencies=(dependencies)
+      @_policy_dependencies = dependencies
+    end
+    
+    # Utility for depends_on macro
+    # @private
+    def self.policy_dependencies
+      @_policy_dependencies
+    end
+    
+    # Utility for depends_on macro
+    # @private
+    def self.return_policy
+      if policy_dependencies.nil?
+        self
+      else
+        andP(*policy_dependencies)
+      end
+    end
+    
+    # Utility method (copied from ActiveSupport)
+    # @private
+    def self.underscore(camel_cased_word)
+      if camel_cased_word.empty?
+        camel_cased_word
+      else
+        camel_cased_word.to_s.split('::').last.
+                gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+                gsub(/([a-z\d])([A-Z])/,'\1_\2').
+                tr("-", "_").
+                downcase
+      end
+    end
+    
+    
+    #
+    # Verifies if the actor is authorized to interact with the subject
+    # Params:
+    #   - actor: The object who checks if it is authorized
+    #   - subject: The object that is going to be accesed
+    #
+    # Returns: [Bool, Hash]
+    #
+    def authorized?(actor, subject)
+      raise NotImplementedError.new("You need to implement policy")
+    end
+    
+    #
+    # Returns the identifier of the Policy that will be setted on the 
+    # policy params hash once the authorization is executed. 
+    # 
+    # Returns:
+    # By default it will return a symbol with the name of the Policy class in underscore (unless the policy label
+    # was setted, in that case the policy label will be used) with an '?' appended
+    #
+    def self.policy_keyword
+      if self.policy_label.nil?
+        nil
+      else
+        :"#{self.policy_label}?"
+      end
+      
+    end
+    
+    def self.policy_label
+      @policy_label ||= (self.name.empty? ? nil : :"#{self.underscore(self.name)}")
+    end
+    
+    #
+    # Sets the identifier of the Policy for using on the `satisfies?` method
+    #
+    # Parameters:
+    #   - label: Symbol that represents the policy
+    # 
+    def self.set_policy_label(label)
+      @policy_label = label
+    end
+    
+    # @private
+    def safe_authorized?(actor, subject)
+      result = Array(authorized?(actor, subject))
+      result[1] ||= {}
+      result[1][self.class.policy_keyword] = result[0] unless self.class.policy_keyword.nil?
+      result
+    end
+    
+    # @private
+    def set_params(params)
+      @params = params
+    end    
+    
+  end
+end