scram 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4d4f42aaff808f60d5d9c3c1fd55749eb3b04f6a
+  data.tar.gz: 04e6595617fdea9551367a3e3cfff2c77cacb8c3
+SHA512:
+  metadata.gz: 20c53c83ef0fccbb4ab243a7e29bd950840428bbbbe5795f466b4ae2bef8cab43d7eb7dfde66596c48bae33c4f45df1c2834dc7e77d27ee53327c301d3ac0cdc
+  data.tar.gz: 242ed1189b2f8d7074def6194593c1fead56d0d8090ddfd73a1031aafc6c4512be40b4b9e555cd3e6af8a7085353c1975a415945fff783a5d494d8401dc913e8

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2017 skreem
+
+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,173 @@
+# Scram [![Build Status](https://travis-ci.org/skreem/scram.svg?branch=master)](https://travis-ci.org/skreem/scram) [![Coverage Status](https://coveralls.io/repos/github/skreem/scram/badge.svg?branch=master)](https://coveralls.io/github/skreem/scram?branch=master)
+An awesome authorization system
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'scram'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install scram
+
+## Usage
+
+[Click here to see YARD Documentation](http://www.rubydoc.info/github/skreem/scram/master)
+
+### Quick Overview of Scram
+- Holder
+  - Scram doesn't force you to use a specific group system. Instead, just include `Holder` into any class which can hold `Policies`.
+  - Scram provides a class for objects like Groups through an `AggregateHolder`. This is a class which should be included in anything which holds policies through other holders.
+  - In most cases, your `AggregateHolder` will be a `User` model. Your `Group` model will be a `Holder`. If you don't want to use a group system, then your `User` model will likely be a `Holder`.
+- Policy
+  - Policies are used to bundle together permissions.
+  - There are 2 kinds of `Policies`: Those for a specific model, and "global" `Policies` for permissions that aren't bound to a specific model.
+- Target
+  - `Targets` are a way to declare what actions are allowed in a `Policy`.
+  - `Targets` have a list of actions and conditions.
+    - Actions are anything a user can do to an object. For example: `:update, :view, :create, :destroy`.
+    - Conditions are used to refine what instances a target applies to. They support basic comparisons to attributes, but can be used to support more complex logic with the DSL.
+
+### Example Usage
+If you choose to implement Holder into your user class directly, it may look something like the following.
+```ruby
+class User
+  ...
+  include Scram::Holder
+
+  # Will automatically implement the needed #policies method for Holder.
+  has_many :policies, class: "Scram::Policy"
+
+  def scram_compare_value
+    self.id
+  end
+end
+```
+This sort of system would not include a group system at all (for simplicity). If you want a Group system, have your user include `Scram::AggregateHolder` and then implement `#aggregates` to return your groups (which should be `Holder`s themselves).
+
+We will be providing a full fledge example application of Scram shortly which will include a Group and membership system, and will clarify how the `AggregateHolder` system works. For now, lets see how Scram works in its simplest usage (a user who stores policies just for themselves).
+
+#### Adding a String Permission
+Now lets add a String permission to display a statistics bar for users like admins. We want to call `user.can? :view, "peek_bar"` and have it return true for admins.
+
+To do this, we'll need to define a non-model Policy (because our object is a string, "peek_bar").
+```ruby
+user = ...
+policy = Scram::Policy.new
+policy.name = "global-strings-policy" # Note that we're setting name, and we will leave context nil.
+policy.context = nil # This would be nil by default as well. By not setting this to anything, we let this Policy handle String permissions, and not be bound to a model.
+policy.save
+user.policies << policy
+user.save
+```
+
+Now we want to add a target that represents the ability to `view "peek_bar"`.
+```ruby
+target = Target.new
+target.conditions = {:equals => { :'*target_name' =>  "peek_bar"}}
+target.actions << "view"
+policy.targets << target
+policy.save
+```
+
+This code creates a target which permits viewing if the `*target_name` equals "peek_bar".
+
+Scram automatically replaces `*target_name` with the action being compared. For example, in `can? :view, "something_else"` Scram would check if `"something_else" == "peek_bar"`.
+
+And now we're done! :tada:
+
+#### Adding a Model Permission
+Now lets add something a bit more complex. Say we're developing a Forum application. We want to add the ability for a user to edit their own `Posts` using Scram.
+
+Here's our simple `Post` model:
+```ruby
+class Post
+  ...
+  belongs_to :user
+end
+```
+
+Lets make a Policy that handles post related permissions.
+```ruby
+user = ...
+policy = Scram::Policy.new
+policy.name = "Post Stuff" # This name is just for organizational/display purposes
+policy.context = Post.to_s # Note: By setting context, we bind this policy to the model "Post"
+policy.save
+user.policies << policy
+user.save
+```
+
+Now we need a Target in our Policy to let users edit their own Posts.
+```ruby
+target = Target.new
+target.conditions = {:equals => {:user => "*holder"}}
+target.actions << "edit"
+policy.save
+```
+What is `*holder`? Well, Scram replaces this special variable with the current user being compared. In `User#scram_compare_value` we return the User's ObjectId, and this is exactly what Scram replaced `*holder` with.
+
+So now this Target reads "allow a holder to edit a Post if the user of that Post is the holder". Pretty neat, huh?
+
+And now we're done! Go ahead and call `holder.can? :edit, @post` on a post which they own, and you'll see that Scram allows it! :tada:
+
+#### Using conditions
+In our last example, we let Scram directly compare an attribute of the model. What if we need more complex checking behavior? Luckily, Scram provides a DSL for models to easily define conditions which can be referenced in the database in place of attributes.
+
+Lets revisit the `Post` example, but this time we'll define how to get the owner using a condition DSL, instead of the attribute.
+
+```ruby
+class Post
+  include Scram::DSL::ModelConditions
+  ...
+  belongs_to :user
+
+  scram_define do
+    condition :owner do |post|
+      post.user
+    end
+  end
+end
+```
+
+Now we no longer need to directly tell our Target to access the user field. Here's what the equivalent Target would look like from our previous example, now using the new condition:
+
+```ruby
+...
+target.conditions = {:equals => {:'*owner' => "*holder"}}
+...
+```
+
+Scram is smart enough to realize that any key starting with an `*`, like `*owner`, is a manually defined condition. Now, calling `user.can? :edit, @post` will compare the value returned by the `condition` block to the hash value (which in this case is the Holder).
+
+#### Defining a New Comparator
+You may have noticed from the previous examples that the keys of our Target conditions were things like `equals` and `less_than`. These come from our Comparator definitions (see `Scram::DSL::Definitions::COMPARATORS`).
+
+These comparators are defined using the DSL for comparators. We provide a basic set of comparing operators, but you may need to add your own. To do this, we recommend creating an initializer file and then calling something like the following:
+
+```ruby
+builder = Scram::DSL::Builders::ComparatorBuilder.new do
+  comparator :asdf do |a,b|
+    true
+  end
+end
+Scram::DSL::Definitions.add_comparators(builder)
+```
+
+Now your targets can use `asdf` as a conditions key, and Scram will use your method of comparison to determine if something is true or not. In this case, `asdf` returns true regardless of the two objects being compared.
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/skreem/scram.

data/Rakefile

@@ -0,0 +1,32 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Scram'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+load 'rails/tasks/statistics.rake'
+
+
+
+require 'bundler/gem_tasks'
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+desc "Run all specs in spec directory (excluding plugin specs)"
+RSpec::Core::RakeTask.new(:spec => 'app:db:test:prepare')
+
+task :default => :spec

data/app/models/scram/policy.rb

@@ -0,0 +1,67 @@
+module Scram
+  # Model to represent a Holder's permission policy
+  class Policy
+    include Mongoid::Document
+
+    embeds_many :targets, class_name: "Scram::Target"
+
+    validates_presence_of :name
+
+    # @return [String] Name for this Policy. Purely for organizational purposes.
+    field :name, type: String
+
+    # @return [String] What model this Policy applies to. Will be nil if this Policy is not bound to a model.
+    field :context, type: String
+
+    # @return [Integer] Priority to allow this policy to override another conflicting {Scram::Policy} opinion.
+    field :priority, type: Integer, default: 0
+
+    # Helper method to easily tell if this policy is bound to a model
+    # @note Unnecessary since we can just call model.nil?, but it is helpful nonetheless
+    # @return [Boolean] True if this Policy is bound to a model, false otherwise
+    def model?
+      return !model.nil?
+    end
+
+    # Attempts to constantize and get a model
+    # @return [Object, nil] An object, likely a {::Mongoid::Document}, that this policy is bound to. nil if there is none.
+    def model
+      begin
+        return Module.const_get(context)
+      rescue # NameError if context as a constant doesn't exist, TypeError if context nil
+        return nil
+      end
+    end
+
+    # Checks if a {Scram::Holder} can perform some action on an object by checking targets
+    # @param holder [Scram::Holder] The actor
+    # @param action [String] What the user is trying to do to obj
+    # @param obj [Object] The receiver of the action
+    # @return [Symbol] This policy's opinion on an action and object. :allow and :deny mean this policy has a target who explicitly defines
+    #   its opinion, while :abstain means that none of the targets are applicable to the action, and so has no opinion.
+    def can? holder, action, obj
+      obj = obj.to_s if obj.is_a? Symbol
+      action = action.to_s
+      # Abstain if policy doesn't apply to the obj
+      if obj.is_a? String # String permissions
+        return :abstain if self.model? # abstain if policy doesn't handle strings
+      else                # Model permissions
+        return :abstain if !self.model? # abstain if policy doesn't handle models
+
+        if obj.is_a?(Class) # Passed in a class, need to check based off the passed in model's name
+          return :abstain if self.context != obj.to_s # abstain if policy doesn't handle these types of models
+        else # Passed in an instance of a model, need to check based off the instance's class's name
+          return :abstain if self.context != obj.class.name
+        end
+      end
+
+      # Checks targets in priority order for explicit allow or deny.
+      targets.order_by([[:priority, :desc]]).each do |target|
+        opinion = target.can?(holder, action, obj)
+        return opinion if %i[allow deny].include? opinion
+      end
+
+      return :abstain
+    end
+  end
+end

data/app/models/scram/target.rb

@@ -0,0 +1,70 @@
+module Scram
+  # A broad Target interface to scope in a {Scram::Policy}. A target must either whitelist or deny through its allow attribute.
+  class Target
+    include Mongoid::Document
+    embedded_in :policy, class_name: "Scram::Policy"
+
+    # @return [Array] Actions which this target applies to
+    field :actions, type: Array, default: []
+
+    # @return [Hash] Conditions which this target filters through. Keys are comparators, values are hashes of fields and values to compare.
+    field :conditions, type: Hash, default: {}
+
+    # @return [Integer] Priority to allow this target to override another conflicting {Scram::Target} opinion.
+    field :priority, type: Integer, default: 0
+
+    # @return [Boolean] This target's modification onto a permission (allow or deny), i.e. its type
+    field :allow, type: Boolean, default: true
+
+    # @return [Symbol] The type of this target (either permissive as allow or deny)
+    def target_type
+      allow ? :allow : :deny
+    end
+
+    # Checks if a {Scram::Holder} can perform some action on an object given this target's conditions and allow-stance.
+    #
+    # Scram allows for special names:
+    #   To make this target applicable to a string, use a key `*target_name` with value of the string permission.
+    #   To compare a value to a holder, use `*holder` for a value. To compare a value to a custom condition defined by {Scram::DSL::Builders::ConditionBuilder}
+    #   use an * before a key name (this name should match the one defined in your model).
+    # @param holder [Scram::Holder] The actor
+    # @param action [String] What the user is trying to do to obj
+    # @param obj [Object] The receiver of the action
+    # @return [Symbol] This target's opinion on an action and object. :allow and :deny mean this target explicitly defines
+    #   its opinion, while :abstain means that this Target is not applicable to the action, and so has no opinion.
+    def can? holder, action, obj
+      obj = obj.to_s if obj.is_a? Symbol
+      action = action.to_s
+
+      return :abstain unless actions.include? action
+
+      # Handle String permissions
+      if obj.is_a? String
+        if obj == conditions[:equals][:'*target_name']
+          return target_type
+        else
+          return :abstain
+        end
+      end
+
+      # Model permissions
+      # Attempts to abstain by finding a condition or attribute where comparisons fail (and thus this target would be unapplicable)
+      conditions.each do |comparator_name, fields_hash|
+        comparator = Scram::DSL::Definitions::COMPARATORS[comparator_name.to_sym]
+        fields_hash.each do |field, model_value|
+          # Either gets the model's attribute or gets the DSL defined condition.
+          # Abstains if neither can be reached
+          attribute = begin obj.send(:"#{field}") rescue return :abstain end
+
+          # Special value substitutions
+          model_value.gsub! "*holder", holder.scram_compare_value if model_value.respond_to?(:gsub!)
+
+          # Abstain if this target doesn't apply to obj in any of its attributes
+          return :abstain unless comparator.call(attribute, model_value)
+        end
+      end
+
+      return target_type
+    end
+  end
+end

data/lib/scram.rb

@@ -0,0 +1,11 @@
+require "scram/engine"
+
+require "scram/core_ext/symbol_extensions.rb"
+require "scram/dsl/builders.rb"
+require "scram/dsl/definitions.rb"
+require "scram/dsl/model_conditions.rb"
+require "scram/concerns/holder.rb"
+require "scram/concerns/aggregate_holder.rb"
+
+module Scram
+end

data/lib/scram/concerns/aggregate_holder.rb

@@ -0,0 +1,23 @@
+module Scram
+  # Class representing a Holder of policies through other Holders
+  # @note Implementing classes must implement #aggregates and #scram_compare_value
+  module AggregateHolder
+    include Holder
+
+    # @return [Array] other holders to consider in Policy inclusion
+    def aggregates
+      raise NotImplementedError # should be implemented by subclass
+    end
+
+    # @return [Array] list of policies through aggregates
+    def policies
+      aggregate_policies = aggregates.map {|a| a.policies}.flatten.sort_by {|p| p.priority}.reverse
+    end
+
+    # @return [Object] a value to compare {AggregateHolder} in the database. For example, an ObjectID would be suitable.
+    def scram_compare_value
+      raise NotImplementedError
+    end
+
+  end
+end

data/lib/scram/concerns/holder.rb

@@ -0,0 +1,38 @@
+module Scram
+  using SymbolExtensions
+
+  # Base class to represent a Holder of permissions through policies.
+  # @note Implementing classes must implement #policies and #scram_compare_value
+  module Holder
+    extend ActiveSupport::Concern
+
+    # @return [Array] list of policies
+    def policies
+      raise NotImplementedError
+    end
+
+    # @return [Object] a value to compare {Holder} in the database. For example, an ObjectID would be suitable.
+    def scram_compare_value
+      raise NotImplementedError
+    end
+
+    # Checks if this holder can perform some action on an object by checking the Holder's policies
+    # @param action [String] What the user is trying to do to obj
+    # @param obj [Object] The receiver of the action
+    # @return [Boolean] Whether or not holder can action to object. We define a full abstainment as a failure to perform the action.
+    def can? action, target
+      target = target.to_s if target.is_a? Symbol
+      action = action.to_s
+
+      # Checks policies in priority order for explicit allow or deny.
+      policies.sort_by(&:priority).reverse.each do |policy|
+        opinion = policy.can?(self, action, target)
+        return opinion.to_bool if %i[allow deny].include? opinion
+      end
+
+      return false
+    end
+
+
+  end
+end