authority 0.3.0 → 0.9.0

data/README.md

@@ -1,12 +1,10 @@
 # Authority
 
-## SUPER BETA VERSION. Stabler release coming soon.
-
 ## TL;DR
 
 No time for reading! Reading is for chumps! Here's the skinny:
 
-- Install in your Rails project
+- Install in your Rails project: add to Gemfile, `bundle`, then `rails g authority:install`
 - Put this in your controllers: `check_authorization_on YourModelNameHere` (the model that controller works with)
 - Put this in your models:  `include Authority::Abilities`
 - For each model you have, create a corresponding `YourModelNameHereAuthorizer`. For example, for `app/models/lolcat.rb`, create `app/authorizers/lolcat_authorizer.rb` with an empty class inheriting from `Authority::Authorizer`.
@@ -19,23 +17,19 @@ Still here? Reading is fun! You always knew that. Time for a deeper look at thin
 
 Authority gives you a clean and easy way to say, in your Rails app, **who** is allowed to do **what** with your models.
 
-It assumes that you already have some kind of user object in your application.
+It requires that you already have some kind of user object in your application, accessible from all controllers (like `current_user`).
 
 The goals of Authority are:
 
 - To allow broad, class-level rules. Examples: 
-  - "Basic users cannot delete **any** Widget."
+  - "Basic users cannot delete any Widget."
   - "Only admin users can create Offices."
-
 - To allow fine-grained, instance-level rules. Examples: 
-  - "Management users can only edit schedules in their jurisdiction."
+  - "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."
-
 - To provide a clear syntax for permissions-based views. Example:
-  - `link_to 'Edit Widget', edit_widget_path(@widget) if current_user.can_edit?(@widget)`
-
+  - `link_to 'Edit Widget', edit_widget_path(@widget) if current_user.can_update?(@widget)`
 - To gracefully handle any access violations: display a "you can't do that" screen and log the violation.
-
 - To do all of this **without cluttering** either your controllers or your models. This is done by letting Authorizer classes do most of the work. More on that below.
 
 ## The flow of Authority
@@ -73,89 +67,170 @@ Hooray! New files! Go look at them.
 
 ### Users
 
-Your user model (whatever you call it) should `include Authority::UserAbilities`. This defines methods like `can_edit?(resource)`, which are just nice shortcuts for `resource.editable_by?(user)`.
+Your user model (whatever you call it) should `include Authority::UserAbilities`. This defines methods like `can_update?(resource)`. These methods do nothing but pass the question on to the resource itself. For example, `resource.updatable_by?(user)`.
 
 ### Models
 
-In your models, simply `include Authority::Abilities`. This sets up both class-level and instance-level methods like `creatable_by?(user)`, etc, all of which delegate to the model's corresponding authorizer. For example, the `Rabbit` model would delegate to `RabbitAuthorizer`.
-
-### Controllers
-
-#### Basic Usage
+In your models, `include Authority::Abilities`. This sets up both class-level and instance-level methods like `creatable_by?(user)`, etc. 
 
-In your controllers, add this method call:
-
-`check_authorization_on ModelName`
-
-That sets up a `:before_filter` that calls your class-level methods before each action. For instance, before running the `update` action, it will check whether `ModelName` is `updatable_by?` the current user at a class level. A return value of false means "this user can never update models of this class."
-
-If that's all you need, one line does it.
-
-#### In-action usage
+You **could** define those methods yourself on the model, but to keep things organized, we want to put all our authorization logic in authorizer classes. Therefore, these methods, too, are pass-through, which delegate to corresponding methods on the model's authorizer. For example, the `Rabbit` model would delegate to `RabbitAuthorizer`.
 
-If you need to check some attributes of a model instance to decide if an action is permissible, you can use `check_authorization_for(:action, @model_instance, @user)`
+Which leads us to...
 
 ### Authorizers
 
-Authorizers should be added under `app/authorizers`, one for each of your models. Each authorizer should correspond to a single model. So if you have `app/models/laser_cannon.rb`, you should have, at minimum:
+Authorizers should be added under `app/authorizers`, one for each of your models. So if you have a `LaserCannon` model, you should have, at minimum:
 
     # app/authorizers/laser_cannon_authorizer.rb
     class LaserCannonAuthorizer < Authority::Authorizer
+      # Nothing defined - just use the default strategy
     end
 
 These are where your actual authorization logic goes. You do have to specify your own business rules, but Authority comes with the following baked in:
 
 - All instance-level methods defined on `Authority::Authorizer` call their corresponding class-level method by default. In other words, if you haven't said whether a user can update **this particular** widget, we'll decide by checking whether they can update **any** widget.
-- All class-level methods defined on `Authority::Authorizer` will use the `default_strategy` you define in your configuration.
-- The **default** default strategy simply returns false; you must override it in your configuration and/or write methods on your individual `Authorizer` classes to grant permissions. This whitelisting approach will keep you from accidentally allowing things you didn't intend.
+- All class-level methods defined on `Authority::Authorizer` will use the `default_strategy` you define in your configuration (see the notes in the generated file).
+- The **default** default strategy simply returns false, so unless you redefine it or write methods in your Authorizer classes, **everything is forbidden**. This whitelisting approach will keep you from accidentally allowing things you didn't intend.
 
-This combination means that, with this code:
+Let's work our way up from the simplest possible authorizer to see how you can customize your rules.
+
+If your authorizer looks like this:
 
     # app/authorizers/laser_cannon_authorizer.rb
     class LaserCannonAuthorizer < Authority::Authorizer
     end
 
-... you can already do the following:
+... you will find that everything is forbidden:
 
-    current_user.can_create?(LaserCannon)    # false; all inherited class-level permissions are false
-    current_user.can_create?(@laser_cannon)  # false; instance-level permissions check class-level ones by default
+    current_user.can_create?(LaserCannon)    # false; you haven't defined a class-level `can_create?`, so the 
+                                             # `default_strategy` is used. It returns false.
+    current_user.can_create?(@laser_cannon)  # false; instance-level permissions check class-level ones by default,
+                                             # so this is the same as the previous example.
 
 If you update your authorizer as follows:
 
     # app/authorizers/laser_cannon_authorizer.rb
     class LaserCannonAuthorizer < Authority::Authorizer
 
-      def self.creatable_by?(user) # class-level permission
-        true
+      # Class-level permissions
+      #
+      def self.creatable_by?(user)
+        true # blanket true means that **any** user can create a laser cannon
+      end
+
+      def self.deletable_by?(user)
+        false # blanket false means that **no** user can delete a laser cannon
       end
 
-      def deletable_by?(user)      # instance_level permission
+      # Instance-level permissions
+      #
+      def updatable_by?(user)
         user.first_name == 'Larry' && Date.today.friday?
       end
 
     end
 
-... you can now do this following:
+... you can now do the following:
 
     current_user.can_create?(LaserCannon)    # true, per class method above
     current_user.can_create?(@laser_cannon)  # true; inherited instance method calls class method
-    current_user.can_delete?(@laser_cannon)  # Only Larry, and only on Fridays
+    current_user.can_delete?(@laser_cannon)  # false
+    current_user.can_update?(@laser_cannon)  # Only Larry, and only on Fridays (weapons maintenance day)
+
+### Controllers
+
+#### Basic Usage
+
+In your controllers, add this method call:
+
+`check_authorization_on ModelName`
+
+That sets up a `before_filter` that calls your class-level methods before each action. For instance, before running the `update` action, it will check whether `ModelName` is `updatable_by?` the current user at a class level. A return value of false means "this user can never update models of this class."
+
+If that's all you need, one line does it.
+
+#### In-action usage
+
+If you need to check some attributes of a model instance to decide if an action is permissible, you can use `check_authorization_for(@resource_instance, @user)`. This will check the proper instance method on the authorizer, based on which controller action you're currently in.
+
+The default map from controller actions to authorizations is as follows: 
+
+    {
+      :index   => 'read',
+      :show    => 'read',
+      :new     => 'create',
+      :create  => 'create',
+      :edit    => 'update',
+      :update  => 'update',
+      :destroy => 'delete'
+    }
+
+Each controller gets its own copy of this hash.
+
+If you want to edit a **single** controller's action map, you can either pass a hash into `check_authorization_on`, which will get merged into the existing actions hash...
+
+    class BadgerController < ApplicationController
+      check_authorization_on Badger, :actions => {:neuter => 'update'}
+      ...
+    end
+
+...or you can use a separate method call:
+
+    class BadgerController < ApplicationController
+      check_authorization_on Badger
+
+      authority_action :neuter => 'update'
+
+      ...
+    end
+
+Finally, if you want to update this hash for **all** your controllers, you can do that in `config.authority_actions` in the initializer.
+
+## Configuration
+
+Configuration should be done from `config/initializers/authority.rb`, which will be generated for you by `rails g authority:install`. That file includes copious documentation. Copious, do you hear me?!
+
+Ahem. Note that the configuration block in that file **must** run in your application. Authority metaprograms its methods on boot, but waits until your configuration block has run to do so. If you want the default settings, you don't have to put anything in your configure block, but you must at least run `Authority.configure`.
+
+Some of the things you can configure which haven't already been mentioned are...
+
+### Abilities
+
+If you want to be able to say `user.can_eat?` and have Authority ask the model and authorizer if the resource is `edible_by?` the user, edit your `config.abilities` to include `{:eat => 'edible'}`.
+
+### Logging
+
+Authority will log a message any time a user tries to access a resource for which they are not authorized. By default, this is logged to standard error, but you can supply whatever logger you want, as long as it responds to `warn`. Some possible settings are:
+
+    config.logger = Rails.logger
+    config.logger = Logger.new('logs/authority.log') # From Ruby standard library
+
+## Further customization of authorizers
+
+If you want to customize your authorizers even further - for example, maybe you want them to have a method like `has_permission?(user, permission_name)` - just add an extra class into their hierarchy.
+
+    # lib/my_app/authorizer
+    module MyApp
+      class Authorizer < Authority::Authorizer
+      
+        def self.has_permission(user, permission_name)
+          # look that up somewhere
+        end
+
+      end
+    end
+
+Require that file in an `after_initialize` block, and have all your other authorizers subclass `MyApp::Authorizer` instead of `Authority::Authorizer`.
 
 ## Integration Notes
 
-- If you want to have nice log messages for security violations, you should ensure that your user object has a `to_s` method; this will control how it shows up in log messages saying things like "Harvey Johnson is not allowed to delete this resource:..."
+- If you want to have nice log messages for security violations, you should ensure that your user object has a `to_s` method; this will control how it shows up in log messages saying things like "**Regina Johnson** is not allowed to delete this resource:..."
 
-## TODO
+## Credits, AKA 'Shout-Outs'
 
-- Document syntax for checking rules during a controller action
-- Update generator to create an authorizer for every model
-- Generator
-  - Add generators or hook into existing rails generators
-  - Add generator to installation instructions
-  - Generate well-commented default configuration file like Devise does (shout out!)
-  - Generate 403.html, with option to skip if exists
-- Note that you MUST call configure; internals aren't included until you do.
-- Write about configuration file and options in Configuration section.
+- @adamhunter for pairing with me on this gem.
+- @nkallen for [this 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.
+- @jnunemaker for creating Canable, another inspiration for Authority.
 
 ## Contributing
 
@@ -167,3 +242,11 @@ If you update your authorizer as follows:
 6. Commit your changes (`git commit -am 'Added some feature'`)
 7. Push to the branch (`git push origin my-new-feature`)
 8. Create new Pull Request
+
+## TODO
+
+- Integrate Travis CI
+- Add YARD docs everywhere
+- Test generators
+- Test view helpers
+- Make TL;DR examples link to examples further down in README

data/lib/authority/abilities.rb

@@ -21,31 +21,25 @@ module Authority
       end
 
       def authorizer
-        begin
-          @authorizer ||= authorizer_name.constantize
-        rescue StandardError => e
-          if e.is_a?(NameError)
-            raise Authority::NoAuthorizerError.new("#{authorizer_name} does not exist in your application")
-          else
-            raise e
-          end
-        end
+        @authorizer ||= authorizer_name.constantize
+      rescue NameError => e
+        raise Authority::NoAuthorizerError.new("#{authorizer_name} does not exist in your application")
       end
     end
 
-      Authority.adjectives.each do |adjective|
+    Authority.adjectives.each do |adjective|
 
-        # Metaprogram needed methods, allowing for nice backtraces
-        class_eval <<-RUBY, __FILE__, __LINE__ + 1
-          def #{adjective}_by?(user)
-            authorizer.#{adjective}_by?(user)
-          end
+      # Metaprogram needed methods, allowing for nice backtraces
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{adjective}_by?(user)
+          authorizer.#{adjective}_by?(user)
+        end
 
-          def authorizer
-            self.class.authorizer.new(self)
-          end
-        RUBY
-      end
+        def authorizer
+          self.class.authorizer.new(self)
+        end
+      RUBY
+    end
 
   end
 end

data/lib/authority/controller.rb

@@ -24,7 +24,7 @@ module Authority
 
     def authority_forbidden(error)
       Authority.configuration.logger.warn(error.message)
-      render :file => Rails.root.join('public', '403.html'), :status => 403
+      render :file => Rails.root.join('public', '403.html'), :status => 403, :layout => false
     end
 
     def run_authorization_check

data/lib/authority/version.rb

@@ -1,3 +1,3 @@
 module Authority
-  VERSION = "0.3.0"
+  VERSION = "0.9.0"
 end

data/lib/generators/authority/install_generator.rb

@@ -9,13 +9,17 @@ module Authority
       desc "Creates an Authority initializer for your application." 
 
       def copy_initializer
-        template "authority.rb", "config/initializers/authority.rb"
+        template "authority_initializer.rb", "config/initializers/authority.rb"
       end
 
       def copy_forbidden
         template "403.html", "public/403.html"
       end
-      
+
+      def create_authorizers_directory
+        empty_directory "app/authorizers" # creates empty directory if none; doesn't empty the directory
+      end
+
     end
   end
 end

data/lib/generators/templates/{authority.rb → authority_initializer.rb}

@@ -17,9 +17,8 @@ Authority.configure do |config|
   #
   # The arguments passed to this proc will be:
   #
-  # able       - symbol name of class method being called on the Authorizer. 
-  #              Ex: `:deletable_by?` or `:updatable_by?`
-  # authorizer - constant name of authorizer. Ex: `WidgetAuthorizer` or `UserAuthorizer`
+  # able       - symbol name of 'able', like `:creatable`, or `:deletable`
+  # authorizer - authorizer constant. Ex: `WidgetAuthorizer` or `UserAuthorizer`
   # user       - user object (whatever that is in your application; found using config.user_method)
   #
   # For example:
@@ -32,10 +31,10 @@ Authority.configure do |config|
   # OR
   #
   # config.default_strategy = Proc.new { |able, authorizer, user|
-  #   able != 'implodable_by?' && user.has_hairstyle?('pompadour')
+  #   able != :implodable && user.has_hairstyle?('pompadour')
   # }
   #
-  # Default strategy simply returns false, as follows:
+  # Default default strategy simply returns false, as follows:
   #
   # config.default_strategy =  Proc.new { |able, authorizer, user| false }
   

data/spec/authority/controller_spec.rb

@@ -84,7 +84,7 @@ describe Authority::Controller do
 
         it "should render the public/403.html file" do
           forbidden_page = Rails.root.join('public/403.html')
-          @controller.should_receive(:render).with(:file => forbidden_page, :status => 403)
+          @controller.should_receive(:render).with(:file => forbidden_page, :status => 403, :layout => false)
           @controller.send(:authority_forbidden, @mock_error)
         end
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: authority
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.9.0
   prerelease: 
 platform: ruby
 authors:
@@ -14,7 +14,7 @@ date: 2012-03-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
-  requirement: &2160392740 !ruby/object:Gem::Requirement
+  requirement: &2164617440 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -22,10 +22,10 @@ dependencies:
         version: 3.0.0
   type: :runtime
   prerelease: false
-  version_requirements: *2160392740
+  version_requirements: *2164617440
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &2160392220 !ruby/object:Gem::Requirement
+  requirement: &2164616920 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -33,7 +33,7 @@ dependencies:
         version: 1.0.0
   type: :development
   prerelease: false
-  version_requirements: *2160392220
+  version_requirements: *2164616920
 description: Gem for managing authorization on model actions in Rails
 email:
 - nathanmlong@gmail.com
@@ -59,7 +59,7 @@ files:
 - lib/authority/version.rb
 - lib/generators/authority/install_generator.rb
 - lib/generators/templates/403.html
-- lib/generators/templates/authority.rb
+- lib/generators/templates/authority_initializer.rb
 - spec/authority/abilities_spec.rb
 - spec/authority/authorizer_spec.rb
 - spec/authority/configuration_spec.rb