cancannible 0.0.1

data/lib/cancannible/config.rb

@@ -0,0 +1,26 @@
+module Cancannible
+
+  mattr_accessor :refinements
+  mattr_accessor :get_cached_abilities
+  mattr_accessor :store_cached_abilities
+
+  # Default way to configure the gem. Yields a block that gives access to all the config variables.
+  # Calling setup will reset all existing values.
+  def self.setup
+    reset!
+    yield self
+    self
+  end
+
+  def self.reset!
+    self.refinements = []
+    self.get_cached_abilities = nil
+    self.store_cached_abilities = nil
+  end
+  reset!
+
+  def self.refine_access(refinement={})
+    self.refinements << refinement
+  end
+
+end

data/lib/cancannible/version.rb

@@ -0,0 +1,3 @@
+module Cancannible
+  VERSION = "0.0.1"
+end

data/lib/generators/cancannible/install_generator.rb

@@ -0,0 +1,39 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+require 'rails/generators/active_record'
+
+module Cancannible
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      self.source_paths << File.join(File.dirname(__FILE__), 'templates')
+
+      desc "This generator creates a cancannible initializer file and permissions model migration"
+
+      def create_initializer_file
+        template 'cancannible_initializer.rb', 'config/initializers/cancannible.rb'
+      end
+
+      def create_permission_migration_file
+        migration_template 'migration.rb', 'db/migrate/create_cancannible_permissions.rb'
+      end
+
+      def create_permission_model_file
+        template 'permission.rb', 'app/models/permission.rb'
+      end
+
+      # while methods have moved around this has been the implementation
+      # since ActiveRecord 3.0
+      def self.next_migration_number(dirname)
+        next_migration_number = current_migration_number(dirname) + 1
+        if ActiveRecord::Base.timestamped_migrations
+          [Time.now.utc.strftime("%Y%m%d%H%M%S"), "%.14d" % next_migration_number].max
+        else
+          "%.3d" % next_migration_number
+        end
+      end
+    end
+
+  end
+end

data/lib/generators/cancannible/templates/cancannible_initializer.rb

@@ -0,0 +1,97 @@
+Cancannible.setup do |config|
+
+  # ABILITY CACHING
+  # ===============
+  # Cancannible supports optional ability caching. This can provide a significant performance
+  # improvement, since abilities do not need to be recalculated on each web request.
+  # No specific caching technology is enforced: you can use whatever makes sense in your application
+  # environment. To enable caching, you just need to provide two methods here: `get_cached_abilities`
+  # and `store_cached_abilities`.
+
+  # Return an Ability object for +grantee+ or nil if not found
+  # config.get_cached_abilities = proc{|grantee|
+  #   # This is a simple example of using Redis (assumes @redis correctly connected)
+  #   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|
+  #   # This is a simple example of using Redis (assumes @redis correctly connected)
+  #   key = "user:#{grantee.id}:abilities"
+  #   @redis.set(key, Marshal.dump(ability))
+  # }
+
+
+  # ACCESS REFINMENTS
+  # Cancannible allows general-purpose access refinements to be declared here. This will be enforced
+  # in addition to any rules defined in you Ability.rb file.
+
+  # These are primarily intended to enforce data partitioning (multi-tenancy) and general security rules such as:
+  # "only show data related to customers that I have permissions to see", or
+  # "make sure I can see records that I created (regardless of other restrictions)"
+
+  # The syntax here is not as flexible as that supported in the Ability.rb file, but have the benefit of
+  # potentially refining any/all permissions that are configured in the permissions tables.
+
+  # The following examples illustrate the options that are available. These can be used individually or in combination.
+
+
+  # Basic syntax example:
+  #   config.refine_access customer_id: :accessible_customer_ids
+  #
+  # This means:
+  # - for any resource permission loaded/inherited from the database
+  # - where the resource has a :customer_id attribute
+  # - restrict access to only those with values from my (the grantee) :accessible_customer_ids method
+  #
+  # In other words, say we have a Contract model that has a :customer_id attribute, and permissions are granted thus:
+  #    user.can(:read,Contract)
+  # Then if we define a user.accessible_customer_ids method, these values will be used to restrict user's access to Contract records
+  #
+  # Note: the rule is ignored if the resource does not sport the attribute mentioned, or if the grantee method is not defined.
+
+
+  # Multiple conditions syntax example:
+  #   config.refine_access customer_id: :accessible_customer_ids, product_id: :accessible_product_ids
+  #
+  # This restricts access to only records matching all conditions
+
+
+  # Fixed value conditions syntax example:
+  #   config.refine_access customer_id: 42, status: 'open'
+  #
+  # Fixed match-values may be provided instead of methods
+
+
+  # Limited ability scope syntax example:
+  #   config.refine_access customer_id: :accessible_customer_ids, scope: :read
+  #   config.refine_access customer_id: :accessible_customer_ids, scope: [:read,:update]
+  #
+  # The `scope` parameter causes the rule to only be applied for the specified ability rules
+
+
+  # Limited ability scope syntax example:
+  #   config.refine_access customer_id: :accessible_customer_ids, except: :read
+  #   config.refine_access customer_id: :accessible_customer_ids, except: [:read,:update]
+  #
+  # The `except` parameter causes the rule to be applied for all abilities except those specified.
+
+
+  # Allow nil syntax example:
+  #   config.refine_access customer_id: :accessible_customer_ids, allow_nil: true
+  #
+  # The `allow_nil` parameter changes the rule so that nil/NULL values are allowed through. By default, this is false.
+
+
+  # Conditional syntax example:
+  #   config.refine_access customer_id: :accessible_customer_ids, if: proc{|grantee,model_resource|
+  #     grantee.name = 'Paul' && model_resource.is_a?(Special)
+  #   }
+  #
+  # The `if` parameter allowws you to provide a procedure that will dynamically determine if the rule should be applied.
+  # It should return true or false. The `grantee` is the actual instance that permissions are being applied to,
+  # and `model_resource` is an example record (unsaved) of the kind of resource that the rule is being applied to.
+
+
+end

data/lib/generators/cancannible/templates/migration.rb

@@ -0,0 +1,15 @@
+class CreateCancanniblePermissions < ActiveRecord::Migration
+  def change
+    create_table :permissions, force: true do |table|
+      table.integer  :permissible_id
+      table.string   :permissible_type
+      table.integer  :resource_id
+      table.string   :resource_type
+      table.string   :ability
+      table.boolean  :asserted
+      table.datetime :created_at
+      table.datetime :updated_at
+    end
+    add_index :permissions, [:permissible_id, :permissible_type], name: "index_permissions_permissible"
+  end
+end

data/lib/generators/cancannible/templates/permission.rb

@@ -0,0 +1,8 @@
+# The Permission class stores permissions managed by CanCan and Cancannible
+class Permission < ActiveRecord::Base
+  belongs_to :permissible, polymorphic: true
+  belongs_to :resource, polymorphic: true
+
+  validates_uniqueness_of :ability, scope: [:resource_id, :resource_type, :permissible_id, :permissible_type]
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,16 @@
+ENV["RAILS_ENV"] ||= 'test'
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+require 'cancannible'
+require 'active_record'
+require 'sqlite3'
+
+# Requires supporting files with custom matchers and macros, etc,
+# in ./support/ and its subdirectories.
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}
+
+RSpec.configure do |config|
+  config.before do
+    Cancannible.reset!
+    run_migrations
+  end
+end

data/spec/support/ability.rb

@@ -0,0 +1,5 @@
+class Ability
+  include CanCan::Ability
+  def initialize(user)
+  end
+end

data/spec/support/migrations_helper.rb

@@ -0,0 +1,61 @@
+module MigrationsHelper
+
+  def run_migrations
+    ActiveRecord::Base.establish_connection({
+        adapter:   'sqlite3',
+        database:  ':memory:'
+    })
+
+    ActiveRecord::Migration.suppress_messages do
+      ActiveRecord::Schema.define(:version => 0) do
+
+        create_table "members", :force => true do |t|
+          t.string   "name"
+          t.string   "email"
+        end
+
+        create_table "users", :force => true do |t|
+          t.string   "username"
+          t.string   "email"
+          t.integer  "group_id"
+        end
+
+        create_table "permissions", :force => true do |t|
+          t.boolean  "asserted"
+          t.integer  "permissible_id"
+          t.string   "permissible_type"
+          t.integer  "resource_id"
+          t.string   "resource_type"
+          t.string   "ability"
+          t.datetime "created_at"
+          t.datetime "updated_at"
+        end
+
+        create_table "roles", :force => true do |t|
+          t.string   "name"
+        end
+
+        create_table "roles_users", :force => true do |t|
+          t.string   "name"
+          t.integer  "role_id"
+          t.integer  "user_id"
+        end
+
+        create_table "groups", :force => true do |t|
+          t.string   "name"
+        end
+
+        create_table "widgets", :force => true do |t|
+          t.string   "name"
+          t.integer  "category_id"
+        end
+
+      end
+    end
+  end
+
+end
+
+RSpec.configure do |conf|
+  conf.include MigrationsHelper
+end

data/spec/support/models.rb

@@ -0,0 +1,45 @@
+# These model definitions are just used for the test scenarios
+
+# The Permission class stores permissions maanged by CanCan and Cancannible
+class Permission < ActiveRecord::Base
+  belongs_to :permissible, polymorphic: true
+  belongs_to :resource, polymorphic: true
+
+  validates_uniqueness_of :ability,
+    :scope => [:resource_id, :resource_type,
+      :permissible_id, :permissible_type]
+end
+
+class Member < ActiveRecord::Base
+  include Cancannible
+end
+
+class User < ActiveRecord::Base
+  has_many :roles_users, class_name: 'RolesUsers'
+  has_many :roles, :through => :roles_users
+  belongs_to :group
+
+  include Cancannible
+  inherit_permissions_from :roles, :group
+end
+
+class RolesUsers < ActiveRecord::Base
+  belongs_to :role
+  belongs_to :user
+end
+
+class Role < ActiveRecord::Base
+  has_many :roles_users, :class_name => 'RolesUsers'
+  has_many :users, :through => :roles_users
+
+  include Cancannible
+end
+
+class Group < ActiveRecord::Base
+  has_many :users
+
+  include Cancannible
+end
+
+class Widget < ActiveRecord::Base
+end

data/spec/unit/base_spec.rb

@@ -0,0 +1,152 @@
+require 'spec_helper'
+
+describe Cancannible do
+  let(:grantee_class) { Member }
+
+  context "without permissions inheritance" do
+
+    describe "##inheritable_permissions" do
+      subject { grantee_class.inheritable_permissions }
+      it { should be_empty }
+    end
+
+    subject(:grantee) { grantee_class.create! }
+
+    describe "#abilities" do
+      subject(:abilities) { grantee.abilities }
+      it { should be_a(Ability) }
+      it "should initialise @abilities instance var" do
+        expect { abilities }.to change { grantee.instance_variable_get("@abilities") }.from(nil)
+      end
+    end
+
+    context "with a symbolic resource" do
+      let!(:resource) { :something }
+
+      describe "#can?" do
+        subject { grantee.can?(:read, resource) }
+        context "when permission is not set" do
+          it { should be_falsey }
+        end
+        context "when permission is set" do
+          before { grantee.can(:read, resource) }
+          it { should be_truthy }
+        end
+        context "when cannot is asserted" do
+          before { grantee.cannot(:read, resource) }
+          it { should be_falsey }
+        end
+      end
+
+      describe "#cannot?" do
+        subject { grantee.cannot?(:read, resource) }
+        context "when permission is not asserted" do
+          it { should be_truthy }
+        end
+        context "when permission is not asserted but can is" do
+          before { grantee.can(:read, resource) }
+          it { should be_falsey }
+        end
+        context "when permission is asserted" do
+          before { grantee.cannot(:read, resource) }
+          it { should be_truthy }
+        end
+      end
+    end
+
+    context "with a nil resource" do
+      let!(:resource) { nil }
+      describe "#can? -> nil" do
+        subject { grantee.can?(:read, nil) }
+        context "when permission is not set" do
+          it { should be_falsey }
+        end
+        context "when permission is set" do
+          before { grantee.can(:read, resource) }
+          it { should be_truthy }
+        end
+      end
+      describe "#can? -> ''" do
+        subject { grantee.can?(:read, '') }
+        context "when permission is not set" do
+          it { should be_falsey }
+        end
+        context "when permission is set" do
+          before { grantee.can(:read, resource) }
+          it { should be_falsey }
+        end
+      end
+    end
+
+
+    context "with a resource class" do
+      let!(:resource) { Widget }
+
+      describe "#can?" do
+        subject { grantee.can?(:read, resource) }
+        context "when permission is not set" do
+          it { should be_falsey }
+        end
+        context "when permission is set" do
+          before { grantee.can(:read, resource) }
+          it { should be_truthy }
+        end
+      end
+    end
+
+    context "with a resource instance" do
+      let!(:resource) { Widget.create! }
+      let!(:other_resource) { Widget.create! }
+
+      describe "#can?" do
+        subject { grantee.can?(:read, resource) }
+        context "when permission is not set" do
+          it { should be_falsey }
+        end
+        context "when permission is set" do
+          before { grantee.can(:read, resource) }
+          it { should be_truthy }
+          context "but for other instances" do
+            subject { grantee.can?(:read, other_resource) }
+            it { should be_falsey }
+          end
+        end
+      end
+    end
+
+    context "with a non-existent model" do
+      describe "instance" do
+        let!(:obsolete_permission) {grantee.permissions.create!(asserted: true, ability: 'manage', resource_type: 'Bogative', resource_id: 33) }
+        it "should not error on load" do
+          expect { grantee.abilities }.to_not raise_error
+        end
+      end
+      describe "class" do
+        let!(:obsolete_permission) {grantee.permissions.create!(asserted: true, ability: 'manage', resource_type: 'Bogative') }
+        it "should not error on load" do
+          grantee.abilities
+          expect { grantee.abilities }.to_not raise_error
+        end
+      end
+    end
+
+    context "with an invalid model" do
+      class SuperBogative < ActiveRecord::Base
+      end
+      context "instance" do
+        let!(:obsolete_permission) { grantee.permissions.create!(asserted: true, ability: 'manage', resource_type: 'SuperBogative', resource_id: 33) }
+        it "should not error on load" do
+          expect { grantee.abilities }.to_not raise_error
+        end
+      end
+      context "class" do
+        let!(:obsolete_permission) { grantee.permissions.create!(asserted: true, ability: 'manage', resource_type: 'SuperBogative') }
+        it "should not error on load" do
+          expect { grantee.abilities }.to_not raise_error
+        end
+      end
+    end
+
+  end
+
+end