rbacanable 0.2

data/.document

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

data/.gitignore

@@ -0,0 +1,22 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC
+tmp

data/Changes.rdoc

@@ -0,0 +1,141 @@
+= RBACanable 
+=== Canable (by John Nunemaker) with a Role Based Access System 
+
+== How the system used to work
+
+The User class or whichever object needed to be authorized against an action would include <tt>Canable::Cans</tt>. Objects being manipulated that needed protection would include <tt>Canable::Ables</tt>, and you would override the <tt>viewable_by?(user)</tt> methods to implement the various permissions governing that resource and the user trying to access it.
+
+== How RBACanable works now
+
+RBACanable is significantly different than the original Canable and unfortunately not compatible with existing code that uses Canable. The original Canable was oriented so that each resource (an object including <tt>Canable::Able</tt>) managed it's own permissions. RBACanable is oriented in the opposite way, where each object that wants to preform an action and needs authorization manages the permissions that govern it. This is necessary because each one of these action-performing objects (called Actors in RBACanable) get their governing rules from a series of Roles (any module including <tt>Canable::Role</tt>).
+
+== Actors
+
+Whatever class(es) you want all permissions to run through should include <tt>Canable::Actor</tt> instad of <tt>Canable::Cans</tt>.
+
+    class User > ActiveRecord::Base
+      include Canable::Actor
+	  default_role :employee
+    end
+
+Actors represent objects in the system that want to preform an action. An actor's abilities are defined by the role(s) it plays.
+
+== Roles
+
+The rules that govern your actors are defined in modules extending <tt>Canable::Role</tt> and/or each other.
+
+	module EmployeeRole
+	  include Canable::Role
+	  default_response false
+	end
+	
+	module ManagerRole
+	  include Canable::Role
+	  default_response true
+	end
+	
+== Ables
+
+    class Article
+      include MongoMapper::Document
+      include Canable::Ables
+    end
+
+Including Canable::Ables adds the able methods to the class including it. In this instance, any article instance now has viewable_by?(actor), creatable_by?(actor), updatable_by?(actor) and destroyable_by?(actor). Now
+
+Lets say an article can be viewed and created by anyone, but only updated or destroyed by the user that created the article. To do that, you could leave viewable_by? and creatable_by? alone as they default to true and just override the other methods.
+
+    class Article
+      include MongoMapper::Document
+      include Canable::Ables
+      userstamps! # adds creator and updater
+      
+      def updatable_by?(user)
+        creator == user
+      end
+      
+      def destroyable_by?(user)
+        updatable_by?(user)
+      end
+    end
+
+Lets look at some sample code now:
+
+    john = User.create(:name => 'John')
+    steve = User.create(:name =. 'Steve')
+    
+    ruby = Article.new(:title => 'Ruby')
+    john.can_create?(ruby) # true
+    steve.can_create?(ruby) # true
+    
+    ruby.creator = john
+    ruby.save
+    
+    john.can_view?(ruby) # true
+    steve.can_view?(ruby) # true
+    
+    john.can_update?(ruby) # true
+    steve.can_update?(ruby) # false
+    
+    john.can_destroy?(ruby) # true
+    steve.can_destroy?(ruby) # false
+    
+Now we can implement our permissions for each resource and then always check whether a user can or cannot do something. This makes it all really easy to test. Next, how would you use this in the controller.
+
+== Enforcers
+
+    class ApplicationController
+      include Canable::Enforcers
+    end
+
+Including Canable::Enforcers adds an enforce permission method for each of the actions defined (by default view/create/update/destroy). It is the same thing as doing this for each Canable action:
+
+    class ApplicationController
+      include Canable::Enforcers
+
+      delegate :can_view?, :to => :current_user
+      helper_method :can_view? # so you can use it in your views
+      hide_action :can_view?
+
+      private
+        def enforce_view_permission(resource)
+          raise Canable::Transgression unless can_view?(resource)
+        end
+    end
+
+Which means you can use it like this:
+
+    class ArticlesController < ApplicationController
+      def show
+        @article = Article.find!(params[:id])
+        enforce_view_permission(@article)
+      end
+    end
+
+If the user can_view? the article, all is well. If not, a Canable::Transgression is raised which you can decide how to handle (show 404, slap them on the wrist, etc.).
+
+== Adding Your Own Actions
+
+You can add your own actions like this:
+
+    Canable.add(:publish, :publishable)
+
+The first parameter is the can method (ie: can_publish?) and the second is the able method (ie: publishable_by?). 
+
+== Review
+
+So, lets review: cans go on user model, ables go on everything, you override ables in each model where you want to enforce permissions, and enforcers go after each time you find or initialize an object in a controller. Bing, bang, boom.
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2010 John Nunemaker. See LICENSE for details.

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 John Nunemaker
+
+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,164 @@
+= RBACanable 
+=== Canable (by John Nunemaker) with a Role Based Access System latched on
+
+Simple permissions system that features easily actors, resources for actors to manipulate, and roles actors play to define their permissions.
+
+
+== Ables
+
+Ables are the resource objets that an actor will want to manipulate.
+
+    class Article
+      include MongoMapper::Document
+      include Canable::Ables
+    end
+
+Including Canable::Ables adds the able methods to the class including it. In this instance, any article instance now has viewable_by?(actor), creatable_by?(actor), updatable_by?(actor) and destroyable_by?(actor).
+
+== Roles
+
+The rules that govern your actors are defined in roles. Roles are modules that extend <tt>Canable::Role</tt> and/or other roles. Roles can be nested as deep and mixed and matched using Ruby's mixin system, as they are just normal Ruby modules that carry permission sets with them. The order they are included in each other will define the final permission set of the role: Roles included after (on a lower line) than others will override the settings of the others.
+	module Canable::Roles
+  	  module EmployeeRole
+  	    include Canable::Role
+  	    default_response false
+    
+	    def can_view_article?(article)
+	      true
+	    end 
+
+	    def can_update_article?(article)
+		  article.owner == @name
+	    end
+  
+	    def can_destroy_article?(article)
+	      self.can_update_article?(article)
+	    end
+	  end
+
+	  module ManagerRole
+	    include Canable::Role
+	    include EmployeeRole
+
+	    def can_update_article?(article)
+	      true
+	    end
+  
+	    def can_destroy_article(article)
+	      article.owner == @name
+	    end
+	  end
+	end
+
+Here two roles are defined, one for employees and one for managers. Employees by default can't do anything, this is set by <tt>default_response false</tt> on the module. Then methods governing the actor's interaction with the Article model by defining the <tt>can_view_article?</tt> to always return true (Employees can view any article), and defining the <tt>can_update_article?</tt> method to only return true if the actor playing the employee role is the owner of the article. 
+
+The manager role includes the employee role, so it inherits the default_response behaviour of false and the defined rules for interactions with articles. Here, the <tt>can_update_article?</tt> method is override to always return true, so managers can edit any article. Note that <tt>EmployeeRole#can_destroy_article?(article)</tt> calls <tt>self.can_update_article?(article)</tt>, so when the ManagerRole inherits the EmployeeRole, <tt>ManagerRole#can_destroy_article?(article)</tt> returns the result of <tt>ManagerRole#can_update_article?(article)</tt>, which returns true. This means that when ManagerRole inherits EmployeeRole, the inherited methods behave differently, which might be unexpected. To mitigate this in the example above, <tt>ManagerRole#can_destroy_article?(article)</tt> is overridden to check if the Manager trying to destroy the role is the article owner.
+
+== Actors
+
+Whatever class(es) you want all permissions to run through should include <tt>Canable::Actor</tt>, instead of <tt>Canable::Cans</tt> from the original Canable gem.
+
+    class User > ActiveRecord::Base
+      include Canable::Actor
+	  default_role :employee
+    end
+
+Actors represent objects in the system that want to preform an action. An actor's abilities are defined by the role(s) it plays because the actor simply inherits any permission. Roles can be assigned to an actor ("played") by using the <tt>default_role(role)</tt> class method, or calling <tt>act(role)<tt> on an actor instance.
+
+
+Lets say an article can be viewed and created by anyone, but only updated or destroyed by the user that created the article. To do that, you could leave viewable_by? and creatable_by? alone as they default to true and just override the other methods.
+
+    class Article
+      include MongoMapper::Document
+      include Canable::Ables
+      userstamps! # adds creator and updater
+      
+      def updatable_by?(user)
+        creator == user
+      end
+      
+      def destroyable_by?(user)
+        updatable_by?(user)
+      end
+    end
+
+Lets look at some sample code now:
+
+    john = User.create(:name => 'John')
+    steve = User.create(:name =. 'Steve')
+    
+    ruby = Article.new(:title => 'Ruby')
+    john.can_create?(ruby) # true
+    steve.can_create?(ruby) # true
+    
+    ruby.creator = john
+    ruby.save
+    
+    john.can_view?(ruby) # true
+    steve.can_view?(ruby) # true
+    
+    john.can_update?(ruby) # true
+    steve.can_update?(ruby) # false
+    
+    john.can_destroy?(ruby) # true
+    steve.can_destroy?(ruby) # false
+    
+Now we can implement our permissions for each resource and then always check whether a user can or cannot do something. This makes it all really easy to test. Next, how would you use this in the controller.
+
+== Enforcers
+
+    class ApplicationController
+      include Canable::Enforcers
+    end
+
+Including Canable::Enforcers adds an enforce permission method for each of the actions defined (by default view/create/update/destroy). It is the same thing as doing this for each Canable action:
+
+    class ApplicationController
+      include Canable::Enforcers
+
+      delegate :can_view?, :to => :current_user
+      helper_method :can_view? # so you can use it in your views
+      hide_action :can_view?
+
+      private
+        def enforce_view_permission(resource)
+          raise Canable::Transgression unless can_view?(resource)
+        end
+    end
+
+Which means you can use it like this:
+
+    class ArticlesController < ApplicationController
+      def show
+        @article = Article.find!(params[:id])
+        enforce_view_permission(@article)
+      end
+    end
+
+If the user can_view? the article, all is well. If not, a Canable::Transgression is raised which you can decide how to handle (show 404, slap them on the wrist, etc.).
+
+== Adding Your Own Actions
+
+You can add your own actions like this:
+
+    Canable.add(:publish, :publishable)
+
+The first parameter is the can method (ie: can_publish?) and the second is the able method (ie: publishable_by?). 
+
+== Review
+
+So, lets review: cans go on user model, ables go on everything, you override ables in each model where you want to enforce permissions, and enforcers go after each time you find or initialize an object in a controller. Bing, bang, boom.
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2010 John Nunemaker. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,44 @@
+require 'rubygems'
+require 'rake'
+
+require File.dirname(__FILE__) + '/lib/canable'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name        = "rbacanable"
+    gem.summary     = %Q{Simple role based permissions system}
+    gem.description = %Q{Simple role based permissions system}
+    gem.email       = "harry.brundage@gmail.com"
+    gem.homepage    = "http://github.com/hornairs/rbacanable"
+    gem.authors     = ["John Nunemaker", "Harry Brundage"]
+    gem.version     = Canable::Version
+    gem.add_development_dependency "shoulda", "2.10.3"
+    gem.add_development_dependency "mocha", "0.9.8"
+    gem.add_development_dependency "yard", ">= 0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.ruby_opts << '-rubygems'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+task :test => :check_dependencies
+task :default => :test
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yardoc do
+    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+  end
+end

data/examples/basic.rb

@@ -0,0 +1,41 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'rubygems'
+require 'active_support'
+require 'canable'
+
+class User
+  include Canable::Cans  
+  attr_accessor :name
+  
+  def initialize(attributes = {})
+    @name = attributes[:name]
+  end
+  
+  def can_update_article(article)
+    article.creator == @name
+  end
+end
+
+class Article
+  include Canable::Ables
+  attr_accessor :creator
+  
+  def initialize(attributes = {})
+    @creator = attributes[:creator]
+  end
+end
+
+post1 = Article.new(:creator => "John")
+user1 = User.new(:name => "John")
+user2 = User.new(:name => "Steve")
+
+puts "Can User1 view Post1? #{user1.can_view?(post1)}"
+puts "Can User2 view Post1? #{user2.can_view?(post1)}"
+puts "Is Post1 viewable by User1? #{post1.viewable_by?(user1)}"
+puts "Is Post1 viewable by User2? #{post1.viewable_by?(user2)}"
+puts 
+puts "Can User1 update Post1? #{user1.can_update?(post1)}"
+puts "Can User2 update Post1? #{user2.can_update?(post1)}"
+puts "Is Post1 updatable by User1? #{post1.updatable_by?(user1)}"
+puts "Is Post1 updatable by User2? #{post1.updatable_by?(user2)}"

data/examples/roles.rb

@@ -0,0 +1,100 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'rubygems'
+require 'active_support'
+require 'canable'
+require 'terminal-table/import'
+
+
+module Canable::Roles
+  module BasicRole
+    include Canable::Role
+    default_response false
+  end
+  
+  module EmployeeRole
+    include Canable::Role
+    default_response false
+    
+    def can_destroy_article?(article)
+      article.creator == @name
+    end
+  
+    def can_update_article?(article)
+      article.creator == @name
+    end
+  end
+
+  module ManagerRole
+    include Canable::Role
+    include EmployeeRole
+        
+    def can_destroy_article?(article)
+      true
+    end
+  end
+
+  module AdminRole
+    include Canable::Role
+    default_response true
+    
+    def can_create_article?(article)
+      false
+    end
+  end
+end
+
+class User
+  include Canable::Actor
+  attr_accessor :name
+  
+  default_role Canable::Roles::BasicRole
+  # role_attribute :@role -- RBACanable by default looks in @role for a Module constant or string to use as a role
+  
+  def initialize(attributes = {})
+    @name = attributes[:name]
+    @role = attributes[:role]
+    self.__initialize_canable_role # nessecary since initialize is overridden
+  end
+  
+  def to_s
+    "#{@role.to_s}: #{@name}"
+  end
+end
+
+class Article
+  include Canable::Ables
+  attr_accessor :creator
+  
+  def initialize(attributes = {})
+    @creator = attributes[:creator]
+  end
+  
+  def to_s
+    "#{@creator}'s article"
+  end
+end
+
+users = [
+  User.new(:name => "John", :role => :employee),
+  User.new(:name => "Steve", :role => :manager),
+  User.new(:name => "Harry", :role => :admin),
+  User.new(:name => "Jim")
+]
+
+posts = [
+  Article.new(:creator => "John"),
+  Article.new(:creator => "Steve"),
+  Article.new(:creator => "Harry")
+]
+
+
+user_table = table do |t|
+  t.headings = "User", "Resource", "Can View?", "Can Create?", "Can Update?", "Can Destroy?", "Role"
+  users.each do |user|
+    posts.each do |post|
+      t << [user.to_s, post.to_s, user.can_view?(post), user.can_create?(post), user.can_update?(post), user.can_destroy?(post), user.canable_included_role]
+    end
+  end
+end
+puts user_table