arrthorizer 0.1.1 → 0.1.2

data/README.md

@@ -1,9 +1,15 @@
 [![Code Climate](https://codeclimate.com/github/BUS-OGD/arrthorizer.png)](https://codeclimate.com/github/BUS-OGD/arrthorizer)
 [![Build Status](https://travis-ci.org/BUS-OGD/arrthorizer.png)](https://travis-ci.org/BUS-OGD/arrthorizer)
+[![Dependency Status](https://gemnasium.com/BUS-OGD/arrthorizer.png)](https://gemnasium.com/BUS-OGD/arrthorizer)
+[![Gem Version](http://badge.fury.io/rb/arrthorizer.png)](http://badge.fury.io/rb/arrthorizer)
 
 # Arrthorizer
 
-TODO: Write a gem description
+Dynamic and static access control for your Rails (3+) application. Arrthorizer revolves around the concept of static roles (some kind of 'groups' the user can be a member of) and dynamic roles (detecting the relation the user has to the current context, like 'the writer of this blog post').
+
+Arrthorizer is flexible and allows you to inject much of your own application logic into your authorization subsystem. It allows (that is, *requires*) you to determine which elements of a context are relevant for authorization and accepts your logic for determining whether a given user is part of a certain group.
+
+Arrthorizer is [designed for ease of use and configurability](https://github.com/BUS-OGD/arrthorizer/wiki/Desired-and-required-features). Its Rails version (currently the *only* version) comes bundled with some useful generators and most of the configuration is done using a DSL in your controllers, along with a plain old YAML file.
 
 ## Installation
 
@@ -18,10 +24,22 @@ And then execute:
 Or install it yourself as:
 
     $ gem install arrthorizer
+    
+### Rails
+
+After the above installation, run:
+
+    $ bin/rails g arrthorizer:install
 
 ## Usage
 
-TODO: Write usage instructions here
+After using the `arrthorizer:install` generator, your `git diff` will tell you everything you need to know. *Read the comments* to understand what you need to do to make it work.
+
+When new ContextRoles are required later on, [Arrthorizer provides a generator for that](https://github.com/BUS-OGD/arrthorizer/wiki/HOWTO:-Write-a-ContextRole), too:
+
+    $ bin/rails g arrthorizer:context_role {namespace_if_you_need_it/role_name}
+    
+This will generate a file containing the scaffold for the ContextRole and a couple of test cases for your test framework.
 
 ## Contributing
 

data/lib/arrthorizer.rb

@@ -44,4 +44,8 @@ module Arrthorizer
   def self.membership_service
     @membership_service
   end
+
+  if defined?(RSpec)
+    require 'arrthorizer/rspec'
+  end
 end

data/lib/arrthorizer/rails/controller_action.rb

@@ -3,6 +3,7 @@ module Arrthorizer
     class ControllerAction
       ControllerNotDefined = Class.new(Arrthorizer::ArrthorizerException)
       ActionNotDefined = Class.new(Arrthorizer::ArrthorizerException)
+      ActionNotConfigured = Class.new(Arrthorizer::ArrthorizerException)
 
       attr_accessor :privilege
       attr_reader :controller_path, :action_name
@@ -31,6 +32,8 @@ module Arrthorizer
 
       def self.fetch(key)
         registry.fetch(key)
+      rescue Arrthorizer::Registry::NotFound
+        raise ActionNotConfigured, "No privileges granted for #{key}"
       end
 
       def self.register(controller_action)

data/lib/arrthorizer/rails/controller_concern.rb

@@ -6,6 +6,11 @@ module Arrthorizer
       included do
       protected
         class_attribute :arrthorizer_configuration, instance_writer: false
+        class_attribute :arrthorizer_scope, instance_writer: false
+
+        def arrthorizer_scope
+          send(self.class.arrthorizer_scope || :current_user)
+        end
 
         ##
         # This is a hook method that provides access to the context for a
@@ -23,9 +28,16 @@ module Arrthorizer
         def authorize
           action = Arrthorizer::Rails::ControllerAction.get_current(self)
           roles = action.privilege.permitted_roles
+          scope = arrthorizer_scope
 
           roles.any? do |role|
-            role.applies_to_user?(current_user, arrthorizer_context)
+            begin
+              role.applies_to_user?(scope, arrthorizer_context)
+            rescue StandardError
+              ::Rails.logger.warn("Error occurred while evaluating #{role} for #{current_user}.\nCurrent context: #{arrthorizer_context.inspect}")
+
+              false
+            end
           end || forbidden
         end
 
@@ -39,6 +51,15 @@ module Arrthorizer
       end
 
       module ClassMethods
+        ##
+        # This method tells Arrthorizer the name of the method that it is supposed
+        # to use to find the user who is currently attempting to use a certain
+        # controller action. This user is subsequently passed into all role
+        # verifications.
+        def authorization_scope(scope)
+          self.arrthorizer_scope = scope
+        end
+
         ##
         # This method sets up Arrthorizer to verify that a user has the proper
         # rights to access a # given controller action. Options can be provided

data/lib/arrthorizer/rspec.rb

@@ -0,0 +1,16 @@
+require 'rspec/expectations'
+
+module Arrthorizer
+  module RSpec
+    autoload :Matchers,   'arrthorizer/rspec/matchers'
+  end
+
+  ::RSpec.configure do |config|
+    config.include Arrthorizer::RSpec::Matchers::Roles, {
+      type: :role,
+      example_group: { file_path: %r(spec/roles) }
+    }
+  end
+end
+
+

data/lib/arrthorizer/rspec/matchers.rb

@@ -0,0 +1,46 @@
+require 'rspec/expectations'
+
+module Arrthorizer
+  module RSpec
+    module Matchers
+      module Roles
+        class AppliesToUser
+          def initialize(user)
+            @user = user
+          end
+
+          def matches?(role)
+            @role = role
+
+            role.applies_to_user?(user, context)
+          end
+
+          def failure_message
+            "Expected role #{@role.name} to apply in context #{context.inspect}\nfor user #{user.inspect}, but it does not apply!"
+          end
+
+          def negative_failure_message
+            "Expected role #{@role.name} not to apply in context #{context.inspect}\nfor user #{user.inspect}, but it applies!"
+          end
+
+          def with_context(hash)
+            @context = to_context(hash)
+
+            self
+          end
+
+        protected
+          attr_accessor :context, :user
+
+          def to_context(context_hash)
+            Arrthorizer::Context.new(context_hash)
+          end
+        end
+
+        def apply_to_user(user, context = {})
+          AppliesToUser.new(user).with_context(context)
+        end
+      end
+    end
+  end
+end

data/lib/arrthorizer/version.rb

@@ -1,3 +1,3 @@
 module Arrthorizer
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/lib/generators/arrthorizer/context_role/USAGE

@@ -0,0 +1,14 @@
+Description:
+    Generate a template for a new Arrthorizer::ContextRole
+
+Example:
+    rails generate context_role forum/post_author
+
+    This will create:
+        app/roles/forum/post_author.rb
+
+    and a unit test file for the new role, depending
+    on your framework:
+        rspec: spec/roles/forum/post_author_spec.rb
+        test_unit: test/roles/forum/post_author_test.rb
+        mini_test: test/roles/forum/post_author_test.rb

data/lib/generators/arrthorizer/context_role/context_role_generator.rb

@@ -0,0 +1,9 @@
+class Arrthorizer::ContextRoleGenerator < Rails::Generators::NamedBase
+  source_root File.expand_path('../templates', __FILE__)
+
+  def create_role
+    template "role.rb", "app/roles/#{name}.rb"
+  end
+
+  hook_for :test_framework
+end

data/lib/generators/arrthorizer/context_role/templates/role.rb

@@ -0,0 +1,16 @@
+<% inner = capture do -%>
+class <%= file_name.camelize %> < Arrthorizer::ContextRole
+  def applies_to_user?(user, context)
+    # TODO: insert logic here
+    false
+  end
+end
+<% end -%>
+<% regular_class_path.reverse.map do |mod| -%>
+<%  inner = capture do -%>
+module <%= mod.camelize %>
+<%= indent(inner,2) -%>
+end
+<% end -%>
+<% end -%>
+<%= inner %>

data/lib/generators/arrthorizer/install/install_generator.rb

@@ -13,10 +13,19 @@ module Arrthorizer
 
       def activate_filter
         insert_into_file 'app/controllers/application_controller.rb', filter_code, after: /class ApplicationController.*$/
+        insert_into_file 'app/controllers/application_controller.rb', scope_code, after: /class ApplicationController.*$/
         insert_into_file 'app/controllers/application_controller.rb', context_preparation_code, before: /end$\s*\z/
       end
 
     protected
+      def scope_code
+        <<-SCOPE_CODE
+  # Tell Arrthorizer how to find the user who needs to be authorized to execute
+  # a given controller action
+  authorization_scope :current_user
+        SCOPE_CODE
+      end
+
       def filter_code
         <<-FILTER_CODE
 

data/lib/generators/mini_test/context_role/context_role_generator.rb

@@ -0,0 +1,11 @@
+module MiniTest
+  module Generators
+    class ContextRoleGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path('../templates', __FILE__)
+
+      def unit_test
+        template "role_test.rb", "test/roles/#{name}_test.rb"
+      end
+    end
+  end
+end

data/lib/generators/mini_test/context_role/templates/role_test.rb

@@ -0,0 +1,62 @@
+require 'test_helper'
+
+class <%= class_name %>Test < ActiveSupport::TestCase
+  def user
+    @user ||= OpenStruct.new
+  end
+
+  def context_hash
+    @context_hash ||= {}
+  end
+
+  def current_context
+    Arrthorizer::Context.new(context_hash)
+  end
+
+  def role
+    <%= class_name %>
+  end
+
+  def make_role_apply!
+    # TODO: make the changes to the context_hash that make the role
+    # apply to the user
+  end
+
+  def make_role_not_apply!
+    # TODO: make the changes to the context_hash that make the role
+    # *not* apply to the user
+  end
+
+  def test_returns_true_when_some_context
+    make_role_apply!
+
+    failure_message = "Expected #{role} to apply when context = #{current_context}"
+    assert role.applies_to_user?(user, current_context), failure_message
+  end
+
+  def test_returns_false_when_some_other_context
+    make_role_not_apply!
+
+    failure_message = "Expected #{role} not_to apply when context = #{current_context}"
+    refute role.applies_to_user?(user, current_context), failure_message
+  end
+
+  def test_when_true_no_state_is_maintained_in_instance
+    make_role_apply!
+
+    role.applies_to_user?(user, current_context)
+    ivars = role.instance.instance_variables
+
+    failure_message = "Expected apply_to_user? not to change state for #{role} (on instance), but it did"
+    assert_empty ivars, failure_message
+  end
+
+  def test_when_false_no_state_is_maintained_in_instance
+    make_role_not_apply!
+
+    failure_message = "Expected apply_to_user? not to change state for #{role} (on instance), but it did"
+    ivars = role.instance.instance_variables
+
+    assert_empty ivars, failure_message
+  end
+end

data/lib/generators/rspec/context_role/context_role_generator.rb

@@ -0,0 +1,11 @@
+module Rspec
+  module Generators
+    class ContextRoleGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path('../templates', __FILE__)
+
+      def unit_test
+        template "role_spec.rb", "spec/roles/#{name}_spec.rb"
+      end
+    end
+  end
+end

data/lib/generators/rspec/context_role/templates/role_spec.rb

@@ -0,0 +1,53 @@
+require 'spec_helper'
+
+describe <%= class_name %> do
+  subject(:role) { <%= class_name %> }
+
+  let(:user) { double(:user) }
+
+  let(:context_hash) { { } }
+  let(:current_context) { Arrthorizer::Context.new(context_hash) }
+
+  describe :applies_to_user? do
+    context "when some_condition" do
+      before :each do
+        # TODO: Add the required elements to the context_hash to make the ContextRole apply to the user
+      end
+
+      it "returns true" do
+        pending
+
+        expect(role.applies_to_user?(user, current_context)).to be_true
+      end
+
+      # This is an extremely important test - it safeguards against
+      # persisting data between requests.
+      specify "no state is maintained in the role object" do
+        role.applies_to_user?(user, current_context)
+
+        role.instance.instance_variables.should be_empty
+      end
+    end
+
+    context "when some_other_condition" do
+      before :each do
+        # TODO: Add the required elements to the context_hash
+        # to make the ContextRole *not* apply to the user
+      end
+
+      it "returns false" do
+        pending
+
+        expect(role.applies_to_user?(user, current_context)).to be_false
+      end
+
+      # This is an extremely important test - it safeguards against
+      # persisting data between requests.
+      specify "no state is maintained in the role object" do
+        role.applies_to_user?(user, current_context)
+
+        role.instance.instance_variables.should be_empty
+      end
+    end
+  end
+end

data/lib/generators/test_unit/context_role/context_role_generator.rb

@@ -0,0 +1,11 @@
+module TestUnit
+  module Generators
+    class ContextRoleGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('../templates', __FILE__)
+
+      def unit_test
+        template "role_test.rb", "test/roles/#{name}_test.rb"
+      end
+    end
+  end
+end

data/lib/generators/test_unit/context_role/templates/role_test.rb

@@ -0,0 +1,61 @@
+require 'test_helper'
+
+class <%= class_name %>Test < ActiveSupport::TestCase
+  def user
+    @user ||= OpenStruct.new
+  end
+
+  def context_hash
+    @context_hash ||= {}
+  end
+
+  def current_context
+    Arrthorizer::Context.new(context_hash)
+  end
+
+  def role
+    <%= class_name %>
+  end
+
+  def make_role_apply!
+    # TODO: make the changes to the context_hash that make the role
+    # apply to the user
+  end
+
+  def make_role_not_apply!
+    # TODO: make the changes to the context_hash that make the role
+    # *not* apply to the user
+  end
+
+  test "returns true when some context" do
+    make_role_apply!
+
+    failure_message = "Expected #{role} to apply when context = #{current_context}"
+    assert role.applies_to_user?(user, current_context), failure_message
+  end
+
+  test "returns false when some other context" do
+    make_role_not_apply!
+
+    failure_message = "Expected #{role} not_to apply when context = #{current_context}"
+    assert !role.applies_to_user?(user, current_context), failure_message
+  end
+
+  test "when true no state is maintained in role" do
+    make_role_apply!
+
+    role.applies_to_user?(user, current_context)
+
+    failure_message = "Expected apply_to_user? not to change state for #{role} (on instance), but it did"
+    assert_empty role.instance.instance_variables, failure_message
+  end
+
+  test "when false no state is maintained in role" do
+    make_role_not_apply!
+
+    role.applies_to_user?(user, current_context)
+
+    failure_message = "Expected apply_to_user? not to change state for #{role} (on instance), but it did"
+    assert_empty role.instance.instance_variables, failure_message
+  end
+end

data/spec/rails/controller_action/get_current_spec.rb

@@ -0,0 +1,21 @@
+require 'spec_helper'
+
+describe Arrthorizer::Rails::ControllerAction do
+  describe :get_current do
+    let(:controller) { double('controller') }
+
+    before :each do
+      Arrthorizer::Rails::ControllerAction.stub(:key_for).with(controller).and_return("controller#action")
+    end
+
+    context "when there is no configuration for the current action" do
+      let(:expected_error) { Arrthorizer::Rails::ControllerAction::ActionNotConfigured }
+
+      specify "an ActionNotConfigured exception is raised" do
+        expect {
+          Arrthorizer::Rails::ControllerAction.get_current(controller)
+        }.to raise_error(expected_error)
+      end
+    end
+  end
+end

data/spec/rails/controller_concern/authorization_scope_spec.rb

@@ -0,0 +1,30 @@
+require 'spec_helper'
+
+describe Arrthorizer::Rails::ControllerConcern do
+  describe :authorization_scope do
+    let(:controller) { SomeController.new }
+
+    context "when no scope is explicitly configured" do
+      specify "the default of :current_user is tried" do
+        expect(controller).to receive(:current_user)
+
+        controller.send(:arrthorizer_scope)
+      end
+
+      context "when a different scope is explicitly configured" do
+        let(:controller_class) { Class.new(SomeController) }
+        let(:controller)       { controller_class.new }
+
+        before :each do
+          controller_class.authorization_scope :some_other_method
+        end
+
+        specify "that scope is used for authorization" do
+          expect(controller).to receive(:some_other_method)
+
+          controller.send(:arrthorizer_scope)
+        end
+      end
+    end
+  end
+end

data/spec/rails/controller_concern/authorize_spec.rb

@@ -107,6 +107,44 @@ describe Arrthorizer::Rails::ControllerConcern do
             end
           end
         end
+
+        context "but evaluating the role raises any kind of StandardError" do
+          before do
+            role.stub(:applies_to_user?).with(current_user, context).and_raise("Some exception")
+          end
+
+          specify "a warning is logged" do
+            # for testing purposes. We're testing a filter here, so no request exists, causing #status= to fail
+            controller.stub(:forbidden)
+
+            expect(::Rails.logger).to receive(:warn).with(an_instance_of(String))
+
+            controller.send(:authorize)
+          end
+
+          context "but more roles are provided access" do
+            let(:another_role){ Arrthorizer::Group.new("some other role") }
+
+            before :each do
+              another_role.stub(:applies_to_user?).and_return(true)
+              permitted_roles.add(another_role)
+            end
+
+            specify "those roles are checked next" do
+              expect(another_role).to receive(:applies_to_user?)
+
+              controller.send(:authorize)
+            end
+          end
+
+          context "and no other roles are provided access" do
+            specify "a #forbidden handler is triggered" do
+              expect(controller).to receive(:forbidden)
+
+              controller.send(:authorize)
+            end
+          end
+        end
       end
     end
   end

data/spec/rails/controller_configuration/for_action_spec.rb

@@ -0,0 +1,21 @@
+require "spec_helper"
+
+describe Arrthorizer::Rails::ControllerConfiguration do
+  let(:config) { Arrthorizer::Rails::ControllerConfiguration.new do end }
+
+  describe :for_action do
+    context "when multiple actions are provided" do
+      let(:actions) { [:show, :index] }
+
+      it "calls add_action_block with each of those actions" do
+        actions.each do |action|
+          expect(config).to receive(:add_action_block).with(action)
+        end
+
+        config.for_action *actions do
+          {}
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: arrthorizer
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-20 00:00:00.000000000 Z
+date: 2014-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -109,10 +109,21 @@ files:
 - lib/arrthorizer/registry.rb
 - lib/arrthorizer/role.rb
 - lib/arrthorizer/roles.rb
+- lib/arrthorizer/rspec.rb
+- lib/arrthorizer/rspec/matchers.rb
 - lib/arrthorizer/version.rb
+- lib/generators/arrthorizer/context_role/USAGE
+- lib/generators/arrthorizer/context_role/context_role_generator.rb
+- lib/generators/arrthorizer/context_role/templates/role.rb
 - lib/generators/arrthorizer/install/USAGE
 - lib/generators/arrthorizer/install/install_generator.rb
 - lib/generators/arrthorizer/install/templates/config.yml
+- lib/generators/mini_test/context_role/context_role_generator.rb
+- lib/generators/mini_test/context_role/templates/role_test.rb
+- lib/generators/rspec/context_role/context_role_generator.rb
+- lib/generators/rspec/context_role/templates/role_spec.rb
+- lib/generators/test_unit/context_role/context_role_generator.rb
+- lib/generators/test_unit/context_role/templates/role_test.rb
 - spec/arrthorizer_exception/inner_spec.rb
 - spec/context/equals_spec.rb
 - spec/context/merge_spec.rb
@@ -156,13 +167,16 @@ files:
 - spec/privilege/initialize_spec.rb
 - spec/privilege/make_accessible_to_spec.rb
 - spec/rails/.gitkeep
+- spec/rails/controller_action/get_current_spec.rb
 - spec/rails/controller_action/initialize_spec.rb
 - spec/rails/controller_action/key_for_spec.rb
 - spec/rails/controller_action/to_key_spec.rb
 - spec/rails/controller_concern/arrthorizer_context_spec.rb
+- spec/rails/controller_concern/authorization_scope_spec.rb
 - spec/rails/controller_concern/authorize_spec.rb
 - spec/rails/controller_concern/integration_spec.rb
 - spec/rails/controller_concern/to_prepare_context_spec.rb
+- spec/rails/controller_configuration/for_action_spec.rb
 - spec/rails/controller_configuration/initialize_spec.rb
 - spec/role/get_spec.rb
 - spec/role/shared_examples/finding_the_right_role.rb
@@ -180,15 +194,21 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: -2335547421098657015
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: -2335547421098657015
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.23
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: Contextual authorization for your Rails (3+) application
@@ -236,13 +256,16 @@ test_files:
 - spec/privilege/initialize_spec.rb
 - spec/privilege/make_accessible_to_spec.rb
 - spec/rails/.gitkeep
+- spec/rails/controller_action/get_current_spec.rb
 - spec/rails/controller_action/initialize_spec.rb
 - spec/rails/controller_action/key_for_spec.rb
 - spec/rails/controller_action/to_key_spec.rb
 - spec/rails/controller_concern/arrthorizer_context_spec.rb
+- spec/rails/controller_concern/authorization_scope_spec.rb
 - spec/rails/controller_concern/authorize_spec.rb
 - spec/rails/controller_concern/integration_spec.rb
 - spec/rails/controller_concern/to_prepare_context_spec.rb
+- spec/rails/controller_configuration/for_action_spec.rb
 - spec/rails/controller_configuration/initialize_spec.rb
 - spec/role/get_spec.rb
 - spec/role/shared_examples/finding_the_right_role.rb