policy_machine 0.0.1

data/lib/policy_machine_storage_adapters/template.rb

@@ -0,0 +1,169 @@
+require 'policy_machine'
+
+# This class provides a template for creating your own Policy Machine
+# Storage Adapter.  Simply copy this file and implement all public methods.
+# Ensure correctness using the shared examples in
+# 'spec/support/shared_examples_policy_machine_storage_adapter_spec.rb'.
+# Ensure your adapter integrates properly with the policy machine using the shared
+# examples in 'spec/support/shared_examples_policy_machine_spec.rb'.
+
+module PolicyMachineStorageAdapter
+  class Template
+
+    ##
+    # The following add_* methods store a policy element in the policy machine.
+    # The unique_identifier identifies the element within the policy machine.
+    # The policy_machine_uuid is the uuid of the containing policy machine.
+    # Extra attributes should be persisted as metadata associated with the object.
+    # Each method should return the persisted policy element.  Persisted policy
+    # element objects should respond to each extra attribute key as well as the following methods:
+    # * unique_identifier
+    # * policy_machine_uuid
+    # * persisted
+    #
+    def add_user(unique_identifier, policy_machine_uuid, extra_attributes = {})
+
+    end
+    def add_user_attribute(unique_identifier, policy_machine_uuid, extra_attributes = {})
+
+    end
+    def add_object(unique_identifier, policy_machine_uuid, extra_attributes = {})
+
+    end
+    def add_object_attribute(unique_identifier, policy_machine_uuid, extra_attributes = {})
+
+    end
+    def add_operation(unique_identifier, policy_machine_uuid, extra_attributes = {})
+
+    end
+    def add_policy_class(unique_identifier, policy_machine_uuid, extra_attributes = {})
+
+    end
+
+    ##
+    # The following find_* methods should return an array of persisted
+    # policy elements of the given type (e.g. user or object_attribute) and extra attributes.
+    # If no such persisted policy elements are found, the empty array should
+    # be returned.
+    #
+    def find_all_of_type_user(options = {})
+
+    end
+    def find_all_of_type_user_attribute(options = {})
+
+    end
+    def find_all_of_type_object(options = {})
+
+    end
+    def find_all_of_type_object_attribute(options = {})
+
+    end
+    def find_all_of_type_operation(options = {})
+
+    end
+    def find_all_of_type_policy_class(options = {})
+
+    end
+
+    ##
+    # Assign src to dst in policy machine.
+    # The two policy elements must be persisted policy elements; otherwise the method should raise
+    # an ArgumentError.
+    # Returns true if the assignment occurred, false otherwise.
+    #
+    def assign(src, dst)
+
+    end
+
+    ##
+    # Determine if there is a path from src to dst in the policy machine.
+    # The two policy elements must be persisted policy elements; otherwise the method should raise
+    # an ArgumentError.
+    # Returns true if there is a such a path and false otherwise.
+    # Should return true if src == dst
+    #
+    def connected?(src, dst)
+
+    end
+
+    ##
+    # Disconnect two policy elements in the machine
+    # The two policy elements must be persisted policy elements; otherwise the method should raise
+    # an ArgumentError.
+    # Returns true if unassignment occurred and false otherwise.
+    # Generally, false will be returned if the assignment didn't exist in the PM in the
+    # first place.
+    #
+    def unassign(src, dst)
+
+    end
+
+    ##
+    # Remove a persisted policy element. This should remove its assignments and
+    # associations but must not cascade to any connected policy elements.
+    # Returns true if the delete succeeded.
+    #
+    def delete(element)
+
+    end
+
+    ##
+    # Update the extra_attributes of a persisted policy element.
+    # This should only affect attributes corresponding to the keys passed in.
+    # Returns true if the update succeeded or was redundant.
+    #
+    def update(element, changes_hash)
+
+    end
+
+    ##
+    # Determine if the given node is in the policy machine or not.
+    # Returns true or false accordingly.
+    #
+    def element_in_machine?(pe)
+
+    end
+
+    ##
+    # Add the given association to the policy map.  If an association between user_attribute
+    # and object_attribute already exists, then replace it with that given in the arguments.
+    # Returns true if the association was added and false otherwise.
+    #
+    def add_association(user_attribute, operation_set, object_attribute, policy_machine_uuid)
+
+    end
+
+    ##
+    # Return an array of all associations in which the given operation is included.
+    # Each element of the array should itself be an array in which the first element
+    # is the user_attribute member of the association, the second element is a
+    # Ruby Set, each element of which is an operation, the third element is the
+    # object_attribute member of the association.
+    # If no associations are found then the empty array should be returned.
+    #
+    def associations_with(operation)
+
+    end
+
+    ##
+    # Return array of all policy classes which contain the given object_attribute (or object).
+    # Return empty array if no such policy classes found.
+    def policy_classes_for_object_attribute(object_attribute)
+
+    end
+
+    ##
+    # Return array of all user attributes which contain the given user.
+    # Return empty array if no such user attributes are found.
+    def user_attributes_for_user(user)
+    end
+
+    ##
+    # Execute the passed-in block transactionally: any error raised out of the block causes
+    # all the block's changes to be rolled back. Should raise NotImplementedError if the
+    # persistence layer does not support this.
+    def transaction
+    end
+
+  end
+end

data/lib/tasks/policy_machine_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :policy_machine do
+#   # Task goes here
+# end

data/policy_machine.gemspec

@@ -0,0 +1,23 @@
+Gem::Specification.new do |s|
+  s.name        = "policy_machine"
+  s.version     = "0.0.1"
+  s.summary     = "Policy Machine!"
+  s.description = "A ruby implementation of the Policy Machine authorization formalism."
+  s.authors     = ['Matthew Szenher', 'Aaron Weiner']
+  s.email       = s.authors.map{|name|name.sub(/(.).* (.*)/,'\1\2@mdsol.com')}
+  s.homepage    = 'https://github.com/mdsol/the_policy_machine'
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.require_paths = ["lib"]
+
+  s.add_dependency('activesupport')
+
+  s.add_development_dependency('rspec', '~> 2.13.0')
+  s.add_development_dependency('simplecov', '~> 0.7.1')
+  s.add_development_dependency('debugger', '~> 1.6.0')
+  s.add_development_dependency('neography', '~> 1.1')
+  s.add_development_dependency('rails')
+  s.add_development_dependency('mysql2')
+  s.add_development_dependency('database_cleaner')
+
+end

data/spec/policy_machine/association_spec.rb

@@ -0,0 +1,61 @@
+require 'spec_helper'
+
+describe PM::Association do
+
+  describe '#create' do
+    before do
+      @policy_machine = PolicyMachine.new
+      @object_attribute = @policy_machine.create_object_attribute('OA name')
+      @operation1 = @policy_machine.create_operation('read')
+      @operation2 = @policy_machine.create_operation('write')
+      @operation_set = Set.new [@operation1, @operation2]
+      @user_attribute = @policy_machine.create_user_attribute('UA name')
+      
+      other_pm = PolicyMachine.new
+      @other_oa = other_pm.create_object_attribute('UA other')
+      @other_op = other_pm.create_operation('delete')
+    end
+    
+    it 'raises when first argument is not a user attribute' do
+      expect{ PM::Association.create(@object_attribute, @operation_set, @object_attribute, @policy_machine.uuid, @policy_machine.policy_machine_storage_adapter) }.
+        to raise_error(ArgumentError, "user_attribute_pe must be a UserAttribute.")
+    end
+
+    it 'raises when first argument is not in given policy machine' do
+      expect{ PM::Association.create(@user_attribute, @operation_set, @object_attribute, "blah", @policy_machine.policy_machine_storage_adapter) }.
+        to raise_error(ArgumentError, "user_attribute_pe must be in policy machine with uuid blah")
+    end
+
+    it 'raises when second argument is not a set' do
+      expect{ PM::Association.create(@user_attribute, 1, @object_attribute, @policy_machine.uuid, @policy_machine.policy_machine_storage_adapter) }.
+        to raise_error(ArgumentError, "operation_set must be a Set of Operations")        
+    end
+
+    it 'raises when second argument is empty set' do
+      expect{ PM::Association.create(@user_attribute, Set.new, @object_attribute, @policy_machine.uuid, @policy_machine.policy_machine_storage_adapter) }.
+        to raise_error(ArgumentError, "operation_set must not be empty")        
+    end
+
+    it 'raises when second argument is a set in which at least one element is not a PM::Operation' do
+      expect{ PM::Association.create(@user_attribute, Set.new([@operation1, 1]), @object_attribute, @policy_machine.uuid, @policy_machine.policy_machine_storage_adapter) }.
+        to raise_error(ArgumentError, "expected 1 to be PM::Operation; got Fixnum")        
+    end
+
+    it 'raises when second argument is a set in which at least one element is a PM::Operation which is in a different policy machine' do
+      expect{ PM::Association.create(@user_attribute, Set.new([@other_op]), @object_attribute, @policy_machine.uuid, @policy_machine.policy_machine_storage_adapter) }.
+        to raise_error(ArgumentError, "expected #{@other_op.unique_identifier} to be in Policy Machine with uuid #{@policy_machine.uuid}; got #{@other_op.policy_machine_uuid}")        
+    end
+    
+    it 'raises when third argument is not an object attribute' do
+      expect{ PM::Association.create(@user_attribute, @operation_set, "abc", @policy_machine.uuid, @policy_machine.policy_machine_storage_adapter) }.
+        to raise_error(ArgumentError, "object_attribute_pe must be an ObjectAttribute.")
+    end    
+    
+    it 'raises when third argument is not in given policy machine' do
+      expect{ PM::Association.create(@user_attribute, @operation_set, @other_oa, @policy_machine.uuid, @policy_machine.policy_machine_storage_adapter) }.
+        to raise_error(ArgumentError, "object_attribute_pe must be in policy machine with uuid #{@policy_machine.uuid}")
+    end
+    
+  end
+  
+end

data/spec/policy_machine/policy_element_spec.rb

@@ -0,0 +1,20 @@
+require 'spec_helper'
+
+describe PM::PolicyElement do
+
+  before do
+    class GenericPolicyElement < PM::PolicyElement
+      def initialize
+      end
+    end
+  end
+
+  it 'raises if allowed_assignee_classes is not overridden in subclass' do
+    expect{ GenericPolicyElement.new.send(:allowed_assignee_classes) }.to raise_error("Must override this method in a subclass")
+  end
+
+  it 'behaves normally when an unknown method is called' do
+    expect{ GenericPolicyElement.new.creat }.to raise_error(NoMethodError, /^undefined method `creat' for #<GenericPolicyElement/)
+  end
+
+end

data/spec/policy_machine_spec.rb

@@ -0,0 +1,7 @@
+require 'spec_helper'
+
+describe PolicyMachine do
+  it_behaves_like 'a policy machine' do
+    let(:policy_machine) { PolicyMachine.new(:name => 'default PM') }
+  end
+end

data/spec/policy_machine_storage_adapters/active_record_spec.rb

@@ -0,0 +1,54 @@
+require 'spec_helper'
+require 'policy_machine_storage_adapters/active_record'
+require 'database_cleaner'
+
+DatabaseCleaner.strategy = :truncation
+
+describe 'ActiveRecord' do
+
+  before(:each) do
+    Rails.cache.clear
+    DatabaseCleaner.clean
+  end
+
+  describe PolicyMachineStorageAdapter::ActiveRecord do
+    it_behaves_like 'a policy machine storage adapter with required public methods'
+    it_behaves_like 'a policy machine storage adapter'
+    let(:policy_machine_storage_adapter) { described_class.new }
+
+    describe 'find_all_of_type' do
+
+      it 'warns when filtering on an extra attribute' do
+        policy_machine_storage_adapter.should_receive(:warn).once
+        policy_machine_storage_adapter.find_all_of_type_user(foo: 'bar').should be_empty
+      end
+
+      context 'an extra attribute column has been added to the database' do
+
+        it 'does not warn' do
+          policy_machine_storage_adapter.should_not_receive(:warn)
+          policy_machine_storage_adapter.find_all_of_type_user(color: 'red').should be_empty
+        end
+
+        it 'only returns elements that match the hash' do
+          policy_machine_storage_adapter.add_object('some_uuid1', 'some_policy_machine_uuid1')
+          policy_machine_storage_adapter.add_object('some_uuid2', 'some_policy_machine_uuid1', color: 'red')
+          policy_machine_storage_adapter.add_object('some_uuid3', 'some_policy_machine_uuid1', color: 'blue')
+          policy_machine_storage_adapter.find_all_of_type_object(color: 'red').should be_one
+          policy_machine_storage_adapter.find_all_of_type_object(color: nil).should be_one
+          policy_machine_storage_adapter.find_all_of_type_object(color: 'green').should be_none
+          policy_machine_storage_adapter.find_all_of_type_object(color: 'blue').map(&:color).should eql(['blue'])
+        end
+
+      end
+
+    end
+
+  end
+
+  describe 'PolicyMachine integration with PolicyMachineStorageAdapter::ActiveRecord' do
+    it_behaves_like 'a policy machine' do
+      let(:policy_machine) { PolicyMachine.new(:name => 'ActiveRecord PM', :storage_adapter => PolicyMachineStorageAdapter::ActiveRecord) }
+    end
+  end
+end

data/spec/policy_machine_storage_adapters/in_memory_spec.rb

@@ -0,0 +1,13 @@
+require 'spec_helper'
+require 'policy_machine_storage_adapters/in_memory'
+
+describe PolicyMachineStorageAdapter::InMemory do
+  it_behaves_like 'a policy machine storage adapter with required public methods'
+  it_behaves_like 'a policy machine storage adapter'
+end
+
+describe 'PolicyMachine integration with PolicyMachineStorageAdapter::InMemory' do
+  it_behaves_like 'a policy machine' do
+    let(:policy_machine) { PolicyMachine.new(:name => 'in memory PM', :storage_adapter => PolicyMachineStorageAdapter::InMemory) }
+  end    
+end

data/spec/policy_machine_storage_adapters/neography_spec.rb

@@ -0,0 +1,42 @@
+require 'spec_helper'
+require 'policy_machine_storage_adapters/neography'
+
+describe 'Neography' do
+  before(:all) do
+    stop_neo4j
+    reset_neo4j
+    start_neo4j    
+  end
+  before(:each) do
+    clean_neo4j
+  end
+  after(:all) do
+    stop_neo4j
+  end
+  
+  describe PolicyMachineStorageAdapter::Neography do
+    it_behaves_like 'a policy machine storage adapter with required public methods'
+    it_behaves_like 'a policy machine storage adapter'
+  end
+
+  describe 'PolicyMachine integration with PolicyMachineStorageAdapter::Neography' do  
+    it_behaves_like 'a policy machine' do
+      let(:policy_machine) { PolicyMachine.new(:name => 'neography PM', :storage_adapter => PolicyMachineStorageAdapter::Neography) }    
+    end
+    
+    describe '#assign' do
+      # TODO:  storage adapters should be made tolerant to exceptions raised by underlying clients.
+      it 'returns false when relationship cannot be created' do
+        ::Neography::Relationship.stub(:create).and_return(nil)
+        policy_machine_storage_adapter = PolicyMachineStorageAdapter::Neography.new
+        src = policy_machine_storage_adapter.add_user('some_uuid1', 'some_policy_machine_uuid1')
+        dst = policy_machine_storage_adapter.add_user_attribute('some_uuid2', 'some_policy_machine_uuid1')
+        policy_machine_storage_adapter.assign(src, dst).should be_false
+      end
+    end
+  end
+end if neo4j_exists?
+
+unless neo4j_exists?
+  warn "Integration testing with neo4j requires that neo4j be installed in the gem's root directory"
+end

data/spec/policy_machine_storage_adapters/template_spec.rb

@@ -0,0 +1,6 @@
+require 'spec_helper'
+require 'policy_machine_storage_adapters/template'
+
+describe PolicyMachineStorageAdapter::Template do
+  it_behaves_like 'a policy machine storage adapter with required public methods'  
+end

data/spec/spec_helper.rb

@@ -0,0 +1,24 @@
+require_relative '../test/test_helper.rb'
+
+require 'simplecov'
+SimpleCov.start do
+  add_group 'lib', 'lib'
+  add_filter 'spec'
+end
+
+require 'rspec'
+require 'debugger'
+
+SPEC_DIR = File.expand_path("..", __FILE__)
+lib_dir = File.expand_path("../lib", SPEC_DIR)
+
+$LOAD_PATH.unshift(lib_dir)
+$LOAD_PATH.uniq!
+
+require 'policy_machine'
+
+Dir["./spec/support/**/*.rb"].each {|f| require f}
+
+RSpec.configure do |config|
+  config.mock_with :rspec
+end

data/spec/support/neography_helpers.rb

@@ -0,0 +1,39 @@
+# This file contains helper methods to manage a neo4j db via neography, for testing purposes.
+
+def neo4j_exists?
+  system('test -d neo4j')
+end
+
+def start_neo4j
+  # Start the server
+  # TODO:  sometimes the server doesn't start before tests start to run.  Fix!
+  # TODO:  probably have to make a separate connection for test db so as not to wipe out dev data.
+  puts "STARTING NEO4J SERVER..."
+  %x[neo4j/bin/neo4j start]
+end
+
+def stop_neo4j
+  puts "STOPPING NEO4J SERVER..."
+  %x[neo4j/bin/neo4j stop]
+end
+
+def reset_neo4j
+  # Reset the database
+  puts "RESETTING NEO4J DB..."
+  FileUtils.rm_rf("neo4j/data/graph.db")
+  FileUtils.mkdir("neo4j/data/graph.db")
+
+  # Remove log files
+  puts "REMOVING NEO4J LOGS..."
+  FileUtils.rm_rf("neo4j/data/log")
+  FileUtils.mkdir("neo4j/data/log")
+end
+
+# Clear all nodes except start node. Should be run before each unit test.
+def clean_neo4j
+  neo_connection.execute_query("START n0=node(0),nx=node(*) MATCH n0-[r0?]-(),nx-[rx?]-() WHERE nx <> n0 DELETE r0,rx,nx")
+end
+
+def neo_connection
+  @neo ||= Neography::Rest.new
+end