iq-acl 1.0.5 → 1.1.1

data/README.rdoc

@@ -18,28 +18,40 @@ This aim of this gem is to provide a series of classes to handle common ACL requ
   # You could alternatively read rights from a YAML file
   auth = IQ::ACL::Basic.new(YAML.load_file('rights.yml'))
 
-  auth.authorize! 'guest', 'projects'         #=> raises IQ::ACL::AccessDeniedError
-  auth.authorize! 'jonny', 'projects'         #=> 'rw'
-  auth.authorize! 'billy', 'projects'         #=> raises IQ::ACL::AccessDeniedError
-  auth.authorize! 'terry', 'projects'         #=> 'r'
-  auth.authorize! 'guest', 'projects/private' #=> raises IQ::ACL::AccessDeniedError
-  auth.authorize! 'jonny', 'projects/private' #=> 'rw'
-  auth.authorize! 'billy', 'projects/private' #=> 'rw'
-  auth.authorize! 'terry', 'projects/private' #=> raises IQ::ACL::AccessDeniedError
-  auth.authorize! 'guest', 'projects/public'  #=> 'r'
-  auth.authorize! 'jonny', 'projects/public'  #=> 'r'
-  auth.authorize! 'billy', 'projects/public'  #=> 'r'
-  auth.authorize! 'terry', 'projects/public'  #=> 'rw
-
-A block may be given to <tt>authorize!</tt> that should return true if
+  auth.authenticate! 'guest', 'projects'         #=> raises IQ::ACL::AccessDeniedError
+  auth.authenticate! 'jonny', 'projects'         #=> 'rw'
+  auth.authenticate! 'billy', 'projects'         #=> raises IQ::ACL::AccessDeniedError
+  auth.authenticate! 'terry', 'projects'         #=> 'r'
+  auth.authenticate! 'guest', 'projects/private' #=> raises IQ::ACL::AccessDeniedError
+  auth.authenticate! 'jonny', 'projects/private' #=> 'rw'
+  auth.authenticate! 'billy', 'projects/private' #=> 'rw'
+  auth.authenticate! 'terry', 'projects/private' #=> raises IQ::ACL::AccessDeniedError
+  auth.authenticate! 'guest', 'projects/public'  #=> 'r'
+  auth.authenticate! 'jonny', 'projects/public'  #=> 'r'
+  auth.authenticate! 'billy', 'projects/public'  #=> 'r'
+  auth.authenticate! 'terry', 'projects/public'  #=> 'rw
+
+A block may be given to <tt>authenticate!</tt> that should return true if
 the yielded rights are adequate for the user, for example the following
 will raise an IQ::ACL::AccessDeniedError as 'terry' does not have write access
 to the 'projects' path. If 'terry' had write access to the 'projects'
 path, the exception would not be thrown.
 
-  auth.authorize! 'terry', 'projects' do |rights|
+  auth.authenticate! 'terry', 'projects' do |rights|
     rights.include?('w')
   end
+  
+In the previous examples, strings are used to identify the user, however
+user may be any object. This becomes quite powerful as you could use the
+objects returned from an ORM such as ActiveRecord. Also the rights in the
+previous examples were strings, however these may be of any type also,
+again allowing powerful solutions to be built e.g.
+ 
+ user = User.find_by_email('jamie@example.com')
+ auth = IQ::ACL::Basic.new('projects/*' => { user => user.roles })
+ auth.authenticate!(user, 'projects/some-project') do |roles|
+   roles.find_by_name('project_editor')
+ end
 
 == Note on Patches/Pull Requests
  

data/VERSION

@@ -1 +1 @@
-1.0.5
+1.1.1

data/iq-acl.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{iq-acl}
-  s.version = "1.0.5"
+  s.version = "1.1.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Jamie Hill, SonicIQ Ltd."]
-  s.date = %q{2010-05-31}
+  s.date = %q{2010-06-02}
   s.description = %q{IQ::ACL provides a super simple way of implementing access control.}
   s.email = %q{jamie@soniciq.com}
   s.extra_rdoc_files = [

data/lib/iq/acl/basic.rb

@@ -6,80 +6,104 @@
 # @example
 #   # Create an instance of the basic class, supplying rights as a hash, note
 #   # that asterisks are used as wildcards.
-#   auth = IQ::ACL::Basic.new({
+#   auth = IQ::ACL::Basic.new(
 #     '*'                 => { 'terry' => 'r' },
 #     'projects'          => { 'jonny' => 'rw' },
 #     'projects/private'  => { 'billy' => 'rw', 'terry' => nil },
 #     'projects/public'   => { 'terry' => 'rw', '*' => 'r' }
-#   })
+#   )
 #   
-#   # You could alternatively read rights from a YAML file
+#   # You could alternatively read rights from a YAML file.
 #   auth = IQ::ACL::Basic.new(YAML.load_file('rights.yml'))
 # 
-#   auth.authorize! 'guest', 'projects'         #=> raises IQ::ACL::AccessDeniedError
-#   auth.authorize! 'jonny', 'projects'         #=> 'rw'
-#   auth.authorize! 'billy', 'projects'         #=> raises IQ::ACL::AccessDeniedError
-#   auth.authorize! 'terry', 'projects'         #=> 'r'
-#   auth.authorize! 'guest', 'projects/private' #=> raises IQ::ACL::AccessDeniedError
-#   auth.authorize! 'jonny', 'projects/private' #=> 'rw'
-#   auth.authorize! 'billy', 'projects/private' #=> 'rw'
-#   auth.authorize! 'terry', 'projects/private' #=> raises IQ::ACL::AccessDeniedError
-#   auth.authorize! 'guest', 'projects/public'  #=> 'r'
-#   auth.authorize! 'jonny', 'projects/public'  #=> 'r'
-#   auth.authorize! 'billy', 'projects/public'  #=> 'r'
-#   auth.authorize! 'terry', 'projects/public'  #=> 'rw
+#   auth.authenticate! 'guest', 'projects'         #=> raises IQ::ACL::AccessDeniedError
+#   auth.authenticate! 'jonny', 'projects'         #=> 'rw'
+#   auth.authenticate! 'billy', 'projects'         #=> raises IQ::ACL::AccessDeniedError
+#   auth.authenticate! 'terry', 'projects'         #=> 'r'
+#   auth.authenticate! 'guest', 'projects/private' #=> raises IQ::ACL::AccessDeniedError
+#   auth.authenticate! 'jonny', 'projects/private' #=> 'rw'
+#   auth.authenticate! 'billy', 'projects/private' #=> 'rw'
+#   auth.authenticate! 'terry', 'projects/private' #=> raises IQ::ACL::AccessDeniedError
+#   auth.authenticate! 'guest', 'projects/public'  #=> 'r'
+#   auth.authenticate! 'jonny', 'projects/public'  #=> 'r'
+#   auth.authenticate! 'billy', 'projects/public'  #=> 'r'
+#   auth.authenticate! 'terry', 'projects/public'  #=> 'rw
 # 
-#   # A block may be given to authorize! that should return true if the yielded
+#   # A block may be given to authenticate! that should return true if the yielded
 #   # rights are adequate for the user, for example the following will raise an
 #   # IQ::ACL::AccessDeniedError as 'terry' does not have write access to the
 #   # 'projects' path. If 'terry' had write access to the 'projects' path, the
 #   # exception would not be thrown.
 # 
-#   auth.authorize! 'terry', 'projects' do |rights|
+#   auth.authenticate! 'terry', 'projects' do |rights|
 #     rights.include?('w')
 #   end
+# 
+#   # In the previous examples, strings are used to identify the user, however
+#   # user may be any object. This becomes quite powerful as you could use the
+#   # objects returned from an ORM such as ActiveRecord. Also the rights in the
+#   # previous examples were strings, however these may be of any type also,
+#   # again allowing powerful solutions to be built e.g.
+# 
+#   user = User.find_by_email('jamie@example.com')
+#   auth = IQ::ACL::Basic.new('projects/*' => { user => user.roles })
+#   auth.authenticate!(user, 'projects/some-project') do |roles|
+#     roles.find_by_name('project_editor')
+#   end
 #
 class IQ::ACL::Basic
   
   # Returns a new instance to be authenticated against.
   # 
-  # @param [Hash]
+  # @param [Hash] permissions
   def initialize(permissions)
     raise ArgumentError, 'Must supply permissions as a hash' unless permissions.is_a?(Hash)
     @permissions = permissions
   end
-  
+
   # Returns the rights that a user has for a given path. When the user has no
-  # access to the given path, an IQ::ACL::AccessDeniedError is raised. When a
-  # block is given the user rights are yielded as the block parameter and the
-  # block is expected to return true when the rights are sufficient.
+  # access to the given path, nil is returned.
+  # 
+  # When a block is supplied the user rights are yielded as the block parameter
+  # and the block is expected to return true when the rights are sufficient.
   # 
-  # @param [String] user
+  # @param [Object] user
   # @param [String] path
   # 
-  # @return [String] the right for the given user
-  def authorize!(user, path)
+  # @return [nil, Object] the rights that the given user has to the path.
+  def authenticate(user, path)
     raise ArgumentError, 'Path must be a string' unless path.is_a?(String)
     
     segments = path.split('/')
     rights = until segments.empty?
       if rights = permissions[segments.join('/')]
         access = rights[user] || rights['*']
-        access_denied! if (rights.has_key?(user) || rights.has_key?('*')) && access.nil?
+        return nil if (rights.has_key?(user) || rights.has_key?('*')) && access.nil?
         break access if access
       end
       segments.pop
-    end || (global = permissions['*']) && (global[user] || global['*']) || access_denied!
+    end || (global = permissions['*']) && (global[user] || global['*']) || nil
     
-    access_denied! if block_given? && (yield(rights) != true)
+    return nil if block_given? && (yield(rights) != true)
     rights
   end
+  
+  # Returns the rights that a user has for a given path. When the user has no
+  # access to the given path, an IQ::ACL::AccessDeniedError is raised.
+  # When a block is supplied the user rights are yielded as the block parameter
+  # and the block is expected to return true when the rights are sufficient.
+  # 
+  # @param [Object] user
+  # @param [String] path
+  # 
+  # @raise [IQ::ACL::AccessDeniedError] when result of block is not true.
+  # @return [Object] the rights that the given user has to the path.
+  def authenticate!(user, path, &block)
+    authenticate(user, path, &block) || raise(IQ::ACL::AccessDeniedError, 'User does not have access to path')
+  end
 
   private
   
   attr_reader :permissions
-  
-  def access_denied!
-    raise IQ::ACL::AccessDeniedError, 'User does not have access to path'
-  end
+
 end

data/test/iq/acl_test.rb

@@ -13,99 +13,231 @@ class IQ::ACLTest < Test::Unit::TestCase
     end
   end
   
-  context "authorize!" do
+  context "authenticate" do
     should "respond" do
-      assert_respond_to IQ::ACL::Basic.new({}), :authorize!
+      assert_respond_to IQ::ACL::Basic.new({}), :authenticate
     end
 
     should "accept username as first argument" do
       instance = IQ::ACL::Basic.new('the/path' => { 'the user' => true })
-      assert_nothing_raised(ArgumentError) { instance.authorize!('the user', 'the/path') }
+      assert_nothing_raised(ArgumentError) { instance.authenticate('the user', 'the/path') }
     end
 
     should "accept path as second argument" do
       instance = IQ::ACL::Basic.new('the/path' => { 'the user' => true })
-      assert_nothing_raised(ArgumentError) { instance.authorize!('the user', 'the/path') }
+      assert_nothing_raised(ArgumentError) { instance.authenticate('the user', 'the/path') }
     end
 
     should "raise when path is not a string" do
-      assert_raise(ArgumentError) { IQ::ACL::Basic.new({}).authorize!('the user', :not_a_string) }
+      assert_raise(ArgumentError) { IQ::ACL::Basic.new({}).authenticate('the user', :not_a_string) }
+    end
+
+    should "raise return nil when no match" do
+      assert_nil IQ::ACL::Basic.new({}).authenticate('the user', 'will/not/match')
+    end
+    
+    should "return nil when user access explicitly set to nil for given path even when a parent privilege set" do
+      instance = IQ::ACL::Basic.new('the' => { 'the user' => 'ok' }, 'the/path' => { 'the user' => nil })
+      assert_nil instance.authenticate('the user', 'the/path')
+    end
+    
+    should "return nil when user access explicitly set to nil for given path even when root global set" do
+      instance = IQ::ACL::Basic.new('*' => { 'the user' => 'ok' }, 'the/path' => { 'the user' => nil })
+      assert_nil instance.authenticate('the user', 'the/path')
+    end
+    
+    should "return nil when user access not known but global set to nil for given path even when parent set" do
+      instance = IQ::ACL::Basic.new('the' => { 'the user' => 'ok' }, 'the/path' => { 'the user' => nil })
+      assert_nil instance.authenticate('the user', 'the/path')
+    end
+    
+    should "return nil when user access not known but global set to nil for given path even when root global set" do
+      instance = IQ::ACL::Basic.new('*' => { 'the user' => 'ok' }, 'the/path' => { '*' => nil })
+      assert_nil instance.authenticate('the user', 'the/path')
+    end
+
+    should "return result of direct match in permissions hash with path and user when available" do
+      instance = IQ::ACL::Basic.new('the/path' => { 'the user' => 'the access' })
+      assert_equal 'the access', instance.authenticate('the user', 'the/path')
+    end
+    
+    should "return result of direct match in permissions hash with path and user when available special case" do
+      instance = IQ::ACL::Basic.new('projects/rails-site.com' => { 'rails_site' => 'rw' })
+      assert_equal 'rw', instance.authenticate('rails_site', 'projects/rails-site.com')
+    end
+
+    should "return result of direct match in permissions hash with path and star user when user not found" do
+      instance = IQ::ACL::Basic.new('the/path' => { '*' => 'the access' })
+      assert_equal 'the access', instance.authenticate('the user', 'the/path')
+    end
+
+    should "return result of parent match in permissions hash with path and user over global user when no match" do
+      instance = IQ::ACL::Basic.new('the' => { 'the user' => 'the access', '*' => 'global access' })
+      assert_equal 'the access', instance.authenticate('the user', 'the/path')
+    end
+
+    should "return result of parent match in permissions hash with path and star user when user not found" do
+      instance = IQ::ACL::Basic.new('the' => { '*' => 'the access' })
+      assert_equal 'the access', instance.authenticate('the user', 'the/path')
+    end
+
+    should "continue down permissions tree until a match with path and user is found over global access" do
+      instance = IQ::ACL::Basic.new('the/long' => { 'the user' => 'the access', '*' => 'global access' })
+      assert_equal 'the access', instance.authenticate('the user', 'the/long/big/nested/path')
+    end
+
+    should "continue down permissions tree until a match with path and star user when user not found" do
+      instance = IQ::ACL::Basic.new('the/long' => { '*' => 'the access' })
+      assert_equal 'the access', instance.authenticate('the user', 'the/long/big/nested/path')
+    end
+
+    should "return result of user in star entry of permissions hash over star user when no other matches" do
+      instance = IQ::ACL::Basic.new('*' => { 'the user' => 'the access', '*' => 'global access' }, 'other/path' => {})
+      assert_equal 'the access', instance.authenticate('the user', 'the/path')
+    end
+
+    should "return result of star user in star entry of permissions hash when no user match" do
+      instance = IQ::ACL::Basic.new('*' => { '*' => 'the access' }, 'other/path' => {})
+      assert_equal 'the access', instance.authenticate('the user', 'the/path')
+    end
+    
+    context "using a block" do
+      should "yield the user rights when block given" do
+        instance = IQ::ACL::Basic.new('the/path' => { 'the user' => 'the access' })
+        the_rights = nil
+        instance.authenticate('the user', 'the/path') do |rights|
+          the_rights = rights
+          true
+        end
+        assert_equal 'the access', the_rights
+      end
+    
+      should "return nil if block evaluates to false" do
+        instance = IQ::ACL::Basic.new('the/path' => { 'the user' => 'the access' })
+
+        assert_nil(
+          instance.authenticate('the user', 'the/path') do |rights|
+            false
+          end
+        )
+      end
+    
+      should "return nil if block evaluates to anything other than true" do
+        instance = IQ::ACL::Basic.new('the/path' => { 'the user' => 'the access' })
+
+        assert_nil(
+          instance.authenticate('the user', 'the/path') do |rights|
+            'not true'
+          end
+        )
+      end
+    
+      should "return rights when block evaluates to true" do
+        instance = IQ::ACL::Basic.new('the/path' => { 'the user' => 'the access' })
+
+        assert_equal(
+          'the access',
+          instance.authenticate('the user', 'the/path') do |rights|
+            true
+          end
+        )
+      end
+    end
+  end
+  
+  context "authenticate!" do
+    should "respond" do
+      assert_respond_to IQ::ACL::Basic.new({}), :authenticate!
+    end
+
+    should "accept username as first argument" do
+      instance = IQ::ACL::Basic.new('the/path' => { 'the user' => true })
+      assert_nothing_raised(ArgumentError) { instance.authenticate!('the user', 'the/path') }
+    end
+
+    should "accept path as second argument" do
+      instance = IQ::ACL::Basic.new('the/path' => { 'the user' => true })
+      assert_nothing_raised(ArgumentError) { instance.authenticate!('the user', 'the/path') }
+    end
+
+    should "raise when path is not a string" do
+      assert_raise(ArgumentError) { IQ::ACL::Basic.new({}).authenticate!('the user', :not_a_string) }
     end
 
     should "raise access denied error when no match" do
-      assert_raise(IQ::ACL::AccessDeniedError) { IQ::ACL::Basic.new({}).authorize!('the user', 'will/not/match') }
+      assert_raise(IQ::ACL::AccessDeniedError) { IQ::ACL::Basic.new({}).authenticate!('the user', 'will/not/match') }
     end
     
     should "raise when user access explicitly set to nil for given path even when a parent privilege set" do
       instance = IQ::ACL::Basic.new('the' => { 'the user' => 'ok' }, 'the/path' => { 'the user' => nil })
-      assert_raise(IQ::ACL::AccessDeniedError) { instance.authorize!('the user', 'the/path') }
+      assert_raise(IQ::ACL::AccessDeniedError) { instance.authenticate!('the user', 'the/path') }
     end
     
     should "raise when user access explicitly set to nil for given path even when root global set" do
       instance = IQ::ACL::Basic.new('*' => { 'the user' => 'ok' }, 'the/path' => { 'the user' => nil })
-      assert_raise(IQ::ACL::AccessDeniedError) { instance.authorize!('the user', 'the/path') }
+      assert_raise(IQ::ACL::AccessDeniedError) { instance.authenticate!('the user', 'the/path') }
     end
     
     should "raise when user access not known but global set to nil for given path even when parent privilege set" do
       instance = IQ::ACL::Basic.new('the' => { 'the user' => 'ok' }, 'the/path' => { 'the user' => nil })
-      assert_raise(IQ::ACL::AccessDeniedError) { instance.authorize!('the user', 'the/path') }
+      assert_raise(IQ::ACL::AccessDeniedError) { instance.authenticate!('the user', 'the/path') }
     end
     
     should "raise when user access not known but global set to nil for given path even when root global set" do
       instance = IQ::ACL::Basic.new('*' => { 'the user' => 'ok' }, 'the/path' => { '*' => nil })
-      assert_raise(IQ::ACL::AccessDeniedError) { instance.authorize!('the user', 'the/path') }
+      assert_raise(IQ::ACL::AccessDeniedError) { instance.authenticate!('the user', 'the/path') }
     end
 
     should "return result of direct match in permissions hash with path and user when available" do
       instance = IQ::ACL::Basic.new('the/path' => { 'the user' => 'the access' })
-      assert_equal 'the access', instance.authorize!('the user', 'the/path')
+      assert_equal 'the access', instance.authenticate!('the user', 'the/path')
     end
     
     should "return result of direct match in permissions hash with path and user when available special case" do
       instance = IQ::ACL::Basic.new('projects/rails-site.com' => { 'rails_site' => 'rw' })
-      assert_equal 'rw', instance.authorize!('rails_site', 'projects/rails-site.com')
+      assert_equal 'rw', instance.authenticate!('rails_site', 'projects/rails-site.com')
     end
 
     should "return result of direct match in permissions hash with path and star user when user not found" do
       instance = IQ::ACL::Basic.new('the/path' => { '*' => 'the access' })
-      assert_equal 'the access', instance.authorize!('the user', 'the/path')
+      assert_equal 'the access', instance.authenticate!('the user', 'the/path')
     end
 
     should "return result of parent match in permissions hash with path and user over global user when no match" do
       instance = IQ::ACL::Basic.new('the' => { 'the user' => 'the access', '*' => 'global access' })
-      assert_equal 'the access', instance.authorize!('the user', 'the/path')
+      assert_equal 'the access', instance.authenticate!('the user', 'the/path')
     end
 
     should "return result of parent match in permissions hash with path and star user when user not found" do
       instance = IQ::ACL::Basic.new('the' => { '*' => 'the access' })
-      assert_equal 'the access', instance.authorize!('the user', 'the/path')
+      assert_equal 'the access', instance.authenticate!('the user', 'the/path')
     end
 
     should "continue down permissions tree until a match with path and user is found over global access" do
       instance = IQ::ACL::Basic.new('the/long' => { 'the user' => 'the access', '*' => 'global access' })
-      assert_equal 'the access', instance.authorize!('the user', 'the/long/big/nested/path')
+      assert_equal 'the access', instance.authenticate!('the user', 'the/long/big/nested/path')
     end
 
     should "continue down permissions tree until a match with path and star user when user not found" do
       instance = IQ::ACL::Basic.new('the/long' => { '*' => 'the access' })
-      assert_equal 'the access', instance.authorize!('the user', 'the/long/big/nested/path')
+      assert_equal 'the access', instance.authenticate!('the user', 'the/long/big/nested/path')
     end
 
     should "return result of user in star entry of permissions hash over star user when no other matches" do
       instance = IQ::ACL::Basic.new('*' => { 'the user' => 'the access', '*' => 'global access' }, 'other/path' => {})
-      assert_equal 'the access', instance.authorize!('the user', 'the/path')
+      assert_equal 'the access', instance.authenticate!('the user', 'the/path')
     end
 
     should "return result of star user in star entry of permissions hash when no user match" do
       instance = IQ::ACL::Basic.new('*' => { '*' => 'the access' }, 'other/path' => {})
-      assert_equal 'the access', instance.authorize!('the user', 'the/path')
+      assert_equal 'the access', instance.authenticate!('the user', 'the/path')
     end
     
     context "using a block" do
       should "yield the user rights when block given" do
         instance = IQ::ACL::Basic.new('the/path' => { 'the user' => 'the access' })
         the_rights = nil
-        instance.authorize!('the user', 'the/path') do |rights|
+        instance.authenticate!('the user', 'the/path') do |rights|
           the_rights = rights
           true
         end
@@ -116,7 +248,7 @@ class IQ::ACLTest < Test::Unit::TestCase
         instance = IQ::ACL::Basic.new('the/path' => { 'the user' => 'the access' })
 
         assert_raise(IQ::ACL::AccessDeniedError) do
-          instance.authorize!('the user', 'the/path') do |rights|
+          instance.authenticate!('the user', 'the/path') do |rights|
             false
           end
         end
@@ -126,7 +258,7 @@ class IQ::ACLTest < Test::Unit::TestCase
         instance = IQ::ACL::Basic.new('the/path' => { 'the user' => 'the access' })
 
         assert_raise(IQ::ACL::AccessDeniedError) do
-          instance.authorize!('the user', 'the/path') do |rights|
+          instance.authenticate!('the user', 'the/path') do |rights|
             'not true'
           end
         end
@@ -136,7 +268,7 @@ class IQ::ACLTest < Test::Unit::TestCase
         instance = IQ::ACL::Basic.new('the/path' => { 'the user' => 'the access' })
 
         assert_nothing_raised(IQ::ACL::AccessDeniedError) do
-          instance.authorize!('the user', 'the/path') do |rights|
+          instance.authenticate!('the user', 'the/path') do |rights|
             true
           end
         end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 1
-  - 0
-  - 5
-  version: 1.0.5
+  - 1
+  - 1
+  version: 1.1.1
 platform: ruby
 authors: 
 - Jamie Hill, SonicIQ Ltd.
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-05-31 00:00:00 +01:00
+date: 2010-06-02 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency