cjbottaro-aegis 1.3.0

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,182 @@
+= Abstract
+
+Aegis modified to support multiple roles per actors based on context and your data model hierarchy.
+
+This file will only describe the new functionality I added to Aegis.  See the original Aegis README.rdoc here:  http://github.com/makandra/aegis/tree/master
+
+== Description (aka longer abstract)
+
+Aegis is a pretty simple permission system:  a user belongs to a single role, and a role has many permissions associated with it.
+
+My work requires a user to have multiple roles.  Which one is chosen at any given time is based on a context.  For example, we want <tt>user:123</tt> to have role <tt>:writer</tt> in <tt>forum:abc</tt>, but role <tt>:reader</tt> in <tt>forum:xyz</tt>.
+
+Furthermore, we want to have a role hierarchy that follows our object model.  If no role is defined for a user for a given context, then we ask if that context has a parent and if a role is defined there (again for that user).  For example, does <tt>user:123</tt> have a role for <tt>forum:ijk</tt>?  No.  Does <tt>forum:ijk</tt> have a parent?  Yes, it is <tt>account:1</tt>.  Does <tt>user:123</tt> have a role in <tt>account:1</tt>?  Yes, it is <tt>:writer</tt>.
+
+Note that all previous Aegis functionality still exists and works (none of the existing unit tests were changed at all).
+
+== Installation
+
+Add the following to your <tt>Initializer.run</tt> block in your <tt>environment.rb</tt>:
+    config.gem 'cjbottaro-aegis', :lib => 'aegis', :source => 'http://gems.github.com'
+Then do a 
+    sudo rake gems:install
+
+Alternatively, use
+    sudo gem sources -a http://gems.github.com
+    sudo gem install cjbottaro-aegis
+
+== Database Migration
+
+You need to create a table to keep track of which actors are assigned which roles for each context.
+
+  class CreateRoleAssignments < ActiveRecord::Migration
+    def self.up
+      create_table :role_assignments do |t|
+        t.string  :actor_type,    :null => false
+        t.integer :actor_id,      :null => false
+        t.string  :role_name,     :null => false
+        t.string  :context_type,  :null => false
+        t.integer :context_id,    :null => false
+        t.timestamps
+      end
+    end
+    
+    def self.down
+      drop_table :role_assignments
+    end
+  end
+
+== Example
+
+First, let's define a data model for our example.  An Account has many Users and Forums.  A Forum has many Posts.
+
+  Account
+  |-> User
+  |-> Forum
+      |-> Post
+
+Now let's assign some roles for our user.
+
+  user = User.find_by_name("chris")
+  forum = Forum.find_by_name("coping with metrosexuality")
+  RoleAssignment.create! :actor     => user,
+                         :role_name => :admin,
+                         :context   => forum
+  post = forum.posts.find_by_title("acceptance")
+  RoleAssignment.create! :actor     => user,
+                         :role_name => :reader,
+                         :context   => post
+
+Now we can query permissions.
+
+  user.may_create_posts_in?(forum) # user has role of :admin in this forum.
+  => true
+  
+  user.may_edit_content_for?(post) # user has role of :reader for this post.
+  => false
+  
+  post = forum.posts.find_by_title("denial")
+  user.may_edit_content_for?(post) # user does not have role for this post, so we look at that
+                                   # post's parent and see he is a an :admin there.
+  => true
+  
+The syntax is very similar to normal Aegis except you can suffix permission queries with <tt>_in?</tt> or <tt>_for?</tt> and the last argument to the query is the context.  So permission queries that accept parameters work like normal, you just pass in the context as the last parameter.
+
+== How does Aegis know the object model hierarchy?
+
+First way... you specify the hierarchy as a hash where the key is a class name and the value is an association name that invokes the parent.
+
+  class User < ActiveRecord::Base
+    has_role :hierarchy => { "Post" => "forum",
+                             "Forum" => "account" }
+  end
+
+Second way... you specify a single association name that will always return a model's parent.
+
+  class User < ActiveRecord::Base
+    has_role :hierarchy_accessor => "parent"
+  end
+  
+  class Post < ActiveRecord::Base
+    belongs_to :forum
+    def parent
+      forum
+    end
+  end
+  
+  class Forum < ActiveRecord::Base
+    belongs_to :account
+    def parent
+      account
+    end
+  end
+
+== Forcing certain roles under specific conditions
+
+My work had an additional requirement that if User#is_admin? is true, then that user should always have the role of <tt>:superuser</tt>, regardless of the context.
+
+  class User < ActiveRecord::Base
+    has_role :force_superuser_if => Proc.new{ |user| user.is_admin? }
+  end
+  
+  user = User.first(:conditions => { :is_admin => true })
+  user.role_in(anything)
+  => :superuser
+  
+  user.may_edit_content_for?(anything)
+  => true
+
+The format of the key is special.  It must be of the form <tt>force_<role_name>_if</tt>.  There can be multiple keys of this form.  The role is determined by the first one who's Proc returns true.  They are evaluated in random order (thus is the nature of Hashes).
+
+== Optimizations
+
+We don't want to read the role assignments from the database every time we do a permission check.  The solution to this is to read them once when the user logs in, store it in the session, then load from the session on each request.
+
+In your login controller/action...
+
+  if successful_login?
+    session[:permissions] = current_user.role_assignments_hash
+  else
+    ...
+  end
+
+In your controller/action that checks if a user is logged in...
+
+  if logged_in?
+    current_user.role_assignments_override = session[:permissions]
+  else
+    ...
+  end
+    
+This way the role assignments are only read when a user logs in.
+
+== Associating permissions to contexts
+
+Now that we have contexts, one might think we should be able to say only certain permissions make sense in given contexts.
+
+  Permissions < Aegis::Permissions
+    permission :delete_forum do
+      context "Account"
+      allow :admin
+    end
+  end
+  
+  user = User.find(...)
+  post = Post.find(...)
+  
+  user.may_delete_forum(post)
+  => Exception, "permission :delete_forum does not make sense for Post"
+
+Note that you can specify multiple contexts...
+
+  Permissions < Aegis::Permissions
+    permission :some_permission do
+      contexts "Classname1", "Classname2"
+      allow :admin
+    end
+  end
+
+=== Author
+
+Christopher J. Bottaro
+http://github.com/cjbottaro

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.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.3.0

data/aegis.gemspec

@@ -0,0 +1,117 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE
+# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{aegis}
+  s.version = "1.3.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Henning Koch"]
+  s.date = %q{2009-09-07}
+  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/meta_class.rb",
+     "lib/aegis/normalization.rb",
+     "lib/aegis/permission_error.rb",
+     "lib/aegis/permission_evaluator.rb",
+     "lib/aegis/permissions.rb",
+     "lib/aegis/role.rb",
+     "lib/aegis/role_assignments.rb",
+     "lib/rails/active_record.rb",
+     "test/app_root/app/controllers/application_controller.rb",
+     "test/app_root/app/models/account.rb",
+     "test/app_root/app/models/forum.rb",
+     "test/app_root/app/models/permissions.rb",
+     "test/app_root/app/models/post.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/db/migrate/20090903234709_create_role_assignments.rb",
+     "test/app_root/db/migrate/20090903234759_create_accounts.rb",
+     "test/app_root/db/migrate/20090903234821_create_forums.rb",
+     "test/app_root/db/migrate/20090903234828_create_posts.rb",
+     "test/app_root/lib/console_with_fixtures.rb",
+     "test/app_root/log/.gitignore",
+     "test/app_root/script/console",
+     "test/fixtures/accounts.yml",
+     "test/fixtures/forums.yml",
+     "test/fixtures/posts.yml",
+     "test/fixtures/role_assignments.yml",
+     "test/fixtures/users.yml",
+     "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.2}
+  s.summary = %q{Role-based permissions for your user models.}
+  s.test_files = [
+    "test/app_root/app/controllers/application_controller.rb",
+     "test/app_root/app/models/account.rb",
+     "test/app_root/app/models/forum.rb",
+     "test/app_root/app/models/permissions.rb",
+     "test/app_root/app/models/post.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/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/db/migrate/20090903234709_create_role_assignments.rb",
+     "test/app_root/db/migrate/20090903234759_create_accounts.rb",
+     "test/app_root/db/migrate/20090903234821_create_forums.rb",
+     "test/app_root/db/migrate/20090903234828_create_posts.rb",
+     "test/app_root/lib/console_with_fixtures.rb",
+     "test/has_role_options_test.rb",
+     "test/has_role_test.rb",
+     "test/permissions_test.rb",
+     "test/test_helper.rb",
+     "test/validation_test.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

data/lib/aegis.rb

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

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,156 @@
+module Aegis
+  module HasRole
+    
+    def self.extended(mod)
+      mod.send(:extend,  ClassMethods)
+    end
+    
+    module ClassMethods
+    
+      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
+        
+        @aegis_role_name_reader        = (options[:name_reader] || "role_name").to_sym
+        @aegis_role_name_writer        = (options[:name_writer] || "role_name=").to_sym
+        @aegis_role_hierarchy          = (options[:hierarchy]   || {})
+        @aegis_role_hierarchy_accessor = (options[:hierarchy_accessor])
+        @aegis_forced_roles            = options.inject({}) do |memo, (k, v)|
+          (m = k.to_s.match(/force_(.+)_if/)) and (memo[v] = m[1])
+          memo
+        end
+        
+        meta_eval do
+          attr_reader :aegis_role_name_reader
+          attr_reader :aegis_role_name_writer
+          attr_reader :aegis_role_hierarchy
+          attr_reader :aegis_role_hierarchy_accessor
+          attr_reader :aegis_forced_roles
+        end
+        
+        has_many :role_assignments, :class_name  => "Aegis::RoleAssignment",
+                                    :as          => "actor"
+        
+        attr_writer :role_assignments_override
+        
+        include(InstanceMethods)
+        
+        alias_method_chain :method_missing, :aegis_permissions
+      end
+      
+      alias_method :has_roles, :has_role
+      
+    end # module ClassMethods
+    
+    module InstanceMethods
+        
+      def aegis_role_name_reader
+        self.class.aegis_role_name_reader
+      end
+
+      def aegis_role_name_writer
+        self.class.aegis_role_name_writer
+      end
+      
+      def aegis_role_hierarchy
+        self.class.aegis_role_hierarchy
+      end
+      
+      def aegis_role_hierarchy_accessor
+        self.class.aegis_role_hierarchy_accessor
+      end
+      
+      def aegis_forced_roles
+        self.class.aegis_forced_roles
+      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
+        (forced_role = role_forced) and return forced_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
+      
+      def role_in(context, tried_contexts = [])
+        (forced_role = role_forced) and return forced_role
+        context_key = "#{context.class}:#{context.id}"
+        tried_contexts << context_key
+        roles_by_context = role_assignments_hash
+        if roles_by_context.has_key?(context_key)
+          ::Permissions.find_role_by_name!(roles_by_context[context_key])
+        elsif !aegis_role_hierarchy.blank? and (parent_class_accessor = aegis_role_hierarchy[context.class.name])
+          role_in(context.send(parent_class_accessor), tried_contexts)
+        elsif aegis_role_hierarchy_accessor and context.respond_to?(aegis_role_hierarchy_accessor)
+          role_in(context.send(aegis_role_hierarchy_accessor), tried_contexts)
+        else
+          actor_key = "#{self.class}:#{self.id}"
+          tried_contexts = tried_contexts.join(", ")
+          raise Aegis::PermissionError, "cannot find role for #{actor_key} in #{tried_contexts}"
+        end
+      end
+      
+      def role_assignments_hash(*args)
+        return @role_assignments_override unless @role_assignments_override.blank?
+        role_assignments.inject({}) do |memo, role_assignment|
+          memo[role_assignment.context_key] = role_assignment.role_name
+          memo
+        end
+      end
+      
+      def role_forced
+        aegis_forced_roles.each do |proc, role_name|
+          return role_name if proc.call(self)
+        end
+        nil
+      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_(.+?)_in[\!\?]$/
+          #method_name = method_name[0...-4] + method_name[-1, 1] # may_edit_post_in? => may_edit_post?
+          role_in(args.first).send(method_name, self, *args)
+        elsif 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
+      
+    end # InstanceMethods
+      
+  end # module HasRole
+  
+end # module Aegis