cancannible 0.0.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    YTJjNWE0NzMzZTcyNDAxMDRhOTMxZmE4ODRkYWZkMWU1ZDcwNjczMw==
+  data.tar.gz: !binary |-
+    NGY4MDliNGJlMGMwZjBkYTc5MjYyYzcyNWI0MWZiNWJmMmU1ZjU3Mw==
+SHA512:
+  metadata.gz: !binary |-
+    MTliYzQ2MGYzZWQyODhiMTk0ZTgzODhjNDQ1MDEwMzdmZDNjOWY0ZjRiY2Q0
+    NDNjZGUwYmE4OTQ3Zjc2MjZkMDc1N2JjOTYyOWE2ZGY4OWZhNGE5NTkyYjg4
+    ODFjZTYyODc0Yjg5ZGM4YWRmMjI1ZmU4ZmFmZGU5NmExMzhjZTE=
+  data.tar.gz: !binary |-
+    NmM5ODQ3NmUwNDIzYjJkYTZjZTZlYzhiNDEzMTAxYWQzMmE0ODU1OGJiNTFm
+    OWRjMzUyZWUzMmQxYTI1ZmQ2MGIzMjZjOWRkNTI0N2VlZjkyN2NjNjljM2Ez
+    ZmY5M2RkMzgyYTk1OWE5OGFkYzUwNTE1ZjRlNmQyNzVkYjkxNWE=

data/.gitignore

@@ -0,0 +1,24 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+.rvm*
+.ruby*

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,4 @@
+# These are specific configuration settings required for travis-ci
+language: ruby
+rvm:
+  - 1.9.3

data/Gemfile

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+# currently testing on the 3.2 branch of rails
+# gem "activemodel", '~> 3.2'
+# gem "activerecord", '~> 3.2'
+
+# Specify your gem's dependencies in cancannible.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,18 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+# Note: The cmd option is now required due to the increasing number of ways
+#       rspec may be run, below are examples of the most common uses.
+#  * bundler: 'bundle exec rspec'
+#  * bundler binstubs: 'bin/rspec'
+#  * spring: 'bin/rsspec' (This will use spring if running and you have
+#                          installed the spring binstubs per the docs)
+#  * zeus: 'zeus rspec' (requires the server to be started separetly)
+#  * 'just' rspec: 'rspec'
+guard :rspec, cmd: 'bundle exec rspec' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/unit/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+
+end
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2011 Paul Gallagher
+
+MIT License
+
+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.md

@@ -0,0 +1,85 @@
+# Cancannible
+[![Build Status](https://travis-ci.org/evendis/cancannible.svg?branch=master)](https://travis-ci.org/evendis/cancannible)
+
+Cancannible is a gem that extends CanCan with a range of capabilities:
+* database-persisted permissions
+* export CanCan methods to the model layer (so that permissions can be applied in model methods, and easily set in a test case)
+* permissions inheritance (so that, for example, a User can inherit permissions from Roles and/or Groups)
+* caching of abilities (so that they don't need to be recalculated on each web request)
+* general-purpose access refinements (so that, for example, CanCan will automatically enforce multi-tenant or other security restrictions)
+
+## Limitations
+Cancannible's origin was in a web application that's been in production for over 3 years.
+This gem is an initial refactoring as a separate component. It continues to be used in production, but
+there are some limitations and constraints that will ideally be removed or changed over time:
+
+* It only supports ActiveRecord for permissions storage (specifically, it has been tested with PostgreSQL and SQLite)
+* It currently assumes permissions are stored in a Permission model with a specific structure
+* It works with the [CanCan](https://github.com/ryanb/cancan) gem. It has not yet been tested with the new [CanCanCan](https://github.com/CanCanCommunity/cancancan) gem.
+* It assumes and is only tested with Rails 3.2. Not yet with Rails 4.
+* It assumes your CanCan rules are setup with the default `Ability` class
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'cancannible'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install cancannible
+
+## Configuration
+
+A generator is provided to create:
+* a default initialization template
+* a Permission model and migration
+
+After installing the gem, run the generator:
+
+    $ rails generate cancannible:install
+
+## The Cancannible initialization file
+
+See the initialization file template for specific instructions. Use the initialization file to configure:
+* abilities caching
+* general-purpose access refinements
+
+## Configuring cached abilities storage
+
+Cancannible does not implement any specific storage mechanism - that is up to you to provide if you wish.
+
+Cached abilities storage is enabled by setting the `get_cached_abilities` and `store_cached_abilities` hooks with
+the appropriate implementation for your caching infrastructure.
+
+For example, this is a simple scheme using Redis:
+
+    Cancannible.setup do |config|
+
+      # Return an Ability object for +grantee+ or nil if not found
+      config.get_cached_abilities = proc{|grantee|
+        key = "user:#{grantee.id}:abilities"
+        Marshal.load(@redis.get(key))
+      }
+
+      # Command: put the +ability+ object for +grantee+ in the cache storage
+      config.store_cached_abilities = proc{|grantee,ability|
+        key = "user:#{grantee.id}:abilities"
+        @redis.set(key, Marshal.dump(ability))
+      }
+
+    end
+
+
+## Contributing
+
+1. Fork it ( https://github.com/evendis/cancannible/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+desc "Open an irb session preloaded with this library"
+task :console do
+  sh "irb -rubygems -I lib -r cancannible.rb"
+end

data/cancannible.gemspec

@@ -0,0 +1,31 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'cancannible/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "cancannible"
+  spec.version       = Cancannible::VERSION
+  spec.authors       = ["Paul Gallagher"]
+  spec.email         = ["paul@evendis.com"]
+  spec.summary       = "Dynamic, configurable permissions for CanCan"
+  spec.description   = "Extends CanCan with dynamic, inheritable permissions stored in a database, with caching and multi-tenant refinements"
+  spec.homepage      = "https://github.com/evendis/cancannible"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "activesupport", "~> 3.2"
+  spec.add_runtime_dependency "activemodel", "~> 3.2"
+  spec.add_runtime_dependency "cancan", "~> 1.6"
+
+  spec.add_development_dependency "activerecord", "~> 3.2"
+  spec.add_development_dependency "sqlite3", "~> 1.3"
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "guard-rspec", "~> 4.0"
+end

data/lib/cancannible.rb

@@ -0,0 +1,8 @@
+require 'active_support'
+require 'active_support/core_ext'
+require 'cancan'
+
+require "cancannible/version"
+require "cancannible/config"
+require "cancannible/ability_preload_adapter"
+require "cancannible/base"

data/lib/cancannible/ability_preload_adapter.rb

@@ -0,0 +1,15 @@
+module Cancannible::AbilityPreloadAdapter
+  extend ActiveSupport::Concern
+
+  included do
+
+    # Tap Ability.new to first preload permissions via Cancannible
+    alias_method :cancan_initialize, :initialize
+    def initialize(user)
+      user.preload_abilities(self) if user.respond_to? :preload_abilities
+      cancan_initialize(user)
+    end
+
+  end
+
+end

data/lib/cancannible/base.rb

@@ -0,0 +1,213 @@
+module Cancannible
+  extend ActiveSupport::Concern
+
+  included do
+    class_attribute :inheritable_permissions
+    self.inheritable_permissions = [] # default
+
+    has_many :permissions, as: :permissible, dependent: :destroy do
+      # generally use instance.can method, not permissions<< directly
+      def <<(arg)
+        ability, resource = arg
+        resource = nil if resource.blank?
+        asserted = arg[2].nil? ? true : arg[2]
+
+        case resource
+        when Class, Symbol
+          resource_type = resource.to_s
+          resource_id = nil
+        when nil
+          resource_type = resource_id = nil
+        else
+          resource_type = resource.class.to_s
+          resource_id = resource.try(:id)
+        end
+
+        permission = find_by_asserted_and_ability_and_resource_id_and_resource_type(
+          asserted, ability, resource_id, resource_type)
+        unless permission
+          permission = find_or_initialize_by_asserted_and_ability_and_resource_id_and_resource_type(
+            !asserted, ability, resource_id, resource_type)
+          permission.asserted = asserted
+          permission.save!
+        end
+
+        # if Rails.version =~ /3\.0/ # the rails 3.0 way
+        #   proxy_owner.instance_variable_set :@permissions, nil # invalidate the owner's permissions collection
+        #   proxy_owner.instance_variable_set :@abilities, nil # invalidate the owner's ability collection
+        # else
+          proxy_association.owner.instance_variable_set :@abilities, nil # invalidate the owner's ability collection
+        # end
+        permission
+      end
+    end
+
+  end
+
+  module ClassMethods
+    def inherit_permissions_from(*relations)
+      self.inheritable_permissions = relations
+    end
+  end
+
+  # Returns the Ability set for the owner.
+  # Set +refresh+ to true to force a reload of permissions.
+  def abilities(refresh = false)
+    @abilities = if refresh
+      nil
+    elsif get_cached_abilities.respond_to?(:call)
+      get_cached_abilities.call(self)
+    end
+    return @abilities if @abilities
+
+    @abilities ||= if ability_class = ('Ability'.constantize rescue nil)
+      unless ability_class.included_modules.include?(Cancannible::AbilityPreloadAdapter)
+        ability_class.send :include, Cancannible::AbilityPreloadAdapter
+      end
+      ability_class.new(self)
+    end
+
+    store_cached_abilities.call(self,@abilities) if store_cached_abilities.respond_to?(:call)
+    @abilities
+  end
+
+  def preload_abilities(cancan_ability_object)
+    # load inherited permissions to CanCan Abilities
+    preload_abilities_from_permissions(cancan_ability_object, inherited_permissions)
+    # load user-based permissions from database to CanCan Abilities
+    preload_abilities_from_permissions(cancan_ability_object, self.permissions.reload)
+    cancan_ability_object
+  end
+
+  def inherited_permissions
+    inherited_perms = []
+    self.class.inheritable_permissions.each do |relation|
+      Array(self.send(relation)).each do |record|
+        inherited_perms.concat(record.permissions.reload)
+      end
+    end
+    inherited_perms
+  end
+
+  # test for a permission - persisted or dynamic (delegated to CanCan)
+  def can?(ability, resource)
+    abilities.can?(ability, resource)
+  end
+
+  # test for a prohibition - persisted or dynamic (delegated to CanCan)
+  def cannot?(ability, resource)
+    abilities.cannot?(ability, resource)
+  end
+
+  # define a persisted permission
+  def can(ability, resource)
+    permissions << [ability, resource]
+  end
+
+  # define a persisted prohibition
+  def cannot(ability, resource)
+    permissions << [ability, resource, false]
+  end
+
+  private
+
+  def preload_abilities_from_permissions(cancan_ability_object,perms)
+    perms.each do |permission|
+      ability = permission.ability.to_sym
+      action = permission.asserted ? :can : :cannot
+
+      if resource_type = permission.resource_type
+        begin
+          resource_type = resource_type==resource_type.downcase ? resource_type.to_sym : resource_type.constantize
+          model_resource = resource_type.respond_to?(:new) ? resource_type.new : resource_type
+        rescue
+          model_resource = nil
+        end
+      end
+
+      if !resource_type || resource_type.is_a?(Symbol)
+        # nil or symbolic resource types:
+        # apply generic unrestricted permission to the resource_type
+        cancan_ability_object.send( action,  ability, resource_type )
+        next
+      else
+        # model-based resource types:
+        # skip if we cannot get a model instance
+        next unless model_resource
+      end
+
+      if permission.resource_id.nil?
+
+        if action == :cannot
+          # apply generic unrestricted permission to the class
+          cancan_ability_object.send( action, ability, resource_type )
+        else
+
+          refinements = Cancannible.refinements.each_with_object([]) do |refinement,memo|
+            refinement_attributes = refinement.dup
+
+            allow_nil = !!(refinement_attributes.delete(:allow_nil))
+
+            refinement_if_condition = refinement_attributes.delete(:if)
+            next if refinement_if_condition.respond_to?(:call) && !refinement_if_condition.call(self,model_resource)
+
+            refinement_scope = Array(refinement_attributes.delete(:scope))
+            next if refinement_scope.present? &&  !refinement_scope.include?(ability)
+
+            refinement_except = Array(refinement_attributes.delete(:except))
+            next if refinement_except.present? &&  refinement_except.include?(ability)
+
+            refinement_attribute_names = refinement_attributes.keys.map{|k| "#{k}" }
+            next unless (refinement_attribute_names - model_resource.attribute_names).empty?
+
+            restriction = {}
+            refinement_attributes.each do |key,value|
+              if value.is_a?(Symbol)
+                if self.respond_to?(value)
+                  restriction[key] = if allow_nil
+                    Array(self.send(value)) + [nil]
+                  else
+                    self.send(value)
+                  end
+                end
+              else
+                restriction[key] = value
+              end
+            end
+            memo.push(restriction) if restriction.present?
+          end
+
+          if refinements.empty?
+            # apply generic unrestricted permission to the class
+            cancan_ability_object.send( action, ability, resource_type )
+          else
+            refinements.each do |refinement|
+              cancan_ability_object.send( action,  ability, resource_type, refinement)
+            end
+          end
+
+        end
+
+      elsif resource_type.find_by_id(permission.resource_id)
+        cancan_ability_object.send( action,  ability, resource_type, id: permission.resource_id)
+      end
+    end
+  end
+end
+
+
+module Cancannible
+  # This module is automatically included into all controllers.
+  # It overrides some CanCan ControllerAdditions
+  module ControllerAdditions
+    def current_ability
+      current_user.try(:abilities)
+    end
+  end
+end
+
+if defined? ActionController::Base
+  ActionController::Base.class_eval do
+    include Cancannible::ControllerAdditions
+  end
+end