mongoid_ability 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1c92cfc98a8f67825aeaad355026c5f72ae43663
+  data.tar.gz: e571fe34334634fba9f92751354d775af59e4439
+SHA512:
+  metadata.gz: 80315b4061b1a1700d2a5ac4980972203afe88060731315954ef6ec0e6b2bdd6a7094d8f7f2f32bc53385fbb01e7ee29d923d8da10dc562fb39b4b54b748de01
+  data.tar.gz: dd66e44b4e6e513be6e5d128ca8a50457f103071abc759972cbf04f849d5ecabffc875e4fa082455fdd7c60682cb336e0634c37cc99f760bb219eb2104f023af

data/.coveralls.yml

@@ -0,0 +1 @@
+service_name: travis-ci

data/.gitignore

@@ -0,0 +1,22 @@
+*.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

data/.travis.yml

@@ -0,0 +1,14 @@
+language: ruby
+cache: bundler
+script: 'bundle exec rake'
+rvm:
+  - 2.1.2
+services:
+  - mongodb
+
+notifications:
+  email:
+    recipients:
+      - tomas.celizna@gmail.com
+    on_failure: change
+    on_success: never

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in mongoid_ability.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,8 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard :minitest do
+  watch(%r{^lib/(.+)\.rb$})                               { |m| "test/#{m[1]}_test.rb" }
+  watch(%r{^test/.+_test\.rb$})
+  watch(%r{^test/test_helper\.rb$})                       { 'test' }
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Tomas Celizna
+
+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,154 @@
+# Mongoid Ability
+
+[![Build Status](https://travis-ci.org/tomasc/mongoid_ability.svg)](https://travis-ci.org/tomasc/mongoid_ability) [![Gem Version](https://badge.fury.io/rb/mongoid_ability.svg)](http://badge.fury.io/rb/mongoid_ability) [![Coverage Status](https://img.shields.io/coveralls/tomasc/mongoid_ability.svg)](https://coveralls.io/r/tomasc/mongoid_ability)
+
+Custom `Ability` class that allows [CanCanCan](https://github.com/CanCanCommunity/cancancan) authorization library store permissions in [MongoDB](http://www.mongodb.org) via the [Mongoid](https://github.com/mongoid/mongoid) gem.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'mongoid_ability'
+```
+
+And then execute:
+
+```
+$ bundle
+```
+
+Or install it yourself as:
+
+```
+$ gem install mongoid_ability
+```
+
+## Setup
+
+The permissions are defined by a `Lock` that applies to a `Subject` and defines access for its owner – `User` and/or its `Role`.
+
+### Lock
+
+A `Lock` class can be any class that include `MongoidAbility::Lock`.
+
+```ruby
+class MyLock
+    include Mongoid::Document
+    include MongoidAbility::Lock
+
+    embedded_in :owner, polymorphic: true
+end
+```
+
+This class defines a permission itself using the following fields:
+
+`:subject_type, type: String`  
+`:subject_id, type: Moped::BSON::ObjectId`  
+`:action, type: Symbol, default: :read`  
+`:outcome, type: Boolean, default: false`  
+
+These fields define what subject (respectively subject type, when referring to a class) the lock applies to, which action it is defined for (for example `:read`), and whether the outcome is positive or negative.
+
+For more specific behavior, it is possible to override the `#calculated_outcome` method (should, for example, the permission depend on some additional factors).
+
+```ruby
+def calculated_outcome
+    # custom behaviour
+    # returns true/false
+end
+```
+
+If you wish to check the state of a lock directly, please use the convenience methods `#open?` and `#closed?`. These take into account the `#calculated_outcome`. Using the `:outcome` field directly is discouraged.
+
+The lock class can be further subclassed in order to customise its behavior, for example per action.
+
+### Subject
+
+All subjects (classes which permissions you want to control) have to include the `MongoidAbility::Subject` module.
+
+Each action and its default outcome, needs to be defined using the `.default_lock` macro.
+
+```ruby
+class MySubject
+    include Mongoid::Document
+    include MongoidAbility::Subject
+
+    default_lock :read, true
+    default_lock :update, false
+end
+```
+
+The subject classes can be subclassed. Subclasses inherit the default locks (unless they override them), the resulting outcome being correctly calculated bottom-up the superclass chain. 
+
+The subject also acquires a convenience `Mongoid::Criteria` named `.accessible_by`. This criteria can be used to query for subject based on the user's ability:
+
+```ruby
+ability = MongoidAbility::Ability.new(current_user)
+MySubject.accessible_by(ability, :read)
+```
+
+### Owner
+
+This gem supports two levels of ownership of a lock: a `User` and its many `Role`s. The locks can be either embedded (via `.embeds_many`) or associated (via `.has_many`). Please make sure to include the `as: :owner` option.
+
+```ruby
+class MyUser
+    include Mongoid::Document
+    include MongoidAbility::Owner
+
+    embeds_many :locks, class_name: 'MyLock', as: :owner
+    has_and_belongs_to_many :roles, class_name: 'MyRole'
+
+    # override if your relation is named differently
+    def self.roles_relation_name
+        :roles
+    end
+end
+```
+
+```ruby
+class MyRole
+    include Mongoid::Document
+    include MongoidAbility::Owner
+
+    embeds_many :locks, class_name: 'MyLock', as: :owner
+    has_and_belongs_to_many :users, class_name: 'MyUser'
+end
+```
+
+Both users and roles can be further subclassed.
+
+The owner also gains the `#can?` and `#cannot?` methods, that are delegate to the user's ability. It is then easy to perform permission checks per user:
+
+```ruby
+current_user.can?(:read, resource)
+other_user.can?(:read, resource)
+```
+
+### CanCanCan
+
+The default `:current_ability` defined by [CanCanCan](https://github.com/CanCanCommunity/cancancan) will be automatically overriden by the `Ability` class provided by this gem.
+
+## Usage
+
+1. Setup subject classes and their default locks.
+2. Define permissions using lock objects embedded (or associated to) either in user or role.
+3. Use standard [CanCanCan](https://github.com/CanCanCommunity/cancancan) helpers (`authorize!`, `can?`, `cannot?`) to authorize the current user.
+
+## How it works?
+
+The ability class in this gem looks up and calculates the outcome in the following order:
+
+1. User locks, defined for `:subject_id`, then `:subject_type` (then its superclasses), then defined in the subject class itself (via the `.default_lock` macro) and its superclasses.
+2. Role locks have the same look up chain as the user locks. The role permissions are optimistic, meaning that in case a user has multiple roles, and the roles have locks with conflicting outcomes, the ability favors the positive one.
+
+See the test suite for more details.
+
+## Contributing
+
+1. Fork it ( https://github.com/tomasc/mongoid_ability/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,9 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+ 
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+end
+
+task :default => :test

data/lib/mongoid_ability.rb

@@ -0,0 +1,17 @@
+require "mongoid_ability/version"
+
+require "mongoid_ability/ability"
+require "mongoid_ability/ability_resolver"
+require "mongoid_ability/lock"
+require "mongoid_ability/owner"
+require "mongoid_ability/subject"
+
+# ---------------------------------------------------------------------
+
+if defined?(Rails)
+  class ActionController::Base
+    def current_ability
+      @current_ability ||= MongoidAbility::Ability.new(current_user)
+    end
+  end
+end

data/lib/mongoid_ability/ability.rb

@@ -0,0 +1,29 @@
+require 'cancancan'
+  
+module MongoidAbility
+  class Ability
+
+    include CanCan::Ability
+
+    # ---------------------------------------------------------------------
+    
+    attr_reader :user
+
+    # =====================================================================
+
+    def initialize user
+      @user = user
+      
+      can do |action, subject_type, subject|
+        subject_class = subject_type.to_s.constantize
+        outcome = nil
+        subject_class.self_and_ancestors_with_default_locks.each do |cls|
+          outcome = AbilityResolver.new(user, action, cls.to_s, subject).outcome
+          break unless outcome.nil?
+        end
+        outcome
+      end
+    end
+
+  end
+end

data/lib/mongoid_ability/ability_resolver.rb

@@ -0,0 +1,87 @@
+module MongoidAbility
+  class AbilityResolver
+
+    def initialize user, action, subject_type, subject=nil
+      @subject_class = subject_type.to_s.constantize
+      
+      raise StandardError, "#{subject_type} class does not have default locks" unless @subject_class.respond_to?(:default_locks)
+      raise StandardError, "#{subject_type} class does not have default lock for :#{action} action" unless @subject_class.self_and_ancestors_with_default_locks.any? do |cls|
+        cls.default_locks.any?{ |l| l.action == action }
+      end
+
+      @user = user
+      @action = action.to_sym
+      @subject_type = subject_type.to_s
+      @subject = subject
+      @subject_id = subject.id if subject.present?
+    end
+
+    # ---------------------------------------------------------------------
+    
+    def outcome
+      ua = user_outcome
+      return ua unless ua.nil?
+
+      ra = roles_outcome
+      return ra unless ra.nil?
+
+      class_outcome
+    end
+
+    # ---------------------------------------------------------------------
+
+    def user_outcome
+      locks_for_subject_type = @user.locks_relation.for_action(@action).for_subject_type(@subject_type)
+
+      return unless locks_for_subject_type.exists?
+
+      # return outcome if user defines lock for id
+      if @subject.present?
+        id_locks = locks_for_subject_type.id_locks.for_subject_id(@subject_id)
+        return false if id_locks.any?(&:closed?)
+        return true if id_locks.any?(&:open?)
+      end
+
+      # return outcome if user defines lock for subject_type
+      class_locks = locks_for_subject_type.class_locks
+      return false if class_locks.class_locks.any?(&:closed?)
+      return true if class_locks.class_locks.any?(&:open?)
+    end
+
+    # ---------------------------------------------------------------------
+
+    def roles_outcome
+      locks_for_subject_type = @user.roles_relation.collect(&@user.class.locks_relation_name).flatten.select{ |l| l.subject_type == @subject_type && l.action == @action }
+
+      return unless locks_for_subject_type.present?
+
+      # return outcome if any role defines lock for id
+      if @subject.present?
+        id_locks = locks_for_subject_type.select{ |l| l.subject_id == @subject_id }
+        # for same role, prefer closed lock
+        id_locks = id_locks.reject{ |l| l.open? && id_locks.any?{ |ol| ol.closed? && ol.owner == l.owner } }
+        # across multiple roles, prefer open lock
+        return true if id_locks.any?(&:open?)
+        return false if id_locks.any?(&:closed?)
+      end
+
+      # for same role prefer closed lock
+      class_locks = locks_for_subject_type.reject(&:id_lock?)
+      class_locks = class_locks.reject{ |l| l.open? && class_locks.any?{ |ol| ol.closed? && ol.owner == l.owner } }
+
+      # across multiple roles, prefer open lock
+      return true if class_locks.any?(&:open?)
+      return false if class_locks.any?(&:closed?)
+    end
+
+    # ---------------------------------------------------------------------
+
+    def class_outcome
+      class_locks = @subject_class.default_locks.select{ |l| l.action == @action }
+
+      return false if class_locks.any?(&:closed?)
+      return true if class_locks.any?(&:open?)
+    end
+
+  end
+end

data/lib/mongoid_ability/lock.rb

@@ -0,0 +1,64 @@
+module MongoidAbility
+  module Lock
+
+    def self.included base
+      base.extend ClassMethods
+      base.class_eval do
+        field :action, type: Symbol, default: :read
+        field :outcome, type: Boolean, default: false
+
+        # ---------------------------------------------------------------------
+        
+        belongs_to :subject, polymorphic: true, touch: true
+
+        # ---------------------------------------------------------------------
+          
+        validates :action, presence: true, uniqueness: { scope: [ :subject_type, :subject_id, :outcome ] }
+        validates :outcome, presence: true
+
+        # ---------------------------------------------------------------------
+          
+        scope :for_action, -> action { where(action: action.to_sym) }
+
+        scope :for_subject_type, -> subject_type { where(subject_type: subject_type.to_s) }
+        scope :for_subject_id, -> subject_id { where(subject_id: subject_id) }
+        scope :for_subject, -> subject { where(subject_type: subject.class.model_name, subject_id: subject.id) }
+
+        scope :class_locks, -> { ne(subject_type: nil).where(subject_id: nil) }
+        scope :id_locks, -> { ne(subject_type: nil, subject_id: nil) }
+      end
+    end
+
+    # =====================================================================
+      
+    module ClassMethods
+    end
+
+    # =====================================================================
+    
+    def calculated_outcome
+      self.outcome
+    end
+
+    # ---------------------------------------------------------------------
+    
+    def open?
+      self.calculated_outcome == true
+    end
+
+    def closed?
+      !open?
+    end
+
+    # ---------------------------------------------------------------------
+      
+    def class_lock?
+      !id_lock?
+    end
+
+    def id_lock?
+      self.subject_id.present?
+    end
+
+  end
+end