activity_permission_engine 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a75028aa4cbffc505ba30e007ae904d27e57e911
+  data.tar.gz: 72824891b3e32831dcd869f5bbab72ba265ce298
+SHA512:
+  metadata.gz: 010ad27442d918988ee0aa4e522d206e03370df9f3645c448d4798c804c4a94280daf18f338c811ffbb6b92f24226749e6249709fd3afcf0fe581214d0f4211a
+  data.tar.gz: 5355706b432b57c95676f1f08949b9e500455e1333bc83184cc4b55318baac7d3565665acd0b4e50dd06a34201c5dacd2cee42af1b389940e6eee50328bd9d8f

data/.gitignore

@@ -0,0 +1,16 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+.idea/
+activity_permission_engine.iml

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2016 Cedric Brancourt, Synbioz
+
+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,167 @@
+# ActivityPermissionEngine
+
+This gem provides flexible tooling for managing application permissions
+
+It allows you to:
+
+* Set permissions on activities (strings) for some entities like roles.
+* Check for authorization
+
+You can use it on its own but, it will fit very well with [Pundit](https://github.com/elabs/pundit) or cancan
+
+## Installation
+
+### Using Bundler
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'activity_permission_engine'
+```
+
+And then execute:
+
+    $ bundle
+
+### System-wide installation
+
+    $ gem install activity_permission_engine
+
+## Usage
+
+### Configure
+
+You need a persistence adapter. See [activity_permission_engine_redis](https://github.com/synbioz/activity_permission_engine_redis)
+
+```ruby
+ActivityPermissionEngine.configure do |config|
+  config.activity_permissions_registry =  # Provide the persistence adapter choose from existing ones around the web or create yours
+  config.activities = ['accounting:payments:register','accounting:accounts:read'] # Optional. The list of activities, can be provided at run time.
+end
+```
+
+### Roles refs and activities refs
+
+This library does not make assumptions upon roles except that they should be strings.
+We do recommend to use business role from the organization chart.
+
+eg : 'accounting:payment:register' may be allowed to 'accountant' and/or 'sales_executive'
+'person:update_profile' maybe to 'it_staff:administrator'
+
+But keep in mind to only use references (not database id). References do not changes and are easy to translate in user readable values.
+( with I18n if you wish )
+
+
+### Manage activities
+
+Activities are part of code and rely on code, they can not persist they are refreshed at each application start.
+
+eg:  'accounting:payment:register' or 'person:update_profile'
+
+Activities can be provided at configuration time or run time. It's up to you to choose / mix strategies.
+
+At run time you may want to create helper method that register the activity once the file is required.
+At configuration time you'll likely maintain a file that contains all the activity refs.
+
+
+#### Register an activity
+
+`ActivityPermissionEngine.register_activity(#activity_ref)`
+
+Given an activity_ref
+It will add the activity_ref ( basically a string ) within the activities store.
+
+```ruby
+ActivityPermissionEngine.register_activity('accounting:payments:register')
+#=> #<ActivityPermissionEngine::RegisterActivity::Response:0x0055c7cdc90f00 @success=true>
+```
+
+#### List activities
+
+`ActivityPermissionEngine.list_activities`
+
+Returns the list of activities. You'll need this to provide in your UI the list of activities.
+The user should then allow role to perform activities.
+
+```ruby
+ActivityPermissionEngine.list_activities
+#=> #<ActivityPermissionEngine::ListActivities::Response:0x0055c7cdc78d38 @activity_refs=["accounting:payments:register"]>
+```
+
+
+### Activity permissions
+
+Activities permissions are persisted ( if you set the correct adapter ).
+This data structure holds the role_ref allowed to perform an activity_ref
+
+#### Allow role to perform activity
+
+To allow a role to perform an activity use
+
+`ActivityPermissionEngine.allow_activity(activity_ref, role_ref)`
+
+
+```ruby
+ActivityPermissionEngine.allow_activity('accounting:payments:register', 'accountant')
+#=> #<ActivityPermissionEngine::AllowActivity::Response:0x0055c7cdc63938 @success=["accountant"]>
+
+ActivityPermissionEngine.allow_activity('accounting:payments:register', 'sales:executives')
+#=> #<ActivityPermissionEngine::AllowActivity::Response:0x0055c7cdc42828 @success=["accountant", "sales:executives"]>
+```
+
+#### Disallow role to perform activity
+
+To disallow a role to perform an activity use
+
+`ActivityPermissionEngine.disallow_activity(activity_ref, role_ref)`
+
+```ruby
+ActivityPermissionEngine.disallow_activity('accounting:payments:register', 'sales:executives')
+#=> #<ActivityPermissionEngine::DisallowActivity::Response:0x0055c7cdc10c88 @success=["accountant"]
+```
+
+#### List existing permissions
+
+A permission exists once you allow a user to perform an activity.
+
+Use
+
+`ActivityPermissionEngine.list_activities_permissions` to get a full list of existing activity permissions.
+
+It returns a Response object that respond to `#activities_permissions` and returns an Array of activities permissions.
+
+```ruby
+response = ActivityPermissionEngine.list_activities_permissions
+#=> #<ActivityPermissionEngine::ListActivitiesPermissions::Response:0x0055c7cdbe4278 @activities_permissions=[#<ActivityPermissionEngine::ActivityPermissionsRegistry::ActivityPermission:0x0055c7cdbe42a0 @activity_ref="accounting:payments:register", @role_refs=["accountant"]>]>
+response.activities_permissions
+#=> [#<ActivityPermissionEngine::ActivityPermissionsRegistry::ActivityPermission:0x0055c7cdbe42a0 @activity_ref="accounting:payments:register", @role_refs=["accountant"]>]
+```
+
+### Authorization check
+
+To check for authorization you will use `ActivityPermissionEngine.check_authorization(#activity_ref, #role_refs)`
+The request must respond to role_refs with an array, since most of the time a user can have many roles.
+It only needs a single matching one to be authorized.
+
+```ruby
+response = ActivityPermissionEngine.check_authorization('accounting:payments:register',['accountant'])
+#=> #<ActivityPermissionEngine::CheckAuthorization::Response:0x0055c7cdb95600 @authorized=true>
+response.authorized?
+#=> true
+```
+
+### Request objects
+
+You are free to not use the request objects like `ActivityPermissionEngine::AllowActivity::Request`
+You just need to supply an object that respond to the same methods like a struct.
+
+But I think it could be wise to use it in order to ensure API compliance and forward compatibility.
+By the way they are readonly data structures.
+
+## Contributing
+
+1. Fork it ( https://github.com/synbioz/activity_permission_engine/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,6 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new do |tt|
+  tt.test_files = FileList['test/**/*_test.rb']
+end

data/activity_permission_engine.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'activity_permission_engine/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "activity_permission_engine"
+  spec.version       = ActivityPermissionEngine::VERSION
+  spec.authors       = ["Cedric Brancourt", "Synbioz"]
+  spec.email         = ["cedric.brancourt@gmail.com", "opensource@synbioz.com"]
+  spec.summary       = %q{Simple library to manage permissions}
+  spec.description   = %q{Allow you to map roles to activities and to check for allowance}
+  spec.homepage      = "https://github.com/synbioz/activity_permission_engine"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.8"
+  spec.add_development_dependency "simplecov", "~> 0.11"
+end

data/lib/activity_permission_engine.rb

@@ -0,0 +1,47 @@
+require_relative 'activity_permission_engine/version'
+require_relative 'activity_permission_engine/interface_helpers'
+require_relative 'activity_permission_engine/framework/request'
+require_relative 'activity_permission_engine/register_activity'
+require_relative 'activity_permission_engine/list_activities'
+require_relative 'activity_permission_engine/unregister_activity'
+require_relative 'activity_permission_engine/allow_activity'
+require_relative 'activity_permission_engine/disallow_activity'
+require_relative 'activity_permission_engine/check_authorization'
+require_relative 'activity_permission_engine/activities_registry'
+require_relative 'activity_permission_engine/adapters/activity_permissions_registry/memory'
+require_relative 'activity_permission_engine/list_activities_permissions'
+
+module ActivityPermissionEngine
+  extend InterfaceHelpers
+
+  class << self
+    attr_accessor :configuration
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+
+  class Configuration
+    def initialize(options={})
+      @activity_permissions_registry = options.fetch(:activity_permissions_registry, Defaults.activities_permissions_registry)
+      @activities = options.fetch(:activities, [])
+    end
+
+    attr_accessor :activity_permissions_registry, :activities
+
+    def activities_registry
+      @activities_registry ||= ActivitiesRegistry.new(activities)
+    end
+  end
+
+  module Defaults
+    def self.activities_permissions_registry
+      Adapters::ActivityPermissionsRegistry::Memory.new
+    end
+  end
+end

data/lib/activity_permission_engine/activities_registry.rb

@@ -0,0 +1,20 @@
+module ActivityPermissionEngine
+  class ActivitiesRegistry
+    def initialize(activities)
+      @activities = activities
+    end
+
+    def all
+      activities
+    end
+
+    def add(activity_refs)
+      activities << activity_refs
+      activities.uniq!
+      true
+    end
+
+    private
+    attr_accessor(:activities)
+  end
+end

data/lib/activity_permission_engine/activity_permissions_registry.rb

@@ -0,0 +1,59 @@
+module ActivityPermissionEngine
+  module ActivityPermissionsRegistry
+    # Include this module in adapters to provide expected behavior
+    module Interface
+
+      # @param [String] activity_ref
+      # @return [Boolean] true if added or false
+      def add(activity_ref)
+        raise NotImplementedError
+      end
+
+      # @return [Array(ActivityPermission)]
+      def all
+        get_all_activities.map { |activity| ActivityPermission.new(activity[:activity_ref], activity[:role_refs])}
+      end
+
+      # @param [String] activity_ref
+      # @return [Boolean] true if deleted or false
+      def del(activity_ref)
+        raise NotImplementedError
+      end
+
+      # @param [String] activity_ref
+      # @param [Array(String)] role_ref
+      # @return [Boolean] true if added or false
+      def add_role(activity_ref, role_ref)
+        raise NotImplementedError
+      end
+
+      # @param [String] activity_ref
+      # @return [ActivityPermission] the found activity or false
+      def find_by_activity_ref(activity_ref)
+        activity = get_activity_by_ref(activity_ref)
+        activity && ActivityPermission.new(activity[:activity_ref], activity[:role_refs])
+      end
+
+      private
+
+      # @return [Array(Hash{Symbol => String})]
+      def get_all_activities
+        raise NotImplementedError
+      end
+
+      # @return [Hash{Symbol => String}] {activity_ref: '', role_refs: ''}
+      def get_activity_by_ref(activity_ref)
+        raise NotImplementedError
+      end
+    end
+
+    class ActivityPermission
+      def initialize(activity_ref, role_refs)
+        @activity_ref = activity_ref
+        @role_refs = role_refs
+      end
+
+      attr_reader(:activity_ref, :role_refs)
+    end
+  end
+end

data/lib/activity_permission_engine/adapters/activity_permissions_registry/memory.rb

@@ -0,0 +1,39 @@
+require_relative '../../activity_permissions_registry'
+
+module ActivityPermissionEngine
+  module Adapters
+    module ActivityPermissionsRegistry
+      class Memory
+        include ActivityPermissionEngine::ActivityPermissionsRegistry::Interface
+
+        def initialize(store = {})
+          @store = store
+          @store.default = []
+        end
+
+        def del(activity_ref)
+          store.delete(activity_ref)
+        end
+
+        def add_role(activity_ref, role_ref)
+          store.has_key?(activity_ref) ? store[activity_ref].push(role_ref) : store[activity_ref] = [role_ref]
+        end
+
+        def remove_role(activity_ref, role_ref)
+          store[activity_ref] = store[activity_ref] - [role_ref]
+        end
+
+        private
+        attr_reader(:store)
+
+        def get_activity_by_ref(activity_ref)
+          store.has_key?(activity_ref) ? {activity_ref: activity_ref, role_refs: store[activity_ref]} : false
+        end
+
+        def get_all_activities
+          store.map {|k,v| {activity_ref: k, role_refs: v} }
+        end
+      end
+    end
+  end
+end

data/lib/activity_permission_engine/allow_activity.rb

@@ -0,0 +1,38 @@
+module ActivityPermissionEngine
+  class AllowActivity
+    def initialize(request, activities_registry = ActivityPermissionEngine.configuration.activity_permissions_registry)
+      @request = request
+      @activities_registry = activities_registry
+    end
+
+
+    def call
+      Response.new(activities_registry.add_role(request.activity_ref, request.role_ref))
+    end
+
+    private
+    attr_reader(:request, :activities_registry)
+
+    class Request
+      include Framework::Request
+      def initialize(activity_ref, role_ref)
+        @activity_ref = activity_ref
+        @role_ref = role_ref
+      end
+      attr_reader(:activity_ref, :role_ref)
+    end
+
+    class Response
+      def initialize(success)
+        @success = success
+      end
+
+      def success?
+        success
+      end
+
+      private
+      attr_reader(:success)
+    end
+  end
+end