trust 0.6.3 → 0.7.0

data/README.md

@@ -141,8 +141,32 @@ can? :edit, @account, @client       # is current user allowed to edit the accoun
 #### On ActiveRecord objects you will use permits?
 
 ``` Ruby
-@customer.permits? :edit            # does the current user have permission to edit the given customer?
-Customer.permits? :create, @client  # does the current user have permission to create customers?
+@customer.permits? :edit                             # does the current user have permission to edit the given customer?
+Customer.permits? :create, @client                   # does the current user have permission to create customers for client?
+Customer.permits? :create, @client, :by => @auditor  # does the auditor have permission to create customers?
+Customer.permits? :create, :for => @client, :by => @auditor  # same as above
+```
+
+#### You can also designate actors in your model so you can test if other people has access to do operations on a subject
+
+Include the Actor role in the class
+``` Ruby
+class Auditor
+  include Trust::Actor
+  ...
+end
+```
+
+Now you can test if the auditor has permission to modify customer for client. Three ways of writing it
+``` Ruby
+  @auditor.can? :update, @customer, @client
+  @auditor.can? :update, @customer, :for => @client
+  @auditor.can? :update, @customer, :parent => @client
+```
+
+The above is the same as
+``` Ruby
+@customer.permits? :update, @client, :by => @auditor 
 ```
 
 ## Instance variables

data/lib/trust/active_model.rb

@@ -0,0 +1,76 @@
+# Copyright (c) 2012 Bingo Entreprenøren AS
+# Copyright (c) 2012 Teknobingo Scandinavia AS
+# Copyright (c) 2012 Knut I. Stenmark
+# Copyright (c) 2012 Patrick Hanevold
+#
+# 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.
+
+module Trust
+  # = Trust::ActiveModel extension
+  #
+  # Extends ActiveRecord with the +permits?+ and +ensure_permitted!+ method on class and instances
+  # If using Mongoid same features are included there
+  #
+  # Options:
+  #
+  # * +:parent+ - Specifies that the persmision should be tested in the context of a parent 
+  # * +:by+ - Specifies an actor to be used instead of the currently logged in user
+  #
+  # ==== Examples
+  #
+  #    # If current user is permitted to create customers, create it
+  #    if Customer.permits? :create
+  #      Customer.create attributes
+  #    end
+  #    
+  #    # If current user is permitted to create accounts for the given customer, create it
+  #    if Account.permits? :create, @customer
+  #      Account.create attributes
+  #    end
+  #    
+  #    # If the specified actor is permitted to create accounts for the given customer, create it
+  #    if Account.permits? :create, @customer, :by => @actor
+  #      Account.create attributes
+  #    end
+  #    
+  #    # Raise an exception if user is not permitted to update the given customer, else save it
+  #    @customer.ensure_permitted! :update
+  #    @customer.save
+  #    
+  #    # Raise an exception if the specified user is not permitted to update the given customer, else save it
+  #    @customer.ensure_permitted! :update, :by => @actor
+  #    @customer.save
+  module ActiveModel
+    extend ActiveSupport::Concern
+
+    included do
+      include ClassMethods
+    end
+    
+    module ClassMethods
+      def permits?(action, *args)
+        Trust::Authorization.authorized?(action, self, *args)
+      end
+      def ensure_permitted!(action, *args)
+        Trust::Authorization.authorize!(action, self, *args)
+      end
+    end
+  end
+end

data/lib/trust/{active_record.rb → actor.rb}

@@ -23,43 +23,33 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 module Trust
-  module ActiveRecord
+  # = Trust::Actor extension
+  #
+  # Include this module if you want to check if an actor can act upon a specific subject
+  #
+  # ==== Examples
+  #
+  #    # If the @actor can create customers, create it
+  #    if @actor.can? :create, Customer
+  #      Customer.create attributes
+  #    end
+  #    
+  #    # If @actor can create accounts for the given customer, create it
+  #    if @actor.can? :create, Account, @customer
+  #      Account.create attributes
+  #    end
+  #    # It is also possible to make code more descripting for the same as above
+  #    if @actor.can? :create, Account, :parent => @customer     # or, ...
+  #    if @actor.can? :create, Account, :for => @customer
+  #    
+  module Actor
     extend ActiveSupport::Concern
-# = Trust::ActiveRecord extension
-# Extends ActiveRecord with the +permits?+ and +ensure_permitted!+ method on class and instances
-#
-# ==== Examples
-#
-#    # If current user is permitted to create customers, create it
-#    if Customer.permits? :create
-#      Customer.create attributes
-#    end
-#    
-#    # If current user is permitted to create accounts for the given customer, create it
-#    if Account.permits? :create, @customer
-#      Account.create attributes
-#    end
-#    
-#    # If current user is permitted to update the given customer, update it
-#    if @customer.permits? :update
-#      @customer.save
-#    end
-#    
-#    # Raise an exception if user is not permitted to update the given customer, else save it
-#    @customer.ensure_permitted! :update 
-#    @customer.save
 
-    included do
-      include ClassMethods
-    end
-    
-    module ClassMethods
-      def permits?(action, parent = nil)
-        Trust::Authorization.authorized?(action, self, parent)
-      end
-      def ensure_permitted!(action, parent = nil)
-        Trust::Authorization.authorize!(action, self, parent)
-      end
+    def can?(action, subject, *args)
+      options = args.extract_options!
+      options[:parent] ||= args.first || options.delete(:for)
+      options[:by] = self
+      Trust::Authorization.authorized?(action, subject, options)
     end
   end
 end

data/lib/trust/authorization.rb

@@ -23,13 +23,26 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 module Trust
+  # = Trust Authorization
   class Authorization
     class << self
-      # Returns true if user is authorized to perform +action+ on +object+ or +class+
-      # If +parent+ is given, +parent+ may be tested in the implemented Permissions class
+      
+      # Returns true if user is authorized to perform +action+ on +object+ or +class+.
+      #
+      # Options:
+      # 
+      # * +:parent+ - the parent class to associate the subject with, can also be specified after the object
+      #   or class. If +parent+ is given, +parent+ may be tested in the implemented Permissions class.
+      #   +:parent+ is also aliased to +:for+.
+      #
+      # * +:by+ - Spoecify an actor instead of the user currently logged in 
+      # 
       # This method is called by the +can?+ method in Trust::Controller, and is normally 
       # not necessary to call directly.
-      def authorized?(action, object_or_class, parent)
+      def authorized?(action, object_or_class, *args)
+        options = args.extract_options!
+        parent = options[:parent] || options[:for] || args.first
+        actor = options[:by] || user
         if object_or_class.is_a? Class
           klass = object_or_class
           object = nil
@@ -40,35 +53,47 @@ module Trust
         # Identify which class to instanciate and then check authorization
         auth = authorizing_class(klass)
         # Rails.logger.debug "Trust: Authorizing class for #{klass.name} is #{auth.name}"
-        auth.new(user, action.to_sym, klass, object, parent).authorized?
+        auth.new(actor, action.to_sym, klass, object, parent).authorized?
       end
       
       # Tests if user is authorized to perform +action+ on +object+ or +class+, with the 
       # optional parent and raises Trust::AccessDenied exception if not permitted.
-      # If using this method directly, an optional +message+ can be passed in to 
-      # replace the default message used.
+      #
+      # Options:
+      #
+      # * +:parent+ - the parent class to associate the subject with, can also be specified after the object
+      #   or class. If +parent+ is given, +parent+ may be tested in the implemented Permissions class.
+      #   +:parent+ is also aliased to +:for+.
+      #
+      # * +:by+ - Spoecify an actor instead of the user currently logged in 
+      # 
+      # * +:message+ - The message to be passed onto the AccessDenied exception class      
+      #
       # This method is used by the +access_control+ method in Trust::Controller
-      def authorize!(action, object_or_class, parent, message = nil)
-        access_denied!(message, action, object_or_class, parent) unless authorized?(action, object_or_class, parent)
+      def authorize!(action, object_or_class, *args)
+        options = args.extract_options!
+        parent = options[:parent] || options[:for] || args.first
+        message = options[:message]
+        access_denied!(message, action, object_or_class, parent) unless authorized?(action, object_or_class, parent, options)
       end
       
-      def access_denied!(message = nil, action = nil, subject = nil, parent = nil) # nodoc
+      def access_denied!(message = nil, action = nil, subject = nil, parent = nil) #:nodoc:
         raise AccessDenied.new(message, action, subject)
       end
       
-      # returns the current +user+ being used in the authorization process
+      # Returns the current +user+ being used in the authorization process
       def user
         Thread.current["current_user"] 
       end
       
-      # sets the current +user+ to be used in the authorization process.
-      # the +user+ is thread safe.
+      # Sets the current +user+ to be used in the authorization process.
+      # The +user+ is thread safe.
       def user=(user)
         Thread.current["current_user"] = user
       end
       
     private
-      def authorizing_class(klass) # nodoc
+      def authorizing_class(klass) #:nodoc:
         auth = nil
         klass.ancestors.each do |k|
           break if k == ::ActiveRecord::Base

data/lib/trust/controller/properties.rb

@@ -24,6 +24,7 @@
 
 module Trust
   module Controller
+    # = Trust Coontroller Properties
     class Properties
       delegate :logger, :to => Rails
       attr_reader :controller
@@ -33,7 +34,7 @@ module Trust
       attr_accessor :member_actions
       attr_accessor :collection_actions
       
-      def initialize(controller, properties) # nodoc
+      def initialize(controller, properties) #:nodoc:
         @controller = controller
         @model = controller.controller_path
         if properties
@@ -50,16 +51,18 @@ module Trust
       end
 
       class << self
-        # returns a controller properties object
-        # ensures controller properties are instantiated in a correct manner and that inheritance is supported
+        # Returns a controller properties object.
+        #
+        # Ensures controller properties are instantiated in a correct manner and that inheritance is supported
         def instantiate(controller)
           new(controller, controller.superclass.instance_variable_get(:@properties))
         end
       end
 
-      # returns or sets the model to be used in a controller
-      # If not set, the controller_path is used
-      # You can override the model to be accessed in a controller by setting the model
+      # Returns or sets the model to be used in a controller
+      #
+      # If not set, the controller_path is used.
+      # You can override the model to be accessed in a controller by setting the model.
       # Note that you should specify the model in plural form.
       #
       # ==== Example
@@ -81,10 +84,12 @@ module Trust
       end
       
       # Specify associated resources (nested resources)
-      # Example:
-      #   belongs_to :lottery
-      #   belongs_to :table, :card_game
-      #   belongs_to :card_game, :as => :bridge
+      #
+      # === Example
+      #
+      #   +belongs_to+ :lottery
+      #   +belongs_to+ :table, :card_game
+      #   +belongs_to+ :card_game, :as => :bridge
       #
       def belongs_to(*resources)
         raise ArgumentError, "You must specify at least one resource after belongs_to" unless resources
@@ -99,8 +104,10 @@ module Trust
         @associations.size > 0
       end
       
-      # actions(options)
-      # Options
+      # Specify actions to handle
+      #
+      # === Options
+      #
       #  :new => actions        # specify new actions - default id :new, :create
       #  :member => actions     # specify member actions - default is :show, :edit, :update, :destroy
       #  :collection => actions # specify collection actions - default is :index

data/lib/trust/controller/resource.rb

@@ -61,7 +61,8 @@ module Trust
       end
       
       # Sets the instance variable
-      # Normally set by +load+
+      #
+      # Normally set by +load+.
       # You can access this method from the resource object.
       #
       # ==== Example
@@ -97,12 +98,14 @@ module Trust
       end
 
       # Sets the instance variable for collection
+      #
       # You may want to set this variable in your index action, we do not yet support loading of collections
       def instances=(instances)
         @controller.instance_variable_set(:"@#{plural_instance_name}", instances)
       end
 
       # Returns either the instances or the instance. 
+      #
       # We have found that this can be useful in some implementation patterns
       def instantiated
         instances || instance
@@ -113,8 +116,10 @@ module Trust
         info.klass
       end
 
-      # Loads the resource 
+      # Loads the resource
+      #
       # See Trust::Controller::Properties which controls the behavior of this method.
+      #
       # It will normally find the instance variable for existing object or initialize them as new.
       # If using nested resources and +belongs_to+ has been declared in the controller it will use the 
       # parent relation if found.
@@ -134,6 +139,7 @@ module Trust
       end
       
       # Returns the name of the instance for the resource
+      #
       # ==== Example
       #
       #     # in AccountsController
@@ -143,6 +149,7 @@ module Trust
       end
       
       # Returns the plural name of the instance for the resource
+      #
       # ==== Example
       #
       #     # in AccountsController
@@ -152,6 +159,7 @@ module Trust
       end
       
       # Returns the name of the parent resource
+      #
       # ==== Example
       #
       #     # in AccountsController where belongs_to :customer has been declared
@@ -171,31 +179,35 @@ module Trust
       end      
     end
 
-    # ResorceInfo resolves information about the resource accessed in action controller
+    # = ResorceInfo 
+    #
+    # resolves information about the resource accessed in action controller
     #
-    # Examples in PeopleController (simple case)
-    # ===
+    # === Examples in PeopleController (simple case)
+    # 
     #   resource.info.klass => Person
     #   resource.info.params => {:person => {...}}       # fetches the parameters for the resource
     #   resource.info.name => :person
     #   resource.info.plural_name => :people
     #   resource.info.path => 'people'                   # this is the controller_path
     #
-    # Examples in Lottery::AssignmentsController (with name space)
-    # ===
+    # === Examples in Lottery::AssignmentsController (with name space)
+    # 
     #   resource.info.klass => Lottery::Assignment
     #   resource.info.params => {:lottery_assignment => {...}}
     #   resource.info.name => :lottery_assignment
     #   resource.info.plural_name => :lottery_assignments
     #   resource.info.path => 'lottery/assignments'      # this is the controller_path
     #
-    # Examples in ArchiveController (with inheritance) 
+    # === Examples in ArchiveController (with inheritance) 
     # Assumptions on routes:
+    #
     #   resources :archives
     #   resources :secret_acrvives, :controller => :archives
     #   resources :public_acrvives, :controller => :archives
-    # examples below assumes that the route secret_arcives is being accessed at the moment
-    # ===
+    #
+    # === Examples below assumes that the route secret_arcives is being accessed at the moment
+    # 
     #   resource.info.klass => Archive
     #   resource.info.params => {:secret_archive => {...}}
     #   resource.info.name => :archive
@@ -203,27 +215,29 @@ module Trust
     #   resource.info.path => 'archive'                   # this is the controller_path
     #   resource.info.real_class => SecretArchive         # Returns the real class which is accessed at the moment
     #
-    
     class Resource::Info
       attr_reader :klass, :params, :name, :path, :real_class
       
-      def params
+      def params #:nodoc:
         @data
       end
    
     protected
-      def self.var_name(klass)
+      def self.var_name(klass)  #:nodoc:
         klass.to_s.underscore.tr('/','_').to_sym
       end
-      def var_name(klass)
+      def var_name(klass)  #:nodoc:
         self.class.var_name(klass)
       end
     end
     
-
+    # = Resource::ResorceInfo 
+    # 
+    # Resolves the resource in subject
+    # (see #ResourceInfo)
     class Resource::ResourceInfo < Resource::Info
 
-      def initialize(model, params)
+      def initialize(model, params)  #:nodoc:
         @path, params = model, params
         @klass = model.to_s.classify.constantize
         @name = model.to_s.singularize.underscore.gsub('/','_').to_sym
@@ -234,13 +248,15 @@ module Trust
         @data = params[var_name(ptr)]
       end
 
+      # Returns the plural name of the resource
       def plural_name
         @plural_name ||= path.underscore.tr('/','_').to_sym
       end
 
-      # returns an accessor for association. Tries with full name association first, and if that does not match, tries the demodularized association.
+      # Returns an accessor for association. Tries with full name association first, and if that does not match, tries the demodularized association.
+      #
+      # === Explanation
       #
-      # Explanation:
       #   Assuming 
       #     resource is instance of Lottery::Package #1 (@lottery_package)
       #     association is Lottery::Prizes
@@ -258,6 +274,10 @@ module Trust
       end
     end
 
+    # = Resource::ParentInfo 
+    # 
+    # Resolves the parent resource in subject
+    # (see #ResourceInfo)
     class Resource::ParentInfo < Resource::Info
       attr_reader :object,:as
       def initialize(resources, params, request)

data/lib/trust/controller.rb

@@ -23,6 +23,7 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 module Trust
+  # = Trust Controller
   module Controller
     autoload :Resource,           'trust/controller/resource'
     autoload :Properties,         'trust/controller/properties'
@@ -49,6 +50,7 @@ module Trust
       delegate :belongs_to, :actions, :model, :to => :properties
 
       # Enables authorization in controller
+      #
       # +trustee+ accepts +:off+ or a hash of +callback+ options such as +:except+ and +:only+
       #
       # +trustee+ automatically calls the class methods: +set_user+, +load_resource+ and +access_control+
@@ -82,8 +84,6 @@ module Trust
       #       redirect_to root_url, :alert => exception.message
       #     end
       #   end
-      
-
       def trustee(*args)
         module_eval do
           include TrustInstanceMethods
@@ -95,15 +95,20 @@ module Trust
       end
       
       # Enable or disable +before_filter+ callback for setting the current user
-      # Arguments:
+      #
+      # === Arguments:
+      #
       #  :off - switch callback off
       #  :only - only include these actions
       #  :except - except these actions
       def set_user(*args)
         _filter_setting(:set_user, *args)
       end
+      
       # Enable or disable +before_filter+ callback for setting the loading resource
-      # Arguments:
+      #
+      # === Arguments:
+      #
       #  :off - switch callback off
       #  :only - only include these actions
       #  :except - except these actions
@@ -112,7 +117,9 @@ module Trust
       end
       # Enable or disable +before_filter+ callback for setting the access control, i.e. verifying permissions
       # for the logged in user
-      # Arguments:
+      #
+      # === Arguments:
+      #
       #  :off - switch callback off
       #  :only - only include these actions
       #  :except - except these actions
@@ -132,7 +139,7 @@ module Trust
     
     module TrustInstanceMethods
       # Returns the controller Trust::Controller::Properties.
-      # If no properties are instantiated, it will be instantiated
+      # If no properties are instantiated, it will be instantiated.
       # 
       # == Delegated methods
       #
@@ -146,8 +153,9 @@ module Trust
         self.class.properties
       end
       
-      # Sets the current user. It assumes +current_user+ is defined
-      # This method is triggered as a callback on +before_filter+
+      # Sets the current user. It assumes +current_user+ is defined.
+      #
+      # This method is triggered as a callback on +before_filter+.
       # You may override this method.
       #
       # ==== Example
@@ -160,28 +168,32 @@ module Trust
       end
 
       # Returns the Trust::Controller::Resource resource for the controller.
-      # Available as a helper in views
-      # See Trust::Controller::Resource for relevant methods
+      #
+      # Available as a helper in views.
+      # See {Trust::Controller::Resource} for relevant methods.
       def resource
         @resource ||= Trust::Controller::Resource.new(self, self.class.properties, action_name, params, request)
       end
       
       # Loads the resource which basically means loading the instance and eventual parent defined through +belongs_to+
+      #
       # This method is triggered as a callback on +before_filter+
-      # See Trust::Controller::Resource for more information
+      # See {Trust::Controller::Resource} for more information
       def load_resource
         resource.load
       end
       
-      # Performs the actual access_control
+      # Performs the actual access_control.
+      #
       # This method is triggered as a callback on +before_filter+
       def access_control
         Trust::Authorization.authorize!(action_name, resource.instance || resource.klass, resource.parent)
       end
 
-      # Tests for current users permissions
+      # Tests for current users permissions.
+      #
       # If access control is not sufficient in controller, you may use this method.
-      # Also available as a helper in views
+      # Also available as a helper in views.
       #
       # ==== Examples
       #   can? :edit                          # does the current user have permission to edit the current resource? 

data/lib/trust/inheritable_attribute.rb

@@ -23,9 +23,10 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 module Trust
+  # = Trust InheritableAttribute
   module InheritableAttribute
 
-    def self.deep_copy value
+    def self.deep_copy( value) #:nodoc:
       if value.is_a? Hash
         Hash[*value.map{ |k,v| [self.deep_copy(k),self.deep_copy(v)] }.flatten(1)]
       elsif value.is_a? Array
@@ -40,11 +41,12 @@ module Trust
     extend ActiveSupport::Concern
 
     module ClassMethods
-      # Creates an inheritable attribute with accessors in the singleton class. Derived classes inherit the
-      # attributes. This is especially helpful with arrays or hashes that are extended in the inheritance
-      # chain. Note that you have to initialize the inheritable attribute.
+      # Creates an inheritable attribute with accessors in the singleton class. 
+      # 
+      # Derived classes inherit the attributes. This is especially helpful with arrays or hashes that 
+      # are extended in the inheritance chain. Note that you have to initialize the inheritable attribute.
       #
-      # Example:
+      # === Example
       #
       #   class Cat
       #     inheritable_attr :drinks