sanction 0.0.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e14e098c1724519c24335f03af617abd5382bcb1
-  data.tar.gz: aad98cfafac83ac05de0e46add2b9246e5507440
+  metadata.gz: 0d9b7c911e6b858db458af6c2a1a1a2576831c6c
+  data.tar.gz: dfc5c0aa9ea471972fb4897649e195195b8d4002
 SHA512:
-  metadata.gz: c2b809a7fea3393d9791768d380f2aa5dd04e869ac72d356f6e97aab425bbd18deff762fbbeb438ddd1bf45de2b7347f714fc1da45bc49f08207b3295d7bdee6
-  data.tar.gz: bc6699456115656c49c2e6ca8717f152d03a35595111165e55c2f8bab695e3ff8243c11768e9e31bf74961c6cb5a00abd4a96ab0669b4d56052660ba1c19a984
+  metadata.gz: 627ca53b8f5c5d2d162b4035e792f94af8560e6f66cb6ab4030db8a646ccb909a9078a28c3e7d16c6f59254a3ef03cffd61c2fd9d38f48db93ea4b2ee550e7ed
+  data.tar.gz: 31e827b77feb6d04d471d54e08f260b833bf845d930fbab5cf401ecd4f2ea18d0936455d78f7c94c17fda1e043c673a30af6c6c094ac9653bf904165627b32b5

data/.gitignore

@@ -1,20 +1,12 @@
-*.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/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
 *.bundle
 *.so
 *.o

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 2.1.0
+  - 2.0.0
+  - jruby-19mode # JRuby in 1.9 mode
+script: bundle exec rake test

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2014 JGW Maxwell
+Copyright (c) 2014 Adam Carlile
 
 MIT License
 

data/README.md

@@ -1,12 +1,14 @@
 # Sanction
 
-TODO: Write a gem description
+Sanction is a permissions manager specifically for managing nested permission sets, with varying scopes or roles. Having found nothing that fit our specific problem domain. The idea is that object relationships are stored as a Hash, and persisted as JSON, and Sanction can then read that permission graph, and return you a true or false for your resource, or scope for that resource.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'sanction'
+```ruby
+gem 'sanction'
+```
 
 And then execute:
 
@@ -16,13 +18,111 @@ Or install it yourself as:
 
     $ gem install sanction
 
-## Usage
+## What can it give me?
 
-TODO: Write usage instructions here
+Sanction is designed to be as flexible as possible, allowing various scopes to be applied to specific points in the resource graph, along with specific grant or deny to global resource types at specific levels. With either whitelisting or blacklisting, plus wildcarding for whitelists.
+
+### Object Structure
+```ruby
+{
+  id:        1
+  type:      'bookcase'
+  mode:      'whitelist',
+  scope:     ['manage', 'read'],
+  resources: ['shelf'],
+  subjects:  [ ... ]
+}
+```
+* __ID__: The ID of the object that this permission applies to, is optional, root nodes will have a nil ID, in a whitelist node, this can be a wildcard("*") character to allow access to all
+* __Type__: The Type of object in this graph, again it is optional, root nodes will have a nil type.
+* __Mode__: The mode of operation for the subjects and resources arrays:
+  * Whitelist:
+    * Objects that exist in the subjects array are allowed, others are denied
+    * A blank array is an implicit *DENY ALL* subjects
+  * Blacklist:
+    * Objects that exist in the subjects array are denied, others are allowed
+    * A blank array is an implicit *ALLOW ALL* subjects
+* __Scope__: An array of 'actions' that can be performed on the object, this can be anything, 'read', 'write', 'testing' etc.
+* __Resources__: Resources are subject to the mode, blacklist is to exclude these resources from being accessed, whitelist being the opposite.
+  * Resources allows/denies will always take precedence over objects in the subjects array
+* __Subjects__: An array that contains more of these objects, subject to the whitelist/blacklist mode of operation
+
+### Interface
+
+To generate an interactive object graph from storage:
+```ruby
+perms = Sanction.build(hash)
+```
+
+This will return you the root node of the graph, and you can navigate it by using hash accessors, and then call interrogation methods on the returned objects
+
+```ruby
+perms[:bookcase][1]                    # => Node in the graph
+perms[:bookcase][1].permitted?         # => true/false
+perms[:bookcase][1].has_scope?(:read)  # => true/false
+perms[:bookcase][1].whitelist?         # => true/false
+perms[:bookcase][1].blacklist?         # => true/false
+```
+
+You can also get the state of the collection of objects too.
+
+```ruby
+perms[:bookcase].allowed_ids          # => Array of allowed ids
+perms[:bookcase].denied_ids           # => Array of allowed ids
+perms[:bookcase].whitelist?           # => true/false
+perms[:bookcase].blacklist?           # => true/false
+perms[:bookcase].permitted?           # => true/false
+perms[:bookcase].has_scope?(:read)    # => true/false
+```
+
+And mutate the state of the graph
+
+```ruby
+perms.whitelist?               # => true
+perms[:bookcase][1].allow! 
+perms[:bookcase][1].permitted? # => true
+
+perms[:bookcase][1].deny!
+perms[:bookcase][1].permitted? # => false
+
+perms[:bookcase][1].scope << :testing
+perms[:bookcase][1].has_scope? :testing # => true
+
+perms = perms.change_type! :blacklist # => Returns a new root graph, blacklisted at root
+perms[:bookcase].whitelist?           # => false
+
+perms[:bookcase][1].change_type! :blacklist # => Changes this to blacklist mode, applies to children
+perms[:bookcase][1][:shelf].whitelist?      # => false
+```
+
+And of course add/remove objects.
+
+```ruby
+perms.add_subject({
+  id:   1
+  type: 'user'
+})
+
+perms.whitelist?             # => true
+perms[:user][1].permitted?   # => true
+
+
+perms[:user][1].unlink
+perms[:user][1].permitted?   # => false
+```
+
+One caveat is that for nodes that have a deny on a specific resource type, even if you add it in the graph it will still return false, ensure you either remove/add the resource type to the resources array, or ensure that a whitelisted node has a wildcard("*").
+
+The best bit is that the objects don't have to exist in the graph to be queried against, it just relies on the last fragment it could find and applies the rule that was set there.
+
+```ruby
+perms.whitelist? # => true
+perms[:bookcase][1][:shelf][12][:book][3].permitted? # => false
+```
 
 ## Contributing
 
-1. Fork it ( https://github.com/[my-github-username]/sanction/fork )
+1. Fork it ( https://github.com/boardiq/sanction/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`)

data/Rakefile

@@ -1,2 +1,7 @@
 require "bundler/gem_tasks"
+require 'rake/testtask'
 
+Rake::TestTask.new do |t|
+  t.libs << 'spec'
+  t.pattern = "spec/*_spec.rb"
+end

data/lib/sanction/attached_list.rb

@@ -0,0 +1,57 @@
+module Sanction
+  class AttachedList < SimpleDelegator
+
+    attr_accessor :key, :parent
+
+    def initialize(array = [])
+      super(array)
+    end
+
+    def [](index)
+      detect {|x| x.id == index} || wildcard_member || null_node_class.new({id: index, type: key, scope: []}, @parent)
+    end
+
+    def type
+      key
+    end
+
+    def ids_blank?
+      denied_ids.blank? && allowed_ids.blank?
+    end
+
+    def denied_ids
+      []
+    end
+
+    def allowed_ids
+      []
+    end
+
+    def has_scope? scope
+      @parent.has_scope? scope
+    end
+
+    def wildcard_member
+      detect {|x| x.wildcarded? }
+    end
+
+    def wildcarded?
+      !!wildcard_member
+    end
+
+    def wildcard_resource?
+      resources.include?(:*)
+    end
+
+    def resources
+      @parent.resources
+    end
+
+    private
+
+      def null_node_class
+        raise NotImplementedError
+      end
+
+  end
+end

data/lib/sanction/blacklist/list.rb

@@ -0,0 +1,34 @@
+module Sanction
+  module Blacklist
+    class List < Sanction::AttachedList
+
+      def allowed_ids
+        []
+      end
+
+      def permitted?
+        return false if wildcard_resource?
+        return false if resources.include?(@key)
+        return true if ids_blank?
+        true
+      end
+
+      def blacklist?
+        true
+      end
+
+      def whitelist?
+        false
+      end
+
+      def denied_ids
+        entries.map {|x| x.id}
+      end
+
+      def null_node_class
+        Sanction::Blacklist::NullNode
+      end
+
+    end
+  end
+end

data/lib/sanction/blacklist/node.rb

@@ -0,0 +1,42 @@
+module Sanction
+  module Blacklist
+    class Node < Sanction::Node
+
+      def permitted?
+        super
+        root? ? true : (@parent[type].permitted? && @parent[type].allowed_ids.include?(id))
+      end
+
+      def allow!
+        @parent.resources.reject! {|x| x == type } unless @parent[type].count > 1
+        unlink
+        true
+      end
+
+      def deny!
+        false
+      end
+
+      def whitelist?
+        false
+      end
+
+      def blacklist?
+        true
+      end
+
+      def mode
+        'blacklist'
+      end
+
+      def array_class
+        Sanction::Blacklist::List
+      end
+
+      def null_array_class
+        Sanction::Blacklist::NullList
+      end
+
+    end
+  end
+end

data/lib/sanction/blacklist/null_list.rb

@@ -0,0 +1,21 @@
+module Sanction
+  module Blacklist
+    class NullList < Sanction::Blacklist::List
+
+      def permitted?
+        return false if wildcard_resource?
+        return false if resources.include?(@key) && ids_blank?
+        return true if ids_blank?
+      end
+
+      def persisted?
+        false
+      end
+
+      def null_node_class
+        Sanction::Blacklist::NullNode
+      end
+
+    end
+  end
+end

data/lib/sanction/blacklist/null_node.rb

@@ -0,0 +1,37 @@
+module Sanction
+  module Blacklist
+    class NullNode < Sanction::Blacklist::Node
+
+      def permitted?
+        a = ancestors.reject(&:root?).map(&:permitted?)
+        a << true 
+        a.all?
+      end
+
+      def allow!
+        false
+      end
+
+      def deny!
+        ancestors.reject(&:persisted?).each(&:deny!)
+        @parent.resources << type
+        @parent.resources.uniq!
+        @parent.add_subject({
+          id:   id,
+          type: type
+        })
+      end
+
+      def persisted?
+        false
+      end
+
+      def array_class
+        Sanction::Blacklist::NullList
+      end
+
+      alias :null_array_class :array_class
+
+    end
+  end
+end

data/lib/sanction/node.rb

@@ -0,0 +1,135 @@
+module Sanction
+  class Node
+    include Tree
+
+    attr_reader :id, :type
+
+    def initialize(hash, parent=nil)
+      @parent = parent
+      process_hash(hash)
+    end
+
+    def permitted?
+      return false if wildcarded? && @parent.blacklist?
+      return true  if wildcarded? && @parent.whitelist?
+    end
+
+    def to_hash
+      {
+        id: @id,
+        type: @type,
+        mode: mode,
+        scope: @scope,
+        subjects: subjects.map {|x| x.to_hash},
+        resources: @resources
+      }.reject { |k, v| v.blank? }
+    end
+
+    def persisted?
+      true
+    end
+
+    # Returns the new graph with the switched mode
+    def change_type! type
+      hash = to_hash
+      klass = "sanction/#{type}/node".classify.constantize
+      if root?
+        klass.new(hash)
+      else
+        node = klass.new(hash, parent)
+        parent.children << node
+        unlink
+        node.root
+      end
+    end
+
+    def add_subject(hash)
+      mode_class = hash[:mode] || mode
+      children << "sanction/#{mode_class}/node".classify.constantize.new(hash, self)
+    end
+
+    # Virtual
+    def array_class
+      raise NotImplementedError
+    end
+
+    def null_array_class
+      raise NotImplementedError
+    end
+
+    def [](key)
+      klass = subjects.select {|x| x.type?(key) }.any? ? array_class : null_array_class
+      klass.new(subjects.select {|x| x.type?(key) }).tap do |x| 
+        x.key = key
+        x.parent = self
+      end
+    end
+
+    def find(type, id)
+      out = root
+      walk do |child|
+        out = child if (child.type?(type) && child.id?(id))
+      end
+      out
+    end
+
+    def has_scope? scope_symbol
+      scope.include? scope_symbol.to_sym
+    end
+
+    def type?(type)
+      @type == type.to_sym
+    end
+
+    def id?(id)
+      @id == id
+    end
+
+    def scope
+      @scope.blank? ? parent.scope : @scope
+    end
+    
+    def scope=(scope)
+      @scope = [scope].flatten.compact.map(&:to_sym)
+    end
+
+    def resources
+      return [] if (@resources.blank? && root?)
+      @resources.blank? ? parent.resources : @resources
+    end
+
+    def resources=(resource)
+      @resources = [resource].flatten.compact.map(&:to_sym)
+    end
+
+    def mode
+      raise NotImplementedError
+    end
+
+    def children?
+      children.any?
+    end
+
+    def wildcarded?
+      @id == '*'
+    end
+
+    def children
+      @children ||= array_class.new
+    end
+
+    alias :subjects :children
+
+    private
+
+      def process_hash(hash)
+        @id         = hash[:id]
+        @scope      = hash[:scope].map(&:to_sym) unless hash[:scope].blank?
+        @type       = hash[:type].to_sym if hash[:type]
+        @resources  = []
+        @resources  += hash[:resources].map(&:to_sym) unless hash[:resources].blank?
+        hash[:subjects].each { |subject| add_subject(subject) } unless hash[:subjects].blank?
+      end
+
+  end
+end

data/lib/sanction/permission.rb

@@ -0,0 +1,38 @@
+module Sanction
+  class Permission
+
+    attr_reader :predicates
+
+    def initialize(permission_graph, *predicates)
+      @graph      = permission_graph
+      @predicates = predicates
+    end
+
+    def path
+      @path ||= begin
+        path = @graph.root
+        @predicates.each do |predicate|
+          if predicate.is_a?(Class)
+            path = path[predicate.to_s.demodulize.underscore.to_sym]
+          else
+            path = path[predicate.class.to_s.demodulize.underscore.to_sym][predicate.id]
+          end
+        end
+        path
+      end
+    end
+
+    def persisted?
+      path.persisted?
+    end
+
+    def permitted?
+      path.permitted?
+    end
+
+    def permitted_with_scope?(scope)
+      permitted? && path.has_scope?(scope)
+    end
+
+  end
+end

data/lib/sanction/tree.rb

@@ -0,0 +1,124 @@
+module Sanction
+  module Tree
+      
+    # This node's parent.
+    def parent
+      @parent
+    end
+    
+    # Is this node the root of the tree?
+    def root?
+      parent.nil?
+    end
+    
+    # Is this node a leaf node? Is this node childless?
+    def leaf?
+      children.nil? || children.empty?
+    end
+    
+    # Get the root node in this tree.
+    def root
+      if root?
+        self
+      else
+        parent.root
+      end
+    end
+    
+    # Get the children of this node.
+    def children
+      @children ||= []
+    end
+    
+    # Get the siblings of this node. The other children belonging to this node's parent.
+    def siblings
+      if parent
+        parent.children.reject {|child| child == self }
+      end
+    end
+    
+    # Is this node the only child of its parent. Does it have any siblings?
+    def only_child?
+      if parent
+        siblings.empty?
+      end
+    end
+    
+    # Does this node have children? Is it not a leaf node?
+    def has_children?
+      !leaf?
+    end
+    
+    # Get all of the ancestors for this node.
+    def ancestors
+      ancestors = []
+      if parent
+        ancestors << parent
+        parent.ancestors.each {|ancestor| ancestors << ancestor }
+      end
+      ancestors
+    end
+    
+    # Get all of the descendants of this node.
+    # All of its children, and its childrens' children, and its childrens' childrens' children...
+    def descendants
+      descendants = []
+      if !children.empty?
+        (descendants << children).flatten!
+        children.each {|descendant| descendants << descendant.descendants }
+        descendants.flatten!   
+      end
+      descendants
+    end
+    
+    # An integer representation of how deep in the tree this node is.
+    # The root node has a depth of 1, its children have a depth of 2, etc.
+    def depth
+      ancestors.size + 1
+    end
+    
+    # From Wikipedia: The height of a node is the length
+    # of the longest downward path to a leaf from that node. 
+    # In other words, the length of this node to its furthest descendant.
+    def height
+      if !leaf?
+        descendants.collect {|child| child.depth }.uniq.size + 1
+      else
+        1
+      end
+    end
+    
+    # Orphan this node. Remove it from its parent node.
+    def unlink
+      if parent
+        parent.children.delete(self)
+        self.instance_variable_set(:@parent, nil)
+        return self
+      end
+    end
+    
+    # Abandon all of this node's children.
+    def prune
+      if children
+        children.each {|child| child.unlink }
+      end
+    end
+    
+    # Append a node to this node's children, and return the node.
+    def graft(node)
+      node.instance_variable_set(:@parent, self)
+      children << node
+      node
+    end
+    
+    # Recursively yield every node in the tree.
+    def walk(&block)
+      if block_given?
+        yield self
+        children.each {|child| child.walk(&block) }
+      end
+    end
+    
+    
+  end
+end

data/lib/sanction/version.rb

@@ -1,3 +1,3 @@
 module Sanction
-  VERSION = "0.0.1"
+  VERSION = "2.1.0"
 end