cancan-permits 0.1.0

data/.document

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

data/.gitignore

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

data/.rspec

@@ -0,0 +1 @@
+--format nested --color

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Kristian Mandrup
+
+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.markdown

@@ -0,0 +1,103 @@
+# CanCan Permits
+
+Role specific Permits for use with CanCan permission system. 
+
+## Install
+
+<code>gem install cancan-permits</code>
+
+## Usage
+
+* Define Roles that Users can have
+* Define which Roles are available
+* Define a Permit for each Role. 
+* For each Permit, define what that Role can do
+
+To add Roles to your app, you might consider using a *roles* gem such as *roles_generic*
+
+### Define which Roles are available
+
+You can override the default configuration here:
+
+<pre>
+  module Permits::Roles
+    def self.available
+      # return symbols array of Roles available to users 
+    end
+  end
+</pre>  
+
+By default it returns User.roles if such exists, otherwise it returns [:guest, :admin] by default.
+
+### Define a Permit for each Role. 
+
+_Note:_ You might consider using the Permits generator in order to generate your permits for you (see below)
+
+<pre>
+  module RolePermit  
+    class Admin < Base
+      def initialize(ability)
+        super
+      end
+
+      def permit?(user, request=nil)    
+        super
+        return if !role_match? user
+
+        can :manage, :all    
+      end  
+    end
+  end
+</pre>
+
+## Special Permits
+
+The Permits generator always generates the special permits *Any* and *System*.
+
+### Any permit
+
+The Any permit, can be used to set permissions that should hold true for a user in any role. 
+F.ex, maybe in your app, any user should be able to read comments, articles and posts:
+
+For this to hold true, put the following permit logic in your Any permit.
+<pre>
+  can :read, [Comment, Article, Post]
+</pre>
+
+### System permit
+
+The System permit is run before any of the other permits. This gives you a chance to control the permission flow.
+By returning a value of :break you force a break-out from the permission flow, ensuring none of the other permits are run.
+
+Example:
+The system permit can be used to allow management of all resources given the request is from localhost (which usually means "in development mode"). By default this logic is setup and ready to go. 
+
+You can be enable this simply by setting the following class instance variable: 
+
+<code>Permits::Configuration.localhost_manager = true</code>
+
+## Permits Generator
+
+Options
+* --orm   : The ORM to use (active_record, data_mapper, mongoid, mongo_mapper)
+* --roles : The roles for which to generate permits ; default Guest (read all) and Admin (manage all) 
+
+Note, by default the Permits generator will attempt to discover which roles are currently defined as available to the system
+and generate permits for those roles (using some conventions - TODO). Any roles specified in the --roles option are merged
+with the roles found to be available in the app.
+
+<code>$ rails g permits --orm active_record --roles guest author admin</code>
+
+## 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 Kristian Mandrup. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,19 @@
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "cancan-permits"
+    gem.summary = %Q{Permits for use with CanCan}
+    gem.description = %Q{Role specific Permits for use with CanCan permission system}
+    gem.email = "kmandrup@gmail.com"
+    gem.homepage = "http://github.com/kristianmandrup/cancan-permits"
+    gem.authors = ["Kristian Mandrup"]
+    gem.add_development_dependency "rspec", "~> 2.0.0"
+    gem.add_dependency 'cancan', "~> 1.3"
+    gem.add_dependency 'require_all', "~> 1.1"
+    gem.add_dependency 'sugar-high', "~> 0.1"
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+

data/VERSION

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

data/lib/cancan-permits.rb

@@ -0,0 +1,3 @@
+require 'cancan'
+require 'require_all'
+require_all File.dirname(__FILE__) + '/cancan-permits'

data/lib/cancan-permits/namespaces.rb

@@ -0,0 +1,6 @@
+module Permits
+  modules :ability, :roles
+end 
+
+module Permit
+end

data/lib/cancan-permits/permit/base_permit.rb

@@ -0,0 +1,44 @@
+module Permit
+  class Base 
+    attr_reader :ability
+       
+    def initialize(ability)
+      @ability = ability
+    end
+
+    def permit?(user, request=nil) 
+      false
+    end
+
+    def can(action, subject, conditions = nil, &block)
+      can_definitions << CanCan::CanDefinition.new(true, action, subject, conditions, block)
+    end
+        
+    def cannot(action, subject, conditions = nil, &block)
+      can_definitions << CanCan::CanDefinition.new(false, action, subject, conditions, block)
+    end
+    
+    def owns(user, clazz, ownership_relation = :user_id, user_id_attribute = :id)
+      begin
+        user_id = user.send :"#{user_id_attribute}"              
+      rescue
+        raise ArgumentError, "ERROR (owns) - The user of class #{user.class} does not respond to ##{user_id_attribute}"
+      end
+        can :manage, clazz, ownership_relation => user_id
+    end 
+
+    protected
+
+    def localhost_manager?
+      Permits::Configuration.localhost_manager
+    end
+
+    def role_match? user
+      user.has_role? self.class.last_name.downcase.to_sym
+    end
+      
+    def can_definitions
+      ability.send :can_definitions
+    end    
+  end
+end

data/lib/cancan-permits/permits/abiity.rb

@@ -0,0 +1,40 @@
+module Permits
+  class Ability
+    include CanCan::Ability
+
+    # set up each RolePermit instance to share this same Ability 
+    # so that the can and cannot operations work on the same permission collection!
+    def self.permits ability
+      special_permits << [:system, :any].map{|name| make_permit(role, ability)}
+      role_permits = Permits::Roles.available.inject([]) do |permits, role|
+        permits << make_permit role, ability
+      end
+      special_permits + role_permits
+    end
+
+    def initialize(user, request=nil)
+      # put ability logic here!
+      user ||= Guest.new   
+                  
+      Ability.permits(self).each do |permit|
+        # get role name of permit 
+        permit_role = permit.class.demodulize.to_sym                      
+        
+        if permit_role == :system
+          # always execute system permit
+          result = role_permit.permit?(user, request)
+          break if result == :break
+        else
+          # only execute the permit if the user has the role of the permit or is for any role
+          role_permit.permit?(user, request) if user.has_role?(permit_role) || permit_role == :any
+        end
+      end
+    end      
+    
+    protected
+    
+    def self.make_permit role, ability
+      "Permit::#{role.to_s.camelize}".constantize.new(ability)
+    end          
+  end
+end      

data/lib/cancan-permits/permits/configuration.rb

@@ -0,0 +1,7 @@
+module Permits
+  class Configuration
+    class << self
+      attr_accessor :localhost_manager
+    end
+  end
+end

data/lib/cancan-permits/permits/roles.rb

@@ -0,0 +1,9 @@
+module Permits::Roles
+  def self.available
+    if Module.const_defined? :User
+      User.roles if User.respond_to? roles
+    else
+      [:guest, :admin]
+    end
+  end
+end

data/lib/generators/permits/permits_generator.rb

@@ -0,0 +1,71 @@
+require 'sugar-high/array'
+require 'active_support/inflector'
+
+class PermitsGenerator < Rails::Generators::Base
+  desc "Creates a Permit for each role in 'app/permits' and ensures that the permit folder is added to Rails load path."
+
+  class_option :roles,  :type => :array,    :default => [], :desc => "Roles to create permits for"
+  # ORM to use
+  class_option :orm,    :type => :string,   :desc => "ORM to use", :default => 'active_record'
+
+  source_root File.dirname(__FILE__) + '/templates'
+
+  def main_flow      
+    template_permit :admin,   :admin_permit 
+    template_permit :any,     :any_permit 
+    template_permit :system,  :barebones_permit
+    
+    permit_logic = base_logic
+    roles.each do |role|      
+      template_permit role if !role == :admin     
+    end    
+  end
+  
+  protected
+
+  attr_accessor :permit_name, :permit_logic
+
+  # TODO: merge with any registered roles in application
+  def roles
+    options[:roles].uniq.to_symbols
+  end
+
+  def template_permit name, template_name=nil
+    permit_logic = send "#{name}_logic" if [:admin, :system, :any].include?(name)
+    self.permit_name = name
+
+    template "permit.rb", "app/permits/#{name}_permit.rb"
+  end 
+
+  def any_logic
+    ""
+  end
+
+  def system_logic
+    %{
+      # allow to manage all and return :break to 
+      # abort calling any other permissions
+  
+      if request.host.localhost? && localhost_manager?
+        can(:manage, :all) 
+        return :break
+      end
+}
+  end
+
+  def base_logic
+    %{
+      return if !role_match? user
+
+      # can :create, Comment
+      # owns(user, Comment)
+}
+  end
+  
+  def admin_logic
+    %{
+      return if !role_match? user
+      can :manage, :all
+}
+  end
+end

data/lib/generators/permits/templates/permit.rb

@@ -0,0 +1,12 @@
+module Permit  
+  class <%= permit_name %> < Base
+    def initialize(ability)
+      super
+    end
+
+    def permit?(user, request=nil) 
+      super
+      <%= permit logic %>
+    end  
+  end
+end

data/spec/cancan-permits/fixtures/ability.rb

@@ -0,0 +1,19 @@
+module AuthAssistant
+  class Ability
+    include CanCan::Ability
+
+    # set up each RolePermit instance to share this same Ability 
+    # so that the can and cannot operations work on the same permission collection!
+    def self.role_permits ability
+      @role_permits = AuthAssistant::Roles.available.inject([]) do |permits, role|
+        permits << "RolePermit::#{role.to_s.camelize}".constantize.new(ability)
+      end
+    end
+
+    def initialize(user, request=nil)
+      # put ability logic here!
+      user ||= Guest.new   
+      Ability.role_permits(self).each{|role_permit| role_permit.permit?(user, request) }
+    end      
+  end
+end      

data/spec/cancan-permits/fixtures/permits/admin_permit.rb

@@ -0,0 +1,14 @@
+module RolePermit
+  class Admin < Base
+    def initialize(ability)
+      super
+    end
+
+    def permit?(user, request=nil)    
+      super
+      return if !role_match? user
+      
+      can :manage, :all    
+    end  
+  end
+end

data/spec/cancan-permits/fixtures/permits/editor_permit.rb

@@ -0,0 +1,26 @@
+module RolePermit
+  class Editor < Base
+    def initialize(ability)
+      super
+    end
+
+    def permit?(user, request=nil) 
+      super
+      return if !role_match? user
+     
+      # uses default user_id
+      owns(user, Comment)     
+      # 
+      owns(user, Post, :writer)
+      # 
+      owns(user, Article, :author, :name)
+
+      # a user can manage comments he/she created
+      # can :manage, Comment do |comment|
+      #   comment.try(:user) == user
+      # end            
+
+      # can :create, Comment
+    end 
+  end
+end

data/spec/cancan-permits/fixtures/permits/guest_permit.rb

@@ -0,0 +1,25 @@
+module RolePermit
+  class Guest < Base
+    def initialize(ability)
+      super
+    end
+
+    def permit?(user, request=nil) 
+      super
+      return if !role_match? user
+      
+      can :read, [Comment, Post]
+      can [:update, :destroy], [Comment]
+      can :create, Article
+      
+      # owns(user, Comment)
+      
+      # a user can manage comments he/she created
+      # can :manage, Comment do |comment|
+      #   comment.try(:user) == user
+      # end            
+      
+      # can :create, Comment
+    end  
+  end
+end

data/spec/cancan-permits/permits/fixtures/models.rb

@@ -0,0 +1,23 @@
+class Comment
+  attr_accessor :user_id
+
+  def initialize user_id
+    self.user_id = user_id
+  end
+end
+
+class Post
+  attr_accessor :writer  
+
+  def initialize user_id
+    self.writer = user_id
+  end
+end
+
+class Article
+  attr_accessor :author
+  
+  def initialize name
+    self.author = name
+  end
+end

data/spec/cancan-permits/permits/owner_permits_spec.rb

@@ -0,0 +1,33 @@
+require 'spec_helper'
+
+# can :read, [Comment, Post]
+# can [:update, :destroy], [Comment]
+# can :create, Article
+
+
+describe AuthAssistant::Ability do
+  context "Editor user" do
+    before :each do
+      @editor = User.new(1, :editor, 'kristian')
+      @ability = AuthAssistant::Ability.new @editor
+      @comment  = Comment.new(1)
+      @post     = Post.new(1)
+      @article  = Article.new('kristian')      
+    end
+   
+    it "should be able to :read Comment he owns, using default :user_id relation - foreign key to User.id" do
+      @ability.should be_able_to(:read, Comment)
+      @ability.should be_able_to(:read, @comment)      
+    end
+
+    it "should be able to :read Post he owns, using :owner relation - foreign key to User.id" do
+      @ability.should be_able_to(:read, Post)
+      @ability.should be_able_to(:read, @post)      
+    end
+    
+    it "should be able to :read Article he owns, using :author relation - foreign key to User.name" do
+      @ability.should be_able_to(:read, Article)
+      @ability.should be_able_to(:read, @article)
+    end 
+  end        
+end

data/spec/cancan-permits/permits/permits_spec.rb

@@ -0,0 +1,79 @@
+require 'spec_helper'
+
+class Comment
+  attr_accessor :owner
+end
+
+class Post
+  attr_accessor :writer  
+end
+
+class Article
+  attr_accessor :author
+end
+
+
+describe AuthAssistant::Ability do
+  context "Guest user" do
+    before :each do
+      @guest = User.new(1, :guest)
+      @ability = AuthAssistant::Ability.new @guest 
+      @comment  = Comment.new(1)
+      @post     = Post.new(1)
+    end
+
+    # can :read, [Comment, Post]
+    # can [:update, :destroy], [Comment]
+    # can :create, Article
+
+    it "should be able to :read Comment and Post but NOT Article" do
+      @ability.can?(:read, Comment).should be_true
+      @ability.can?(:read, @comment).should be_true
+
+      @ability.can?(:read, Post).should be_true      
+      @ability.can?(:read, @post).should be_true      
+      
+      @ability.can?(:read, Article).should be_false
+      @ability.can?(:read, @article).should be_false      
+    end
+
+    it "should be not able to :update only Comment" do
+      @ability.can?(:update, Comment).should be_true
+      @ability.can?(:update, @comment).should be_true      
+      
+      @ability.can?(:update, Post).should be_false
+      @ability.can?(:update, @post).should be_false
+    end
+
+  end
+  
+  context "Admin user" do
+    before do
+      admin = User.new(2, :admin)
+      @ability = AuthAssistant::Ability.new admin
+    end
+  # 
+  #   # can :manage, :all    
+  # 
+    it "should be able to :read anything" do
+      @ability.can?(:read, Comment).should be_true
+      @ability.can?(:read, Post).should be_true      
+    end
+  
+    it "should be not able to :update everything" do
+      @ability.can?(:update, Comment).should be_true
+      @ability.can?(:update, Post).should be_true
+    end
+  
+    it "should be not able to :create everything" do
+      @ability.can?(:create, Comment).should be_true
+      @ability.can?(:create, Post).should be_true      
+    end
+  
+    it "should be not able to :update everything" do
+      @ability.can?(:destroy, Comment).should be_true
+      @ability.can?(:destroy, Post).should be_true
+    end
+  end
+      
+end

data/spec/generators/permit_generator_spec.rb

@@ -0,0 +1,35 @@
+require 'spec_helper' 
+require 'generator-spec'
+
+describe 'Permits generator' do
+  GeneratorSpec.with_generator do
+    tests PermitsGenerator
+  end
+
+  describe 'result of running generator with default profile' do
+    before :each do
+      GeneratorSpec.with_generator do |g, check|    
+        g.run_generator
+      end
+    end
+
+    it "should create Admin permit" do
+      g.should have_permit :admin
+    end
+  end
+
+  describe 'result of running generator with option to create permit for each registered role' do
+    context "Registered roles :guest, :admin"
+      before :each do
+        GeneratorSpec.with_generator do |g, check|    
+          g.run_generator "--roles admin guest"
+        end
+      end
+
+      it "should have created Guest and Admin permits" do
+        # Find at: 'app/permits/admin_permit.rb'
+        g.should have_permits :guest, :admin
+      end
+    end
+  end    
+end

data/spec/spec_helper.rb

@@ -0,0 +1,36 @@
+require 'rspec'
+require 'rspec/autorun' 
+require 'cancan/matchers'
+require 'cancan-permits'
+
+require_all File.dirname(__FILE__) + 'cancan-permits/fixtures/permits'
+require 'cancan-permits/fixtures/ability'
+
+RSpec.configure do |config|
+  config.mock_with :mocha
+end
+
+module AuthAssistant::Roles
+  def self.available
+    User.roles
+  end
+end
+
+class User
+  attr_accessor :id, :role, :name
+
+  def self.roles
+    [:guest, :admin, :editor]
+  end    
+
+  def initialize id, role, name
+    self.id = id    
+    raise ArgumentError, "Role #{role} is not in list of available roles: #{self.class.roles}" if !self.class.roles.include? role
+    self.role = role
+    self.name = name
+  end
+  
+  def has_role? role
+    self.role == role
+  end     
+end

metadata

@@ -0,0 +1,154 @@
+--- !ruby/object:Gem::Specification 
+name: cancan-permits
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Kristian Mandrup
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-09-17 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 0
+        - 0
+        version: 2.0.0
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: cancan
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 3
+        version: "1.3"
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: require_all
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 1
+        version: "1.1"
+  type: :runtime
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: sugar-high
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 1
+        version: "0.1"
+  type: :runtime
+  version_requirements: *id004
+description: Role specific Permits for use with CanCan permission system
+email: kmandrup@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.markdown
+files: 
+- .document
+- .gitignore
+- .rspec
+- LICENSE
+- README.markdown
+- Rakefile
+- VERSION
+- lib/cancan-permits.rb
+- lib/cancan-permits/namespaces.rb
+- lib/cancan-permits/permit/base_permit.rb
+- lib/cancan-permits/permits/abiity.rb
+- lib/cancan-permits/permits/configuration.rb
+- lib/cancan-permits/permits/roles.rb
+- lib/cancan-permits/rspec/config.rb
+- lib/cancan-permits/rspec/matchers/have_permits.rb
+- lib/generators/permits/permits_generator.rb
+- lib/generators/permits/templates/permit.rb
+- spec/cancan-permits/fixtures/ability.rb
+- spec/cancan-permits/fixtures/permits/admin_permit.rb
+- spec/cancan-permits/fixtures/permits/editor_permit.rb
+- spec/cancan-permits/fixtures/permits/guest_permit.rb
+- spec/cancan-permits/permits/fixtures/models.rb
+- spec/cancan-permits/permits/owner_permits_spec.rb
+- spec/cancan-permits/permits/permits_spec.rb
+- spec/generators/permit_generator_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/kristianmandrup/cancan-permits
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Permits for use with CanCan
+test_files: 
+- spec/cancan-permits/fixtures/ability.rb
+- spec/cancan-permits/fixtures/permits/admin_permit.rb
+- spec/cancan-permits/fixtures/permits/editor_permit.rb
+- spec/cancan-permits/fixtures/permits/guest_permit.rb
+- spec/cancan-permits/permits/fixtures/models.rb
+- spec/cancan-permits/permits/owner_permits_spec.rb
+- spec/cancan-permits/permits/permits_spec.rb
+- spec/generators/permit_generator_spec.rb
+- spec/spec_helper.rb