cannibal 0.5.0

data/README.mdown

@@ -0,0 +1,114 @@
+Cannibal
+========
+
+A simple permissions system for declaring and querying permissions between Ruby objects.
+
+Background
+----------
+
+Cannibal is based around defining interactions between Actors and Subjects.
+
+An Actor participates in your system as an agent that "does" things. Cannibal lets you declare what
+each Actor can do, and Actors are queried to determine whether or not they are permitted to perform
+a particular action.
+
+You can turn any class into an Actor by including Cannibal::Actor within it.
+
+A Subject participates in your system as something that is acted upon. You declare for each Subject
+the conditions under which each Actor may or may not interact with it.
+
+You can turn any class into a Subject by including Cannibal::Actor within it.
+
+If for example you are using Cannibal in a Rails application, an example of an Actor might be a
+User model. An example of a Subject might be a Task model. You may want all Users in the system to
+be able to view all of the available Tasks, but you may want to restrict tasks to only be editable
+by their creators.
+
+Permissions can be set at various levels, starting at the Class level and getting finer grained
+right down to the field or method level of your models.
+
+In addition, you can specify static permissions (no User may modify a Task) or dynamic permissions
+that are evaluated at query time (ie. a specific user may or may not be able to modify a specific
+task, based on whatever rules you put forth).
+
+Sample Scenarios
+----------------
+
+Class-level permissions:
+
+    class User
+      include Cannibal::Actor
+    end
+
+    class Thing
+      include Cannibal::Subject
+      allow User, :edit
+    end
+
+    @user = User.new
+    @thing = Thing.new
+
+    puts "Yay!" if @user.can? :edit, @thing
+
+Actor object-level permissions:
+
+    class User
+      include Cannibal::Actor
+      attr_accessor :role
+    end
+
+    class Thing
+      include Cannibal::Subject
+      permission({
+        :actor => User,
+        :verb => :edit,
+        :actor_proc => Proc.new { |user|
+          if user.role == 'administrator'
+            true
+          else
+            false
+          end
+        }
+      })
+    end
+
+    @user = User.new; @user.role = 'user'
+    @admin = User.new; @user.role = 'administrator'
+    @thing = Thing.new
+
+    puts "Back off!" unless @user.can? :edit, @thing
+    puts "Yay!" if @admin.can? :edit, @thing
+
+Actor and subject object-to-object level permissions:
+
+    class User
+      include Cannibal::Actor
+      attr_accessor :role
+    end
+
+    class Thing
+      include Cannibal::Subject
+      attr_accessor :owner
+      permission({
+        :actor => User,
+        :verb => :edit,
+        :proc => Proc.new { |user, thing|
+          if user.role == 'administrator' or user == thing.owner
+            true
+          else
+            false
+          end
+        }
+      })
+    end
+
+    @user_a = User.new; @user.role = 'user'
+    @user_b = User.new; @user.role = 'user'
+    @admin = User.new; @user.role = 'administrator'
+
+    @thing = Thing.new; @thing.owner = @user_a
+
+    puts "Back off!" unless @user_b.can? :edit, @thing
+    puts "Yay!" if @user_a.can? :edit, @thing
+    puts "Yay!" if @admin.can? :edit, @thing
+

data/lib/cannibal/actor.rb

@@ -0,0 +1,24 @@
+module Cannibal
+  module Actor
+
+    module ClassMethods
+      def can?(verb, subject, attribute=nil)
+        permissions.allowed?(self, subject, verb, attribute)
+      end
+
+      def permissions
+        @@registry = Cannibal::PermissionRegistry.instance
+      end
+    end
+
+    def self.included(klass)
+      klass.extend ClassMethods
+    end
+
+    def can?(verb, subject, attribute=nil)
+      self.class.permissions.allowed?(self, subject, verb, attribute)
+    end
+
+  end
+end
+

data/lib/cannibal/permission_registry.rb

@@ -0,0 +1,135 @@
+require 'singleton'
+
+module Cannibal
+  class PermissionRegistry
+    include Singleton
+
+    def set(options)
+      actor = options[:actor]
+      verb = options[:verb]
+      subject = options[:subject]
+
+      if actor.is_a? Class
+        actor_class = actor
+      else
+        actor_class = actor.class
+      end
+
+      if subject.is_a? Class
+        subject_class = subject
+      else
+        subject_class = subject.class
+      end
+
+      actor_proc = options[:actor_proc]
+      gproc = options[:proc]
+
+      perm = options[:perm]
+      attributes = options[:attribute]
+      if attributes.nil?
+        # Set class-wide perms if no attributes specified
+        verb_hash(actor_class, subject_class, verb)[:perm] = perm unless perm.nil?
+        verb_hash(actor_class, subject_class, verb)[:actor_proc] = actor_proc unless actor_proc.nil?
+        verb_hash(actor_class, subject_class, verb)[:proc] = gproc unless gproc.nil?
+      else
+        attributes = [ attributes ] unless attributes.is_a? Array
+        attributes.each do |attribute|
+          attribute_hash(actor_class, subject_class, verb)[attribute] = {}
+          attribute_hash(actor_class, subject_class, verb)[attribute][:perm] = perm unless perm.nil?
+          attribute_hash(actor_class, subject_class, verb)[attribute][:actor_proc] = actor_proc unless actor_proc.nil?
+          attribute_hash(actor_class, subject_class, verb)[attribute][:proc] = gproc unless gproc.nil?
+        end
+      end
+    end
+
+    def allowed?(actor, subject, verb, attribute=nil)
+      ok = false
+
+      if actor.is_a? Class
+        actor_class = actor
+      else
+        actor_class = actor.class
+      end
+      if subject.is_a? Class
+        subject_class = subject
+      else
+        subject_class = subject.class
+      end
+
+      ph = verb_hash(actor_class, subject_class, verb)
+#puts "\n########### PERM HASH FOR #{actor_class} #{subject_class} #{verb} #{attribute}"
+#puts "#{ph.inspect}\n\n"
+
+      # Check class perms first
+      if ph.has_key? :perm
+        ok = ph[:perm]
+      end
+
+      unless actor.is_a? Class
+        # Allow object perms to override
+        if ph.has_key? :actor_proc
+          ok = ph[:actor_proc].call actor
+        end
+      end
+
+      unless subject.is_a? Class
+        # Allow object-to-object perms to override
+        if ph.has_key? :proc
+          ok = ph[:proc].call actor, subject
+        end
+      end
+
+      unless attribute.nil?
+#        puts "Evaluating attribute #{attribute}"
+        ah = attribute_hash(actor_class, subject_class, verb)
+#        puts ah.inspect
+        if ah.has_key? attribute
+#          puts "Found key #{attribute}"
+
+          if ah[attribute].has_key? :perm
+#            puts "Setting from perm"
+            ok = ah[attribute][:perm]
+          end
+
+          unless actor.is_a? Class or ah[attribute][:actor_proc].nil?
+#            puts "Setting from actor_proc"
+            ok = ah[attribute][:actor_proc].call actor
+          end
+
+          unless subject.is_a? Class or ah[attribute][:proc].nil?
+#            puts "Setting from proc"
+            ok = ah[attribute][:proc].call actor, subject
+          end
+        end
+#        puts "Found #{ok}"
+      end
+
+      ok
+    end
+
+    def permstore
+      @perms ||= {}
+    end
+
+    def reset
+      @perms = {}
+    end
+
+    def verb_hash(actor, subject, verb)
+      actor_hash = hash_or_init permstore, actor
+      subject_hash = hash_or_init actor_hash, subject
+      hash_or_init subject_hash, verb
+    end
+
+    def attribute_hash(actor, subject, verb)
+      hash_or_init verb_hash(actor, subject, verb), :attributes
+    end
+
+    def hash_or_init(hash, key)
+      unless hash.include? key
+        hash[key] = {}
+      end
+      hash[key]
+    end
+  end
+end

data/lib/cannibal/subject.rb

@@ -0,0 +1,44 @@
+module Cannibal
+
+  module Subject
+
+    module ClassMethods
+
+      def allow(actor, verb, attribute=nil)
+        permissions.set(
+          :actor => actor,
+          :verb => verb,
+          :subject => self,
+          :attribute => attribute,
+          :perm => true
+        )
+      end
+
+      def deny(actor, verb, attribute=nil)
+        permissions.set(
+          :actor => actor,
+          :verb => verb,
+          :subject => self,
+          :attribute => attribute,
+          :perm => false
+        )
+      end
+
+      def permission(options)
+        options[:subject] = self
+        permissions.set(options)
+      end
+
+      def permissions
+        @registry ||= Cannibal::PermissionRegistry.instance
+      end
+
+    end
+  
+    def self.included(klass)
+      klass.extend ClassMethods
+    end
+
+  end
+end
+

data/lib/cannibal.rb

@@ -0,0 +1,3 @@
+require 'cannibal/permission_registry'
+require 'cannibal/actor'
+require 'cannibal/subject'

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification 
+name: cannibal
+version: !ruby/object:Gem::Version 
+  hash: 11
+  prerelease: false
+  segments: 
+  - 0
+  - 5
+  - 0
+  version: 0.5.0
+platform: ruby
+authors: 
+- Three Wise Men
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-08-17 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: Use this library in a Ruby application to provide permission declaration and querying capabilities between Ruby objects.
+email: info @nospam@ threewisemen.ca
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.mdown
+files: 
+- lib/cannibal.rb
+- lib/cannibal/actor.rb
+- lib/cannibal/permission_registry.rb
+- lib/cannibal/subject.rb
+- README.mdown
+has_rdoc: true
+homepage: 
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Permission framework for Ruby objects
+test_files: []
+