roleback 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ba408ae577a2cf4e25474b107715294f454a7d1f9c99b390d4f19b10e4c9e355
+  data.tar.gz: 268e804302e6b0f79a51b6e0620b03850927eee864c6d17232fe2c37868ed07f
+SHA512:
+  metadata.gz: 56ab51c35baeed4d942250986065461deec60ac9cc0c32d5d46058b26b8bc32f043e179cbcafa17daf7fe8e97028acf3975ea7a858f762319bc3ff7762a9998c
+  data.tar.gz: f833af2acffdb889406f0d61e6c32beef2f805044ee233a27acce888b257b2db2627dfcb42bdacabe3c579fbc7e0c775108fe105d546326f501e9bc1948abd87

data/.editorconfig

@@ -0,0 +1,37 @@
+# EditorConfig is awesome: http://EditorConfig.org
+# top-most EditorConfig file
+root = true
+# all files
+[*]
+# Unix-style newlines
+end_of_line = lf
+# newline ending every file
+insert_final_newline = true
+# utf-8 charset
+charset = utf-8
+# remove and trailing whitespace chars
+trim_trailing_whitespace = true
+# default to space spacing
+indent_style = space
+# default to 2 char tabs
+indent_size = 2
+# no max line length
+max_line_length = off
+# keep curly on same line if possible
+curly_bracket_next_line = false
+# https://en.wikipedia.org/wiki/Indent_style#K.26R_style
+indent_brace_style = K&R
+# "something + something" not "something+something"
+spaces_around_operators = true
+# "something(true)" not "something ( true )"
+spaces_around_brackets = none
+[*.{js,css,scss,html,xml}]
+indent_style = space
+indent_size = 4
+[*.{yml,sh,sh.erb}]
+indent_style = space
+indent_size = 2
+spaces_around_operators = false
+[*.{rb,rb.erb,rb.static,gemspec}]
+indent_style = tab
+indent_size = 4

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,7 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.6.10
+before_install: gem install bundler -v 1.17.2

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in roleback.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,44 @@
+PATH
+  remote: .
+  specs:
+    roleback (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    debug (1.8.0)
+      irb (>= 1.5.0)
+      reline (>= 0.3.1)
+    diff-lcs (1.5.0)
+    io-console (0.7.1)
+    irb (1.6.3)
+      reline (>= 0.3.0)
+    rake (10.5.0)
+    reline (0.4.2)
+      io-console (~> 0.5)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.2)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.6)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.17)
+  debug
+  rake (~> 10.0)
+  roleback!
+  rspec (~> 3.0)
+
+BUNDLED WITH
+   1.17.2

data/README.md

@@ -0,0 +1,226 @@
+# Roleback
+
+Roleback is a simple DSL for writing static RBAC rules for your application. Roleback is not concerned with how you store or enforce your roles, it only cares about how you define them. Storing roles against a user class is easy enough, and there are plenty of gems out there to help you enforce them, like [Pundit](https://github.com/varvet/pundit) and [CanCanCan](https://github.com/CanCanCommunity/cancancan).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'roleback'
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install roleback
+```
+
+## Usage
+
+Using Roleback is simple. Define your roles in a ruby file, and then load them into your application. For example in Rails, you can create a file loaded during your application load, like `config/initializers/roles.rb`:
+
+```ruby
+# config/initializers/roles.rb
+Roleback.define do
+  role :admin do
+    can :manage
+  end
+end
+```
+
+Roleback defines permissions on by roles. In the example above, we've defined a role called `admin` that can `manage` anything. Usually permissions are defined with three pieces of information: `scope`, `resource` and `action`.
+
+`resource` is the object you want to check permissions against. `action` is the action you want to check permissions for. For example, you might want to check `read` action, on a blog `post`:
+
+```ruby
+# config/initializers/roles.rb
+Roleback.define do
+  role :admin do
+    resource :post do
+      can :read
+    end
+  end
+end
+```
+
+`resource` however, always includes 7 more actions: `create`, `read`, `update`, `delete`, `list`, `edit` and `new` to make it easier to define permissions for common actions. You can change this behavior using the `only` and `except` options:
+
+```ruby
+# config/initializers/roles.rb
+Roleback.define do
+  role :admin do
+    resource :post, only: [:read, :create, :update, :delete] do
+      can :read
+    end
+  end
+end
+```
+
+`scope` adds context to your permissions. For example, you might want to grant `read` on a `post` in the web, but not in other contexts (like an API):
+
+```ruby
+# config/initializers/roles.rb
+Roleback.define do
+  role :admin do
+    scope :web do
+      resource :post do
+        can :read
+      end
+    end
+  end
+end
+```
+
+## Grant and Deny
+Permissions are granted using `can` and denied using `cannot`:
+
+```ruby
+# config/initializers/roles.rb
+Roleback.define do
+  role :admin do
+    scope :web do
+      resource :post do
+        can :read
+        cannot :write
+      end
+    end
+  end
+end
+```
+
+By default, all `resource` default permissions (create, read, update, delete, list, edit and new) are granted (ie `can`).
+
+## Inheritance
+Roles can inherit from other roles:
+
+```ruby
+# config/initializers/roles.rb
+Roleback.define do
+  role :admin do
+    can :manage
+  end
+
+  role :editor, inherits_from: :admin do
+    cannot :delete
+  end
+end
+```
+
+Roles can also inherit from multiple roles:
+
+```ruby
+# config/initializers/roles.rb
+Roleback.define do
+  role :admin do
+    can :manage
+  end
+
+  role :author do
+    can :write
+  end
+
+  role :editor, inherits_from: [:admin, :author] do
+    cannot :delete
+  end
+end
+```
+
+While you don't need to define a parent role before the child role, circular dependencies are not allowed, within the same parental line. For example, if `:moderator` inherits from `:admin`, `:admin` cannot inherit from `:moderator`, directly or indirectly. However, when inheriting from multiple parents, circular dependencies are allowed, as long as they are not in the same parental line. For example, `:editor` can inherit from `:admin` and `:author`, and `:author` can inherit from `:editor`, as long as `:editor` does not inherit from `:author` directly or indirectly.
+
+When it comes to consolidating the rules of inherited roles, Roleback allows repeated rules as long as they don't belong to the same role. For example, it is not allowed to define a rule twice, even with the same outcome:
+
+```ruby
+# config/initializers/roles.rb
+Roleback.define do
+  role :admin do
+    can :manage
+    can :manage # <- not allowed
+  end
+end
+```
+
+You can however, define the same rule in different roles, as long as they don't contradict each other:
+
+```ruby
+# config/initializers/roles.rb
+Roleback.define do
+  role :admin do
+    can :manage
+  end
+
+  role :editor, inherits_from: :admin do
+    can :manage
+  end
+end
+```
+
+```ruby
+# config/initializers/roles.rb
+Roleback.define do
+  role :admin do
+    can :manage
+  end
+
+  role :editor, inherits_from: :admin do
+    cannot :manage # <- not allowed
+  end
+end
+```
+
+## Checking Permissions
+Roleback doesn't care how you check permissions, but it does provide a simple API for doing so:
+
+```ruby
+Roleback.can?(:admin, resource: :post, action: :read) # => true
+Roleback.can?(:editor, resource: :post, :delete) # => false
+```
+
+After the definition of roles is finished (`Roleback.define`), all each role, ends up with the collection of all rules it has plus all the rules it has inherited from other roles. These rules are used to check for permissions. When the `can?` method is called with `scope`, `resource` and `action`, `can?` will return the outcome of the most specific rule that matches the given `scope`, `resource` and `action`. If no rule matches, `can?` will return `false`. If you have both `can` and `cannot` rules for a check, `cannot` will take precedence (deny over grant).
+
+### `User` class
+If you have a `User` class, Roleback will automatically, add a `can?` method to it:
+
+```ruby
+user = User.find(1)
+user.can?(:admin, resource: :post, action: :read) # => true
+user.can?(:editor, resource: :post, :delete) # => false
+```
+
+Your `User` class has to have a method called `roles` that returns an array of role names as symbols.
+
+The `User` class returns an array of roles, then Roleback will check each role for a match and will return `true` (grant) when the first role matches. If no role matches, `can?` will return `false`. This is an important point to remember when using class extension, which basically means if you grant the user multiple rules, it will return `true` if any of the rules match, even you have rules that deny access to the same resource and action.
+
+You can change the class to be extended from `User`, using `user_class` option in `define`:
+
+```ruby
+Roleback.define(user_class: Admin) do
+  # ...
+end
+```
+
+If you don't want to extend your `User` class, pass in `nil` as the `user_class` option:
+
+```ruby
+Roleback.define(user_class: nil) do
+  # ...
+end
+```
+
+## Recommendations
+
+Even though Roleback doesn't impose any opinions on how define your rules (sacrilegious in Rails world, I know), here are some recommendations that might help using it with more ease:
+
+1. Although Roleback, support deny permissions (`cannot`), I recommend against using those and always define your rules with grant permissions (`can`). This will make it easier to reason about your rules and will make it easier to debug them.
+2. Either map your roles to actual organizational roles (marketing, support, etc), or define them based on their access context (commenter, editor, etc). Don't mix the two. Use multiple inheritance when defining the roles based on access context and use single inheritance when defining them based on organizational roles.
+3. Define your roles in a single file, and load them during application load. (`config/initializers/roles.rb` in Rails is a good place).
+
+## Contributing
+
+Bug reports and pull requests are welcome on this GitHub repository. PRs are welcome and more likely to be accepted if they include tests.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "roleback"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/roleback/configuration.rb

@@ -0,0 +1,138 @@
+module Roleback
+	def self.define(options = {}, &block)
+		@config = ::Roleback::Configuration::Builder.new(options, &block).build if block_given?
+		@config.construct!
+
+		# is there a ::User class defined?
+		if options[:user_class]
+			@user_class = options[:user_class]
+		elsif defined?(::User)
+			@user_class = ::User
+		else
+			@user_class = nil
+		end
+
+		# extend the user class
+		::Roleback::UserExtension.extend!(@user_class) if @user_class
+
+		@config
+	end
+
+	def self.configuration
+		@config || (raise ::Roleback::NotConfiguredError)
+	end
+
+	def self.any
+		::Roleback::ANY
+	end
+
+	def self.allow
+		::Roleback::ALLOW
+	end
+
+	def self.deny
+		::Roleback::DENY
+	end
+
+	def self.clear!
+		@config = nil
+	end
+
+	def self.roles
+		self.configuration.roles
+	end
+
+	def self.can?(role_name, resource: ::Roleback.any, scope: ::Roleback.any, action: ::Roleback.any)
+		role = self.configuration.find_role!(role_name)
+
+		return true if role.rules.can?(resource: resource, scope: scope, action: action)
+
+		false
+	end
+
+	class Configuration
+		attr_reader :roles
+		attr_reader :max_inheritance_depth
+
+		def initialize(options = {})
+			@options = options
+			@roles = {}
+
+			if options[:max_inheritance_depth]
+				@max_inheritance_depth = options[:max_inheritance_depth]
+			else
+				@max_inheritance_depth = 10
+			end
+		end
+
+		def find_role!(name)
+			role = self.roles[name.to_sym]
+			raise ::Roleback::MissingRole, "Role #{name} not found" unless role
+			role
+		end
+
+		def can?(role_name, scope: ::Roleback::ANY, resource: ::Roleback::ANY, action: ::Roleback::ANY)
+			role = self.find_role!(role_name)
+			role.can?(scope: scope, resource: resource, action: action)
+		end
+
+		def construct!
+			# go through all roles and find their parents
+			@roles.each do |name, role|
+				parents = role.parents
+				next unless parents && !parents.empty?
+
+				found_parents = []
+
+				parents.each do |parent|
+					found_parent = @roles[parent]
+					raise ::Roleback::BadConfiguration, "Role #{parent} not found" unless found_parent
+
+					found_parents << found_parent
+					role.instance_variable_set(:@parents, found_parents)
+				end
+			end
+
+			# go through all roles, and inherit their parents' rules
+			@roles.each do |name, role|
+				role.inherit
+			end
+		end
+
+		class Builder
+			def initialize(options = {}, &block)
+				@options = options
+				@config = ::Roleback::Configuration.new(options)
+				@parent = nil
+
+				instance_eval(&block) if block_given?
+			end
+
+			def build
+				@config
+			end
+
+			def role(name, options = {}, &block)
+				roles = @config.instance_variable_get(:@roles) || {}
+
+				raise ::Roleback::BadConfiguration, "Role #{name} already defined" if roles[name]
+
+				validate_options!(options)
+
+				parents = options[:inherits_from]
+
+				role = ::Roleback::Definitions::Role.new(name, parents: parents)
+				role.instance_eval(&block) if block_given?
+
+				roles[name] = role
+				@config.instance_variable_set(:@roles, roles)
+
+				role
+			end
+
+			def validate_options!(options)
+				raise ::Roleback::BadConfiguration, "Invalid options" if options.keys.any? { |k| ![:inherits_from].include?(k) }
+			end
+		end
+	end
+end

data/lib/roleback/definitions/load.rb

@@ -0,0 +1,2 @@
+require_relative 'rule_based'
+Dir["#{File.dirname(__FILE__)}/roleback/**/*.rb"].each { |f| load(f) }

data/lib/roleback/definitions/resource.rb

@@ -0,0 +1,68 @@
+module Roleback
+	module Definitions
+		class Resource < ::Roleback::Definitions::RuleBased
+			attr_reader :name
+
+			DEFAULT_ACTION_PATH = [:create, :show, :update, :delete, :index, :new, :edit]
+
+			def initialize(name, role:, scope: ::Roleback::ANY, options: {}, &block)
+				@name = name
+				@role = role
+				@scope = scope
+				@options = options
+
+				super(role: role, resource: self, scope: scope)
+
+				validate_options!
+
+				# create rules for each action
+				selected_actions.each do |action|
+					do_rule(role: @role, resource: self, scope: @scope, action: action, outcome: ::Roleback::ALLOW)
+				end
+
+				instance_eval(&block) if block_given?
+			end
+
+			def match(resource)
+				to_check = resource.is_a?(::Roleback::Definitions::Resource) ? resource.name.to_s : resource.to_s
+				@name.to_s == to_check || @name == ::Roleback.any || resource == ::Roleback.any
+			end
+
+			def ==(other)
+				return false unless other.respond_to?(:name)
+
+				other.name == name
+			end
+
+			private
+
+			def validate_options!
+				if @options[:only] && @options[:except]
+					raise ::Roleback::BadConfiguration, "You can't specify both :only and :except options"
+				end
+
+				if @options[:only] && !@options[:only].is_a?(Array)
+					raise ::Roleback::BadConfiguration, "The :only option must be an array"
+				end
+
+				if @options[:except] && !@options[:except].is_a?(Array)
+					raise ::Roleback::BadConfiguration, "The :except option must be an array"
+				end
+
+				if @options.keys.any? { |k| ![:only, :except].include?(k) }
+					raise ::Roleback::BadConfiguration, "Invalid options"
+				end
+			end
+
+			def selected_actions
+				if @options[:only]
+					return @options[:only]
+				elsif @options[:except]
+					return DEFAULT_ACTION_PATH - @options[:except]
+				else
+					return DEFAULT_ACTION_PATH
+				end
+			end
+		end
+	end
+end

data/lib/roleback/definitions/role.rb

@@ -0,0 +1,98 @@
+module Roleback
+	module Definitions
+		class Role < Roleback::Definitions::RuleBased
+			attr_reader :name
+			attr_reader :parents
+
+			def initialize(name, parents: nil)
+				@name = name
+				@rule_book = ::Roleback::RuleBook.new(self)
+				@scopes = {}
+				@resources = {}
+
+				if parents
+					if parents.is_a?(Symbol)
+						@parents = [parents]
+					elsif parents.is_a?(Array)
+						# check for duplicates
+						raise ::Roleback::BadConfiguration, "Duplicate parents found for role #{name}" if parents.uniq.length != parents.length
+
+						@parents = parents
+					else
+						raise ::Roleback::BadConfiguration, "Parent must be a symbol or an array of symbols"
+					end
+				else
+					@parents = nil
+				end
+
+				super(role: self, resource: ::Roleback::ANY, scope: ::Roleback::ANY)
+			end
+
+			def rules
+				@rule_book
+			end
+
+			def keys
+				@rule_book.rules.keys
+			end
+
+			def add_rule(rule)
+				@rule_book.add(rule)
+			end
+
+			def resource(name, options = {}, &block)
+				raise ::Roleback::BadConfiguration, "Resource #{name} already defined" if @resources[name]
+
+				resource = ::Roleback::Definitions::Resource.new(name, role: self, options: options, &block)
+				@resources[name] = resource
+			end
+
+			def scope(name, &block)
+				raise ::Roleback::BadConfiguration, "Scope #{name} already defined" if @scopes[name]
+
+				scope = ::Roleback::Definitions::Scope.new(name, role: self, &block)
+				@scopes[name] = scope
+			end
+
+			def to_s
+				self.name.to_s
+			end
+
+			def inherit
+				return if @parents.nil?
+
+				new_rules = do_inherit
+
+				if new_rules.empty?
+					# no rules to inherit
+					return
+				end
+
+				# add the new rules to the rule book
+				self.rules.clear_rules
+				new_rules.each do |rule|
+					self.rules.add(rule)
+				end
+			end
+
+			private
+
+			def do_inherit(rule_set = [], level = 0)
+				# don't go too deep
+				raise ::Roleback::BadConfiguration, "Circular dependency detected (#{level} out of maximum allowed of #{::Roleback.configuration.max_inheritance_depth})" if level > ::Roleback.configuration.max_inheritance_depth
+
+				new_rules = rule_set + self.rules.to_a
+
+				return new_rules if @parents.nil? || @parents.empty?
+
+				@parents.each do |parent|
+					parent_rules = parent.send(:do_inherit, rule_set, level + 1)
+					new_rules = new_rules + parent_rules
+				end
+
+				return new_rules
+			end
+
+		end
+	end
+end

data/lib/roleback/definitions/rule_based.rb

@@ -0,0 +1,39 @@
+module Roleback
+	module Definitions
+		class RuleBased
+			attr_reader :role
+			attr_reader :resource
+
+			def initialize(role:, resource:, scope:)
+				@role = role
+				@resource = resource
+				@scope = scope
+			end
+
+			def can(action)
+				do_rule(role: @role, resource: @resource, scope: @scope, action: action, outcome: ::Roleback::ALLOW)
+			end
+
+			def cannot(action)
+				do_rule(role: @role, resource: @resource, scope: @scope, action: action, outcome: ::Roleback::DENY)
+			end
+
+			def <=>(other)
+				other.numerical_value <=> numerical_value
+			end
+
+			protected
+
+			def do_rule(role:, resource:, scope:, action:, outcome:)
+				rule = ::Roleback::Rule.new(
+					role: role,
+					resource: resource,
+					scope: scope,
+					action: action,
+					outcome: outcome)
+
+				role.add_rule(rule)
+			end
+		end
+	end
+end

data/lib/roleback/definitions/scope.rb

@@ -0,0 +1,33 @@
+module Roleback
+	module Definitions
+		class Scope < ::Roleback::Definitions::RuleBased
+			attr_reader :name
+
+			def initialize(name, role:, options: {}, &block)
+				@name = name
+				@role = role
+				@options = options
+
+				super(role: role, scope: self, resource: ::Roleback::ANY)
+
+				instance_eval(&block) if block_given?
+			end
+
+			def resource(name, options = {}, &block)
+				::Roleback::Definitions::Resource.new(name, role: @role, scope: self, options: options, &block)
+			end
+
+			def match(scope)
+				to_check = scope.is_a?(::Roleback::Definitions::Scope) ? scope.name.to_s : scope.to_s
+				@name.to_s == scope.name.to_s || @name == ::Roleback.any || scope == ::Roleback.any
+			end
+
+			def ==(other)
+				return false unless other.respond_to?(:name)
+
+				other.name == name
+			end
+
+		end
+	end
+end

data/lib/roleback/outcome.rb

@@ -0,0 +1,61 @@
+module Roleback
+	class OutcomeBase
+		attr_reader :outcome
+
+		def initialize(outcome)
+			@outcome = outcome
+		end
+
+		def allowed?
+			@outcome == :allow
+		end
+
+		def denied?
+			@outcome == :deny
+		end
+
+		def to_s
+			@outcome.to_s
+		end
+
+		def ==(other)
+			return false unless other.respond_to?(:outcome)
+
+			other.outcome == outcome
+		end
+	end
+
+	class Allow < OutcomeBase
+		def initialize
+			super(:allow)
+		end
+	end
+
+	class Deny < OutcomeBase
+		def initialize
+			super(:deny)
+		end
+	end
+
+	class Any
+		def name
+			:'*'
+		end
+
+		def ==(other)
+			return true if other.is_a?(Any)
+			return false unless other.respond_to?(:name)
+
+			other.name.to_s == name.to_s
+		end
+
+		def match(scope)
+			true
+		end
+	end
+
+	ANY = Any.new
+
+	ALLOW = Allow.new
+	DENY = Deny.new
+end

data/lib/roleback/rule.rb

@@ -0,0 +1,65 @@
+module Roleback
+	class Rule
+		attr_reader :role
+		attr_reader :resource
+		attr_reader :scope
+		attr_reader :action
+		attr_reader :outcome
+
+		def initialize(role:, resource:, scope:, action:, outcome:)
+			@role = role
+			@resource = resource
+			@scope = scope
+			@action = action
+			@outcome = outcome
+		end
+
+		def key
+			"#{@scope.name}:/#{@resource.name}/#{@action}"
+		end
+
+		def to_s
+			"#{key}->#{@outcome}"
+		end
+
+		def match(resource:, scope:, action:)
+			if @resource.match(resource) && @scope.match(scope)
+				if @action == ::Roleback.any || @action.to_s == action.to_s
+					return self
+				end
+			end
+
+			nil
+		end
+
+		# two rules are conflicting, when the have the same scope, resource and action, but different outcomes
+		def conflicts_with?(rule)
+			# if the rules are the same, they don't conflict
+			return false if self == rule
+
+			# if the scope, resource and action are the same, but the outcome is different, they conflict
+			return true if @scope.name == rule.scope.name && @resource.name == rule.resource.name && @action == rule.action && @outcome.outcome != rule.outcome.outcome
+
+			# otherwise, they don't conflict
+			false
+		end
+
+		# calculate a numerical value for this rule to be used for sorting
+		# the value is the sum of the following:
+		# (scope_value * scope_weight) + (resource_value * resource_weight) * (outcome_value * outcome_weight)
+		# scope_weight = 100
+		# resource_weight = 10
+		# outcome_weight = 1
+		# scope_value = 0 if scope == ANY, 1 otherwise
+		# resource_value = 0 if resource == ANY, 1 otherwise
+		# outcome_value = 0 if outcome == ALLOW, 1 otherwise
+		def numerical_value
+			scope_value = @scope == ::Roleback::ANY ? 0 : 1
+			resource_value = @resource == ::Roleback::ANY ? 0 : 1
+			outcome_value = @outcome == ::Roleback::ALLOW ? 0 : 1
+
+			(scope_value * 100) + (resource_value * 10) + (outcome_value * 1)
+		end
+
+	end
+end

data/lib/roleback/rule_book.rb

@@ -0,0 +1,119 @@
+module Roleback
+	class RuleBook
+		attr_reader :rules
+
+		def initialize(role)
+			@rules = {}
+			@role = role
+		end
+
+		def add(rule)
+			raise ::Roleback::BadConfiguration, "Adding a rule with no role" unless rule.role
+
+			if @rules[rule.key]
+				if @rules[rule.key].outcome.outcome == rule.outcome.outcome
+					# don't allow it if they share a rulebook
+					if @role.name == rule.role.name
+						raise ::Roleback::BadConfiguration, "Rule #{rule.key} already defined"
+					else
+						# this duplicate is through inheritance, so we can safely ignore it
+						return
+					end
+				else
+					raise ::Roleback::BadConfiguration, "Rule #{rule.key} already defined with a different outcome (conflicting rules)"
+				end
+			end
+
+			# detect conflicting rules
+			@rules.each do |key, existing_rule|
+				if existing_rule.conflicts_with?(rule)
+					raise ::Roleback::BadConfiguration, "Rule #{rule.key} conflicts with #{existing_rule.key}"
+				end
+			end
+
+			@rules[rule.key] = rule
+		end
+
+		def clear_rules
+			@rules = {}
+		end
+
+		def length
+			@rules.length
+		end
+
+		def [](key)
+			@rules[key]
+		end
+
+		def keys
+			@rules.keys
+		end
+
+		def match_all(resource:, scope:, action:)
+			result = []
+			@rules.each do |key, rule|
+				result << rule if rule.match(resource: resource, scope: scope, action: action)
+			end
+
+			result
+		end
+
+		def can?(resource:, scope:, action:)
+			# get all rules that matches the given resource, scope and action
+			rules = match_all(resource: resource, scope: scope, action: action)
+
+			# if there are no rules, return false
+			return false if rules.empty?
+
+			# create a rule book with the matching rules
+			match_book = self.class.new(@role)
+			rules.each do |rule|
+				match_book.add(rule)
+			end
+
+			# sort the rules
+			sorted_rules = self.class.sort(match_book.rules)
+
+			# iterate over the sorted rules and find the first rule that matches
+			sorted_rules.each do |rule|
+				if rule.match(resource: resource, scope: scope, action: action)
+					return rule.outcome.allowed?
+				end
+			end
+
+			# if no rule matches, return false
+			return false
+		end
+
+		# sorts the rules, based on the rules' numerical value
+		def self.sort(rules)
+			# rules should be a hash
+			raise ::ArgumentError, "rules should be a hash but it is a #{rules.class}" unless rules.is_a?(Hash)
+
+			# rules is a hash, so we need to convert it to an array
+			rules = rules.values
+
+			# sort the rules
+			rules.sort! do |a, b|
+				b.numerical_value <=> a.numerical_value
+			end
+		end
+
+		def sort!
+			@rules = self.class.sort(@rules)
+		end
+
+		def sort
+			self.class.sort(@rules)
+		end
+
+		def to_s
+			@rules.values.map(&:to_s).join("\n")
+		end
+
+		def to_a
+			@rules.values
+		end
+	end
+end

data/lib/roleback/user_extension.rb

@@ -0,0 +1,33 @@
+module Roleback
+	class UserExtension
+		def self.extend!(user_class)
+			user_instance = user_class.new
+			unless user_instance.respond_to?(:roles) && user_instance.method(:roles).arity == 0
+				raise ::Roleback::InvalidOrMisconfiguredUserClass, "User class #{user_class.name} should have a method call roles that returns an array of role names"
+			end
+
+			if user_class.instance_methods.include?(:can?)
+				raise ::Roleback::InvalidOrMisconfiguredUserClass, "User class #{user_class.name} already has a method called can?"
+			end
+
+			user_class.class_eval do
+				def can?(resource: Roleback.any, scope: Roleback.any, action: Roleback.any)
+					# get all user roles
+					roles = self.roles
+					return false if roles.empty?
+
+					if !roles.is_a?(Array)
+						raise ::Roleback::InvalidOrMisconfiguredUserClass, "User class #{self.class}#roles should return an array of role names"
+					end
+
+					roles.each do |role|
+						return true if ::Roleback.can?(role.to_sym, resource: resource, scope: scope, action: action)
+					end
+
+					# no role can perform the action on the resource
+					false
+				end
+			end
+		end
+	end
+end

data/lib/roleback/version.rb

@@ -0,0 +1,3 @@
+module Roleback
+	VERSION = "0.1.0".freeze
+end

data/lib/roleback.rb

@@ -0,0 +1,12 @@
+require "roleback/version"
+require 'roleback/definitions/load'
+Dir["#{File.dirname(__FILE__)}/roleback/**/*.rb"].each { |f| load(f) }
+
+module Roleback
+	class Error < StandardError; end
+	class NotConfiguredError < StandardError; end
+	class BadConfiguration < StandardError; end
+	class BadMatch < StandardError; end
+	class InvalidOrMisconfiguredUserClass < StandardError; end
+	class MissingRole < StandardError; end
+end

data/roleback.gemspec

@@ -0,0 +1,40 @@
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "roleback/version"
+
+Gem::Specification.new do |spec|
+	spec.name          = "roleback"
+	spec.version       = Roleback::VERSION
+	spec.authors       = ["Khash Sajadi"]
+	spec.email         = ["khash@cloud66.com"]
+
+	spec.summary       = "Roleback provides a simple DSL to define RBAC rules for your application."
+	spec.homepage      = "https://github.com/cloud66-oss/roleback"
+
+	# Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+	# to allow pushing to a single host or delete this section to allow pushing to any host.
+	if spec.respond_to?(:metadata)
+		spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+		spec.metadata["homepage_uri"] = spec.homepage
+		spec.metadata["source_code_uri"] = "https://github.com/cloud66-oss/roleback"
+		spec.metadata["changelog_uri"] = "https://github.com/cloud66-oss/roleback/blob/main/CHANGELOG.md"
+	else
+		raise "RubyGems 2.0 or newer is required to protect against public gem pushes."
+	end
+
+	# Specify which files should be added to the gem when it is released.
+	# The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+	spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+		`git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+	end
+	spec.bindir        = "exe"
+	spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+	spec.require_paths = ["lib"]
+
+	spec.add_development_dependency "bundler", "~> 1.17"
+	spec.add_development_dependency "rake", "~> 10.0"
+	spec.add_development_dependency "rspec", "~> 3.0"
+	spec.add_development_dependency "debug"
+end

metadata

@@ -0,0 +1,125 @@
+--- !ruby/object:Gem::Specification
+name: roleback
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Khash Sajadi
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2024-01-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: debug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- khash@cloud66.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".editorconfig"
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/roleback.rb
+- lib/roleback/configuration.rb
+- lib/roleback/definitions/load.rb
+- lib/roleback/definitions/resource.rb
+- lib/roleback/definitions/role.rb
+- lib/roleback/definitions/rule_based.rb
+- lib/roleback/definitions/scope.rb
+- lib/roleback/outcome.rb
+- lib/roleback/rule.rb
+- lib/roleback/rule_book.rb
+- lib/roleback/user_extension.rb
+- lib/roleback/version.rb
+- roleback.gemspec
+homepage: https://github.com/cloud66-oss/roleback
+licenses: []
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/cloud66-oss/roleback
+  source_code_uri: https://github.com/cloud66-oss/roleback
+  changelog_uri: https://github.com/cloud66-oss/roleback/blob/main/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Roleback provides a simple DSL to define RBAC rules for your application.
+test_files: []