makandra-aegis 1.1.1

data/.gitignore

@@ -0,0 +1,3 @@
+doc
+pkg
+*.gem

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Henning Koch
+
+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.rdoc

@@ -0,0 +1,66 @@
+= Aegis - role-based permissions for your user models
+
+Aegis allows you to managed fine-grained and complex permission for user accounts in a central place.
+
+=== Example 
+
+First, let's define some roles:
+
+    # app/models/permissions.rb
+    class Permissions < Aegis::Permissions
+
+      role :guest
+      role :registered_user
+      role :moderator
+      role :administrator, :default_permission => :allow
+      
+      permission :edit_post do |user, post|
+        allow :registered_user do
+          post.creator == user      # a registered_user can only edit his own posts
+        end
+        allow :moderator
+      end
+      
+      permission :read_post do |post|
+        allow :everyone
+        deny :guest do
+          post.private?             # guests may not read private posts
+        end
+      end
+
+    end
+
+
+Now we assign roles to users. For this, the users table needs to have a string
+column +role_name+.
+
+    # app/models/user.rb
+    class User
+      has_role
+    end
+
+
+These permissions may be used in views and controllers:
+    
+    # app/views/posts/index.html.erb
+    @posts.each do |post|
+      <% if current_user.may_read_post? post %>
+        <%= render post %>
+        <% if current_user.may_edit_post? post %>
+          <%= link_to 'Edit', edit_post_path(post) %>
+        <% end %>
+      <% end %>
+    <% end %>
+
+
+    # app/controllers/posts_controller.rb
+    class PostsController
+      # ...
+
+      def update
+        @post = Post.find(params[:id])
+        current_user.may_edit_post! @post    # raises an Aegis::PermissionError for unauthorized access
+        # ...
+      end
+
+    end

data/Rakefile

@@ -0,0 +1,37 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the aegis gem.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the aegis plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Aegis'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "aegis"
+    gemspec.summary = "Role-based permissions for your user models."
+    gemspec.email = "github@makandra.de"
+    gemspec.homepage = "http://github.com/makandra/aegis"
+    gemspec.description = "Aegis is a role-based permission system, where all users are given a role. It is possible to define detailed and complex permissions for each role very easily."
+    gemspec.authors = ["Henning Koch"]
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+

data/VERSION

@@ -0,0 +1 @@
+1.1.1

data/aegis.gemspec

@@ -0,0 +1,93 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{aegis}
+  s.version = "1.1.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Henning Koch"]
+  s.date = %q{2009-05-29}
+  s.description = %q{Aegis is a role-based permission system, where all users are given a role. It is possible to define detailed and complex permissions for each role very easily.}
+  s.email = %q{github@makandra.de}
+  s.extra_rdoc_files = [
+    "README.rdoc"
+  ]
+  s.files = [
+    ".gitignore",
+     "MIT-LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "aegis.gemspec",
+     "lib/aegis.rb",
+     "lib/aegis/constants.rb",
+     "lib/aegis/has_role.rb",
+     "lib/aegis/normalization.rb",
+     "lib/aegis/permission_error.rb",
+     "lib/aegis/permission_evaluator.rb",
+     "lib/aegis/permissions.rb",
+     "lib/aegis/role.rb",
+     "lib/rails/active_record.rb",
+     "test/app_root/app/controllers/application_controller.rb",
+     "test/app_root/app/models/permissions.rb",
+     "test/app_root/app/models/soldier.rb",
+     "test/app_root/app/models/user.rb",
+     "test/app_root/config/boot.rb",
+     "test/app_root/config/database.yml",
+     "test/app_root/config/environment.rb",
+     "test/app_root/config/environments/in_memory.rb",
+     "test/app_root/config/environments/mysql.rb",
+     "test/app_root/config/environments/postgresql.rb",
+     "test/app_root/config/environments/sqlite.rb",
+     "test/app_root/config/environments/sqlite3.rb",
+     "test/app_root/config/routes.rb",
+     "test/app_root/db/migrate/20090408115228_create_users.rb",
+     "test/app_root/db/migrate/20090429075648_create_soldiers.rb",
+     "test/app_root/lib/console_with_fixtures.rb",
+     "test/app_root/log/.gitignore",
+     "test/app_root/script/console",
+     "test/has_role_options_test.rb",
+     "test/has_role_test.rb",
+     "test/permissions_test.rb",
+     "test/test_helper.rb",
+     "test/validation_test.rb"
+  ]
+  s.has_rdoc = true
+  s.homepage = %q{http://github.com/makandra/aegis}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.1}
+  s.summary = %q{Role-based permissions for your user models.}
+  s.test_files = [
+    "test/app_root/app/models/permissions.rb",
+     "test/app_root/app/models/soldier.rb",
+     "test/app_root/app/models/user.rb",
+     "test/app_root/app/controllers/application_controller.rb",
+     "test/app_root/config/environment.rb",
+     "test/app_root/config/environments/mysql.rb",
+     "test/app_root/config/environments/postgresql.rb",
+     "test/app_root/config/environments/sqlite3.rb",
+     "test/app_root/config/environments/in_memory.rb",
+     "test/app_root/config/environments/sqlite.rb",
+     "test/app_root/config/boot.rb",
+     "test/app_root/config/routes.rb",
+     "test/app_root/db/migrate/20090429075648_create_soldiers.rb",
+     "test/app_root/db/migrate/20090408115228_create_users.rb",
+     "test/app_root/lib/console_with_fixtures.rb",
+     "test/validation_test.rb",
+     "test/test_helper.rb",
+     "test/has_role_options_test.rb",
+     "test/has_role_test.rb",
+     "test/permissions_test.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

data/lib/aegis/constants.rb

@@ -0,0 +1,6 @@
+module Aegis
+  module Constants
+    EVERYONE_ROLE_NAME = :everyone
+    CRUD_VERBS = ["create", "read", "update", "destroy"]
+  end
+end

data/lib/aegis/has_role.rb

@@ -0,0 +1,77 @@
+module Aegis
+  module HasRole
+  
+    def validates_role_name(options = {})
+      validates_each :role_name do |record, attr, value|
+        options[:message] ||= ActiveRecord::Errors.default_error_messages[:inclusion]
+        role = ::Permissions.find_role_by_name(value)
+        record.errors.add attr, options[:message] if role.nil?
+      end
+    end
+    
+    alias_method :validates_role, :validates_role_name
+
+    def has_role(options = {})
+    
+      if options[:name_accessor]
+        options[:name_reader] = "#{options[:name_accessor]}"
+        options[:name_writer] = "#{options[:name_accessor]}="
+        options.delete(:name_accessor)
+      end
+    
+      self.class_eval do
+      
+        @aegis_role_name_reader = (options[:name_reader] || "role_name").to_sym
+        @aegis_role_name_writer = (options[:name_writer] || "role_name=").to_sym
+        
+        def aegis_role_name_reader
+          self.class.class_eval{ @aegis_role_name_reader }
+        end
+
+        def aegis_role_name_writer
+          self.class.class_eval{ @aegis_role_name_writer }
+        end
+
+        def aegis_role_name
+          send(aegis_role_name_reader)
+        end
+
+        def aegis_role_name=(value)
+          send(aegis_role_name_writer, value)
+        end
+
+        def role
+          ::Permissions.find_role_by_name!(aegis_role_name)
+        end
+        
+        def role=(role_or_name)
+          self.aegis_role_name = if role_or_name.is_a?(Aegis::Role)
+            role_or_name.name
+          else
+            role_or_name.to_s
+          end
+        end
+        
+        private
+    
+        # Delegate may_...? and may_...! methods to the user's role.
+        def method_missing_with_aegis_permissions(symb, *args)
+          method_name = symb.to_s
+          if method_name =~ /^may_(.+?)[\!\?]$/
+            role.send(symb, self, *args)
+          elsif method_name =~ /^(.*?)\?$/ && queried_role = ::Permissions.find_role_by_name($1)
+            role == queried_role
+          else
+            method_missing_without_aegis_permissions(symb, *args)
+          end
+        end
+        
+        alias_method_chain :method_missing, :aegis_permissions
+        
+      end
+
+    end
+  
+  end
+
+end

data/lib/aegis/normalization.rb

@@ -0,0 +1,26 @@
+module Aegis
+  class Normalization
+    
+    VERB_NORMALIZATIONS = {
+      "edit"   => "update",
+      "show"   => "read",
+      "list"   => "read",
+      "view"   => "read",
+      "delete" => "destroy",
+      "remove" => "destroy"
+    }
+    
+    def self.normalize_verb(verb)
+      VERB_NORMALIZATIONS[verb] || verb
+    end
+    
+    def self.normalize_permission(permission)
+      if permission =~ /^([^_]+?)_(.+?)$/
+        verb, target = $1, $2
+        permission = normalize_verb(verb) + "_" + target
+      end
+      permission
+    end
+    
+  end
+end

data/lib/aegis/permission_error.rb

@@ -0,0 +1,5 @@
+module Aegis
+  class PermissionError < StandardError
+
+  end
+end

data/lib/aegis/permission_evaluator.rb

@@ -0,0 +1,34 @@
+module Aegis
+  class PermissionEvaluator
+
+	def initialize(role)
+	  @role = role
+	end
+
+	def evaluate(permissions, rule_args)
+	  @result = @role.allow_by_default?
+	  permissions.each do |permission|
+		instance_exec(*rule_args, &permission)
+	  end
+	  @result
+	end
+
+	def allow(*role_name_or_names, &block)
+	  rule_encountered(role_name_or_names, true, &block)
+	end
+
+	def deny(*role_name_or_names, &block)
+	  rule_encountered(role_name_or_names, false, &block)
+	end
+
+	def rule_encountered(role_name_or_names, is_allow, &block)
+	  role_names = Array(role_name_or_names)
+	  if role_names.include?(@role.name) || role_names.include?(Aegis::Constants::EVERYONE_ROLE_NAME)
+		@result = (block ? block.call : true) 
+		@result = !@result unless is_allow
+	  end
+	end
+
+  end
+end
+

data/lib/aegis/permissions.rb

@@ -0,0 +1,111 @@
+module Aegis
+  class Permissions
+  
+    def self.inherited(base)
+      base.class_eval do
+        extend ClassMethods
+      end
+    end    
+
+    module ClassMethods
+    
+      @@roles_by_name = {}
+
+      # Example: @@permission_blocks[:update_users] = 
+	  #         [proc { allow :admin; deny :guest }, proc { deny :student }]
+	  @@permission_blocks = Hash.new { |hash, key| hash[key] = [] }
+ 
+      def role(role_name, options = {})
+        role_name = role_name.to_sym
+        role_name != Aegis::Constants::EVERYONE_ROLE_NAME or raise "Cannot define a role named: #{Aegis::Constants::EVERYONE_ROLE_NAME}"
+        @@roles_by_name[role_name] = Aegis::Role.new(role_name, self, options)
+      end
+      
+      def find_all_role_names
+        @@roles_by_name.keys
+      end
+      
+      def find_all_roles
+        @@roles_by_name.values.sort
+      end
+      
+      def find_role_by_name(name)
+        # cannot call :to_sym on nil or an empty string
+        if name.blank?
+          nil
+        else
+          @@roles_by_name[name.to_sym]
+        end
+      end
+      
+      def find_role_by_name!(name)
+        find_role_by_name(name) or raise "Undefined role: #{name}"
+      end
+      
+      def permission(*permission_name_or_names, &block)
+        permission_names = Array(permission_name_or_names).map(&:to_s)
+        permission_names.each do |permission_name|
+          add_split_crud_permission(permission_name, &block)
+        end
+      end
+      
+      def may?(role_or_role_name, permission, *args)
+        role = role_or_role_name.is_a?(Aegis::Role) ? role_or_role_name : find_role_by_name(role_or_role_name)
+        blocks = @@permission_blocks[permission.to_sym]
+        evaluate_permission_blocks(role, blocks, *args)
+      end
+      
+      def evaluate_permission_blocks(role, blocks, *args)
+		evaluator = Aegis::PermissionEvaluator.new(role)
+		evaluator.evaluate(blocks, args)
+      end
+      
+      def denied?(*args)
+        !allowed?(*args)
+      end
+      
+      private
+
+      def add_split_crud_permission(permission_name, &block)
+        if permission_name =~ /^crud_(.+?)$/
+          target = $1
+          Aegis::Constants::CRUD_VERBS.each do |verb|
+            add_normalized_permission("#{verb}_#{target}", &block)
+          end
+        else
+          add_normalized_permission(permission_name, &block)
+        end
+      end
+
+      def add_normalized_permission(permission_name, &block)
+        normalized_permission_name = Aegis::Normalization.normalize_permission(permission_name)
+        add_singularized_permission(normalized_permission_name, &block)
+      end
+      
+      def add_singularized_permission(permission_name, &block)
+        if permission_name =~ /^([^_]+?)_(.+?)$/
+          verb = $1
+          target = $2
+          singular_target = target.singularize
+          if singular_target.length < target.length
+            singular_block = lambda do |*args|
+		      args.delete_at 1
+			  instance_exec(*args, &block)
+            end
+            singular_permission_name = "#{verb}_#{singular_target}"
+            add_permission(singular_permission_name, &singular_block)
+          end
+        end
+        add_permission(permission_name, &block)
+      end
+      
+      def add_permission(permission_name, &block)
+        permission_name = permission_name.to_sym
+        @@permission_blocks[permission_name] << block
+      end
+ 
+    end # module ClassMethods
+    
+  end # class Permissions
+end # module Aegis
+

data/lib/aegis/role.rb

@@ -0,0 +1,55 @@
+module Aegis
+  class Role
+  
+    attr_reader :name, :default_permission
+          
+    # permissions is a hash like: permissions[:edit_user] = lambda { |user| ... }
+    def initialize(name, permissions, options)
+      @name = name
+      @permissions = permissions
+      @default_permission = options[:default_permission] == :allow ? :allow : :deny
+      freeze
+    end
+    
+    def allow_by_default?
+      @default_permission == :allow
+    end
+    
+    def may?(permission, *args)
+      # puts "may? #{permission}, #{args}"
+      @permissions.may?(self, permission, *args)
+    end
+    
+    def <=>(other)
+      name.to_s <=> other.name.to_s
+    end
+
+    def to_s
+      name.to_s.humanize
+    end
+    
+    def id
+      name.to_s
+    end
+
+    private
+    
+    def method_missing(symb, *args)
+      method_name = symb.to_s
+      if method_name =~ /^may_(.+)(\?|\!)$/
+        permission, severity = $1, $2
+        permission = Aegis::Normalization.normalize_permission(permission)
+        may = may?(permission, *args)
+        if severity == '!' && !may 
+          raise PermissionError, "Access denied: #{permission}" 
+        else
+          may
+        end
+      else
+        super
+      end
+    end
+        
+    
+  end
+end

data/lib/aegis.rb

@@ -0,0 +1,9 @@
+# Include hook code here
+require 'aegis/constants'
+require 'aegis/normalization'
+require 'aegis/permission_error'
+require 'aegis/role'
+require 'aegis/permissions'
+require 'aegis/has_role'
+require 'rails/active_record'
+

data/lib/rails/active_record.rb

@@ -0,0 +1,5 @@
+ActiveRecord::Base.class_eval do
+
+  extend Aegis::HasRole
+  
+end

data/test/app_root/app/controllers/application_controller.rb

@@ -0,0 +1,2 @@
+class ApplicationController < ActionController::Base
+end

data/test/app_root/app/models/permissions.rb

@@ -0,0 +1,49 @@
+
+class Permissions < Aegis::Permissions
+
+  role :guest
+  role :student
+  role :admin, :default_permission => :allow
+  
+  permission :use_empty do
+  end
+  
+  permission :use_simple do
+    allow :student
+    deny :admin
+  end
+
+  permission :update_users do
+    allow :student
+    deny :admin
+  end
+  
+  permission :crud_projects do
+    allow :student
+  end
+  
+  permission :edit_drinks do
+    allow :student
+    deny :admin
+  end
+  
+  permission :hug do
+    allow :everyone
+  end
+  
+  permission :divide do |user, left, right|
+    allow :student do
+      right != 0
+    end
+  end
+  
+  permission :draw do
+    allow :everyone
+  end
+  
+  permission :draw do
+    deny :student
+    deny :admin
+  end
+  
+end

data/test/app_root/app/models/soldier.rb

@@ -0,0 +1,5 @@
+class Soldier < ActiveRecord::Base
+
+  has_role :name_accessor => "rank"
+
+end

data/test/app_root/app/models/user.rb

@@ -0,0 +1,6 @@
+class User < ActiveRecord::Base
+
+  has_role
+  validates_role_name
+
+end

data/test/app_root/config/boot.rb

@@ -0,0 +1,114 @@
+# Allow customization of the rails framework path
+RAILS_FRAMEWORK_ROOT = (ENV['RAILS_FRAMEWORK_ROOT'] || "#{File.dirname(__FILE__)}/../../../../../../vendor/rails") unless defined?(RAILS_FRAMEWORK_ROOT) 
+
+# Don't change this file!
+# Configure your app in config/environment.rb and config/environments/*.rb
+
+RAILS_ROOT = "#{File.dirname(__FILE__)}/.." unless defined?(RAILS_ROOT)
+
+module Rails
+  class << self
+    def boot!
+      unless booted?
+        preinitialize
+        pick_boot.run
+      end
+    end
+
+    def booted?
+      defined? Rails::Initializer
+    end
+
+    def pick_boot
+      (vendor_rails? ? VendorBoot : GemBoot).new
+    end
+
+    def vendor_rails?
+      File.exist?(RAILS_FRAMEWORK_ROOT)
+    end
+
+    def preinitialize
+      load(preinitializer_path) if File.exist?(preinitializer_path)
+    end
+
+    def preinitializer_path
+      "#{RAILS_ROOT}/config/preinitializer.rb"
+    end
+  end
+
+  class Boot
+    def run
+      load_initializer
+      Rails::Initializer.run(:set_load_path)
+    end
+  end
+
+  class VendorBoot < Boot
+    def load_initializer
+      require "#{RAILS_FRAMEWORK_ROOT}/railties/lib/initializer"
+      Rails::Initializer.run(:install_gem_spec_stubs)
+    end
+  end
+
+  class GemBoot < Boot
+    def load_initializer
+      self.class.load_rubygems
+      load_rails_gem
+      require 'initializer'
+    end
+
+    def load_rails_gem
+      if version = self.class.gem_version
+        gem 'rails', version
+      else
+        gem 'rails'
+      end
+    rescue Gem::LoadError => load_error
+      $stderr.puts %(Missing the Rails #{version} gem. Please `gem install -v=#{version} rails`, update your RAILS_GEM_VERSION setting in config/environment.rb for the Rails version you do have installed, or comment out RAILS_GEM_VERSION to use the latest version installed.)
+      exit 1
+    end
+
+    class << self
+      def rubygems_version
+        Gem::RubyGemsVersion rescue nil
+      end
+
+      def gem_version
+        if defined? RAILS_GEM_VERSION
+          RAILS_GEM_VERSION
+        elsif ENV.include?('RAILS_GEM_VERSION')
+          ENV['RAILS_GEM_VERSION']
+        else
+          parse_gem_version(read_environment_rb)
+        end
+      end
+
+      def load_rubygems
+        require 'rubygems'
+        min_version = '1.1.1'
+        unless rubygems_version >= min_version
+          $stderr.puts %Q(Rails requires RubyGems >= #{min_version} (you have #{rubygems_version}). Please `gem update --system` and try again.)
+          exit 1
+        end
+ 
+      rescue LoadError
+        $stderr.puts %Q(Rails requires RubyGems >= #{min_version}. Please install RubyGems and try again: http://rubygems.rubyforge.org)
+        exit 1
+      end
+
+      def parse_gem_version(text)
+        $1 if text =~ /^[^#]*RAILS_GEM_VERSION\s*=\s*["']([!~<>=]*\s*[\d.]+)["']/
+      end
+
+      private
+        def read_environment_rb
+          environment_rb = "#{RAILS_ROOT}/config/environment.rb"
+          environment_rb = "#{HELPER_RAILS_ROOT}/config/environment.rb" unless File.exists?(environment_rb)
+          File.read(environment_rb)
+        end
+    end
+  end
+end
+
+# All that for this:
+Rails.boot!

data/test/app_root/config/database.yml

@@ -0,0 +1,21 @@
+in_memory:
+  adapter: sqlite3
+  database: ":memory:"
+  verbosity: quiet
+sqlite:
+  adapter: sqlite
+  dbfile: plugin_test.sqlite.db
+sqlite3:
+  adapter: sqlite3
+  dbfile: plugin_test.sqlite3.db
+postgresql:
+  adapter: postgresql
+  username: postgres
+  password: postgres
+  database: plugin_test
+mysql:
+  adapter: mysql
+  host: localhost
+  username: root
+  password:
+  database: plugin_test

data/test/app_root/config/environment.rb

@@ -0,0 +1,14 @@
+require File.join(File.dirname(__FILE__), 'boot')
+
+Rails::Initializer.run do |config|
+  config.cache_classes = false
+  config.whiny_nils = true
+  config.action_controller.session = { :key => "_myapp_session", :secret => "gwirofjweroijger8924rt2zfwehfuiwehb1378rifowenfoqwphf23" }
+  config.plugin_locators.unshift(
+    Class.new(Rails::Plugin::Locator) do
+      def plugins
+        [Rails::Plugin.new(File.expand_path('.'))]
+      end
+    end
+  ) unless defined?(PluginTestHelper::PluginLocator)
+end

data/test/app_root/config/routes.rb

@@ -0,0 +1,4 @@
+ActionController::Routing::Routes.draw do |map|
+  map.connect ':controller/:action/:id'
+  map.connect ':controller/:action/:id.:format'
+end

data/test/app_root/db/migrate/20090408115228_create_users.rb

@@ -0,0 +1,14 @@
+class CreateUsers < ActiveRecord::Migration
+
+  def self.up
+    create_table :users do |t|
+      t.string "role_name"
+      t.timestamps
+    end
+  end
+
+  def self.down
+    drop_table :users
+  end
+  
+end

data/test/app_root/db/migrate/20090429075648_create_soldiers.rb

@@ -0,0 +1,16 @@
+class CreateSoldiers < ActiveRecord::Migration
+
+  def self.up
+  
+    create_table :soldiers do |t|
+      t.string :rank
+      t.timestamps
+    end
+    
+  end
+
+  def self.down
+    drop_table :soldiers
+  end
+  
+end

data/test/app_root/lib/console_with_fixtures.rb

@@ -0,0 +1,4 @@
+# Loads fixtures into the database when running the test app via the console
+(ENV['FIXTURES'] ? ENV['FIXTURES'].split(/,/) : Dir.glob(File.join(Rails.root, '../fixtures/*.{yml,csv}'))).each do |fixture_file|
+  Fixtures.create_fixtures(File.join(Rails.root, '../fixtures'), File.basename(fixture_file, '.*'))
+end

data/test/app_root/log/.gitignore

@@ -0,0 +1 @@
+*.log

data/test/app_root/script/console

@@ -0,0 +1,7 @@
+irb = RUBY_PLATFORM =~ /(:?mswin|mingw)/ ? 'irb.bat' : 'irb'
+libs =  " -r irb/completion"
+libs << " -r test/test_helper"
+libs << " -r console_app"
+libs << " -r console_with_helpers"
+libs << " -r console_with_fixtures"
+exec "#{irb} #{libs} --simple-prompt"

data/test/has_role_options_test.rb

@@ -0,0 +1,28 @@
+require "test/test_helper"
+
+class HasRoleOptionsTest < ActiveSupport::TestCase
+
+  context "A record with a custom role field" do
+
+    setup do 
+      @soldier = Soldier.new
+    end
+    
+    should "allow its role to be written and read" do
+      @soldier.role = "guest"
+      assert "guest", @soldier.role.name
+    end
+    
+    should "store the role name in the custom field" do
+      assert "guest", @soldier.rank
+    end
+    
+    should "still work with permissions" do
+      @soldier.role = "guest"
+      assert @soldier.may_hug?
+      assert !@soldier.may_update_users?
+    end
+    
+  end
+
+end

data/test/has_role_test.rb

@@ -0,0 +1,39 @@
+require "test/test_helper"
+
+class HasRoleTest < ActiveSupport::TestCase
+
+  context "Objects that have an aegis role" do
+
+    setup do 
+      @guest = User.new(:role_name => "guest")
+      @student = User.new(:role_name => "student")
+      @admin = User.new(:role_name => "admin")
+    end
+    
+    should "know their role" do
+      assert :guest, @guest.role.name
+      assert :student, @student.role.name
+      assert :admin, @admin.role.name
+    end
+    
+    should "know if they belong to a role" do
+      assert @guest.guest?
+      assert !@guest.student?
+      assert !@guest.admin?
+      assert !@student.guest?
+      assert @student.student?
+      assert !@student.admin?
+      assert !@admin.guest?
+      assert !@admin.student?
+      assert @admin.admin?
+    end
+    
+    should "still behave as usual when a method ending in a '?' does not map to a role query" do
+      assert_raise NoMethodError do
+        @guest.nonexisting_method?
+      end
+    end
+    
+  end
+
+end

data/test/permissions_test.rb

@@ -0,0 +1,92 @@
+require "test/test_helper"
+
+class PermissionsTest < ActiveSupport::TestCase
+
+  context "Aegis permissions" do
+
+    setup do 
+      @guest = User.new(:role_name => "guest")
+      @student = User.new(:role_name => "student")
+      @admin = User.new(:role_name => "admin")
+    end
+    
+    should "use the default permission for actions without any allow or grant directives" do
+      assert !@guest.may_use_empty?
+      assert !@student.may_use_empty?
+      assert @admin.may_use_empty?
+    end
+    
+    should "understand simple allow and deny directives" do
+      assert !@guest.may_use_simple?
+      assert @student.may_use_simple?
+      assert !@admin.may_use_simple?
+    end
+    
+    should 'raise exceptions when a denied action is queried with an exclamation mark' do
+      assert_raise Aegis::PermissionError do
+        @guest.may_use_simple!
+      end
+      assert_raise Aegis::PermissionError do
+        @admin.may_use_simple!
+      end
+    end
+    
+    should 'do nothing if an allowed action is queried with an exclamation mark' do
+      assert_nothing_raised do
+        @student.may_use_simple!
+      end
+    end
+    
+    should "implicate the singular form of an action described in plural form" do
+      assert !@guest.may_update_users?
+      assert !@guest.may_update_user?("foo")
+      assert @student.may_update_users?
+      assert @student.may_update_user?("foo")
+      assert !@admin.may_update_users?
+      assert !@admin.may_update_user?("foo")
+    end
+    
+    should 'implicate create, read, update and destroy forms for actions named "crud_..."' do
+      assert @student.may_create_projects?
+      assert @student.may_read_projects?
+      assert @student.may_update_projects?
+      assert @student.may_destroy_projects?
+    end
+    
+    should 'perform normalization of CRUD verbs (e.g. "edit" and "update")' do
+      assert !@guest.may_edit_drinks?
+      assert @student.may_edit_drinks?
+      assert !@admin.may_edit_drinks?
+      assert !@guest.may_update_drinks?
+      assert @student.may_update_drinks?
+      assert !@admin.may_update_drinks?
+    end
+    
+    should "be able to grant or deny actions to all roles using :everyone" do
+      assert @guest.may_hug?
+      assert @student.may_hug?
+      assert @admin.may_hug?
+    end
+    
+    should "allow the definition of parametrized actions" do
+      assert !@guest.may_divide?(10, 2)
+      assert @student.may_divide?(10, 2)
+      assert !@student.may_divide?(10, 0)
+      assert @admin.may_divide?(10, 2)
+      assert @admin.may_divide?(10, 0)
+    end
+    
+    should 'use default permissions for undefined actions' do
+      !@student.may_do_undefined_stuff?("foo")
+      @admin.may_do_undefined_stuff?("foo")
+    end
+    
+    should 'overshadow previous action definitions with the same name' do
+      assert @guest.may_draw?
+      assert !@student.may_draw?
+      assert !@admin.may_draw?
+    end
+    
+  end
+
+end

data/test/test_helper.rb

@@ -0,0 +1,23 @@
+# Set the default environment to sqlite3's in_memory database
+ENV['RAILS_ENV'] ||= 'in_memory'
+
+# Load the Rails environment and testing framework
+require "#{File.dirname(__FILE__)}/app_root/config/environment"
+require "#{File.dirname(__FILE__)}/../lib/aegis"
+require 'test_help'
+require 'action_view/test_case' # Load additional test classes not done automatically by < Rails 2.2.2
+
+require "shoulda"
+
+# Undo changes to RAILS_ENV
+silence_warnings {RAILS_ENV = ENV['RAILS_ENV']}
+
+# Run the migrations
+ActiveRecord::Migrator.migrate("#{Rails.root}/db/migrate")
+
+# Set default fixture loading properties
+ActiveSupport::TestCase.class_eval do
+  self.use_transactional_fixtures = true
+  self.use_instantiated_fixtures = false
+  self.fixture_path = "#{File.dirname(__FILE__)}/fixtures"
+end

data/test/validation_test.rb

@@ -0,0 +1,49 @@
+require "test/test_helper"
+
+class ValidationTest < ActiveSupport::TestCase
+
+  context "A model that has and validates its role" do
+
+    setup do 
+      @user = User.new()
+    end
+    
+    context "that has a role_name mapping to a role" do
+      
+      setup do
+        @user.role_name = "admin"
+      end
+      
+      should "be valid" do
+        assert @user.valid?
+      end
+      
+    end
+    
+    context "that has a blank role_name" do
+      
+      setup do
+        @user.role_name = ""
+      end
+      
+      should "not be valid" do
+        assert !@user.valid?
+      end
+      
+    end
+    
+    context "that has a role_name not mapping to a role" do
+      
+      setup do
+        @user.role_name = "nonexisting_role_name"
+      end
+      
+      should "not be valid" do
+        assert !@user.valid?
+      end
+      
+    end
+    
+  end
+
+end

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification 
+name: makandra-aegis
+version: !ruby/object:Gem::Version 
+  version: 1.1.1
+platform: ruby
+authors: 
+- Henning Koch
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-05-29 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: Aegis is a role-based permission system, where all users are given a role. It is possible to define detailed and complex permissions for each role very easily.
+email: github@makandra.de
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- .gitignore
+- MIT-LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- aegis.gemspec
+- lib/aegis.rb
+- lib/aegis/constants.rb
+- lib/aegis/has_role.rb
+- lib/aegis/normalization.rb
+- lib/aegis/permission_error.rb
+- lib/aegis/permission_evaluator.rb
+- lib/aegis/permissions.rb
+- lib/aegis/role.rb
+- lib/rails/active_record.rb
+- test/app_root/app/controllers/application_controller.rb
+- test/app_root/app/models/permissions.rb
+- test/app_root/app/models/soldier.rb
+- test/app_root/app/models/user.rb
+- test/app_root/config/boot.rb
+- test/app_root/config/database.yml
+- test/app_root/config/environment.rb
+- test/app_root/config/environments/in_memory.rb
+- test/app_root/config/environments/mysql.rb
+- test/app_root/config/environments/postgresql.rb
+- test/app_root/config/environments/sqlite.rb
+- test/app_root/config/environments/sqlite3.rb
+- test/app_root/config/routes.rb
+- test/app_root/db/migrate/20090408115228_create_users.rb
+- test/app_root/db/migrate/20090429075648_create_soldiers.rb
+- test/app_root/lib/console_with_fixtures.rb
+- test/app_root/log/.gitignore
+- test/app_root/script/console
+- test/has_role_options_test.rb
+- test/has_role_test.rb
+- test/permissions_test.rb
+- test/test_helper.rb
+- test/validation_test.rb
+has_rdoc: true
+homepage: http://github.com/makandra/aegis
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Role-based permissions for your user models.
+test_files: 
+- test/app_root/app/models/permissions.rb
+- test/app_root/app/models/soldier.rb
+- test/app_root/app/models/user.rb
+- test/app_root/app/controllers/application_controller.rb
+- test/app_root/config/environment.rb
+- test/app_root/config/environments/mysql.rb
+- test/app_root/config/environments/postgresql.rb
+- test/app_root/config/environments/sqlite3.rb
+- test/app_root/config/environments/in_memory.rb
+- test/app_root/config/environments/sqlite.rb
+- test/app_root/config/boot.rb
+- test/app_root/config/routes.rb
+- test/app_root/db/migrate/20090429075648_create_soldiers.rb
+- test/app_root/db/migrate/20090408115228_create_users.rb
+- test/app_root/lib/console_with_fixtures.rb
+- test/validation_test.rb
+- test/test_helper.rb
+- test/has_role_options_test.rb
+- test/has_role_test.rb
+- test/permissions_test.rb