walruz 0.0.6 → 0.0.7

data/README.rdoc

@@ -4,27 +4,27 @@
 
 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
+[<b>Subject</b>] Object that is going to be managed (Profile, Posts).
+[<b>Actor</b>] Entity that wants to perform an action on a <em>subject</em> (User, Admin).
+[<b>Policy</b>] A set of rules that tells if the <em>actor</em> can perform the desired action on the <em>subject</em>.
 
 == Walruz Architecture 
 
 Walruz provides modules and classes that help 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
+[<b><tt>Walruz::Subject</tt></b>]
+  Module that provides the interface to associate policies to an action in the <em>subject</em>.
   
-  - Walruz::Actor
-    Module that provides the interface to perform queries to validate if an action can be done between the
-    actor and the subject
+[<b><tt>Walruz::Actor</tt></b>]
+  Module that provides the interface to perform queries to validate if an action can be done between the
+  <em>actor</em> and the <em>subject</em>.
     
-  - Walruz::Policy
-    Class that provides the interface to implement authorization logic
+[<b><tt>Walruz::Policy</tt></b>]
+  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
+Subject classes may specify a set of actions that can be performed to them using the <tt>check_authorization</tt> method
 
   class User
     include Walruz::Subject
@@ -33,7 +33,7 @@ Subject classes may specify a set of actions that can be performed to them using
                         :update => UserUpdatePolicy
   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.
+If there is just one <em>policy</em> to every possible action performed to the <em>subject</em>, you may specify the :default action, or just specify the Policy class.
 
 Example:
 
@@ -63,35 +63,29 @@ You can also specify other flags with the default flag.
 
 == 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 a subject. This are:
+Actor classes can use several methods to check if the <em>actor</em> instance can perform the given action on a <em>subject</em>. This are:
 
-- `can?(action, subject)`
-  Returns boolean that says if the actor can execute or not the action on the subject.
+[<b><tt>can?(action, subject)</tt></b>] Returns boolean that says if the <em>actor</em> can execute or not the action on the <em>subject</em>.
 
-- `authorize(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.
+[<b><tt>authorize(action, subject)</tt></b>] In case the <em>actor</em> can execute the action on the <em>subject</em>, it returns the parameters hash from the <em>policy</em>, otherwise it will raise a <tt>Walruz::NotAuthorized</tt>.
 
-- `satisfies?(policy_label, subject)`
-  It behaves just like the `can?` method, but instead of giving an action to be executed to the subject, it receives a policy label.
+[<b><tt>satisfies?(policy_label, subject)</tt></b>] It behaves just like the <tt>can?</tt> method, but instead of giving an action to be executed to the <em>subject</em>, it receives a <em>policy</em> label.
 
-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::ActionNotFound exception will be raised.
+In case the given action is not assigned to any <em>policy</em>, a default Policy will be executed (if given), if no default <em>policy</em> is given then a <tt>Walruz::ActionNotFound</tt> exception will be raised.
 
 Examples:
   
-  current_user.can?(:read, friends_profile)
-  
-  current_user.satisfies?(:actor_is_admin, nil) do
-    # execute some admin logic
-  end
-  
-  policy_params = current_user.authorize(:read, friends_profile)
-  # all the code executed bellow will be executed when the actor is authorized
+  current_user.can?(:read, friends_profile)      #=> true
+  current_user.satisfies?(:actor_is_admin, nil)  #=> false
+  current_user.satisfies(:actor_is_admin, nil)  #=> nil
+  current_user.authorize(:read, friends_profile) #=> Hash
+  current_user.authorize!(:read, other_person_profile) # => raises Walruz::NotAuthorized 
 
 == Implementing Policies
 
-To implement a policy, it is necessary to inherit 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.
+To implement a <em>policy</em>, it is necessary to inherit from the Walruz::Policy class. This class provides a method called <tt>authorized?</tt> 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.
 
-Every Policy Class also has a label associated to it, by default the label will be the name of the class in underscore case; if you want to have a custom label for a Policy Class, you can invoke the `set_policy_label` method on the class context and specify the label that you want for it. This label is used on the `satisfies?` method.
+Every Policy Class also has a label associated to it, by default the label will be the name of the class in underscore case; if you want to have a custom label for a Policy Class, you can invoke the <tt>set_policy_label</tt> method on the class context and specify the label that you want for it. This label is used on the <tt>satisfies?</tt> method.
 
 Examples:
   
@@ -118,19 +112,26 @@ Examples:
     end
   
   end
+  
+  # Examples using this policies with the satisfies method
+  
+  current_user.satisfies?(:is_admin, nil)
+  
+  # By default, the policy label is the name of the class in underscore case.
+  current_user.satisfies?(:user_is_friend, other_user)
 
 
 == 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 (e.g. ActorCanSeeUserPictures). Instead of creating this new classes that replicates the same logic of basic policies, we could merge them together in the following way:
+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 (e.g. <tt>ActorCanSeeUserPictures</tt>). 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.all(UserIsFriend, UserAllowsDisclosureOfPictures)
+  ActorCanSeeUserPictures = Walruz::Utils.all(UserIsFriend, UserAllowsDisclosureOfPictures)
 
-There is also the utility methods `any` and `not`, to create combinations of policies. 
+There is also the utility methods <tt>any</tt> and <tt>not</tt>, to create combinations of policies. 
 
-If your policy returns a parameters hash, and you are using the `all` method, the parameters of each policy will be merged together, if you are using the `any` method, the parameters of the first policy that returns true will be returned.
+If your <em>policy</em> returns a parameters hash, and you are using the <tt>all</tt> method, the parameters of each <em>policy</em> will be merged together, if you are using the <tt>any</tt> method, the parameters of the first <em>policy</em> that returns true will be returned.
 
-One other thing that the utility methods does for you is that it leaves its track on the returned policy parameters, when you invoke a composite policy, every policy will leave in the parameters hash the policy_label with a question mark at the end, that way you can know which policies were successful or not. 
+One other thing that the utility methods does for you is that it leaves its track on the returned <em>policy</em> parameters, when you invoke a composite <em>policy</em>, every <em>policy</em> will leave in the parameters hash the policy_label with a question mark at the end, that way you can know which policies were successful or not. 
 
 Example:
   
@@ -170,7 +171,7 @@ Example:
 
 == Dependencies between Policies
 
-Sometimes you would like to have a Policy that strictly depends in other policies, 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:
+Sometimes you would like to have a Policy that strictly depends in other policies, on the previous example <tt>UserAllowsDisclosureOfPictures</tt> 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 <em>policy</em> as:
 
 Example:
 
@@ -179,7 +180,7 @@ Example:
     # ...
   end
 
-Suppose you need the parameters returned by the previous Policy, you can have them with the `params` method.
+Suppose you need the parameters returned by the previous Policy, you can have them with the <tt>params</tt> method.
 
 Example:
 
@@ -194,7 +195,7 @@ Example:
   
 == Policy combinators
 
-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.
+Sometimes you would like to execute policies that are not directly related to a <em>subject</em>, but to the association of a <em>subject</em>. 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:
 
@@ -202,11 +203,11 @@ Suppose we have the following model in our system:
     belongs_to :owner
   end
 
-and we would like to check if the current_user can see (read) the picture using:
+and we would like to check if the <tt>current_user</tt> 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.
+If you may recall, we already implemented the logic that checks that authorization in <tt>UserAllowsDisclosureOfPictures</tt>, but that <em>policy</em> only works when the <em>subject</em> is of class User; given that you have a <em>subject</em> of class Picture you can not re-use this <em>policy</em>.
 
 You could solve this issue doing the following:
 
@@ -218,7 +219,7 @@ You could solve this issue doing the following:
     
   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 `PolicyClass.for_subject` method:
+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 <tt>PolicyClass.for_subject</tt> method:
 
   PictureReadPolicy = UserAllowsDisclosureOfPictures.for_subject(:owner)
   
@@ -229,11 +230,11 @@ But as you may see, we are just creating new policies to handle old ones, we are
     check_authorizations :read => PictureReadPolicy
   end
   
-The parameter of `but_for` is the name of the subject's method that will return a new subject, this new subject is then passed through the policy. Pretty neat eh?
+The parameter of <tt>but_for</tt> is the name of the <em>subject's</em> method that will return a new <em>subject</em>, this new <em>subject</em> is then passed through the <em>policy</em>. 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.
+Suppose you want to add an error to the authorization failure that is a more descriptive, you can do so on the <tt>authorized?</tt> method passing a hash with a <tt>:error_message</tt> key on the false return. If you use the <tt>can!</tt> method on the <em>actor</em> model, this will become the <tt>Walruz::NotAuthorized</tt> error message.
 
 Example:
   
@@ -250,26 +251,28 @@ Example:
 
 == 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:
+You'll notice that once you start implementing policies for your system, you'll be lost soon enough asking yourself which type of <em>subject</em> a Policy receives; to avoid such confusions, we suggest that you apply the following rules of thumb:
 
-- 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 = any(ActorIsSubject, ActorIsAdmin`))
-- Use `PolicyClass.but_for` when you are combining the PolicyClass 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))
+- The first name of the <em>policy</em> should be the Subject class (e.g. <tt>UserIsFriend</tt>)
+- If the <em>policy</em> only applies to the <em>actor</em>, the <em>policy</em> class name should start with the Actor word (e.g. <tt>ActorIsAdmin</tt>)
+- You should always have the compositions of policies in just one place in your library folder (e.g. in <tt>policies.rb</tt> file).
+- The result of <em>policy</em> compositions should finish with the word Policy (e.g <tt>UserDeletePolicy = any(ActorIsSubject, ActorIsAdmin)</tt>)
+- Use <tt>PolicyClass.but_for</tt> when you are combining the <em>policy</em> class with other policies, if you are not doing this, consider checking authorizations on parents of the <em>subject</em> instead of the <em>subject</em> (e.g. <tt>current_user.can?(:see_pictures_of, picture.owner)</tt>)
 
 If you follow this rules, it will be much easier for you to merge policies together in an efficient way.
 
 == Rails Integration
 
-See "walruz-rails":http://walruz-rails.rubyforge.com gem
+See 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.
+You may check the project in the examples/ directory for more info; on the rails project, take a look on the <tt>spec/models/beatle_spec.rb</tt> file, it's really illustrating.
 
 == Copyright
 
-Copyright (c) 2009 Roman Gonzalez <romanandreg@gmail.com>. 
-Copyright (c) 2009 Noomii inc. <http://www.noomii.com>
+Copyright (c) 2009 Roman Gonzalez <romanandreg@gmail.com>.
+
+Copyright (c) 2009 Noomii inc. <http://www.noomii.com>.
+
 All rights reserved.

data/Rakefile

@@ -10,6 +10,7 @@ begin
     gem.homepage = "http://github.com/noomii/walruz"
     gem.authors = ["Roman Gonzalez"]
     gem.rubyforge_project = "walruz"
+    gem.has_rdoc = 'yard'
   
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
 :major: 0
 :minor: 0
-:patch: 6
+:patch: 7

data/lib/walruz/actor.rb

@@ -1,23 +1,36 @@
 module Walruz
   
   #
-  # Actors have the role to use subjects, so they are the ones
-  # who can or cannot do something with a given subject
-  # 
+  # This module provides the methods that enable an <em>actor</em> to check if it is able
+  # to do an action on a <em>subject</em>. It also provides methods to check on specific
+  # Policies given the policy label. The methods mostly used by classes that include this module are:
+  #
+  # [<b><tt>can?(action, subject)</tt></b>] Returns a Boolean indicating if the actor is authorized to do an action on the subject.
+  # [<b><tt>authorize(action, subject)</tt></b>] Returns Either nil if the actor is not authorized or a Hash with the parameters returned from the Policy if the actor is authorized.
+  # [<b><tt>authorize!(action, subject)</tt></b>] Returns a Hash returned by the Policy if the actor is authorized or raises a <tt>Walruz::NotAuthorized</tt> exception otherwise.
+  # [<b><tt>satisfies?(policy_label, subject)</tt></b>] Returns true or false if the Policy is satisfied with the actor and subject given.
+  # [<b><tt>satisfies(policy_label, subject)</tt></b>] Returns Either nil if the actor and subject don't satisfy the policy or a Hash with the parameters returned from the Policy.
+  #
   module Actor
     
+    # @overload can?(action, subject)
+    #   Allows an <em>actor</em> to check if he can perform an <em>action</em> on a given <em>subject</em>.
+    #   === Note:
+    #   This method will check the authorization the first time, following invocations will return a cached
+    #   result unless the third parameter is specified.
+    # 
+    #   @param [Symbol] The action as it is declared on the <tt>check_authorizations</tt> method on the <em>subject</em> class.
+    #   @param [Walruz::Subject] The <em>subject</em> on which the <em>actor</em> wants to execute the <em>action</em>.
+    #   @param [Boolean] (optional) A boolean indicating if you want to reset the cached result.
+    #   @return [Boolean] A boolean indicating if the <em>actor</em> is authorized to perform the <em>action</em> (or not) on the <em>subject</em>.
     #
-    # 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
+    # @overload can?(action, subject, reload)
+    #   Allows an <em>actor</em> to check if he can perform an <em>action</em> on a given <em>subject</em>.
+    # 
+    #   @param [Symbol] The action as it is declared on the <tt>check_authorizations</tt> method on the <em>subject</em> class.
+    #   @param [Walruz::Subject] The <em>subject</em> on which the <em>actor</em> wants to execute the <em>action</em>.
+    #   @param [Boolean] A boolean indicating if you want to reset the cached result.
+    #   @return [Boolean] A boolean indicating if the <em>actor</em> is authorized to perform the <em>action</em> (or not) on the <em>subject</em>.
     #
     def can?(*args)
       if args.size == 2
@@ -34,17 +47,29 @@ module Walruz
     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:
-    #   Returns a a Hash with parameters given from the policy.
-    #
+    # @overload authorize(action, subject)
+    #   Allows an actor to check if he can do some action on a given
+    #   subject. The main difference between this method and the <tt>can?</tt> method is that
+    #   this will return a Hash of values returned by the policies, in case the <em>actor</em> is 
+    #   not authorized, it will return nil.
+    #   === Note:
+    #   This method will check the authorization the first time, following invocations will return a cached
+    #   result unless the third parameter is specified.
+    # 
+    #   @param [Symbol] The action as it is declared on the <tt>check_authorizations</tt> method on the <em>subject</em> class.
+    #   @param [Walruz::Subject] The <em>subject</em> on which the <em>actor</em> wants to execute the <em>action</em>.
+    #   @return [Hash] Parameters returned from the <em>policy</em>.
+    #
+    # @overload authorize(action, subject, reload)
+    #   Allows an actor to check if he can do some action on a given
+    #   subject. The main difference between this method and the <tt>can?</tt> method is that
+    #   this will return a Hash of values returned by the policies, in case the <em>actor</em> is 
+    #   not authorized, it will return nil.
+    # 
+    #   @param [Symbol] The action as it is declared on the <tt>check_authorizations</tt> method on the <em>subject</em> class.
+    #   @param [Walruz::Subject] The <em>subject</em> on which the <em>actor</em> wants to execute the <em>action</em>.
+    #   @param [Boolean] A boolean indicating if you want to reset the cached result.
+    #   @return [Hash] Parameters returned from the <em>policy</em>.
     def authorize(*args)
       if args.size == 2
         cached_values_for_can[args] ||= can_without_caching(*args)
@@ -62,29 +87,25 @@ module Walruz
       end
     end
     
-    # :nodoc:
     def can_without_caching(label, subject)
       subject.can_be?(label, self)
     end
     
-    # :nodoc:
     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.
+    # subject. This method will behave similarly to the <tt>authorize</tt> method, the only difference is that
+    # instead of returning nil when the _actor_ is not authorized, it will raise a <tt>Walruz::NotAuthorized</tt> exception.
     #
-    # Params: 
-    #   - label: The label of the action
-    #   - subject: The subject which the actor wants to interact with
+    # @param [Symbol] The action as it is declared on the <tt>check_authorizations</tt> method on the <em>subject</em> class.
+    # @param [Walruz::Subject] The <em>subject</em> on which the <em>actor</em> wants to execute the <em>action</em>.
+    # @return [Hash] Parameters returned from the <em>policy</em>.
     #
-    # Returns:
-    #   Returns a a Hash with parameters given from the policy.
+    # @raise [Walruz::NotAuthorized]  error if the <em>actor</em> is not authorized to perform the specified action on the <em>subject</em>.
     #
-    # Raises: 
-    #   Walruz::NotAuthorized error if the actor can't execute the action on the subject
     #    
     def authorize!(label, subject)
       result = subject.can_be?(label, self)
@@ -99,29 +120,36 @@ module Walruz
     end
     
     #
-    # Allows an actor to check if he the given policy applies to him and the given subject.
+    # Allows an <em>actor</em> to check if he satisfies the condition of a <em>policy</em> with a given <em>subject</em>.
     # 
     # Params:
-    #   - policy: label of the Policy the actor wants to check
-    #   - subject: The subject which the actor wants to interact with
+    # @param [Symbol] The label of the <em>policy</em>.
+    # @param [Walruz::Subject] The <em>subject</em>.
+    # @return [Boolean] saying if the <em>actor</em> and the <em>subject</em> satisify the <em>policy</em>.
     #
-    # 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.
+    def satisfies?(policy_label, subject)
+      policy_clz = Walruz.fetch_policy(policy_label)
+      result = policy_clz.return_policy.new.safe_authorized?(self, subject)
+      result[0]
+    end
+    
+    
     #
-    # Returns:
-    #   It returns a boolean indicating that the actor is authorized to 
-    #   access (or not) the subject with the given Policy.
+    # Allows an <em>actor</em> to check if he satisfies the condition of a <em>policy</em> with a given <em>subject</em>.
+    # 
+    # Params:
+    # @param [Symbol] The label of the <em>policy</em>.
+    # @param [Walruz::Subject] The <em>subject</em>.
+    # @return [Hash] Hash with the parameters returned from the <em>policy</em> if the <em>actor</em> and the <em>subject</em> satisfy the <em>policy</em>, nil otherwise.
     #
-    def satisfies?(policy_label, subject, &block)
-      policy_clz = Walruz.policies[policy_label]
-      raise ActionNotFound.new(:policy_label, :label => policy_label) if policy_clz.nil?
+    def satisfies(policy_label, subject)
+      policy_clz = Walruz.fetch_policy(policy_label)
       result = policy_clz.return_policy.new.safe_authorized?(self, subject)
-      if result[0]
-        block.call(result[1]) if block_given?
-      end
-      result[0]
+      result[0] ? result[1] : nil
     end
     
+    
+    protected :can_without_caching, :cached_values_for_can
+    
   end
 end

data/lib/walruz/core_ext/array.rb

@@ -0,0 +1,79 @@
+module Walruz
+  module CoreExt
+    module Array
+  
+      # @overload only_authorized_for(actor, options = {})
+      #   Filters the +Walruz::Subject+ elements inside an array either by a policy or by an action on the _subject_. 
+      #   This will execute the authorization policies using specified _actor_ and action/policy.
+      #   === Notes:
+      #   * If a policy is given, you have to use the policy label.
+      #   * If an action is given, you have to use the name of the action declared on the subject.
+      # 
+      #   @param [Walruz::Actor] actor The _actor_ that is going to be used on the authorization process
+      # 
+      #   @param [Hash] opts for the filtering process.
+      #   @option opts [Symbol] :action The name of the action to be executed on the list of subjects.
+      #   @option opts [Symbol] :policy The label of an specific policy that is going to be used.
+      # 
+      #   @return [Array<Walruz::Subject>] An array with the authorized subjects.
+      # 
+      #   @raise [Walruz::ActionNotFound] if the opts[:action] is not specified on the subject or 
+      #     if the opts[:policy] label identifying the policy is not recognized
+      # 
+      #   @example Filtering a list of Posts by the read action specified on the Post class
+      #     Post.all.only_authorized_for(current_user, :action => :read)
+      #     # this will execute current_user.can?(:read, post) for each element of the array
+      # 
+      #   @example Filtering a list of Posts by a policy
+      #     Post.all.only_authorized_for(nil, :policy => :public_policy)
+      #     # This will execute the Policy with the label ":public_policy" on every post using the given actor
+      #
+      # @overload only_authorized_for(actor, action)
+      #   Filters the +Walruz::Subject+ elements inside an array by the action specified. 
+      #   This will execute the authorization policies using specified actor and action on each _subject_ of the +Array+.
+      #
+      #   @param [Walruz::Actor] actor The _actor_ that is going to be used on the authorization process
+      #
+      #   @param [Symbol] action to be executed by the _actor_ on each _subject_ in the list.
+      #
+      #   @return [Array<Walruz::Subject>] An array with the authorized of _subjects_.
+      #
+      #   @raise [Walruz::ActionNotFound] if the _action_ specified is not declaredon the _subject_.
+      #
+      #   @example Filtering a list of Posts by the read action specified on the Post class
+      #     Post.all.only_authorized_for(current_user, :read)
+      #     # this will execute current_user.can?(:read, post) for each element of the array
+      #
+      def only_authorized_for(actor, opts = {})
+        if opts.respond_to?(:[])
+          only_authorized_with_options(actor, opts)
+        else # use the opts 
+          only_authorized_on_action(actor, opts)
+        end
+      end
+      
+      protected
+      
+      def only_authorized_with_options(actor, opts)
+        raise ArgumentError.new("You have to specify either the :action or :policy option") if opts[:action] && opts[:policy]
+        if opts[:action]
+          self.select do |subject|
+            actor.can?(opts[:action], subject)
+          end
+        elsif opts[:policy]
+          policy_clz = Walruz.fetch_policy(opts[:policy])
+          self.select(&policy_clz.with_actor(actor))
+        else
+          raise ArgumentError.new("The option hash requires either :action or :policy option")
+        end
+      end
+      
+      def only_authorized_on_action(actor, action)
+        self.select do |subject|
+          actor.can?(action, subject)
+        end
+      end
+      
+    end
+  end
+end