kantox-roles 1.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5120829150bcbfcb385b48107800baf61da72262
+  data.tar.gz: 756e3b82936790094c8d00ed90ff16e8d0610f7c
+SHA512:
+  metadata.gz: 96fd86d02e2c44e7b51c108c4e4f9fabb0fabe306dd5b38e12f2fc40fdcefd896bf95131dc5a1ab8a9627e5a5018a0b0e41eea213021dc58f7757d828ec93891
+  data.tar.gz: 17b617b94f4df54811ca013132aae12f812cd1cb0cde138fadda24e53d03879249453069bb3bedff6acdd33fedbbd9045061b51ca0b4b66ba89215449ea078c0

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.1.1

data/Gemfile

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

data/README.md

@@ -0,0 +1,224 @@
+# Kantox::Roles
+
+Kantox Roles is the library to transparently handle an authorization. It is
+fully backend-agnostic. Current implementation contains a working example
+of pundit wrapping.
+
+The main goal is to separate the wheat from the chaff and not to pollute
+model/controller classes with authorization stuff.
+
+With Kantox Roles one is to define the rules in one or more yaml files:
+
+```yaml
+'Kantox::Managed':
+  :yo : 'aspect'
+  :yo2 : :aspect
+  :yo3 :
+    :runner: 'Kantox::Strategies::Wrapper#wrap'
+  :yo5 :
+    :lambda: '->(context, im) { 42 }'
+  :yo6 :
+    :kantox_managedhandler:
+      :params: ['param1', 'param2']
+'Kantox::WildManaged':
+  'y*' : :aspect
+```
+
+There are four different kinds of handlers available:
+
+* **simple** — like `aspect` above. There should be `Kantox::Strategies#aspect`
+module function available. It will be called with parameters `context` and
+`im` supplying the context instance (usually an instance of guarded controller
+class) and the name of the guarded method in `Module::Class#method` notation.
+The aforementioned function should _raise an exception_ of type
+`Kantox::Strategies::StrategyError` whether the authority check is not passed.
+* **runner** — the most powerful yet complicated guard. Should have the
+executable module function as parameter in `Module::Class#method` notation.
+This function will be called, yielding _`context`, `im` **and** the guarded
+method, converted to `proc`_ as parameters. The typical usage:
+
+```ruby
+def my_runner context, params = nil
+  fail Kantox::Strategies::MyRunnerError unless check_passed
+  params[:user] = :demo if demo_mode
+  params[:credit_card].gsub /\d/, 'X'
+  yield *params if block_given?
+end
+```
+
+As seen above, the full control over context is provided by this guard.
+
+* **lambda** — the simple lambda, getting `context` and `im`. Is actually
+a syntax sugar for the _simple_ guard
+* **object** — used when there is a need to pass complicated parameters and/or
+some other stuff to the guard. The class `Kantox::Managedhandler` must have
+a constructor, accepting one argument (the hash of parameters) and `to_proc`
+method, accepting two arguments (`context`, `im`). The class will be
+instantiated with a parameters list and `to_proc` would be called on context.
+
+## Methods to guard
+
+Wildcard notation is allowed. That said, `'y*'` will guard all the methods
+starting with `y`, and `'*'` will guard everything on the respective class.
+
+## Deny ⇒ Allow
+
+As soon as a method guard is specified in yaml file, the method is considered
+as guarded. If there was an error finding the guard (class not exists, method
+can not be instantiated etc,) the authorization request will be _rejected_.
+
+## Rails integration
+
+```ruby
+# controllers/admin/admin_controller.rb
+
+require 'kantox/roles'
+# Specify the top-parent class to guard
+Kantox::Roles.init Admin::AdminController
+# load strategies
+Dir['strategies/**/*.yml'].each do |f|
+  Kantox::Roles.configure f
+end
+# load stopwords for logger
+Kantox::Helpers.logger_stopwords File.join 'strategies', 'stopwords.txt'
+Kantox::Helpers.info "Strategies were read: #{Kantox::Roles.options}"
+```
+
+```ruby
+# config/application.rb
+
+# Policies are to be loaded on init explicitly
+Dir[File.expand_path('../../app/policies/**/*', __FILE__)].each do |f|
+  require f[/(.*?)\.rb$/, 1] unless File.directory? f
+end
+```
+
+```yaml
+# strategiest/roles.yml
+
+'Admin::TodosController' :
+  '*' : :pundit
+...
+```
+
+## Pundit plug-in
+
+This section shows how to integrate `pundit` to act as backend guard.
+Everything one needs is to implement policies.
+
+Everything in `TodosController` is to be handled by pundit. So, it’s time
+to implement our `pundit` guard. Besides some syntax sugar stuff it is (complete implementation for `kantox-flow` may be seen [here](https://github.com/kantox/kantox-roles/wiki/Pundit-Policy):
+
+```ruby
+# app/policies/pundit.rb
+
+def pundit context, im
+  begin # Whoever does not reply on classify would be punished :)
+    model = context.instance_eval 'controller_path.classify'
+    policy = PolicyFactory.lookup model.split('::').last
+    unless policy.new(context.current_user, model).send("#{im.split('#').last}?")
+      fail PunditError.new(context, im, policy)
+    end
+  rescue NameError => e
+    Kantox::Helpers.err "Error punditing «#{context}». Will reject request.\nOriginal error: #{e}"
+    throw PunditError.new(context, im)
+  end
+end
+module_function :pundit
+```
+Needless to say, the above handler is to be written once per backend. Pundit one is shipped with `Kantox::Roles`. The last but not least is to specify a strategy:
+
+```ruby
+# app/policies/todo_policy.rb
+
+module Kantox
+  module Policies
+      def historic?
+        @user.admin? and [true, false].sample
+      end
+      alias_method :index?, :historic?
+    end
+  end
+end
+```
+
+The above will randomly accept admin’s requests to a controller. I am pretty
+sure one would do more sophisticated check here.
+
+That’s it.
+
+## Policies Generator
+
+`Kantox::Roles` has it’s generator for creating policies.
+
+### Generator invocation
+
+```
+$ bundle exec rails generate kantox:pundit_policy Todo --users Administrator SalesPerson
+```
+
+The above will generate (assuming that `Todo` is a proper model name and `TodosController` exists:
+
+* Policy itself, in `app/policies`,
+* Spec for a policy in `spec/policies`,
+* Default strategy in `strategies`.
+* [optional] if this is a first run, the `pundit:install` generator will be invoked
+  to generate default pundit `ApplicationPolicy`.
+
+By default all the public controller methods will be guarded with `method?` pundit guards,
+returning `true` if the current user was listed during generation process.
+
+![Generate Policy](https://github.com/kantox/kantox-flow/wiki/kantox-roles-generator-1.png)
+
+### Generated specs
+
+The generator above would generate smart specs, more or less ready to use. For
+an example above, it would generate specs, checking whether _all the specified
+users are **allowed**_ to access the controller, and _all others are restricted_.
+
+![Generated Specs](https://github.com/kantox/kantox-flow/wiki/kantox-roles-generator-2.png)
+
+### Vandal-proof
+
+The generator will gracefully reject a request to damage anything as well as
+to generate policies for inexisting controller.
+
+![Vandal-proof](https://github.com/kantox/kantox-flow/wiki/kantox-roles-generator-3.png)
+
+## Installation
+
+```ruby
+gem 'kantox-roles'
+```
+
+## TODOs
+
+* generate policies and rspecs by `yaml`
+* ~~pointcuts *syntax* — DSL vs YAML/JSON~~
+* automatic *tests* for pointcuts — by adding them to descriptions
+* allow⇒deny vs **deny⇒allow**
+* ~~*supersupervisor* to change rights of supervisors~~
+* ~~*groups* with *roles*, or smth morre sophisticated? What?~~
+* ~~where to store rights? 3rd party?~~
+* *edit rights* from the interface.
+
+## Usage
+
+Add a line to `configuration` file (or explicitly by calling `Kantox::Roles.configure` with either hash, or passing a block.)
+
+Optionally, one may specify a custom handler as denoted by `:runner` key in config.
+
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, 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` to create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/kantox-roles/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,2 @@
+require "bundler/gem_tasks"
+

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "kantox/roles"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/kantox-roles.gemspec

@@ -0,0 +1,40 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'kantox/roles/version'
+
+Gem::Specification.new do |spec|
+  spec.required_ruby_version = '~> 2.1'
+
+  spec.name          = 'kantox-roles'
+  spec.version       = Kantox::Roles::VERSION
+  spec.authors       = ['Kantox LTD']
+  spec.email         = ['aleksei.matiushkin@kantox.com']
+  spec.license       = 'Kantox LTD Commercial'
+
+  spec.summary       = 'OmniRoles mechanism for Kantox Role Management'
+  spec.description   = 'Roles Management interface for virtually every backend, mostly like OmniAuth for authentication'
+  spec.homepage      = 'http://kantox.com'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(/(test|spec|features)\//) }
+  spec.bindir        = 'bin'
+  spec.executables   = spec.files.grep(/^exe\//) { |f| File.basename(f) }
+  spec.require_paths = %w(lib)
+
+  if spec.respond_to?(:metadata)
+    #    spec.metadata['allowed_push_host'] = 'http://fury.io'
+  end
+
+  spec.add_dependency 'hashie', '~> 3'
+  spec.add_dependency 'pundit'
+
+  spec.add_development_dependency 'bundler', '~> 1.7'
+  spec.add_development_dependency 'rake', '~> 10.0'
+
+  spec.add_development_dependency 'pry', '~> 0.10'
+
+  spec.add_development_dependency 'rspec', '~> 2.12'
+  spec.add_development_dependency 'cucumber', '~> 1.3'
+  spec.add_development_dependency 'yard', '~> 0'
+  #  spec.add_development_dependency 'yard-cucumber', '~> 0'
+end

data/lib/kantox/roles.rb

@@ -0,0 +1,199 @@
+require 'hashie'
+
+Dir[File.expand_path('../**/*', __FILE__)].each do |f|
+  require f[/(.*?)\.rb$/, 1] unless File.directory? f
+end
+
+module Kantox
+  LOCK_EMOJI = '🔒'
+
+  module Exceptions
+    class StandardError < ::StandardError; end
+    class NotAuthorized <   StandardError; end
+    class NotAllowed    <   NotAuthorized; end
+  end
+
+  # This error is called when a programmer was as lame as to code wrong
+  class LameError < RuntimeError ; end
+
+  module Roles
+    class << self
+      attr_reader :controller
+
+      # Main initializer. This method is to be called before any controller
+      #   is instantiated to prevent leakage of controllers handled.
+      # @param controller [Class] the class of main controller to handle
+      def init controller
+        return @controller if @controller == controller
+
+        fail LameError.new("Roles were already initialized for [#{@controller}]. Tried: [#{controller}]") \
+          unless @controller.nil? ||
+                  # The following must satisfy zeus. Zeus reloads controller class
+                  #   making a comparision to fail. This is an ugly hack to f*ck zeus.
+                  Rails.env.development? &&
+                  !ENV['ZEUS_MASTER_FD'].nil? &&
+                  @controller.name == controller.name
+
+        @controller = controller
+        if @controller.method(:inherited).owner == @controller
+          Kantox::Helpers.warn "#{controller}#inherited was already defined. Realiasing."
+          # FIXME @controller.send :alias_method, "∃inherited", :inherited
+        end
+
+        @controller.class_eval '
+          def self.inherited subclass
+            Kantox::Roles.postpone_strategies subclass
+          end
+        '
+      end
+
+      # Configures Roles by hash or yaml from string or file. Whether code block
+      #   is passed, it is processed with @options instance.
+      # @param hos [String|Hash] the input data to configure
+      def configure hos = nil
+        @options = Kantox::Helpers.merge_hash_or_string options, hos
+        yield @options if block_given?
+        # @options.select! { |_, v| v.is_a? Enumerator } # FIXME WARNING OR LIKE
+        apply_all_strategies # FIXME Do we need this?
+        @options
+      end
+
+      def apply_all_strategies
+        options.keys.each { |klazz| postpone_strategies klazz }
+      end
+
+      def postpone_strategies klazz
+        return if postponed[klazz.to_s] # FIXME FIXME FIXME
+
+        case klazz
+        when Class
+          (@postponed[klazz.to_s] = TracePoint.new(:end) do |tp|
+            if tp.self == klazz
+              apply_strategies klazz.to_s
+              Kantox::Helpers.info "Strategies successfully applied to #{klazz} (callback in inherited)."
+              tp.disable
+            end
+          end).enable
+        when String, Symbol
+          if Kernel.const_defined?(klazz)
+            apply_strategies klazz
+          else
+            (@postponed[klazz] = TracePoint.new(:end) do |tp|
+              if tp.self.name == klazz
+                apply_strategies klazz
+                Kantox::Helpers.info "Strategies successfully applied to #{klazz} (eager waiting)."
+                tp.disable
+              end
+            end).enable
+          end
+        else fail LameError.new("Postpone strategies were called with inknown parameter type [#{klazz} :: #{klazz.class}]")
+        end
+      end
+
+      def apply_strategies klazz
+        return if options[klazz].nil? # no strategies to apply
+        Kantox::Helpers.debug "Request to apply strategies to [#{klazz}]"
+
+        options[klazz].each do |m, strategies|
+          next unless Kernel.const_defined? klazz
+
+          Kernel.const_get(klazz).instance_methods.select do |im|
+            im =~ Regexp.new("\\A#{m.gsub('*', '(?:.*?)')}\\z")
+          end.each do |sim|
+            [*strategies].each do |strategy|
+              apply_strategy klazz, sim, strategy
+            end
+          end
+        end
+      end
+
+      def apply_strategy klazz, m, strategy
+        km = "#{klazz}##{m}"
+        case applied[km]
+        when :success
+          Kantox::Helpers.debug("Trying to reapply #{strategy} to #{km}. «Skipped».")
+          return
+        when NilClass, :error
+          Kantox::Helpers.debug("Will apply strategy [#{strategy}] to [#{km}]")
+        else
+          fail LameError.new
+        end
+
+        if (im = Kantox::Helpers.get_instance_method(km)).nil?
+          @applied[km] = :error
+          return
+        end
+
+        pc = patch_code im, strategy
+        patch = "
+          def #{im[:method][:name]} *args
+            begin
+              #{pc}
+            rescue Kantox::Strategies::StrategyError => e
+              Kantox::Helpers.info '«Denied #{klazz}##{m}» due to #{strategy} strategy.'
+              raise Kantox::Exceptions::NotAllowed, e.message
+            rescue Kantox::Exceptions::NotAllowed => e
+              Kantox::Helpers.info '«Denied #{klazz}##{m}» (deep) due to #{strategy} strategy.'
+              raise Kantox::Exceptions::NotAllowed, e.message
+            rescue Kantox::Exceptions::StandardError => e
+              Kantox::Helpers.catched 'Guarged «#{klazz}##{m}» throws a [kantox] exception.', e
+              raise e
+            rescue ::StandardError => e
+              Kantox::Helpers.catched 'Guarged «#{klazz}##{m}» throws a [generic] exception.', e
+              raise e
+            end
+          end
+        "
+        im[:class].send :alias_method, "∃#{im[:method][:name]}", "#{im[:method][:name]}"
+        im[:class].class_eval patch
+        applied[km] = :success
+      end
+
+      def patch_code im, strategy
+        Kantox::Helpers.debug "Strategy: #{strategy.class} :: [#{strategy}] "
+        args_as_string = im[:params][:string].empty? ? '' : '*args'
+
+        case strategy
+        when String, Symbol
+          "
+            strategy = Kantox::Helpers.get_simple_strategy('#{strategy}')
+            fail Kantox::Strategies::StrategyError(nil, '#{im[:method][:name]}') if strategy.nil?
+            strategy.call(self, '#{im[:class]}##{im[:method][:name]}', *args)
+            ∃#{im[:method][:name]} #{args_as_string}
+          "
+        when Array
+          case strategy.first.to_s
+          when 'runner'
+            "
+              strategy = Kantox::Helpers.get_#{strategy.first}_strategy('#{strategy.last}')
+              fail Kantox::Strategies::StrategyError(nil, '#{im[:method][:name]}') if strategy.nil?
+              p = self.method('∃#{im[:method][:name]}').to_proc
+              strategy.call(self, *args, &p)
+            "
+          when 'lambda'
+            "
+              strategy = Kantox::Helpers.get_#{strategy.first}_strategy('#{strategy.last}')
+              fail Kantox::Strategies::StrategyError(nil, '#{im[:method][:name]}') if strategy.nil?
+              strategy.call(self, '#{im[:class]}##{im[:method][:name]}')
+              ∃#{im[:method][:name]} #{args_as_string}
+            "
+          else
+            # Will try to instantiate the class with a given name
+            "
+              strategy = Kantox::Helpers.get_object_strategy('#{strategy.first}', '#{strategy.last}')
+              fail Kantox::Strategies::StrategyError(nil, '#{im[:method][:name]}') if strategy.nil?
+              strategy.to_proc.call(self, '#{im[:class]}##{im[:method][:name]}')
+              ∃#{im[:method][:name]} #{args_as_string}
+            "
+          end
+        else
+          fail LameError.new "Unknown strategy: #{strategy}."
+        end
+      end
+
+      def applied ; @applied ||= {} ; end
+      def postponed ; @postponed ||= {} ; end
+      def options ; @options ||= Hashie::Mash.new ; end
+    end
+  end
+end