aclatraz 0.0.1 → 0.1.0

data/examples/dinner.rb

@@ -0,0 +1,71 @@
+# == Dinner example.
+# 
+# Don't forget to initialize ACLatraz datastore and your ActiveRecord 
+# connection with database.
+
+class Person < ActiveRecord::Base
+  include Aclatraz::Suspect
+end
+
+class Dinner < ActiveRecord::Base
+end
+
+class Kitchen
+  include Aclatraz::Guard
+  
+  suspects "@person" do 
+    deny all
+    action :eat_dinner do
+      allow :hungry
+    end
+    action :get_dinner do 
+      allow :servant_at => Dinner
+      allow :creator_of => "@dinner"
+    end
+    action :prepare_dinner do 
+      allow :chef
+    end
+  end
+  
+  def initialize(person)
+    @person = person
+  end
+  
+  def prepare_dinner
+    guard! :prepare_dinner
+    @dinner = Dinner.create
+    @person.is.creator_of!(@dinner)
+  end
+  
+  def get_dinner(id)
+    @dinner = Dinner.find(id)
+    guard! :get_dinner
+  end
+  
+  def eat_dinner(id)
+    @dinner = Dinner.find(id)
+    guard! :eat_dinner
+    @dinner.destroy
+  end
+end
+
+# Usage...
+
+person  = Person.find(10)
+kitchen = Kitchen.new(person)
+
+kitchen.prepare_dinner                      # => Access denied
+person.is.chef!
+kitchen.prepare_dinner                      # => Ok
+
+kitchen.get_dinner(10)                      # => Ok, he creates the @dinner
+person.is_not.creator_of!(Dinner.find(10))
+kitchen.get_dinner(10)                      # => Access denied
+person.is.servant_at!(Dinner)
+kitchen.get_dinner(10)                      # => Ok
+
+kitchen.eat_dinner(10)                      # => Access denied, he is not hungry!
+person.is.hungry!
+kitchen.eat_dinner(10)                      # => Ok, enjoy your meal :)
+person.is_not.hungry!
+

data/lib/aclatraz.rb

@@ -7,24 +7,46 @@ require 'aclatraz/guard'
 require 'aclatraz/suspect'
 
 module Aclatraz
+  # Raised when suspect don't have permission to execute action
   class AccessDenied < Exception; end 
+  
+  # Raised when suspect specified in guarded class is invalid
   class InvalidSuspect < ArgumentError; end
+  
+  # Raised when invalid permission is set in ACL
   class InvalidPermission < ArgumentError; end
+  
+  # Raised when try to initialize invalid datastore
   class InvalidStore < ArgumentError; end
+  
+  # Raised when datastore is not initialized when managing permission
   class StoreNotInitialized < Exception; end
   
+  # Raised when try to guard class without any ACL defined
+  class UndefinedAccessControlList < Exception; end
+  
   extend Helpers
+
+  # Initialize Aclatraz system with given datastore. 
+  #
+  #   Aclatraz.init :redis, "redis://localhost:6379/0"
+  #   Aclatraz.init :tokyocabinet, "./permissions.tch"
+  #   Aclatraz.init MyCustomDatastore, :option => 1 # ...
+  def self.init(store, *args)
+    store = eval("Aclatraz::Store::#{camelize(store.to_s)}") unless store.is_a?(Class)
+    @store = store.new(*args)
+  rescue NameError
+    raise InvalidStore, "The #{store.inspect} ACL store is not defined!"
+  end
+  
+  # Returns current datastore object, or raises +StoreNotInitialized+ when 
+  # +init+ method wasn't called before. 
+  def self.store
+    @store or raise StoreNotInitialized, "ACLatraz is not initialized!"
+  end
   
-  def self.store(klass=nil, *args)
-    if klass
-      begin
-        klass = eval("Aclatraz::Store::#{camelize(klass.to_s)}") unless klass.is_a?(Class)
-        @store = klass.new(*args)
-      rescue NameError
-        raise InvalidStore, "The #{klass.inspect} ACL store is not defined!"
-      end
-    else
-      @store or raise StoreNotInitialized, "ACL store is not initialized!"
-    end
+  # Access control lists fof all classes protected by Aclatraz. 
+  def self.acl
+    @acl ||= {}
   end
-end
+end # Aclatraz

data/lib/aclatraz/acl.rb

@@ -1,46 +1,113 @@
 module Aclatraz
   class ACL
     class Action
+      # All permissions defined in this action.  
       attr_reader :permissions
       
-      def initialize(parent, &block)
+      def initialize(parent, &block) # :nodoc:
         @parent = parent
         @permissions = Dictionary.new
-        instance_eval(&block)
+        instance_eval(&block) if block_given?
       end
 
+      # Add permission for objects which have given role. 
+      #
+      # ==== Examples
+      #
+      #   allow :admin
+      #   allow :owner_of => "object"
+      #   allow :owner_of => :object
+      #   allow :owner_of => object
+      #   allow :manager_of => ClassName
+      #   allow all
       def allow(permission)
         @permissions[permission] = true
       end
     
+      # Add permission for objects which don't have given role. 
+      #
+      # ==== Examples
+      #
+      #   deny :admin
+      #   deny :owner_of => "object"
+      #   deny :owner_of => :object
+      #   deny :owner_of => object
+      #   deny :manager_of => ClassName
+      #   deny all
       def deny(permission)
         @permissions[permission] = false
       end
       
+      # Syntactic sugar for aliasing all permissions.
+      #
+      # ==== Examples
+      #  
+      #   allow all
+      #   deny all
       def all
         true
       end
       
+      # See <tt>Aclatraz::ACL#on</tt>.
       def on(*args, &block)
         @parent.on(*args, &block)
       end
-    end    
+      
+      def clone(parent) # :nodoc:
+        cloned = self.class.new(parent)
+        cloned.instance_variable_set("@permissions", Hash.new(permissions))
+        cloned
+      end
+    end # Action
     
+    # All actions defined in current ACL.
     attr_reader :actions
     
-    def initialize(&block)
+    # Current suspected object. 
+    attr_accessor :suspect
+    
+    def initialize(suspect, &block) # :nodoc:
       @actions = {}
+      @suspect = suspect
+      evaluate(&block) if block_given?
+    end
+    
+    # Evaluates given block in default action.
+    #
+    # ==== Example
+    #
+    #   evaluate do 
+    #     allow :foo
+    #     deny :bar
+    #     ...
+    #   end
+    def evaluate(&block)
       on(:_, &block)
     end
     
+    # List of permissions defined in default action. 
     def permissions
       @actions[:_] ? @actions[:_].permissions : Dictionary.new
     end
     
+    # Syntactic sugar for actions <tt>actions[action]</tt>.
     def [](action)
-      @actions[action]
+      actions[action]
     end
     
+    # Defines given action with permissions described in evaluated block.
+    #
+    # ==== Examples
+    #
+    #   suspects do 
+    #     on :create do 
+    #       deny all
+    #       allow :admin
+    #     end
+    #     on :delete do 
+    #       allow :owner_of => "object"
+    #     end
+    #   end 
     def on(action, &block)
       raise ArgumentError, "No block given" unless block_given?
       if @actions.key?(action)
@@ -49,5 +116,13 @@ module Aclatraz
         @actions[action] = Action.new(self, &block)
       end
     end
-  end
-end
+
+    def clone(&block) # :nodoc:
+      actions = Hash[*self.actions.map {|k,v| [k, v.clone(self)] }.flatten]
+      cloned = self.class.new(suspect)
+      cloned.instance_variable_set("@actions", actions)
+      cloned.evaluate(&block)
+      cloned
+    end
+  end # ACL
+end # Aclatraz

data/lib/aclatraz/guard.rb

@@ -1,87 +1,169 @@
 module Aclatraz
   module Guard
-    def self.included(base)
+    def self.included(base) # :nodoc:
       base.send :extend, ClassMethods
       base.send :include, InstanceMethods
     end
     
     module ClassMethods
-      attr_reader :acl_suspect
-      attr_reader :acl_permissions
-      
-      def suspects(name, &block)
-        @acl_suspect = name
-        @acl_permissions = ACL.new(&block)
+      def acl_guard? # :nodoc:
+        true
+      end
+
+      # Define access controll list for current class. 
+      #
+      # ==== Examples
+      #
+      #   suspects :foo do # foo method result will be treated as suspect
+      #     deny all 
+      #     allow :admin
+      #     
+      #     on :create do 
+      #       allow :manager
+      #       allow :manager_of => ClassName 
+      #     end
+      #
+      #     on :edit do
+      #       # only @object_name instance variable owner is allowed to edit it. 
+      #       allow :owner_of => "object_name" 
+      #     end 
+      #   end 
+      #
+      #   # When called second time don't have to specify suspected object.  
+      #   suspects do 
+      #     allow :manager
+      #   end
+      def suspects(suspect=nil, &block)
+        if acl = Aclatraz.acl[name]
+          acl.suspect = suspect if suspect
+          acl.evaluate(&block)
+        elsif superclass.respond_to?(:acl_guard?) && acl = Aclatraz.acl[superclass.name]
+          Aclatraz.acl[name] = acl.clone(&block)
+        else
+          Aclatraz.acl[name] = Aclatraz::ACL.new(suspect, &block)
+        end
       end
       alias_method :access_control, :suspects
-    end
+    end # ClassMethods
     
     module InstanceMethods
-      def current_suspect
-        case self.class.acl_suspect
-        when Symbol
-          @current_suspect ||= send(self.class.acl_suspect)
-        when String
-          @current_suspect ||= instance_variable_get("@#{self.class.acl_suspect}")
-        else
-          @current_suspect ||= self.class.acl_suspect     
+      # Returns suspected object.
+      #
+      # * when suspect name is a String then will return instance variable
+      # * when suspect name is a Symbol then will be returned value of instance method
+      # * otherwise suspect name will be treated as suspect object.  
+      #
+      # ==== Examples
+      #
+      #   class Bar
+      #     suspects(:foo) { ... }
+      #     def foo; @foo = Foo.new; end 
+      #   end
+      #   Bar.new.suspect.class # => Foo
+      #
+      #   class Bla
+      #     suspects("foo") { ... }
+      #     def init; @foo = Foo.new; end
+      #   end 
+      #   Bla.new.suspect.class # => Foo
+      #
+      #   class Spam
+      #     foo = Foo.new
+      #     suspects(foo) { ... }
+      #   end
+      #   Spam.new.suspect.class # => Foo
+      #
+      # You can also override this method in your protected class, and skip
+      # passing arguments to +#suspects+ method, eg.
+      #
+      #   class Eggs
+      #     suspects { ... }
+      #     def suspect; @foo = Foo.new; end
+      #   end
+      def suspect
+        @suspect ||= if acl = Aclatraz.acl[self.class.name]
+          case acl.suspect
+          when Symbol 
+            send(acl.suspect)
+          when String 
+            instance_variable_get("@#{acl.suspect}")
+          else 
+            acl.suspect
+          end
         end
       end
       
-      def guard!(*actions)
-        if current_suspect.respond_to?(:acl_suspect?)
-          actions.unshift(:_)
-          authorized = false
-          permissions = Dictionary.new
-          
-          actions.each do |action| 
-            self.class.acl_permissions.actions[action].permissions.each_pair do |key, value|     
-              permissions.delete(key)
-              permissions.push(key, value)
-            end
+      # Check if current suspect have permissions to execute following code.
+      # If suspect hasn't required permissions, or access for any of his roles 
+      # is denied then raises +Aclatraz::AccessDenied+ error. You can also specify
+      # additional permission inside given block:
+      #
+      #   guard! do 
+      #     deny :foo
+      #     allow :bar
+      #   end
+      def guard!(*actions, &block)
+        acl = Aclatraz.acl[self.class.name] or raise UndefinedAccessControlList, "No ACL for #{self.class.name} class"
+        suspect.respond_to?(:acl_suspect?)  or raise Aclatraz::InvalidSuspect, "Invalid ACL suspect: #{suspect.inspect}"
+        authorized = false
+        permissions = Dictionary.new
+        actions.unshift(:_)
+
+        if block_given?
+          aname = "#{__FILE__}:#{__LINE__}"
+          acl.on(aname, &block)
+          actions.push(aname)
+        end
+
+        actions.each do |action| 
+          acl.actions[action].permissions.each_pair do |key, value|     
+            permissions.delete(key)
+            permissions.push(key, value)
           end
-          
-          permissions.each do |permission, allow|
-            has_permission = check_permission(permission)
-            if permission == true
-              authorized = allow ? true : false
-              next
-            end
-            if allow
-              authorized ||= has_permission  
-            else
-              authorized = false if has_permission
-            end
+        end
+  
+        permissions.each do |permission, allow|
+          if permission == true
+            authorized = allow ? true : false
+            next
+          end
+          if allow
+            authorized ||= assert_permission(permission)  
+          else
+            authorized = false if assert_permission(permission)
           end
-          
-          raise Aclatraz::AccessDenied unless authorized
-          true
-        else
-          raise Aclatraz::InvalidSuspect
         end
+        
+        authorized or raise Aclatraz::AccessDenied, "Access Denied"
+        return true
       end
       alias_method :authorize!, :guard!
       
-      def check_permission(permission)
+      # Check if current suspect has given permissions. 
+      #
+      # ==== Examples
+      #
+      #   assert_permission(:admin)
+      #   assert_permission(:manager_of => ClassName)
+      #   assert_permission(:owner_of => "object")
+      def assert_permission(permission)
         case permission
         when String, Symbol, true
-          current_suspect.has_role?(permission)
+          suspect.roles.has?(permission)
         when Hash
           permission.each do |role, object| 
-            case object
-            when String
-              object = "@#{object}" unless object[0] == "@"
-              object = instance_variable_get(object) 
-            when Symbol
+            if object.is_a?(String)
+              object = instance_variable_get(object[0] ? "@#{object}" : object) 
+            elsif object.is_a?(Symbol) 
               object = send(object)
             end
-            return true if current_suspect.has_role?(role, object)
+            return true if suspect.roles.has?(role, object)
           end
-          false
+          return false
         else
-          raise Aclatraz::InvalidPermission
+          raise Aclatraz::InvalidPermission, "Invalid ACL permission: #{permission.inspect}"
         end
       end
-    end
-  end
-end
+    end # InstanceMethods
+  end # Guard
+end # Aclatraz