authority 2.2.0 → 2.3.0

data/CHANGELOG.markdown

@@ -1,5 +1,11 @@
 # Changelog
 
+## v2.3.0
+
+- Added generic `current_user.can?(:mimic_lemurs)` for cases where there is no resource to work with. This calls a corresponding class method on `ApplicationAuthorizer`, like `ApplicationAuthorizer.can_mimic_lemurs?`.
+- Renamed `authority_action` to `authority_actions` (plural) to reflect the fact that you can set multiple actions at once. Use of the old method will raise a deprecation warning.
+- Lots of test cleanup so that test output is clearer - run rspec with `--format doc --order default` to see it.
+
 ## v2.2.0
 
 Allow passing options hash to `authorize_action_for`, like `authorize_action_for(@llama, :sporting => @hat_style)`.

data/Gemfile

@@ -3,4 +3,4 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in authority.gemspec
 gemspec
 
-gem 'rspec', '>= 2.8.0'
+gem 'rspec', '>= 2.12.0'

data/README.markdown

@@ -7,7 +7,8 @@ Authority will work fine with a standalone app or a single sign-on system. You c
 It requires that you already have some kind of user object in your application, accessible from all controllers and views via a method like `current_user` (configurable).
 
 [![Build Status](https://secure.travis-ci.org/nathanl/authority.png?branch=master)](http://travis-ci.org/nathanl/authority)
-[![Dependency Status](https://gemnasium.com/nathanl/authority.png)](https://gemnasium.com/nathanl/authority)
+<!-- [![Dependency Status](https://gemnasium.com/nathanl/authority.png)](https://gemnasium.com/nathanl/authority) -->
+[![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/nathanl/authority)
 
 ## Contents
 
@@ -29,6 +30,7 @@ It requires that you already have some kind of user object in your application,
     <li><a href="#controllers">Controllers</a></li>
     <li><a href="#views">Views</a></li>
   </ul></li>
+  <li><a href="#the_generic_can">The Generic `can?`</a>
   <li><a href="#security_violations_and_logging">Security Violations &amp; Logging</a></li>
   <li><a href="#credits">Credits</a></li>
   <li><a href="#contributing">Contributing</a></li>
@@ -45,8 +47,9 @@ Using Authority, you have:
 - Fine-grained, **instance-level** rules. Examples: 
   - "Management users can only edit schedules with date ranges in the future."
   - "Users can't create playlists more than 20 songs long unless they've paid."
-- A clear syntax for permissions-based views. Example:
+- A clear syntax for permissions-based views. Examples:
   - `link_to 'Edit Widget', edit_widget_path(@widget) if current_user.can_update?(@widget)`
+  - `link_to 'Keelhaul Scallywag', keelhaul_scallywag_path(@scallywag) if current_user.can_keelhaul?(@scallywag)`
 - Graceful handling of access violations: by default, it displays a "you can't do that" screen and logs the violation.
 - Minimal effort and mess.
 
@@ -265,12 +268,12 @@ describe AdminAuthorizer do
   end
 
   describe "class" do
-    it "should let admins update in bulk" do
-      AdminAuthorizer.should be_bulk_updatable_by(@admin)
+    it "lets admins update in bulk" do
+      expect(AdminAuthorizer).to be_bulk_updatable_by(@admin)
     end
 
-    it "should not let users update in bulk" do
-      AdminAuthorizer.should_not be_bulk_updatable_by(@user)
+    it "doesn't let users update in bulk" do
+      expect(AdminAuthorizer).not_to be_bulk_updatable_by(@user)
     end
   end
 
@@ -281,12 +284,12 @@ describe AdminAuthorizer do
       @admin_resource_instance = mock_admin_resource
     end
 
-    it "should let admins delete" do
-      @admin_resource_instance.authorizer.should be_deletable_by(@admin)
+    it "lets admins delete" do
+      expect(@admin_resource_instance.authorizer).to be_deletable_by(@admin)
     end
 
-    it "should not let users delete" do
-      @admin_resource_instance.authorizer.should_not be_deletable_by(@user)
+    it "doesn't let users delete" do
+      expect(@admin_resource_instance.authorizer).not_to be_deletable_by(@user)
     end
 
   end
@@ -326,7 +329,8 @@ class LlamasController < ApplicationController
   authorize_actions_for Llama, :except => :create, :actions => {:neuter => :update},
   
   # To authorize this controller's 'breed' action, ask whether `current_user.can_create?(Llama)`
-  authority_action :breed => 'create'
+  # To authorize its 'vaporize' action, ask whether `current_user.can_delete?(Llama)`
+  authority_actions :breed => 'create', :vaporize => 'delete'
 
   ...
 
@@ -360,6 +364,17 @@ link_to 'Edit Widget', edit_widget_path(@widget) if current_user.can_update?(@wi
 
 If the user isn't allowed to edit widgets, they won't see the link. If they're nosy and try to hit the URL directly, they'll get a [Security Violation](#security_violations_and_logging) from the controller.
 
+<a name="the_generic_can">
+## The Generic `can?`
+
+Authority is organized around protecting resources. But **occasionally** you **may** need to authorize something that has no particular resource. For that, it provides the generic `can?` method. It works like this:
+
+```ruby
+  current_user.can?(:view_stats_dashboard) # calls `ApplicationAuthorizer.can_view_stats_dashboard?`
+```
+
+Use this very sparingly, and consider it a [code smell](http://en.wikipedia.org/wiki/Code_smell). Overuse will turn your `ApplicationAuthorizer` into a junk drawer of methods. Ask yourself, "am I sure I don't have a resource for this? Should I have one?"
+
 <a name="security_violations_and_logging">
 ## Security Violations & Logging
 
@@ -407,6 +422,7 @@ Your method will be handed the `SecurityViolation`, which has a `message` method
 ## Credits, AKA 'Shout-Outs'
 
 - [adamhunter](https://github.com/adamhunter) for pairing with me on this gem. The only thing faster than his typing is his brain.
+- [kevmoo](https://github.com/kevmoo), [MP211](https://github.com/MP211), and [scottmartin](https://github.com/scottmartin) for pitching in.
 - [nkallen](https://github.com/nkallen) for writing [a lovely blog post on access control](http://pivotallabs.com/users/nick/blog/articles/272-access-control-permissions-in-rails) when he worked at Pivotal Labs. I cried sweet tears of joy when I read that a couple of years ago. I was like, "Zee access code, she is so BEEUTY-FUL!"
 - [jnunemaker](https://github.com/jnunemaker) for later creating [Canable](http://github.com/jnunemaker/canable), another inspiration for Authority.
 - [TMA](http://www.tma1.com) for employing me and letting me open source some of our code.

data/TODO.markdown

@@ -2,12 +2,11 @@
 
 ## Tests
 
-- Add tests for the generators
+- Test with Rails 4 and Ruby 2.0
 - Test `ActionController` integration
+- Add tests for the generators
 
-## Features
-
-### Use translation files
+## Structural changes
 
-- Move all user-facing messages into en.yml
-- Add other languages
+- Consider the huge change from authorizer objects to modules for permissions. This eliminates the awkwardness of "to check a resource instance, let's go instantiate an authorizer and give it this resource instance..." If we make this change, describe a detailed upgrade path.
+- Ensure that Authority can boot without the `configure` method having been run. Maybe this will mean having setters for `abilities` and `controller_action_map` that undefine and redefine those sets of methods if/when the user runs configuration.

data/lib/authority.rb

@@ -3,6 +3,7 @@ require 'active_support/core_ext/class/attribute'
 require 'active_support/core_ext/hash/keys'
 require 'active_support/core_ext/string/inflections'
 require 'logger'
+require 'authority/security_violation'
 
 module Authority
 
@@ -30,16 +31,20 @@ module Authority
   # @raise [SecurityViolation] if user is not allowed to perform action on resource
   # @return [Model] resource instance
   def self.enforce(action, resource, user, *options)
-    action_authorized = if options.empty?
-                          user.send("can_#{action}?", resource)
-                        else
-                          user.send("can_#{action}?", resource, Hash[*options])
-                        end
-    raise SecurityViolation.new(user, action, resource) unless action_authorized
-
+    unless action_authorized?(action, resource, user, *options)
+      raise SecurityViolation.new(user, action, resource) 
+    end
     resource
   end
 
+  def self.action_authorized?(action, resource, user, *options)
+    if options.empty?
+      user.send("can_#{action}?", resource)
+    else
+      user.send("can_#{action}?", resource, Hash[*options])
+    end
+  end
+
   class << self
     attr_accessor :configuration
   end
@@ -60,20 +65,6 @@ module Authority
     require 'authority/user_abilities'
   end
 
-  class SecurityViolation < StandardError
-    attr_reader :user, :action, :resource
-
-    def initialize(user, action, resource)
-      @user = user
-      @action = action
-      @resource = resource
-    end
-
-    def message
-      "#{@user} is not authorized to #{@action} this resource: #{@resource}"
-    end
-  end
-
 end
 
 require 'authority/configuration'

data/lib/authority/abilities.rb

@@ -35,7 +35,9 @@ module Authority
       def authorizer
         @authorizer ||= authorizer_name.constantize # Get an actual reference to the authorizer class
       rescue NameError
-        raise Authority::NoAuthorizerError.new("#{authorizer_name} does not exist in your application")
+        raise Authority::NoAuthorizerError.new(
+          "#{authorizer_name} is set as the authorizer for #{self}, but the constant is missing"
+        )
       end
     end
 

data/lib/authority/controller.rb

@@ -4,11 +4,6 @@ module Authority
 
     extend ActiveSupport::Concern
 
-    included do
-      rescue_from(Authority::SecurityViolation, :with => Authority::Controller.security_violation_callback)
-      class_attribute :authority_resource
-    end
-
     def self.security_violation_callback
       Proc.new do |exception|
         # Through the magic of ActiveSupport's `Proc#bind`, `ActionController::Base#rescue_from`
@@ -17,6 +12,11 @@ module Authority
       end
     end
 
+    included do
+      rescue_from(Authority::SecurityViolation, :with => Authority::Controller.security_violation_callback)
+      class_attribute :authority_resource
+    end
+
     module ClassMethods
 
       # Sets up before_filter to ensure user is allowed to perform a given controller action
@@ -26,17 +26,25 @@ module Authority
       # ones and any other options applicable to a before_filter
       def authorize_actions_for(model_class, options = {})
         self.authority_resource = model_class
-        authority_action(options[:actions] || {})
+        authority_actions(options[:actions] || {})
         before_filter :run_authorization_check, options
       end
 
       # Allows defining and overriding a controller's map of its actions to the model's authorizer methods
       #
       # @param [Hash] action_map - controller actions and methods, to be merged with existing action_map
-      def authority_action(action_map)
+      def authority_actions(action_map)
         authority_action_map.merge!(action_map.symbolize_keys)
       end
 
+      def authority_action(action_map)
+        puts "Authority's `authority_action` method has been renamed \
+        to `authority_actions` (plural) to reflect the fact that you can \
+        set multiple actions in one shot. Please update your controllers \
+        accordingly. (called from #{caller.first})".squeeze(' ')
+        authority_actions(action_map)
+      end
+
       # The controller action to authority action map used for determining
       # which Rails actions map to which authority actions (ex: index to read)
       #
@@ -49,6 +57,22 @@ module Authority
 
     protected
 
+    # To be run in a `before_filter`; ensure this controller action is allowed for the user
+    # Can be used directly within a controller action as well, given an instance or class with or
+    # without options to delegate to the authorizer.
+    #
+    # @param [Class] authority_resource, the model class associated with this controller
+    # @param [Hash] options, arbitrary options hash to forward up the chain to the authorizer
+    # @raise [MissingAction] if controller action isn't a key in `config.controller_action_map`
+    def authorize_action_for(authority_resource, *options)
+      # `action_name` comes from ActionController
+      authority_action = self.class.authority_action_map[action_name.to_sym]
+      if authority_action.nil?
+        raise MissingAction.new("No authority action defined for #{action_name}")
+      end
+      Authority.enforce(authority_action, authority_resource, authority_user, *options)
+    end
+
     # Renders a static file to minimize the chances of further errors.
     #
     # @param [Exception] error, an error that indicates the user tried to perform a forbidden action.
@@ -73,21 +97,6 @@ module Authority
       send(Authority.configuration.user_method)
     end
 
-    # To be run in a `before_filter`; ensure this controller action is allowed for the user
-    # Can be used directly within a controller action as well, given an instance or class with or
-    # without options to delegate to the authorizer.
-    #
-    # @param [Class] authority_resource, the model class associated with this controller
-    # @param [Hash] options, arbitrary options hash to forward up the chain to the authorizer
-    # @raise [MissingAction] if controller action isn't a key in `config.controller_action_map`
-    def authorize_action_for(authority_resource, *options)
-      authority_action = self.class.authority_action_map[action_name.to_sym]
-      if authority_action.nil?
-        raise MissingAction.new("No authority action defined for #{action_name}")
-      end
-      Authority.enforce(authority_action, authority_resource, authority_user, *options)
-    end
-
     class MissingAction < StandardError ; end
   end
 end

data/lib/authority/security_violation.rb

@@ -0,0 +1,15 @@
+module Authority
+  class SecurityViolation < StandardError
+    attr_reader :user, :action, :resource
+
+    def initialize(user, action, resource)
+      @user     = user
+      @action   = action
+      @resource = resource
+    end
+
+    def message
+      "#{@user} is not authorized to #{@action} this resource: #{@resource}"
+    end
+  end
+end

data/lib/authority/user_abilities.rb

@@ -20,5 +20,9 @@ module Authority
       RUBY
     end
 
+    def can?(action)
+      ApplicationAuthorizer.send("can_#{action}?", self)
+    end
+
   end
 end

data/lib/authority/version.rb

@@ -1,3 +1,3 @@
 module Authority
-  VERSION = "2.2.0"
+  VERSION = "2.3.0"
 end

data/spec/authority/abilities_spec.rb

@@ -1,44 +1,50 @@
 require 'spec_helper'
-require 'support/example_model'
-require 'support/user'
+require 'support/example_classes'
 
 describe Authority::Abilities do
 
-  before :each do
-    @user = User.new
-  end
+  let(:user)           { ExampleUser.new }
+  let(:resource_class) { ExampleResource }
 
-  describe "authorizer" do
+  describe "instance methods" do
 
-    it "should have a class attribute getter for authorizer_name" do
-      ExampleModel.should respond_to(:authorizer_name)
-    end
+    describe "authorizer_name" do
 
-    it "should have a class attribute setter for authorizer_name" do
-      ExampleModel.should respond_to(:authorizer_name=)
-    end
+      it "has a class attribute getter for authorizer_name" do
+        expect(resource_class).to respond_to(:authorizer_name)
+      end
 
-    it "should have a default authorizer_name of 'ApplicationAuthorizer'" do
-      ExampleModel.authorizer_name.should eq("ApplicationAuthorizer")
-    end
+      it "has a class attribute setter for authorizer_name" do
+        expect(resource_class).to respond_to(:authorizer_name=)
+      end
 
-    it "should constantize the authorizer name as the authorizer" do
-      ExampleModel.instance_variable_set(:@authorizer, nil)
-      ExampleModel.authorizer_name.should_receive(:constantize)
-      ExampleModel.authorizer
-    end
+      it "has a default authorizer_name of 'ApplicationAuthorizer'" do
+        expect(resource_class.authorizer_name).to eq("ApplicationAuthorizer")
+      end
 
-    it "should memoize the authorizer to avoid reconstantizing" do
-      ExampleModel.authorizer
-      ExampleModel.authorizer_name.should_not_receive(:constantize)
-      ExampleModel.authorizer
     end
 
-    it "should raise a friendly error if the authorizer doesn't exist" do
-      class NoAuthorizerModel < ExampleModel; end ;
-      NoAuthorizerModel.instance_variable_set(:@authorizer, nil)
-      NoAuthorizerModel.authorizer_name = 'NonExistentAuthorizer'
-      expect { NoAuthorizerModel.authorizer }.to raise_error(Authority::NoAuthorizerError)
+    describe "authorizer" do
+
+      it "constantizes the authorizer name as the authorizer" do
+        resource_class.instance_variable_set(:@authorizer, nil)
+        resource_class.authorizer_name.should_receive(:constantize)
+        resource_class.authorizer
+      end
+
+      it "memoizes the authorizer to avoid reconstantizing" do
+        resource_class.authorizer
+        resource_class.authorizer_name.should_not_receive(:constantize)
+        resource_class.authorizer
+      end
+
+      it "raises a friendly error if the authorizer doesn't exist" do
+        class NoAuthorizerModel < resource_class; end ;
+        NoAuthorizerModel.instance_variable_set(:@authorizer, nil)
+        NoAuthorizerModel.authorizer_name = 'NonExistentAuthorizer'
+        expect { NoAuthorizerModel.authorizer }.to raise_error(Authority::NoAuthorizerError)
+      end
+
     end
 
   end
@@ -48,24 +54,28 @@ describe Authority::Abilities do
     Authority.adjectives.each do |adjective|
       method_name = "#{adjective}_by?"
 
-      it "should respond to `#{method_name}`" do
-        ExampleModel.should respond_to(method_name)
+      it "responds to `#{method_name}`" do
+        expect(resource_class).to respond_to(method_name)
       end
 
-      describe "if given an options hash" do
+      describe "#{method_name}" do
+
+        context "when given an options hash" do
+
+          it "delegates `#{method_name}` to its authorizer class, passing the options" do
+            resource_class.authorizer.should_receive(method_name).with(user, :lacking => 'nothing')
+            resource_class.send(method_name, user, :lacking => 'nothing')
+          end
 
-        it "should delegate `#{method_name}` to its authorizer class, passing the options" do
-          ExampleModel.authorizer.should_receive(method_name).with(@user, :lacking => 'nothing')
-          ExampleModel.send(method_name, @user, :lacking => 'nothing')
         end
 
-      end
+        context "when not given an options hash" do
 
-      describe "if not given an options hash" do
+          it "delegates `#{method_name}` to its authorizer class, passing no options" do
+            resource_class.authorizer.should_receive(method_name).with(user)
+            resource_class.send(method_name, user)
+          end
 
-        it "should delegate `#{method_name}` to its authorizer class, passing no options" do
-          ExampleModel.authorizer.should_receive(method_name).with(@user)
-          ExampleModel.send(method_name, @user)
         end
 
       end
@@ -76,50 +86,55 @@ describe Authority::Abilities do
 
   describe "instance methods" do
 
+    let(:resource_instance) { resource_class.new }
+
     before :each do
-      @example_model = ExampleModel.new
-      @authorizer    = ExampleModel.authorizer.new(@example_model)
+      @authorizer = resource_class.authorizer.new(resource_instance)
     end
 
     Authority.adjectives.each do |adjective|
       method_name = "#{adjective}_by?"
 
-      it "should respond to `#{method_name}`" do
-        @example_model.should respond_to(method_name)
+      it "responds to `#{method_name}`" do
+        expect(resource_instance).to respond_to(method_name)
       end
 
-      describe "if given an options hash" do
+      describe "#{method_name}" do
+
+        context "when given an options hash" do
+
+          it "delegates `#{method_name}` to a new authorizer instance, passing the options" do
+            resource_class.authorizer.stub(:new).and_return(@authorizer)
+            @authorizer.should_receive(method_name).with(user, :with => 'mayo')
+            resource_instance.send(method_name, user, :with => 'mayo')
+          end
 
-        it "should delegate `#{method_name}` to a new authorizer instance, passing the options" do
-          ExampleModel.authorizer.stub(:new).and_return(@authorizer)
-          @authorizer.should_receive(method_name).with(@user, :with => 'mayo')
-          @example_model.send(method_name, @user, :with => 'mayo')
         end
 
-      end
+        context "when not given an options hash" do
+
+          it "delegates `#{method_name}` to a new authorizer instance, passing no options" do
+            resource_class.authorizer.stub(:new).and_return(@authorizer)
+            @authorizer.should_receive(method_name).with(user)
+            resource_instance.send(method_name, user)
+          end
 
-      describe "if not given an options hash" do
-        
-        it "should delegate `#{method_name}` to a new authorizer instance, passing no options" do
-          ExampleModel.authorizer.stub(:new).and_return(@authorizer)
-          @authorizer.should_receive(method_name).with(@user)
-          @example_model.send(method_name, @user)
         end
 
       end
 
     end
 
-    it "should provide an accessor for its authorizer" do
-      @example_model.should respond_to(:authorizer)
+    it "provides an accessor for its authorizer" do
+      expect(resource_instance).to respond_to(:authorizer)
     end
 
     # When checking instance methods, we want to ensure that every check uses a new
     # instance of the authorizer. Otherwise, you might check, make a change to the
     # model instance, check again, and get an outdated answer.
-    it "should always create a new authorizer instance when accessing the authorizer" do
-      @example_model.class.authorizer.should_receive(:new).with(@example_model).twice
-      2.times { @example_model.authorizer }
+    it "always creates a new authorizer instance when accessing the authorizer" do
+      resource_instance.class.authorizer.should_receive(:new).with(resource_instance).twice
+      2.times { resource_instance.authorizer }
     end
 
   end