kibali 0.1.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/Gemfile

@@ -0,0 +1,22 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+  gem 'rails', '~> 3.2.8'
+ 
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development, :test do
+  gem "rdoc", "~> 3.12"
+  gem "jeweler", "~> 1.8.4"
+  gem 'sqlite3'
+end
+
+group :test do
+  gem "factory_girl"
+  gem "shoulda"
+  # Pretty printed test output
+  gem 'turn', :require => false
+end
+
+

data/Gemfile.lock

@@ -0,0 +1,110 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    actionmailer (3.2.9)
+      actionpack (= 3.2.9)
+      mail (~> 2.4.4)
+    actionpack (3.2.9)
+      activemodel (= 3.2.9)
+      activesupport (= 3.2.9)
+      builder (~> 3.0.0)
+      erubis (~> 2.7.0)
+      journey (~> 1.0.4)
+      rack (~> 1.4.0)
+      rack-cache (~> 1.2)
+      rack-test (~> 0.6.1)
+      sprockets (~> 2.2.1)
+    activemodel (3.2.9)
+      activesupport (= 3.2.9)
+      builder (~> 3.0.0)
+    activerecord (3.2.9)
+      activemodel (= 3.2.9)
+      activesupport (= 3.2.9)
+      arel (~> 3.0.2)
+      tzinfo (~> 0.3.29)
+    activeresource (3.2.9)
+      activemodel (= 3.2.9)
+      activesupport (= 3.2.9)
+    activesupport (3.2.9)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
+    ansi (1.4.3)
+    arel (3.0.2)
+    builder (3.0.4)
+    erubis (2.7.0)
+    factory_girl (4.1.0)
+      activesupport (>= 3.0.0)
+    git (1.2.5)
+    hike (1.2.1)
+    i18n (0.6.1)
+    jeweler (1.8.4)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    journey (1.0.4)
+    json (1.7.5)
+    mail (2.4.4)
+      i18n (>= 0.4.0)
+      mime-types (~> 1.16)
+      treetop (~> 1.4.8)
+    mime-types (1.19)
+    multi_json (1.3.7)
+    polyglot (0.3.3)
+    rack (1.4.1)
+    rack-cache (1.2)
+      rack (>= 0.4)
+    rack-ssl (1.3.2)
+      rack
+    rack-test (0.6.2)
+      rack (>= 1.0)
+    rails (3.2.9)
+      actionmailer (= 3.2.9)
+      actionpack (= 3.2.9)
+      activerecord (= 3.2.9)
+      activeresource (= 3.2.9)
+      activesupport (= 3.2.9)
+      bundler (~> 1.0)
+      railties (= 3.2.9)
+    railties (3.2.9)
+      actionpack (= 3.2.9)
+      activesupport (= 3.2.9)
+      rack-ssl (~> 1.3.2)
+      rake (>= 0.8.7)
+      rdoc (~> 3.4)
+      thor (>= 0.14.6, < 2.0)
+    rake (10.0.2)
+    rdoc (3.12)
+      json (~> 1.4)
+    shoulda (3.3.2)
+      shoulda-context (~> 1.0.1)
+      shoulda-matchers (~> 1.4.1)
+    shoulda-context (1.0.1)
+    shoulda-matchers (1.4.1)
+      activesupport (>= 3.0.0)
+    sprockets (2.2.1)
+      hike (~> 1.2)
+      multi_json (~> 1.0)
+      rack (~> 1.0)
+      tilt (~> 1.1, != 1.3.0)
+    sqlite3 (1.3.6)
+    thor (0.16.0)
+    tilt (1.3.3)
+    treetop (1.4.12)
+      polyglot
+      polyglot (>= 0.3.1)
+    turn (0.9.6)
+      ansi
+    tzinfo (0.3.35)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  factory_girl
+  jeweler (~> 1.8.4)
+  rails (~> 3.2.8)
+  rdoc (~> 3.12)
+  shoulda
+  sqlite3
+  turn

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Daudi Amani
+
+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.

data/README.md

@@ -0,0 +1,183 @@
+# kibali
+
+Kibali is a simple replacement for ACL9, a role-based authentication gem.
+Kibali is primarily oriented for functioning as a before\_filter role authentication 
+scheme for Rails controllers.
+
+## Basic concepts
+Authentication is often called for on a controller-by-controller basis, restricting
+actions to users who possess certain roles. Kibali (current version) assumes only one role
+per user. Kibali requires a _current\_user_ method accessible at the controller level
+and which returns a User object.
+
+Kibali adds, to the User model, role accessor methods: has\_role?, has\_role!, get\_role
+
+## Structure
+
+* necessary models: user, roles, roles\_users (join table)
+* necessary migrations (for kibali): roles, roles\_users (join table)
+
+## Dependency requirements
+
+* Rails 3.2 or higher
+
+## Installation
+
+Either install the gem manually:
+
+```
+  $ gem install
+```
+
+Or use bundler and place in your Gemfile
+
+```
+  gem 'kibali'
+```
+
+## Setup
+
+### Defaults assumed
+
+**User** is the subject model: 
+indicate by inserting the following macro after the class definition:
+
+```
+    acts_as_authorization_subject
+```
+
+**Role** is the role model: 
+indicate by inserting the following macro after the class definition:
+
+```
+   acts_as_authorization_role
+```
+
+Note: the gem allows the default model/table names to be changed, but I haven't built tests
+for verifying that the changes will work.
+
+```
+   class Role < ActiveRecord::Base
+     acts_as_authorization_role
+   end
+
+   class User < ActiveRecord::Base
+     acts_as_authorization_subject
+   end
+```
+
+### Migrations required
+
+The roles table must be created (sorry, no generator yet)
+Some of the fields are legacy from acl9 and currently are not used.
+
+```
+  create_table "roles", :force => true do |t|
+    t.string   "name",              :limit => 40
+    t.string   "authorizable_type", :limit => 40
+    t.string  "authorizable_id"
+    t.boolean "system", :default=>false
+    t.datetime "created_at"
+    t.datetime "updated_at"
+  end
+```
+
+and the join table
+
+```
+    create_table :roles_users, :id => false, :force => true do |t|
+      t.column  :user_id, :integer
+      t.column  :role_id, :integer
+    end
+      add_index :roles_users, :user_id
+```
+ 
+
+## Usage
+
+At the head of every controller for which you wish to control user access,
+you'll need to place an _access_control_ macro which is used to generate a 
+before_filter for the authorization checks. In the testing, I had to place the
+parameter in a seperate statement because syntax errors were encountered. That
+might be due to the limited test structure used. I'll show both forms here.
+
+Unauthorized access yields an exception: Kibali::AccessDenied .
+Syntax errors in formulating the control parameters will also raise an exception: Kibali::SyntaxError .
+You'll probably want to catch those exceptions and handle them gracefully, probably in your ApplicationController.
+
+Notice that roles, limit_types, and controller actions are all expected to be symbols.
+
+You have complete freedom to define roles to be whatever you want: except for the reserved words: :all, :anonymous.
+
+The access limitation types are: 
+
+* :allow, :to, :only -- control what access is allowed; all else will be denied
+* :deny, :except -- control what is denied; all else will be permitted
+
+The action list can be empty; in which case, for :allow, all actions are permitted; and for :deny, no actions are permitted.
+If both limit_type and action_list are missing, then :allow => [] will be assumed.
+
+```
+class AnyController < ApplicationController
+
+   access_control {
+       :admin   => { :allow => [] },
+       :manager => { :deny  => [ :delete, :edit ] },
+       :member  => { :allow => [ :index, :show  ] }
+   }
+```
+ 
+alternatively
+
+```
+class AnyController < ApplicationController
+
+   control_parameters = {
+       :admin   => { :allow => [] },
+       :manager => { :deny  => [ :delete, :edit ] },
+       :member  => { :allow => [ :index, :show  ] }
+   }
+   access_control control_parameters
+```
+ 
+Catch exceptions:
+
+```
+class ApplicationController < ActionController::Base
+   rescue_from Kibali::AccessDenied do |e|
+     # do something here
+   end
+```
+
+
+## Examples
+
+Please see the examples in the test folder
+ 
+## Acknowledgements
+
+Kibali was influenced by the acl9 gem (https://github.com/be9/acl9). 
+I used acl9 for a number of years until it broke under Rails 3.2.x with a SystemStack error. 
+Trying to fix the bug proved to be difficult due to the extent of meta programming. Noting that Rails now
+had a simple way to designate a class to handle before_filters 
+(Gavin Morrice's excellent tutorial: http://gavinmorrice.com/blog/posts/15-dryer-neater-rails-before_filters-using-classes),
+I decided that a simpler role-based authorization Rails 3.2.x gem would be valuable. As I already had a production app based
+on acl9, I wanted the conversion to be as seamless as possible. I've kept the same tables and naming. And I've made
+the access_control syntax similar (though not the same). I did keep the same model macro names and config default variables,
+but all access_control code has changed. The tests are all different.
+
+
+## Contributing to kibali
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+## Copyright
+
+Copyright (c) 2012 Daudi Amani. See LICENSE.txt for further details.
+

data/Rakefile

@@ -0,0 +1,47 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "kibali"
+  gem.homepage = "http://github.com/dsaronin@gmail.com/kibali"
+  gem.license = "MIT"
+  gem.summary = %Q{rails role authentication}
+  gem.description = %Q{simple Rails role authentication}
+  gem.email = "dsaronin@gmail.com"
+  gem.authors = ["Daudi Amani"]
+  # dependencies defined in Gemfile
+end
+
+Jeweler::RubygemsDotOrgTasks.new
+
+# ------------------------------------------------------------------------
+# don't use normal Rake test routine because of double factory_girl
+# ------------------------------------------------------------------------
+task :test do
+   ruby '-I test "test/test_kibali.rb"'
+   ruby '-I test "test/test_access.rb"'
+end # test task
+
+task :default => :test
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "kibali #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/kibali/access_control.rb

@@ -0,0 +1,89 @@
+module Kibali
+  class AccessControl < Struct.new( :role_control_hash )
+
+# #############################################################################
+# #############################################################################
+
+# ------------------------------------------------------------------------------
+# EXCEPTION: 
+     # Kibali::AccessDenied -- execution denied
+     # Kibali::SyntaxError -- unexpected limit_type, or action_type
+# #############################################################################
+     # see test/app/controllers/empty_controller.rb for sample syntax
+
+     # ---------------------------------------------------------------------------------
+     # possible states and resultant handlings
+     #   limit_type           action_list                  permitted handling
+     # ---------------------------------------------------------------------------------
+     #  :allow, :to, :only    [] empty, action matched     permitted
+     #                           action not matched        denied
+     #
+     #   :deny, :except       [] empty, action matched     denied
+     #                           action not matched        permitted
+     #
+     # ---------------------------------------------------------------------------------
+ # ------------------------------------------------------------------------------
+  def before( controller )
+
+     my_role = controller.current_user.get_role.name.to_sym
+
+         # if current_user's role not present; check if anonymous is
+     unless self.role_control_hash.member?( my_role )
+        # here if current_user's role not specificied in control list
+
+        if self.role_control_hash.member?( :anonymous )  # if anonymous is...
+           my_role = :anonymous    # ...then handle anonymously
+        else   # unauthorized access of controller
+           raise Kibali::AccessDenied 
+        end   # if..then..else anonymous check
+
+     end   # unless current_user has a role to be checked
+
+     expected_action = controller.action_name.to_sym  # action being attempted
+
+   permitted = true   # presume authorized
+
+         # now check the action_hash for action access
+         # shown as a loop, but only the first entry is meaningful
+     self.role_control_hash[my_role].each do |limit_type, action_list|
+
+        permitted = ( action_list.empty? || action_list.include?( expected_action ) )
+        
+        case limit_type
+           when :allow, :to, :only then  permitted
+           when :deny, :except then permitted = !permitted
+        else
+           raise Kibali::SyntaxError, "Unrecognized access_control limit_type: #{limit_type}"
+        end  # case
+
+        
+        unless permitted      # ... figure out the type of exception
+           if action_list.any?{ |actn|  actn.class.name != "Symbol" }
+              raise Kibali::SyntaxError, "all actions should be symbols"
+           else
+              raise Kibali::AccessDenied 
+           end  # syntax checking
+        end  # unless
+
+        break   # always break the loop at success
+
+     end  # do check if role
+
+     return permitted
+  end
+
+# ------------------------------------------------------------------------------
+# ------------------------------------------------------------------------------
+    
+  private
+
+# ------------------------------------------------------------------------------
+# ------------------------------------------------------------------------------
+
+# ------------------------------------------------------------------------------
+# ------------------------------------------------------------------------------
+  
+# #############################################################################
+# #############################################################################
+  end
+end 

data/lib/kibali/base.rb

@@ -0,0 +1,79 @@
+module Kibali
+  module Base
+
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+# #############################################################################
+# @example
+#   class Role < ActiveRecord::Base
+#     acts_as_authorization_role
+#   end
+#
+# @see Kibali::ModelExtensions::Subject#has_role!
+# @see Kibali::ModelExtensions::Subject#has_role?
+# @see Kibali::ModelExtensions::Subject#has_no_role!
+# #############################################################################
+
+    module ClassMethods
+
+# ------------------------------------------------------------------------
+# acts_as_authorization_subject -- designates model to be user subject
+# ------------------------------------------------------------------------
+   def acts_as_authorization_subject(options = {})
+
+     assoc      = options[:association_name] || Kibali::config[:default_roles_collection_name]
+     role       = options[:role_class_name]  || Kibali::config[:default_role_class_name]
+     join_table = options[:join_table_name]  || Kibali::config[:default_join_table_name]
+
+     has_and_belongs_to_many    assoc, :class_name => role, :join_table => join_table
+
+     cattr_accessor :_auth_role_class_name, :_auth_subject_class_name, :_auth_role_assoc_name
+
+     self._auth_role_class_name    = role
+     self._auth_subject_class_name = self.to_s
+     self._auth_role_assoc_name    = assoc
+
+     include Kibali::SubjectExtensions
+
+   end
+
+# ------------------------------------------------------------------------
+# ------------------------------------------------------------------------
+   def acts_as_authorization_role(options = {})
+
+     assoc      = options[:association_name]    || Kibali::config[:default_users_collection_name]
+     subject    = options[:subject_class_name]  || Kibali::config[:default_subject_class_name]
+     join_table = options[:join_table_name]     || Kibali::config[:default_join_table_name]
+
+     has_and_belongs_to_many    assoc, :class_name => subject, :join_table => join_table
+
+     cattr_accessor :_auth_role_class_name, :_auth_subject_class_name, :_auth_role_assoc_name
+
+     self._auth_role_class_name    = self.to_s
+     self._auth_subject_class_name = subject
+     self._auth_role_assoc_name    = assoc
+
+     scope :named_role, lambda { |role_name| where(["name = ?", role_name.to_s]) }
+
+   end
+  
+# ------------------------------------------------------------------------
+# ------------------------------------------------------------------------
+  
+# ------------------------------------------------------------------------
+# ------------------------------------------------------------------------
+
+# ------------------------------------------------------------------------
+# ------------------------------------------------------------------------
+
+# ------------------------------------------------------------------------
+# ------------------------------------------------------------------------
+
+    end  # module ClassMethods
+# #############################################################################
+# #############################################################################
+    
+  end  # module Base
+end  # module Kibali

data/lib/kibali/control.rb

@@ -0,0 +1,39 @@
+module Kibali
+  module Control
+
+# #############################################################################
+# #############################################################################
+    
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+# #############################################################################
+# #############################################################################
+    module ClassMethods
+
+       def access_control( role_control_hash, options = {} )
+          before_filter  Kibali::AccessControl.new( role_control_hash ), options
+       end
+
+    end  # module ClassMethods
+
+# #############################################################################
+# #############################################################################
+    
+  private
+
+# ------------------------------------------------------------------------------
+# ------------------------------------------------------------------------------
+    
+# ------------------------------------------------------------------------------
+# ------------------------------------------------------------------------------
+  
+# ------------------------------------------------------------------------------
+# ------------------------------------------------------------------------------
+
+# #############################################################################
+# #############################################################################
+
+  end  # module Control
+end  # module Kibali

data/lib/kibali/railtie.rb

@@ -0,0 +1,17 @@
+require 'kibali'
+require 'rails'
+
+module Kibali
+  class Railtie < Rails::Railtie
+    initializer :after_initialize do
+ 
+        ActiveRecord::Base.send(:include, Kibali::Base)
+        ActionController::Base.send(:include, Kibali::Control)
+        
+    end
+
+#     rake_tasks do
+#       load 'kibali/tasks.rb'
+#     end
+  end
+end