authorule 1.0.0

data/lib/authorule/rule_base.rb

@@ -0,0 +1,141 @@
+module Authorule
+
+  # A permission rule base. This class performs the heart of the permission checking algorithms.
+  #
+  # == Algorithm description
+  #
+  # A rule base is always queried for one permission. The result should be whether it is allowed or denied.
+  #
+  # When running a permission through the rule base, the permission itself, and all dependent permissions
+  # are run through the rule base. See {Permission#dependencies} for more info about permission dependencies.
+  #
+  # The last defined rule (i.e. the rule with the highest priority) matching *any* of the checks is taken
+  # as the deciding rule.
+  #
+  # == Example
+  #
+  # Let's illustrate the given algorithm with an example. Let's say we have the following permissions, taken
+  # from the UI library:
+  #
+  # * +SpacePermission+: a permission to access a certain UI space (a collection of UI resources)
+  # * +ResourcePermission+: a permission to access a certain resource
+  #
+  # A resource permission has a dependency on its corresponding space permission. In other words, a user must
+  # have access to the resource's space as well as the resource itself for it to be accessible.
+  #
+  # Then, we consider a rule base with the following rules:
+  #
+  # 1. Deny all
+  # 2. Allow space 'CRM'
+  # 3. Deny resource 'Account'
+  #
+  # Now, we need to check whether the user may view the resource 'Account':
+  #
+  #   permission = ResourcePermission.new(account_resource, :view)
+  #
+  # When resolving all dependencies, we end up with the following list of permissions:
+  #
+  #   permissions = permission.resolve_dependencies
+  #   # => [ SpacePermission.new(crm_space), ResourcePermission.new(account_resource, :view) ]
+  #
+  # Both of these permissions are now run through the rule base. The first permission is matched by rules
+  # 1 (all) and 2 (space 'CRM'). The second permission is matched by rules 1 (all) and 3 (resource 'Account').
+  # The last defined rule is the third rule. As it is set to deny access, the resulting access to the permission
+  # is denied. This makes sense because we deny it last in line.
+  #
+  # If however, the rule base were to switch around 2 and 3, the rule base would look as follows:
+  #
+  # 1. Deny all
+  # 2. Deny resource 'Account'
+  # 3. Allow space 'CRM'
+  #
+  # Now, the first permission will be matched by rule 3, which is the last rule to match. As it is set to allow
+  # access, the resulting access to the permission is allowed. As you can see, the second rule is overruled by the
+  # more generic rule 3.
+  class RuleBase
+
+    ######
+    # Initialization
+
+      # Initializes the rule base with the given rules.
+      def initialize(rules)
+        @rules = rules.to_a
+        @index = build_index
+      end
+
+    ######
+    # Attributes
+
+      # @!attribute [r] rules
+      # @return [Array] The rules in the rule base.
+      attr_reader :rules
+
+    ######
+    # Index
+
+      # Builds an index that maps a permission key into a rule index.
+      def build_index
+        index = {}
+
+        rules.each_with_index do |rule, idx|
+          key = rule.key
+
+          # Use this to make sure any duplicate entry uses the maximum index (i.e. last defined rule).
+          index[key] = [ index[key], idx ].compact.max
+        end
+        index
+      end
+      private :build_index
+
+    ######
+    # Runner
+
+      # Runs the given permission through the rule base.
+      #
+      # @return [true|false] +true+ if the permission is allowed, +false+ if not.
+      def run(permission)
+        last_rule_index = nil
+
+        permission.with_dependencies.each do |permission|
+          keys = permission_checks(permission)
+
+          # Compare the current index with the indices of all rules that match and take the maximum.
+          last_rule_index = ([ last_rule_index ] + keys.map{ |key| @index[key] }.flatten).compact.max
+        end
+
+        if last_rule_index
+          rules[last_rule_index].allow?
+        else
+          # The default policy is to deny the permission if no rules match.
+          false
+        end
+      end
+
+      # Determines all permission checks for the given permission.
+      def permission_checks(permission)
+        keys = []
+
+        if permission.action
+          # Add '<kind>:<name>:<action>'
+          keys << [ permission.kind, permission.name, permission.action ].join(':')
+
+          # Add '<kind>:all(:<action>'
+          keys << [ permission.kind, 'all', permission.action ].join(':')
+        end
+
+        # Add '<kind>:<name>'
+        keys << [ permission.kind, permission.name ].join(':')
+
+        # Add '<kind>:all'
+        keys << [ permission.kind, 'all' ].join(':')
+
+        # Add 'all'
+        keys << 'all'
+
+        keys
+      end
+      private :permission_checks
+
+  end
+
+end

data/lib/authorule/version.rb

@@ -0,0 +1,3 @@
+module Authorule
+  VERSION = "1.0.0"
+end

data/lib/authorule.rb

@@ -0,0 +1,79 @@
+require 'active_support'
+require 'active_support/core_ext'
+
+module Authorule
+  extend ActiveSupport::Autoload
+
+  class PermissionResolutionError < RuntimeError
+  end
+
+  autoload :Permission
+  autoload :Rule
+  autoload :RuleBase
+  autoload :PermissionAccessors
+  autoload :PermissionHolder
+
+  ######
+  # Permission registration
+
+    class DuplicatePermission < RuntimeError
+    end
+
+    @@permission_classes = {}
+    mattr_reader :permission_classes
+
+    def self.register(kind, klass)
+      kind = kind.to_sym
+      unless klass < Permission
+        raise ArgumentError, "class #{klass.name} cannot be registered as a permission kind: it should be derived from Authorule::Permission"
+      end
+      if Authorule.permission_classes[kind]
+        raise DuplicatePermission, "another permission class has already been registered for kind :#{kind}"
+      end
+
+      permission_classes[kind] = klass
+    end
+
+  ######
+  # Permission resolution
+
+    # Resolves a target. Tries all registered permission classes with a resolve block, and runs the target
+    # through the block. If anythin is returned, it is passed into the constructor of that permission class.
+    def self.resolve(target, action = nil)
+      return target if target.is_a?(Authorule::Permission)
+
+      permission_classes.values.each do |klass|
+        next unless klass.resolve_block
+        resolved = klass.resolve_block.call(target)
+
+        return klass.new(resolved, action) if resolved
+      end
+
+      # If we got here, no schema returned a matching permission.
+      raise PermissionResolutionError, "target #{target} could not be resolved into a permission"
+    end
+
+  ######
+  # Permission listing
+
+    # Retrieves all available permissions, organized by their kind, into a hash.
+    #
+    # @return [Hash<Symbol,Array<Permission>>] An organized list of permissions.
+    def self.available_permissions
+      available_permissions = {}
+
+      permission_classes.each do |kind, klass|
+        next unless klass.list_block
+
+        available_permissions[kind] = []
+        objects = klass.list_block.call
+
+        objects.each do |object|
+          available_permissions[kind] << klass.new(object)
+        end
+      end
+
+      available_permissions
+    end
+
+end

data/lib/tasks/permissions.rake

@@ -0,0 +1,17 @@
+namespace :authorule do
+
+  desc "Lists all available permissions"
+  task :list => :environment do
+    Authorule.available_permissions.each do |kind, permissions|
+      puts "#{kind}:"
+      permissions.each do |permission|
+        if permission.available_actions.blank?
+          puts "  #{permission.name}"
+        else
+          puts "  #{permission.name} (#{permission.available_actions.join(', ')})"
+        end
+      end
+    end
+  end
+
+end

data/spec/authorule/permission_holder_spec.rb

@@ -0,0 +1,137 @@
+require 'spec_helper'
+require 'active_record'
+
+describe Authorule::PermissionHolder do
+
+  let(:model) do
+    Class.new(ActiveRecord::Base) do
+      include Authorule::PermissionHolder
+      is_permission_holder!
+    end
+  end
+  let(:record) do
+    record = Class.new()
+    record.class.send(:include, Authorule::PermissionHolder)
+    record.class.stub(:has_many)
+    record.class.is_permission_holder!
+    record
+  end
+
+  it "should add a 'rules' association" do
+    association = model.reflect_on_association(:permission_rules)
+
+    association.should_not be_nil
+    association.macro.should == :has_many
+  end
+
+  describe '#permission_rule_base' do
+
+    it "should return a rule base based on the permission rules for the holder" do
+      rules = []
+      record.should_receive(:permission_rules).with(true).and_return(rules)
+
+      record.permission_rule_base.should be_a(Authorule::RuleBase)
+      record.permission_rule_base.rules.should be(rules)
+    end
+
+    it "should cache its value" do
+      rules = []
+      record.should_receive(:permission_rules).with(true).once.and_return(rules)
+
+      base = record.permission_rule_base
+      record.permission_rule_base.should be(base)
+    end
+
+    it "should not cache its value when reload=false" do
+      rules = []
+      record.should_receive(:permission_rules).with(true).twice.and_return(rules)
+
+      base = record.permission_rule_base
+      record.permission_rule_base(true).should_not be(base)
+    end
+
+  end
+
+  describe 'has_permission?' do
+    let(:rule_base) { double() }
+    before { record.should_receive(:permission_rule_base).and_return(rule_base) }
+
+    it "should run the given permission through the rule base, and return true if that returns true" do
+      permission = double()
+      rule_base.should_receive(:run).with(permission).and_return(true)
+      record.should have_permission(permission)
+    end
+
+    it "should run the given permission through the rule base, and return false if that returns false" do
+      permission = double()
+      rule_base.should_receive(:run).with(permission).and_return(false)
+      record.should_not have_permission(permission)
+    end
+  end
+
+  describe 'may_* methods' do
+
+    let(:target) { double() }
+    let(:permission) { double() }
+
+    describe 'may_access?' do
+
+      it "should resolve the given argument to a permission, check it, and return what it returns" do
+        result = double()
+
+        Authorule.should_receive(:resolve).with(target).and_return(permission)
+        record.should_receive(:has_permission?).with(permission).and_return(result)
+        record.may_access?(target).should be(result)
+      end
+
+    end
+
+    describe 'may?' do
+
+      before { Authorule.should_receive(:resolve).with(target, :view).and_return(permission) }
+
+      context "with a valid action" do
+        it "should resolve the given argument to a permission, check it, and return what it returns" do
+          permission.should_receive(:available_actions).and_return([:view])
+
+          result = double()
+          record.should_receive(:has_permission?).with(permission).and_return(result)
+
+          record.may?(:view, target).should be(result)
+        end
+      end
+
+      context "with an invalid action" do
+        it "should raise an error" do
+          permission.should_receive(:available_actions).and_return([:create])
+          permission.should_receive(:class).and_return(double(:kind => :test))
+          expect { record.may?(:view, target) }.to raise_error(ArgumentError, "action :view not available for permission of kind :test")
+        end
+      end
+
+    end
+
+    describe '#may_not_access?' do
+      it "should invert the result from may_access?" do
+        record.should_receive(:may_access?).with(target).and_return(false)
+        record.may_not_access?(target).should == true
+      end
+      it "should invert the result from may_access?" do
+        record.should_receive(:may_access?).with(target).and_return(true)
+        record.may_not_access?(target).should == false
+      end
+    end
+
+    describe '#may_not?' do
+      it "should invert the result from may?" do
+        record.should_receive(:may?).with(:view, target).and_return(false)
+        record.may_not?(:view, target).should == true
+      end
+      it "should invert the result from may?" do
+        record.should_receive(:may?).with(:view, target).and_return(true)
+        record.may_not?(:view, target).should == false
+      end
+    end
+  end
+
+end

data/spec/authorule/rule_base_spec.rb

@@ -0,0 +1,127 @@
+require 'spec_helper'
+
+describe Authorule::RuleBase do
+
+  let(:permission) { double() }
+  let(:rule_base) { Authorule::RuleBase.new(rules) }
+
+  context "providing no rules" do
+    let(:rules) { [] }
+
+    it "should deny all access" do
+      permission.should_receive(:with_dependencies).and_return([
+        double(:kind => :custom, :name => 'something', :action => nil)
+      ])
+      rule_base.run(permission).should == false
+    end
+  end
+
+  context "providing an 'allow all' rule" do
+    let(:rules) { [ double(:key => 'all', :allow? => true) ] }
+
+    it "should allow all access" do
+      permission.should_receive(:with_dependencies).and_return([
+        double(:kind => :custom, :name => 'something', :action => nil)
+      ])
+      rule_base.run(permission).should == true
+    end
+  end
+
+  context "providing a cascading rule set" do
+    let(:rules) do
+      [
+        double(:key => 'all', :allow? => false),   # Deny all
+        double(:key => 'resource:all', :allow? => true),   # Allow all resources
+        double(:key => 'resource:account', :allow? => false),   # Deny access to resource 'account'
+      ]
+    end
+
+    it "should deny access to a non-resource permission" do
+      permission.should_receive(:with_dependencies).and_return([
+        double(:kind => :custom, :name => 'something', :action => nil)
+      ])
+      rule_base.run(permission).should == false
+    end
+
+    it "should allow access to a non-account resource permission" do
+      permission.should_receive(:with_dependencies).and_return([
+        double(:kind => :resource, :name => 'contact', :action => nil)
+      ])
+      rule_base.run(permission).should == true
+    end
+
+    it "should deny access to an account resource permission" do
+      permission.should_receive(:with_dependencies).and_return([
+        double(:kind => :resource, :name => 'account', :action => nil)
+      ])
+      rule_base.run(permission).should == false
+    end
+  end
+
+  context "using a permission with dependencies" do
+
+    let(:permission) do
+      # Create a permission that requires both access to space:crm as well as resource:account.
+      double(:with_dependencies => [
+        double(:kind => :space, :name => 'crm', :action => nil),
+        double(:kind => :resource, :name => 'account', :action => nil)
+      ])
+    end
+
+    # deny CRM, allow account
+    let(:crm_rule) { double(:key => 'space:crm', :allow? => false) }
+    let(:account_rule) { double(:key => 'space:crm', :allow? => true) }
+
+    it "should allow access if the account rule is defined last" do
+      rule_base = Authorule::RuleBase.new([ crm_rule, account_rule ])
+      rule_base.run(permission).should == true
+    end
+
+    it "should deny access if the CRM rule is defined last" do
+      rule_base = Authorule::RuleBase.new([ account_rule, crm_rule ])
+      rule_base.run(permission).should == false
+    end
+
+  end
+
+  context "targeting specific actions" do
+
+    let(:rules) do
+      [
+        double(:key => 'resource:all', :allow? => true),   # Allow all resources
+        double(:key => 'resource:all:create', :allow? => false),   # Deny creating all resources
+        double(:key => 'resource:account:create', :allow? => true),   # Deny creating resource 'account'
+      ]
+    end
+
+    it "should allow viewing a 'contact' resource" do
+      permission.should_receive(:with_dependencies).and_return([
+        double(:kind => :resource, :name => 'contact', :action => :view)
+      ])
+      rule_base.run(permission).should == true
+    end
+
+    it "should allow viewing an 'account' resource" do
+      permission.should_receive(:with_dependencies).and_return([
+        double(:kind => :resource, :name => 'account', :action => :view)
+      ])
+      rule_base.run(permission).should == true
+    end
+
+    it "should deny creating a 'contact' resource" do
+      permission.should_receive(:with_dependencies).and_return([
+        double(:kind => :resource, :name => 'contact', :action => :create)
+      ])
+      rule_base.run(permission).should == false
+    end
+
+    it "should allow creating an 'account' resource" do
+      permission.should_receive(:with_dependencies).and_return([
+        double(:kind => :resource, :name => 'account', :action => :create)
+      ])
+      rule_base.run(permission).should == true
+    end
+
+  end
+
+end

data/spec/authorule_spec.rb

@@ -0,0 +1,113 @@
+require 'spec_helper'
+
+describe Authorule do
+
+  # Stub the permission registry to prevent messing with the actual set up.
+  let(:registry) { Hash.new }
+  before { Authorule.stub(:permission_classes).and_return(registry) }
+
+  ######
+  # Registration
+
+    describe '#register' do
+
+      it "should allow any class derived from Permission to be registered" do
+        klass = Class.new(Authorule::Permission)
+
+        Authorule.register :test, klass
+        registry[:test].should == klass
+      end
+
+      it "should not allow any other class to be registered" do
+        klass = Class.new
+        expect { Authorule.register :test, klass }.to raise_error(ArgumentError)
+      end
+
+      it "should not allow a registration for the same kind twice" do
+        klass = Class.new(Authorule::Permission)
+
+        Authorule.register :test, klass
+        expect { Authorule.register :test, klass }.to raise_error(Authorule::DuplicatePermission)
+      end
+
+
+    end
+
+    describe 'Authorule::Permission.kind' do
+
+      # A bit outside the scope of this file, but it's part of registration.
+      it "should allow any Authorule::Permission derived class to register itself" do
+        klass = Class.new(Authorule::Permission)
+
+        Authorule.should_receive(:register).with(:test, klass)
+        klass.class_eval { register :test }
+      end
+
+    end
+
+  ######
+  # Resolution & available permissions
+
+    describe '.resolve' do
+      let(:permission_class1) { Class.new(Authorule::Permission) }
+      let(:permission_class2) { Class.new(Authorule::Permission) }
+      before do
+        Authorule.stub(:permission_classes).and_return({})
+        Authorule.register :permission1, permission_class1
+        Authorule.register :permission2, permission_class2
+      end
+
+      it "should resolve any instance of Authorule::Permission into itself" do
+        permission = Authorule::Permission.new(double())
+        Authorule.resolve(permission).should be(permission)
+      end
+
+      it "should raise PermissionResolutionError if no permission classes were registered" do
+        Authorule.stub(:permission_classes).and_return({})
+        expect { Authorule.resolve(double()) }.to raise_error(Authorule::PermissionResolutionError)
+      end
+
+      it "should raise PermissionResolutionError if no permission classes with resolution blocks were registered" do
+        expect { Authorule.resolve(double()) }.to raise_error(Authorule::PermissionResolutionError)
+      end
+
+      it "should run through all registered permission classes and try to resolve the target - the first one found should be instantiated" do
+        target = double()
+        resolved = double()
+        permission_class1.stub(:resolve_block).and_return(->(tgt) { tgt != target ? resolved : nil })
+        permission_class2.stub(:resolve_block).and_return(->(tgt) { tgt == target ? resolved : nil })
+
+        permission = double()
+        permission_class2.should_receive(:new).with(resolved, :view).and_return(permission)
+
+        Authorule.resolve(target, :view).should be(permission)
+      end
+    end
+
+    describe '.available_permissions' do
+      let(:permission_class1) { Class.new(Authorule::Permission) }
+      let(:permission_class2) { Class.new(Authorule::Permission) }
+      before do
+        Authorule.stub(:permission_classes).and_return({})
+        Authorule.register :permission1, permission_class1
+        Authorule.register :permission2, permission_class2
+      end
+
+      it "should include an item for each permission class having a list block" do
+        targets = [ :one, :two ]
+        permission_class1.stub(:list_block).and_return(proc { targets })
+
+        permissions = Authorule.available_permissions
+        permissions.should have(1).item
+
+        permissions[:permission1].should be_a(Array)
+        permissions[:permission1].should have(2).items
+
+        permissions[:permission1][0].should be_a(permission_class1)
+        permissions[:permission1][0].object.should == :one
+        permissions[:permission1][1].should be_a(permission_class1)
+        permissions[:permission1][1].object.should == :two
+      end
+    end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,19 @@
+require 'simplecov'
+SimpleCov.start do
+  add_filter "spec/"
+end
+
+require 'authorule'
+require 'rspec/autorun'
+
+RSpec.configure do |config|
+
+  config.mock_with :rspec do |config|
+    config.syntax = [ :should, :expect ]
+  end
+
+end
+
+# Requires supporting ruby files with custom matchers and macros, etc,
+# in spec/support/ and its subdirectories.
+Dir[File.expand_path("../support/**/*.rb", __FILE__)].each {|f| require f}