trust 0.7.0 → 0.8.0

data/README.md

@@ -23,15 +23,15 @@ Well, we used [DeclarativeAuthorization](http://github.com/stffn/declarative_aut
 
 * Loading datasets for the index action. You may use other plugins / gems for doing this, or you may implement your own mechanism.
 
-### Currently not supported, but may be in the future
-
-* cannot and cannot? expressions.
-
 # Install and Setup
 
 Install the gem
 
     gem install trust
+    
+Or, in your Gemfile
+
+    gem 'trust'
 
 ### Define permissions
 
@@ -150,6 +150,7 @@ 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
@@ -158,6 +159,7 @@ 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
@@ -165,6 +167,7 @@ Now you can test if the auditor has permission to modify customer for client. Th
 ```
 
 The above is the same as
+
 ``` Ruby
 @customer.permits? :update, @client, :by => @auditor 
 ```
@@ -229,6 +232,7 @@ end
 ```
 
 #### Alternatives
+
 ``` Ruby
 class MyController < ApplicationController
   set_user :off         # turns off set_user callback
@@ -238,6 +242,7 @@ end
 ```
 
 #### More specifically
+
 For all call backs and ```trustee``` you can use ```:only``` and ```:except``` options.
 Example toggle create action off
 ``` Ruby
@@ -248,6 +253,7 @@ end
 ```
 
 #### Yet another alternative, avoiding resource loading
+
 Avoid resource loading on ```show``` action
 ``` Ruby
 class MyController < ApplicationController

data/lib/trust/actor.rb

@@ -25,7 +25,13 @@
 module Trust
   # = Trust::Actor extension
   #
-  # Include this module if you want to check if an actor can act upon a specific subject
+  # Include this module if you want to check if an actor can act upon a specific subject.
+  # E.g. if your class is Actor, then include like this:
+  #
+  #    class Actor < ActiveRecord::Base
+  #      include Trust::Actor
+  #      ...
+  #    end
   #
   # ==== Examples
   #

data/lib/trust/controller/resource.rb

@@ -24,21 +24,22 @@
 
 module Trust
   module Controller
+    # = Trust::Controller::Resource 
+    #
+    # Collects information about the current resource and relations. 
+    # Handles the loading of the resource and its possible parent, i.e. setting the relevant instance variables
+    # It assumes the name of the resource is built on the controllers name, but this can be overridden in your
+    # controller by setting the +model+
+    #
+    # Examples:
+    #
+    #    # controller name AccountsController
+    #    resource.instance # => @account
+    #
+    #    # controller name Customer::AccountsController
+    #    resource.instance # => @customer_account
+    #
     class Resource
-# = Trust::Controller::Resource 
-# Collects information about the current resource and relations. 
-# Handles the loading of the resource and its possible parent, i.e. setting the relevant instance variables
-# It assumes the name of the resource is built on the controllers name, but this can be overridden in your
-# controller by setting the +model+
-#
-# Examples:
-#
-#    # controller name AccountsController
-#    resource.instance # => @account
-#
-#    # controller name Customer::AccountsController
-#    resource.instance # => @customer_account
-#
       
       delegate :logger, :to => Rails
       attr_reader :properties, :params, :action
@@ -116,6 +117,14 @@ module Trust
         info.klass
       end
 
+      # Returns a collection that can be used for index, new and creation actions
+      #
+      # See Trust::Controller::ResourceInfo.collection which controls the behavior of this method.
+      def collection(instance = nil)
+        @info.collection(@parent_info, instance)
+      end
+      
+      
       # Loads the resource
       #
       # See Trust::Controller::Properties which controls the behavior of this method.
@@ -168,7 +177,10 @@ module Trust
         parent_info && parent_info.name
       end
       
-      
+      # Returns the association name with the parent
+      def association_name
+        parent_info && info.association_name(parent_info)
+      end
     private
       def extract_resource_info(model, params) # nodoc
         ResourceInfo.new(model, params)
@@ -234,7 +246,7 @@ module Trust
     # = Resource::ResorceInfo 
     # 
     # Resolves the resource in subject
-    # (see #ResourceInfo)
+    # (see #Resource::Info)
     class Resource::ResourceInfo < Resource::Info
 
       def initialize(model, params)  #:nodoc:
@@ -265,19 +277,43 @@ module Trust
       #   
       def relation(associated_resource)
         if associated_resource && associated_resource.object
-          name = associated_resource.as || plural_name
-          associated_resource.object.class.reflect_on_association(name) ? 
-            associated_resource.object.send(name) : associated_resource.object.send(klass.to_s.demodulize.underscore.pluralize)
+          associated_resource.object.send(association_name(associated_resource))
         else
           klass
         end
       end
+      
+      # Returns a collection that can be used for index, new and creation actions.
+      #
+      # If specifying an instance, returns the full path for that instance. Can be used when not using shallow routes
+      #
+      # === Example
+      #
+      #   Assumption
+      #     resource is instance of Lottery::Package #1 (@lottery_package)
+      #     association is Lottery::Prizes
+      #     if association is named lottery_prizes, then [@lottery_package, :lottery_prizes] is returned
+      #     if association is named prizes, then [@lottery_package, :prizes] is returned
+      #     if you specify an instance, then [@lottery_package, @prize] is returned
+      #
+      def collection(associated_resource, instance = nil)
+        if associated_resource && associated_resource.object
+          [associated_resource.object, instance || association_name(associated_resource)]
+        else
+          klass
+        end
+      end
+      
+      def association_name(associated_resource) # :nodoc
+        name = associated_resource.as || plural_name
+        associated_resource.object.class.reflect_on_association(name) ? name : klass.to_s.demodulize.underscore.pluralize        
+      end
     end
 
     # = Resource::ParentInfo 
     # 
     # Resolves the parent resource in subject
-    # (see #ResourceInfo)
+    # (see #Resource::ResourceInfo)
     class Resource::ParentInfo < Resource::Info
       attr_reader :object,:as
       def initialize(resources, params, request)

data/lib/trust/controller.rb

@@ -38,9 +38,9 @@ module Trust
       # == Delegated methods
       #
       # The following methods are delegated to properties. See Trust::Controller::Properties for details
-      # * <tt>belongs_to</tt> - define one or more associations to parents
-      # * <tt>actions</tt> - acion definitions outside the restful actions
-      # * <tt>model</tt> - Redefine the model used in the controller (if it's name does not match the 
+      # * +belongs_to+ - define one or more associations to parents
+      # * +actions+ - acion definitions outside the restful actions
+      # * +model+ - Redefine the model used in the controller (if it's name does not match the 
       #   controller_path)
       #
       def properties
@@ -98,9 +98,9 @@ module Trust
       #
       # === Arguments:
       #
-      #  :off - switch callback off
-      #  :only - only include these actions
-      #  :except - except these actions
+      #  +:off+ - switch callback off
+      #  +:only+ - only include these actions
+      #  +:except+ - except these actions
       def set_user(*args)
         _filter_setting(:set_user, *args)
       end
@@ -109,9 +109,9 @@ module Trust
       #
       # === Arguments:
       #
-      #  :off - switch callback off
-      #  :only - only include these actions
-      #  :except - except these actions
+      #  +:off+ - switch callback off
+      #  +:only+ - only include these actions
+      #  +:except+ - except these actions
       def load_resource(*args)
         _filter_setting(:load_resource, *args)
       end
@@ -120,9 +120,9 @@ module Trust
       #
       # === Arguments:
       #
-      #  :off - switch callback off
-      #  :only - only include these actions
-      #  :except - except these actions
+      #  +:off+ - switch callback off
+      #  +:only+ - only include these actions
+      #  +:except+ - except these actions
       def access_control(*args)
         _filter_setting(:access_control, *args)
       end
@@ -144,9 +144,9 @@ module Trust
       # == Delegated methods
       #
       # The following methods are delegated to properties. See Trust::Controller::Properties for details
-      # * <tt>belongs_to</tt> - define one or more associations to parents
-      # * <tt>actions</tt> - acion definitions outside the restful actions
-      # * <tt>model</tt> - Redefine the model used in the controller (if it's name does not match the 
+      # * +belongs_to+ - define one or more associations to parents
+      # * +actions+ - acion definitions outside the restful actions
+      # * +model+ - Redefine the model used in the controller (if it's name does not match the 
       #   controller_path)
       #
       def properties
@@ -196,11 +196,11 @@ module Trust
       # Also available as a helper in views.
       #
       # ==== Examples
-      #   can? :edit                          # does the current user have permission to edit the current resource? 
-      #                                       # If there is a nested resource, the parent is automatically associated
-      #   can? :edit, @customer               # does the current user have permission to edit the given customer? 
-      #                                       # Parent is also passed on here.
-      #   can? :edit, @account, @client       # is current user allowed to edit the account associated with the client?
+      #   +can? :edit+                          # does the current user have permission to edit the current resource? 
+      #                                         # If there is a nested resource, the parent is automatically associated
+      #   +can? :edit, @customer+               # does the current user have permission to edit the given customer? 
+      #                                         # Parent is also passed on here.
+      #   +can? :edit, @account, @client+       # is current user allowed to edit the account associated with the client?
       def can?(action_name, subject = resource.instance || resource.relation.new, parent = resource.parent)
         Trust::Authorization.authorized?(action_name, subject, parent)
       end

data/lib/trust/permissions.rb

@@ -34,8 +34,8 @@ module Trust
   #     ...
   #   end
   #
-  # The above is the minimum required definitions that must exist in you file. <tt>Default</tt> will be used if no classes
-  # match the permissions requested, so the <tt>Default</tt> class definition is mandatory.
+  # The above is the minimum required definitions that must exist in you file. +Default+ will be used if no classes
+  # match the permissions requested, so the +Default+ class definition is mandatory.
   #
   # If you want to separate the permissions into separate files that is ok. Then you shoud place these files in the 
   # /app/model/permissions directory.
@@ -44,10 +44,10 @@ module Trust
   #
   # The basic rules is to define classes in the Permissions module that matches your models.
   # Here are some examples:
-  # * <tt>Project</tt> should have a matching class <tt>Permissions::Project</tt>
-  # * <tt>Account</tt> should have a matching class <tt>Permissions::Account</tt>
-  # * <tt>Account:Credit</tt> may have a matching class <tt>Permissions::Account::Credit</tt>, but if its inheriting from
-  #   <tt>Account</tt> and no special handling is necessary, it is not necessary to create the permissions class.
+  # * +Project+ should have a matching class +Permissions::Project+
+  # * +Account+ should have a matching class +Permissions::Account+
+  # * +Account:Credit+ may have a matching class +Permissions::Account::Credit+, but if its inheriting from
+  #   +Account+ and no special handling is necessary, it is not necessary to create the permissions class.
   #
   # == Using inheritance
   #
@@ -66,26 +66,26 @@ module Trust
   #
   # == Action aliases
   #
-  # You can define aliases for actions. You do this by setting the <tt>action_aliases</tt> attribute on Trust::Permissions class
+  # You can define aliases for actions. You do this by setting the +action_aliases+ attribute on Trust::Permissions class
   # Example:
   #   Trust::Permissions.action_aliases = {
   #      read: [:index, :show],
   #      create: [:create, :new]
   #      }
   #
-  # Keep in mind that all permissions are expanded upon declaration, so when using the <tt>can?</tt> method you must refer to 
+  # Keep in mind that all permissions are expanded upon declaration, so when using the +can?+ method you must refer to
   # the actual action and not the alias. The alias will never give a positive permission.
   #
   # == Accessors
   #
   # Accessors that can be used when testing permissions:
-  # * <tt>user</tt> - the user currently logged in
-  # * <tt>action</tt> - the action request from the controller such as :edit, or the action tested from helper or 
-  #   from the object itself when using <tt>ActiveRecord::can?</tt> is being used.
-  # * <tt>subject</tt> - the object that is being tested for permissions. This may be a an existing object, a new object
+  # * +user+ - the user currently logged in
+  # * +action+ - the action request from the controller such as :edit, or the action tested from helper or
+  #   from the object itself when using +ActiveRecord::can?+ is being used.
+  # * +subject+ - the object that is being tested for permissions. This may be a an existing object, a new object
   #   (such as for +:create+ and +:new+ action), or nil if no object has been instantiated.
-  # * <tt>parent</tt> - the parent object if in a nested route, specified by +belongs_to+ in the controller.
-  # * <tt>klass</tt> - the class of involed in the request. It can be a base class or the real class, depending on
+  # * +parent+ - the parent object if in a nested route, specified by +belongs_to+ in the controller.
+  # * +klass+ - the class of involed in the request. It can be a base class or the real class, depending on
   #   your controller design.
   #
   # == Defining your own accessors or instance methods
@@ -128,11 +128,11 @@ module Trust
     #
     # == Parameters:
     #
-    #   <tt>user</tt> - user object, must respond to role_symbols
-    #   <tt>action</tt> - action, such as :create, :show, etc. Should not be an alias
-    #   <tt>klass</tt> - the class of the subject. 
-    #   <tt>subject</tt> - the subject tested for authorization
-    #   <tt>parent</tt> - the parent object, normally declared through belongs_to
+    #   +user+ - user object, must respond to role_symbols
+    #   +action+ - action, such as :create, :show, etc. Should not be an alias
+    #   +klass+ - the class of the subject.
+    #   +subject+ - the subject tested for authorization
+    #   +parent+ - the parent object, normally declared through belongs_to
     #
     # See {Trust::Authorization} for more details
     #
@@ -181,7 +181,7 @@ module Trust
     class << self
       # Assign permissions to one or more roles.
       #
-      # You may call role or roles, they are the same function like <tt>role :admin</tt> or <tt>roles :admin, :accountant</tt>
+      # You may call role or roles, they are the same function like +role :admin+ or +roles :admin, :accountant+
       #
       # There are two ways to call role, with or without block. If you want to set multiple permissions with different conditons
       # then you should use a block.
@@ -211,23 +211,32 @@ module Trust
             @@can_expressions = 0
             raise RoleAssigmnentMissing 
           end
-          @perms = []
+          @perms = {:can => [], :cannot => []}
           @in_role_block = true
           yield
           @in_role_block = false
-          perms = @perms          
+          perms = @perms
         else
           if @@can_expressions > 1
             @@can_expressions = 0
             raise RoleAssigmnentMissing 
           end
-          options = roles.extract_options!
-          raise ArgumentError, "Must have a block or a can expression" unless perms = options[:can]
+          perms = roles.extract_options!
+          unless perms.size >= 1 && (perms[:can] || perms[:cannot])
+            raise ArgumentError, "Must have a block or a can or a cannot expression: #{perms.inspect}"
+          end
           @@can_expressions = 0
         end
         roles.flatten.each do |role|
           self.permissions[role] ||= []
-          self.permissions[role] += perms
+          if perms[:cannot] && perms[:cannot].size > 0
+            perms[:cannot].each do |p|
+              self.permissions[role].delete_if { |perm| perm[0] == p  }
+            end
+          end
+          if perms[:can] && perms[:can].size > 0
+            self.permissions[role] += perms[:can]
+          end
         end
       end
       alias :roles :role
@@ -237,7 +246,12 @@ module Trust
       # === Arguments
       #
       #   action - can be an alias or an actions of some kind
-      #   options - :if/:unless :symbol or proc that will be called to evaluate an expression
+      #   options - control the behavior of the permission
+      #
+      # === Options
+      #   +:if/:unless+ - :symbol or proc that will be called to evaluate an expression
+      #   +enforce+ - set to true to enforce the permission, delete any previous grants given from parent classes. Most meaningful in
+      #               combination with +:if+ and +:unless+ options
       #
       # === Example
       #
@@ -254,12 +268,65 @@ module Trust
       # In the example above a method is used to test data on the actual record when testing for permissions.
       def can(*args)
         options = args.extract_options!
+        enforce = options.delete(:enforce)
         p = expand_aliases(args).collect { |action| [action, options] }
         if @in_role_block
-          @perms += p
+          @perms[:can] += p
+          if enforce
+            @perms[:cannot] = expand_aliases(args).collect { |action| action }
+          end
+        else
+          @@can_expressions += 1
+          perms = {:can => p }
+          if enforce
+            perms[:cannot] = expand_aliases(args).collect { |action| action }
+          end
+          return perms
+        end
+      end
+      
+      # Revokes permissions.
+      #
+      # Revokes any previous permissions given in parent classes. This cannot be used with conditions. See also +:enforce+ option
+      # for +can+
+      #
+      # +can+ has presedence over +cannot+. In practice this means that in a block; +cannot+ statements are processed before +can+,
+      # and any previously permissions granted are deleted. 
+      # Another way to say this is; if you have +cannot :destroy+ and +can :destroy+, then all inheritied destroys will first be
+      # deleted, and then the can destroy will be granted.
+      #
+      #
+      # === Arguments
+      # 
+      #   action - actions to be revoked permissions for. Cannot be aliases
+      #
+      # === Example
+      #
+      #   module Permissions
+      #     class Account < Trust::Permissions
+      #       role :admin, :accountant do 
+      #         can :read
+      #         can :read
+      #         can :update, :destroy, :unless => :closed?
+      #       end
+      #     end
+      #
+      #     class Account::Credit < Account
+      #        role :accountant do
+      #          cannot :destroy    # revoke permission to destroy
+      #        end
+      #     end
+      #   end
+      #
+      def cannot(*args)
+        options = args.extract_options!
+        raise ArgumentError, "No options (#{options.inspect}) are allowed for cannot. It is just meaning less" if options.size > 0
+        p = expand_aliases(args).collect { |action| action }
+        if @in_role_block
+          @perms[:cannot] += p
         else
           @@can_expressions += 1
-          return {:can => p }
+          return {:cannot => p }
         end
       end
   

data/lib/trust/test_helper.rb

@@ -25,7 +25,7 @@
 class Trust::ResourceHelper
   attr_accessor :instance, :parent, :instances
   attr_accessor :properties, :params, :action, :instance_params
-  attr_accessor :info, :parent_info, :relation
+  attr_accessor :info, :parent_info, :relation, :collection, :association_name
   class << self
     attr_accessor :properties
   end
@@ -42,6 +42,10 @@ class Trust::ResourceHelper
     Trust::Controller::Resource::Info.var_name(parent.class)
   end
   
+  def association_name
+    @association_name || instance_name.to_s.pluralize.to_sym
+  end
+  
   def instantiated
     instances || instance
   end

data/lib/trust/version.rb

@@ -23,5 +23,5 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 module Trust
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end