authority 0.9.0 → 1.0.0.pre2

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - jruby-18mode # JRuby in 1.8 mode
+  - jruby-19mode # JRuby in 1.9 mode
+  - rbx-18mode
+  - rbx-19mode
+script: rspec spec

data/CHANGELOG.markdown

@@ -0,0 +1,18 @@
+# Changelog
+
+This is mainly to document major new features and backwards-incompatible changes.
+
+## v1.0.0.pre2
+
+Rename controller methods:
+
+- `check_authorization_on`  => `authorize_actions_on`
+- `check_authorization_for` => `authorize_action_on`
+
+## v1.0.0.pre1
+
+- Renamed `config.authority_actions` to `config.controller_action_map`.
+
+## v0.9.0
+
+Initial release (basically)

data/README.markdown

@@ -0,0 +1,328 @@
+# Authority
+
+Authority gives you a clean and easy way to say, in your Rails app, **who** is allowed to do **what** with your models. Unauthorized actions get a warning and an entry in a log file.
+
+It requires that you already have some kind of user object in your application, accessible from all controllers (like `current_user`).
+
+[![Build Status](https://secure.travis-ci.org/nathanl/authority.png)](http://travis-ci.org/nathanl/authority)
+
+## TL;DR
+
+No time for reading! Reading is for chumps! Here's the skinny:
+
+- Install in your Rails project: add to Gemfile, `bundle`, then `rails g authority:install`
+- For each model you have, create a corresponding [authorizer](#authorizers). For example, for `app/models/lolcat.rb`, create `app/authorizers/lolcat_authorizer.rb` with an empty `class LolcatAuthorizer < Authority::Authorizer`.
+  - Add class methods to that authorizer to set rules that can be enforced just by looking at the resource class, like "this user cannot create Lolcats, period."
+  - Add instance methods to that authorizer to set rules that need to look at a resource instance, like "a user can only edit a Lolcat if it belongs to that user and has not been marked as 'classic'".
+- Wire up your user, models and controllers to work with your authorizers:
+  - In your [user class](#users), `include Authority::UserAbilities`.
+  - Put this in your [controllers](#controllers): `authorize_actions_on YourModelNameHere` (the model that controller works with)
+  - Put this in your [models](#models):  `include Authority::Abilities`
+
+## Overview
+
+Still here? Reading is fun! You always knew that. Time for a deeper look at things.
+
+The goals of Authority are:
+
+- To allow broad, class-level rules. Examples: 
+  - "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 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_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
+
+In broad terms, the authorization process flows like this:
+
+- A user object is asked whether it can do some action to a resource class or instance, like `current_user.can_create?(Widget)` or `current_user.can_update?(@widget)`.
+- The user just asks the model the same question: `resource.creatable_by?(self)`.
+- The model passes that question to its Authorizer, which actually contains the logic to answer the question.
+- The Authorizer returns an answer back up the call chain to the original caller.
+
+## Installation
+
+First, check in whatever changes you've made to your app already. You want to see what we're doing to your app, don't you?
+
+Now, add this line to your application's Gemfile:
+
+    gem 'authority'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install authority
+
+Then run the generator:
+
+    $ rails g authority:install
+
+Hooray! New files! Go look at them. Look look look.
+
+## Usage
+
+<a name="users">
+### Users
+
+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)`.
+
+The list of methods that get defined comes from `config.abilities`.
+
+<a name="models">
+### Models
+
+In your models, `include Authority::Abilities`. This sets up both class-level and instance-level methods like `creatable_by?(user)`, etc. 
+
+The list of methods that get defined comes from `config.abilities`.
+
+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's `editable_by?(user)` would delegate to `RabbitAuthorizer.editable_by?(user)`.
+
+Which leads us to...
+
+<a name="authorizers">
+### Authorizers
+
+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. Here's how you do it:
+
+- Class methods answer questions about model classes, like "is it **ever** permissible for this user to update a widget?"
+  - Any class method you don't define (for example, if you didn't make a `def self.updatable_by?(user)`) will fall back to your [configurable default strategy](#default_strategies).
+- Instance methods answer questions about model instances, like "can this user update this **particular** widget?" (Within an instance method, you can get the model instance with `resource`).
+  - Any instance method you don't define (for example, if you didn't make a `def deletable_by?(user)`) will fall back to the corresponding class method. 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.
+
+So, suppose you've got the empty `LaserCannonAuthorizer` above and haven't supplied a default strategy. Then you ask the authorizer "is `@laser_cannon_x.deletable_by?(@user_y)`?" It will ask itself:
+
+- "Do I have a `deletable_by?` method, to tell me whether this particular laser cannon can be deleted by this user? ... No."
+- "OK, do I have a `self.deletable_by?` method, to tell me whether **any** laser cannon can be deleted by this user? ... No."
+- "OK, did the user define a default strategy for deciding whether any resource can be deleted by a user? ... No."
+- "Well, I do have a **default** default strategy, which always returns false. So the answer is 'false' - the user can't delete this laser cannon."
+
+As you can see, **you can specify different logic for every method on every model, or [supply a single default strategy](#default_strategies) that covers them all, or anything in between**.
+
+And because the **default** default strategy returns false, we start by assuming that **everything is forbidden**. This whitelisting approach will keep you from accidentally allowing things you didn't intend. 
+
+#### An Authorizer Tutorial
+
+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 will find that everything is forbidden:
+
+    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
+
+      # 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
+
+      # Instance-level permissions
+      #
+      def updatable_by?(user)
+        resource.color == 'blue' && user.first_name == 'Larry' && Date.today.friday?
+      end
+
+    end
+
+... 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)  # false
+    current_user.can_update?(@laser_cannon)  # Only Larry, only blue laser cannons, and only on 
+                                             # Fridays (weapons maintenance day)
+<a name="default_strategies">
+#### Default Strategies
+
+To take a different approach, if you wanted to answer all these questions in a uniform way - perhaps by looking up permissions in a database table - you could just supply a default strategy that does that.
+
+    # In config/initializers/authority.rb
+    config.default_strategy = Proc.new { |able, authorizer, user|
+     # Does the user have any of the roles which give this permission?
+     (roles_which_grant(able, authorizer) & user.roles).any?
+    }
+
+That's it! All your authorizer classes could be left empty.
+
+<a name="controllers">
+### Controllers
+
+#### Basic Usage
+
+In your controllers, add this method call:
+
+    authorize_actions_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 the current user (determined using the configurable `user_method`) `can_update?(ModelName)` at a class level. A return value of false means "this user can never update models of this class."
+
+By the way, any options you pass in will be used on the `before_filter` that gets created, so you can do things like this:
+
+    authorize_actions_on InvisibleSwordsman, :only => :show
+
+#### Usage within a controller action
+
+If you need to check some attributes of a model instance to decide if an action is permissible, you can use the **singular** `authorize_action_on(@resource_instance, @user)`. This method will determine which controller action it was called from, look at the controller action map, determine which method should be checked on the model, and check it.
+
+The default controller action map is as follows:
+
+    {
+      :index   => 'read',   # index action requires that the user can_read?(resource)
+      :show    => 'read',   # etc
+      :new     => 'create',
+      :create  => 'create',
+      :edit    => 'update',
+      :update  => 'update',
+      :destroy => 'delete'
+    }
+
+So, for example, if you did this:
+
+    class MessageController < ApplicationController
+    ...
+
+      def edit
+        @message = Message.find(params[:id])
+        authorize_action_on(@message, current_user)
+      end
+      ...
+
+    end
+
+... Authority would determine that it was called from within `edit`, that the `edit` controller action requires permission to `update`, and check whether the user `can_update?(@message)`.
+
+Each controller gets its own copy of the controller action map. If you want to edit a **single** controller's action map, you can either pass a hash into `authorize_actions_on`, which will get merged into the existing actions hash...
+
+    class BadgerController < ApplicationController
+      authorize_actions_on Badger, :actions => {:neuter => 'update'}
+      ...
+    end
+
+...or you can use a separate method call:
+
+    class BadgerController < ApplicationController
+      authorize_actions_on Badger
+
+      authority_action :neuter => 'update'
+
+      ...
+    end
+
+Finally, if you want to update this hash for **all** your controllers, you can do that with `config.controller_action_map` in the initializer.
+
+## Views
+
+Assuming your user object is available in your views, you can do all kinds of conditional rendering. For example:
+
+    `link_to 'Edit Widget', edit_widget_path(@widget) if current_user.can_update?(@widget)`
+
+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** (cue cheesy, dramatic music).
+
+## Security Violations
+
+Anytime a user attempts an unauthorized action, Authority does two things:
+
+- Renders your `public/403.html`
+- Logs the violation to whatever logger you configured.
+
+If you want to set up a `cron` job to watch the log file, look up the user's name and address, and dispatch minions to fill their mailbox with goose droppings, that's really up to you. I got nothing to do with it, man.
+
+## 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
+
+## Custom authorizer inheritence
+
+If you want to customize your authorizers even further - for example, maybe you want them all to have a method like `has_permission?(user, permission_name)` - you can insert a custom class into the inheritance chain.
+
+    # lib/my_app/authorizer.rb
+    module MyApp
+      class Authorizer < Authority::Authorizer
+      
+        def self.has_permission(user, permission_name)
+          # look that up somewhere
+        end
+
+      end
+    end
+  
+    #app/authorizers/badger_authorizer.rb
+    class BadgerAuthorizer < MyApp::Authorizer
+      # contents
+    end
+
+If you decide to place your custom class in `lib` as shown above (as opposed to putting it in `app`), you should require it at the bottom of `config/initializers/authority.rb`.
+
+## 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 "**Kenneth Lay** is not allowed to delete this resource:..."
+
+## 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.
+- [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.
+
+## Contributing
+
+What should you contribute? Some ideas:
+
+- Documentation improvements will always be welcome (though of course, whether something is an improvement will be up to me to decide).
+- Look in the separate TODO file or grep the project for 'TODO' for other ideas.
+
+How can you contribute?
+
+1. Fork this project
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. `bundle install` to get all dependencies
+4. `rspec spec` to run all tests.
+5. Update/add tests for your changes and code until they pass.
+6. Commit your changes (`git commit -am 'Added some feature'`)
+7. Push to the branch (`git push origin my-new-feature`)
+8. Create a new Pull Request

data/TODO.markdown

@@ -0,0 +1,14 @@
+# TODO
+
+## Design
+
+- Carefully think through names of all public methods & see if they could be clearer or more intuitive
+- Consider making empty authorizers unnecessary: if one isn't defined, automatically define it as empty. This would reduce setup but slightly increase obfuscation of the workings.
+- Decide whether there's any reason why `authorizer_action_on` needs a user argument, when we already know the method to call to get the current user.
+
+## Chores
+
+- Add separate generator to make an empty authorizer for each file in `app/models`
+- Test generators
+- Test view helpers
+- Document how you can bypass creating an authorizer for each model - by setting authorizer name directly and having them share.

data/authority.gemspec

@@ -4,8 +4,8 @@ require File.expand_path('../lib/authority/version', __FILE__)
 Gem::Specification.new do |gem|
   gem.authors       = ["Nathan Long", "Adam Hunter"]
   gem.email         = ["nathanmlong@gmail.com", "adamhunter@me.com"]
-  gem.description   = %q{Gem for managing authorization on model actions in Rails}
-  gem.summary       = %q{Authority gives you a clean and easy way to say, in your Rails app, **who** is allowed to do **what** with your models.}
+  gem.description   = %q{Gem for managing authorization on model actions in Rails.}
+  gem.summary       = %q{Authority gives you a clean and easy way to say, in your Rails app, **who** is allowed to do **what** with your models, with minimal clutter.}
   gem.homepage      = "https://github.com/nathanl/authority"
 
   gem.add_dependency "rails", ">= 3.0.0"

data/lib/authority.rb

@@ -8,18 +8,26 @@ module Authority
 
   # NOTE: once this method is called, the library has started meta programming
   # and abilities should no longer be modified
+  # @return [Hash] list of abilities, mapping verbs and adjectives, like :create => 'creatable'
   def self.abilities
     configuration.abilities.freeze
   end
 
+  # @return [Array] keys from adjectives method
   def self.verbs
     abilities.keys
   end
 
+  # @return [Array] values from adjectives method
   def self.adjectives
     abilities.values
   end
 
+  # @param [Symbol] action
+  # @param [Model] resource instance
+  # @param [User] user instance
+  # @raise [SecurityTransgression] if user is not allowed to perform action on resource
+  # @return [Model] resource instance
   def self.enforce(action, resource, user)
     action_authorized = user.send("can_#{action}?", resource)
     unless action_authorized

data/lib/authority/abilities.rb

@@ -1,10 +1,18 @@
 module Authority
+
+  # Should be included into all models in a Rails app. Provides the model
+  # with both class and instance methods like `updatable_by?(user)`
+  # Exactly which methods get defined is determined from `config.abilities`;
+  # the module is evaluated after any user-supplied config block is run 
+  # in order to make that possible.
+  # All delegate to the methods of the same name on the model's authorizer.
+
   module Abilities
     extend ActiveSupport::Concern
 
+    # Let the Foo model know that its authorizer is called 'FooAuthorizer'
     included do
       class_attribute :authorizer_name
-
       self.authorizer_name = "#{name}Authorizer"
     end
 
@@ -12,7 +20,6 @@ module Authority
 
       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)
@@ -21,7 +28,7 @@ module Authority
       end
 
       def authorizer
-        @authorizer ||= authorizer_name.constantize
+        @authorizer ||= authorizer_name.constantize # Get an actual reference to the authorizer class
       rescue NameError => e
         raise Authority::NoAuthorizerError.new("#{authorizer_name} does not exist in your application")
       end
@@ -29,14 +36,13 @@ module Authority
 
     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
 
         def authorizer
-          self.class.authorizer.new(self)
+          self.class.authorizer.new(self) # instantiate on every check, in case model has changed
         end
       RUBY
     end

data/lib/authority/authorizer.rb

@@ -1,24 +1,33 @@
 module Authority
   class Authorizer
 
+    # The base Authorizer class, from which all the authorizers in an app will
+    # descend. Provides the authorizer with both class and instance methods
+    # like `updatable_by?(user)`.
+    # Exactly which methods get defined is determined from `config.abilities`;
+    # the class is evaluated after any user-supplied config block is run 
+    # in order to make that possible.
+
     attr_reader :resource
 
     def initialize(resource)
       @resource = resource
     end
 
+    # Each instance method simply calls the corresponding class method
     Authority.adjectives.each do |adjective|
       class_eval <<-RUBY, __FILE__, __LINE__ + 1
-        def self.#{adjective}_by?(user)
-          Authority.configuration.default_strategy.call(:#{adjective}, self, user)
+        def #{adjective}_by?(user)
+          self.class.#{adjective}_by?(user)
         end
       RUBY
     end
 
+    # Each class method simply calls the user-definable default strategy
     Authority.adjectives.each do |adjective|
       class_eval <<-RUBY, __FILE__, __LINE__ + 1
-        def #{adjective}_by?(user)
-          self.class.#{adjective}_by?(user)
+        def self.#{adjective}_by?(user)
+          Authority.configuration.default_strategy.call(:#{adjective}, self, user)
         end
       RUBY
     end

data/lib/authority/configuration.rb

@@ -1,7 +1,9 @@
 module Authority
   class Configuration
 
-    attr_accessor :default_strategy, :abilities, :authority_actions, :user_method, :logger
+    # Has default settings, overrideable in the initializer.
+
+    attr_accessor :default_strategy, :abilities, :controller_action_map, :user_method, :logger
 
     def initialize
       @default_strategy = Proc.new { |able, authorizer, user|
@@ -15,7 +17,7 @@ module Authority
         :delete => 'deletable'
       }
 
-      @authority_actions = {
+      @controller_action_map = {
         :index   => 'read',
         :show    => 'read',
         :new     => 'create',

data/lib/authority/controller.rb

@@ -1,38 +1,58 @@
 module Authority
   module Controller
+
+    # Gets included into the app's controllers automatically by the railtie
+
     extend ActiveSupport::Concern
 
     included do
       rescue_from Authority::SecurityTransgression, :with => :authority_forbidden
       class_attribute :authority_resource
-      class_attribute :authority_actions
+      class_attribute :controller_action_map
     end
 
     module ClassMethods
-      def check_authorization_on(model_class, options = {})
+
+      # Sets up before_filter to ensure user is allowed to perform a given controller action
+      #
+      # @param [Class] model_class - class whose authorizer should be consulted
+      # @param [Hash] options - can contain :actions to be merged with existing
+      # ones and any other options applicable to a before_filter
+      def authorize_actions_on(model_class, options = {})
         self.authority_resource = model_class
-        self.authority_actions  = Authority.configuration.authority_actions.merge(options[:actions] || {}).symbolize_keys
+        self.controller_action_map = Authority.configuration.controller_action_map.merge(options[:actions] || {}).symbolize_keys
         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)
-        self.authority_actions.merge!(action_map).symbolize_keys
+        self.controller_action_map.merge!(action_map).symbolize_keys
       end
     end
 
     protected
 
+    # 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. 
     def authority_forbidden(error)
       Authority.configuration.logger.warn(error.message)
       render :file => Rails.root.join('public', '403.html'), :status => 403, :layout => false
     end
 
     def run_authorization_check
-      check_authorization_for self.class.authority_resource, send(Authority.configuration.user_method)
+      authorize_action_on self.class.authority_resource, send(Authority.configuration.user_method)
     end
 
-    def check_authorization_for(authority_resource, user)
-      authority_action = self.class.authority_actions[action_name.to_sym]
+    # To be run in a before_filter; ensure this controller action is allowed for the user
+    #
+    # @param authority_resource [Class], the model class associated with this controller
+    # @param user, object representing the current user of the application
+    # @raise [MissingAction] if controller action isn't a key in `config.controller_action_map`
+    def authorize_action_on(authority_resource, user)
+      authority_action = self.class.controller_action_map[action_name.to_sym]
       if authority_action.nil?
         raise MissingAction.new("No authority action defined for #{action_name}")
       end

data/lib/authority/railtie.rb

@@ -4,6 +4,8 @@ module Authority
   class Railtie < ::Rails::Railtie
 
     initializer "authority.controller" do
+      # Include here instead of ApplicationController to avoid being lost when
+      # classes are reloaded in Rails' development mode
       ActionController::Base.send(:include, Authority::Controller)
     end
 

data/lib/authority/user_abilities.rb

@@ -1,6 +1,13 @@
 module Authority
   module UserAbilities
 
+    # Should be included into whatever class represents users in an app.
+    # Provides methods like `can_update?(resource)`
+    # Exactly which methods get defined is determined from `config.abilities`;
+    # the module is evaluated after any user-supplied config block is run 
+    # in order to make that possible.
+    # All delegate to corresponding methods on the resource.
+
     Authority.verbs.each do |verb|
       class_eval <<-RUBY, __FILE__, __LINE__ + 1
         def can_#{verb}?(resource)

data/lib/authority/version.rb

@@ -1,3 +1,3 @@
 module Authority
-  VERSION = "0.9.0"
+  VERSION = "1.0.0.pre2"
 end

data/lib/generators/authority/install_generator.rb

@@ -17,7 +17,8 @@ module Authority
       end
 
       def create_authorizers_directory
-        empty_directory "app/authorizers" # creates empty directory if none; doesn't empty the directory
+        # creates empty directory if none; doesn't empty the directory
+        empty_directory "app/authorizers" 
       end
 
     end

data/lib/generators/templates/authority_initializer.rb

@@ -24,8 +24,8 @@ Authority.configure do |config|
   # For example:
   #
   # config.default_strategy = Proc.new { |able, authorizer, user|
-  #   # Does the user have any roles which give this permission?
-  #   (Permissions.find_by_name_and_authorizer(able, authorizer).roles & user.roles).any?
+  #   # Does the user have any of the roles which give this permission?
+  #   (roles_which_grant(able, authorizer) & user.roles).any?
   # }
   #
   # OR
@@ -38,13 +38,13 @@ Authority.configure do |config|
   #
   # config.default_strategy =  Proc.new { |able, authorizer, user| false }
   
-  # AUTHORITY_ACTIONS
+  # CONTROLLER_ACTION_MAP
   # For a given controller method, what verb must a user be able to do?
   # For example, a user can access 'show' if they 'can_read' the resource.
   #
   # Defaults are as follows:
   #
-  # config.authority_actions = {
+  # config.controller_action_map = {
   #   :index   => 'read',
   #   :show    => 'read',
   #   :new     => 'create',
@@ -76,8 +76,10 @@ Authority.configure do |config|
   #
   # config.logger = Logger.new(STDERR)
   #
-  # Suggested setting for a Rails app is:
-  config.logger = Rails.logger
+  # Some possible settings:
+  # config.logger = Rails.logger
+  # config.logger = Logger.new('logs/authority.log')
+  # config.logger = Logger.new('/dev/null')
 
 end
 

data/spec/authority/configuration_spec.rb

@@ -12,7 +12,7 @@ describe Authority::Configuration do
     end
 
     it "should have a default authority controller actions map" do
-      Authority.configuration.authority_actions.should be_a(Hash)
+      Authority.configuration.controller_action_map.should be_a(Hash)
     end
 
     it "should have a default controller method for accessing the user object" do

data/spec/authority/controller_spec.rb

@@ -21,30 +21,30 @@ describe Authority::Controller do
 
     describe "DSL (class) methods" do
       it "should allow specifying the model to protect" do
-        ExampleController.check_authorization_on AbilityModel
+        ExampleController.authorize_actions_on AbilityModel
         ExampleController.authority_resource.should eq(AbilityModel)
       end
 
       it "should pass the options provided to the before filter that is set up" do
         @options = {:only => [:show, :edit, :update]}
         ExampleController.should_receive(:before_filter).with(:run_authorization_check, @options)
-        ExampleController.check_authorization_on AbilityModel, @options
+        ExampleController.authorize_actions_on AbilityModel, @options
       end
 
       it "should give the controller its own copy of the authority actions map" do
-        ExampleController.check_authorization_on AbilityModel
-        ExampleController.authority_actions.should be_a(Hash)
-        ExampleController.authority_actions.should_not be(Authority.configuration.authority_actions)
+        ExampleController.authorize_actions_on AbilityModel
+        ExampleController.controller_action_map.should be_a(Hash)
+        ExampleController.controller_action_map.should_not be(Authority.configuration.controller_action_map)
       end
 
-      it "should allow specifying the authority action map in the `check_authorization_on` declaration" do
-        ExampleController.check_authorization_on AbilityModel, :actions => {:eat => 'delete'}
-        ExampleController.authority_actions[:eat].should eq('delete')
+      it "should allow specifying the authority action map in the `authorize_actions_on` declaration" do
+        ExampleController.authorize_actions_on AbilityModel, :actions => {:eat => 'delete'}
+        ExampleController.controller_action_map[:eat].should eq('delete')
       end
 
       it "should have a write into the authority actions map usuable in a DSL format" do
         ExampleController.authority_action :smite => 'delete'
-        ExampleController.authority_actions[:smite].should eq('delete')
+        ExampleController.controller_action_map[:smite].should eq('delete')
       end
     end
 
@@ -57,7 +57,7 @@ describe Authority::Controller do
       end
 
       it "should check authorization on the model specified" do
-        @controller.should_receive(:check_authorization_for).with(AbilityModel, @user)
+        @controller.should_receive(:authorize_action_on).with(AbilityModel, @user)
         @controller.send(:run_authorization_check)
       end
 

data/spec/authority_spec.rb

@@ -9,11 +9,13 @@ describe Authority do
   end
 
   it "should not allow modification of the Authority.abilities hash directly" do
-    expect { Authority.abilities[:exchange] = 'fungible' }.to raise_error(RuntimeError, "can't modify frozen Hash")
+    expect { Authority.abilities[:exchange] = 'fungible' }.to raise_error(
+      StandardError, /modify frozen/
+    ) # can't modify frozen hash - exact error type and message depends on Ruby version
   end
 
   it "should have a convenience accessor for the ability verbs" do
-    Authority.verbs.sort.should eq([:create, :delete, :read, :update])
+    Authority.verbs.map(&:to_s).sort.should eq(['create', 'delete', 'read', 'update'])
   end
 
   it "should have a convenience accessor for the ability adjectives" do

metadata

@@ -1,8 +1,8 @@
 --- !ruby/object:Gem::Specification
 name: authority
 version: !ruby/object:Gem::Version
-  version: 0.9.0
-  prerelease: 
+  version: 1.0.0.pre2
+  prerelease: 6
 platform: ruby
 authors:
 - Nathan Long
@@ -10,11 +10,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-03-13 00:00:00.000000000 Z
+date: 2012-03-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
-  requirement: &2164617440 !ruby/object:Gem::Requirement
+  requirement: &82931510 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -22,10 +22,10 @@ dependencies:
         version: 3.0.0
   type: :runtime
   prerelease: false
-  version_requirements: *2164617440
+  version_requirements: *82931510
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &2164616920 !ruby/object:Gem::Requirement
+  requirement: &82931200 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -33,8 +33,8 @@ dependencies:
         version: 1.0.0
   type: :development
   prerelease: false
-  version_requirements: *2164616920
-description: Gem for managing authorization on model actions in Rails
+  version_requirements: *82931200
+description: Gem for managing authorization on model actions in Rails.
 email:
 - nathanmlong@gmail.com
 - adamhunter@me.com
@@ -44,10 +44,13 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - .rvmrc
+- .travis.yml
+- CHANGELOG.markdown
 - Gemfile
 - LICENSE
-- README.md
+- README.markdown
 - Rakefile
+- TODO.markdown
 - authority.gemspec
 - lib/authority.rb
 - lib/authority/abilities.rb
@@ -87,26 +90,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>='
+  - - ! '>'
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.16
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: Authority gives you a clean and easy way to say, in your Rails app, **who**
-  is allowed to do **what** with your models.
-test_files:
-- spec/authority/abilities_spec.rb
-- spec/authority/authorizer_spec.rb
-- spec/authority/configuration_spec.rb
-- spec/authority/controller_spec.rb
-- spec/authority/user_abilities_spec.rb
-- spec/authority_spec.rb
-- spec/spec_helper.rb
-- spec/support/ability_model.rb
-- spec/support/example_controller.rb
-- spec/support/mock_rails.rb
-- spec/support/no_authorizer_model.rb
-- spec/support/user.rb
+  is allowed to do **what** with your models, with minimal clutter.
+test_files: []

data/README.md

@@ -1,252 +0,0 @@
-# Authority
-
-## TL;DR
-
-No time for reading! Reading is for chumps! Here's the skinny:
-
-- 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`.
-- Add class methods to that authorizer to set rules that can be enforced just by looking at the resource class, like "this user cannot create Lolcats, period."
-- Add instance methods to that authorizer to set rules that need to look at a resource instance, like "a user can only edit a Lolcat if it belongs to that user and has not been marked as 'classic'".
-
-## Overview
-
-Still here? Reading is fun! You always knew that. Time for a deeper look at things.
-
-Authority gives you a clean and easy way to say, in your Rails app, **who** is allowed to do **what** with your models.
-
-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."
-  - "Only admin users can create Offices."
-- To allow 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."
-- To provide a clear syntax for permissions-based views. Example:
-  - `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
-
-In broad terms, the authorization process flows like this:
-
-- A request comes to a model, either the class or an instance, saying "can this user do this action to you?"
-- The model passes that question to its Authorizer
-- The Authorizer checks whatever user properties and business rules are relevant to answer that question.
-- The answer is passed back up to the model, then back to the original caller
-
-## Installation
-
-First, check in whatever changes you've made to your app already. You want to see what we're doing to your app, don't you?
-
-Now, add this line to your application's Gemfile:
-
-    gem 'authority'
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install authority
-
-Then run the generator:
-
-    $ rails g authority:install
-
-Hooray! New files! Go look at them.
-
-## Usage
-
-### Users
-
-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, `include Authority::Abilities`. This sets up both class-level and instance-level methods like `creatable_by?(user)`, etc. 
-
-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`.
-
-Which leads us to...
-
-### Authorizers
-
-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 (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.
-
-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 will find that everything is forbidden:
-
-    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
-
-      # 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
-
-      # Instance-level permissions
-      #
-      def updatable_by?(user)
-        user.first_name == 'Larry' && Date.today.friday?
-      end
-
-    end
-
-... 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)  # 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 "**Regina Johnson** is not allowed to delete this resource:..."
-
-## Credits, AKA 'Shout-Outs'
-
-- @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
-
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. `bundle install` to get all dependencies
-4. `rspec spec` to run all tests.
-5. Make your changes and update/add tests as necessary.
-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