authority 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rvmrc

@@ -0,0 +1 @@
+rvm use --create default@authority

data/Gemfile

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

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Nathan Long
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,135 @@
+# Authority
+
+## SUPER ALPHA VERSION
+
+## Overview
+
+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.
+
+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 in their jurisdiction."
+  - "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)`
+
+- 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.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'authority'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install authority
+
+## How it works
+
+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
+
+## Usage
+
+### 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)`. (TODO: Add this module).
+
+### 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 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(:action, @model_instance, @user)` (TODO: determine this)
+
+### 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:
+
+    # app/authorizers/laser_cannon_authorizer.rb
+    class LaserCannonAuthorizer < Authority::Authorizer
+    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 class-level methods defined on `Authority::Authorizer` return false by default; you must override them in your Authorizers to grant permissions. This whitelisting approach will keep you from accidentally allowing things you didn't intend.
+- All instance-level methods defined on `Authority::Authorizer` call their corresponding class-level method by default.
+
+This combination means that, with this code:
+
+    # app/authorizers/laser_cannon_authorizer.rb
+    class LaserCannonAuthorizer < Authority::Authorizer
+    end
+
+... you can already do the following:
+
+    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
+
+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
+      end
+
+      def deletable_by?(user)      # instance_level permission
+        user.first_name == 'Larry' && Date.today.friday?
+      end
+
+    end
+
+... you can now do this 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
+
+## TODO
+
+- Add a module, to be included in whatever user class an app has, which defines all the `can_(verb)` methods.
+- Determine exact syntax for checking rules during a controller action.
+- Add ability to customize default authorization
+- Add customizable logger for authorization violations
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/authority.gemspec

@@ -0,0 +1,20 @@
+# -*- encoding: utf-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.homepage      = "https://github.com/nathanl/authority"
+
+  gem.add_dependency "rails", ">= 3.0.0"
+  gem.add_development_dependency "bundler", ">= 1.0.0"
+
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.name          = "authority"
+  gem.require_paths = ["lib"]
+  gem.version       = Authority::VERSION
+end

data/lib/authority.rb

@@ -0,0 +1,11 @@
+require 'active_support/concern'
+require 'active_support/core_ext/class/attribute'
+require 'active_support/core_ext/string/inflections'
+
+module Authority
+  ADJECTIVES = %w[creatable readable updatable deletable]
+end
+
+require 'authority/abilities'
+require 'authority/authorizer'
+require 'authority/version'

data/lib/authority/abilities.rb

@@ -0,0 +1,39 @@
+module Authority
+  module Abilities
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :authorizer_name
+
+      self.authorizer_name = "#{name}Authorizer"
+    end
+
+    module ClassMethods
+
+      ADJECTIVES.each do |adjective|
+
+        # Metaprogram needed methods, allowing for nice backtraces
+        class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def #{adjective}_by?(actor)
+            authorizer.#{adjective}_by?(actor)
+          end
+        RUBY
+      end
+
+      def authorizer
+        @authorizer ||= authorizer_name.constantize
+      end
+    end
+
+      ADJECTIVES.each do |adjective|
+
+        # Metaprogram needed methods, allowing for nice backtraces
+        class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def #{adjective}_by?(actor)
+            self.class.authorizer.new(self).#{adjective}_by?(actor)
+          end
+        RUBY
+      end
+
+  end
+end

data/lib/authority/authorizer.rb

@@ -0,0 +1,27 @@
+module Authority
+  class Authorizer
+
+    attr_reader :resource
+
+    def initialize(resource)
+      @resource = resource
+    end
+
+    ADJECTIVES.each do |adjective|
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def self.#{adjective}_by?(actor)
+          false
+        end
+      RUBY
+    end
+
+    ADJECTIVES.each do |adjective|
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{adjective}_by?(actor)
+          false
+        end
+      RUBY
+    end
+
+  end
+end

data/lib/authority/version.rb

@@ -0,0 +1,3 @@
+module Authority
+  VERSION = "0.0.1"
+end

data/spec/authority/abilities_spec.rb

@@ -0,0 +1,88 @@
+require 'spec_helper'
+require 'support/ability_model'
+require 'support/actor'
+
+describe Authority::Abilities do
+
+  before :each do
+    @actor = Actor.new
+  end
+
+  describe "authorizer" do
+
+    it "should have a class attribute getter for authorizer_name" do
+      AbilityModel.should respond_to(:authorizer_name)
+    end
+
+    it "should have a class attribute setter for authorizer_name" do
+      AbilityModel.should respond_to(:authorizer_name=)
+    end
+
+    it "should have a default authorizer_name of '(ClassName)Authorizer'" do
+      AbilityModel.authorizer_name.should eq("AbilityModelAuthorizer")
+    end
+
+    it "should constantize the authorizer name as the authorizer" do
+      AbilityModel.instance_variable_set(:@authorizer, nil)
+      AbilityModel.authorizer_name.should_receive(:constantize)
+      AbilityModel.authorizer
+    end
+
+    it "should memoize the authorizer to avoid reconstantizing" do
+      AbilityModel.authorizer
+      AbilityModel.authorizer_name.should_not_receive(:constantize)
+      AbilityModel.authorizer
+    end
+
+  end
+
+  describe "class methods" do
+
+    Authority::ADJECTIVES.each do |adjective|
+      method_name = "#{adjective}_by?"
+
+      it "should respond to `#{method_name}`" do
+        AbilityModel.should respond_to(method_name)
+      end
+
+      it "should delegate `#{method_name}` to its authorizer class" do
+        AbilityModel.authorizer.should_receive(method_name).with(@actor)
+        AbilityModel.send(method_name, @actor)
+      end
+
+    end
+
+  end
+
+  describe "instance methods" do
+
+    before :each do
+      @ability_model = AbilityModel.new
+      @authorizer    = AbilityModel.authorizer.new(@ability_model)
+    end
+
+    Authority::ADJECTIVES.each do |adjective|
+      method_name = "#{adjective}_by?"
+
+      it "should respond to `#{method_name}`" do
+        @ability_model.should respond_to(method_name)
+      end
+
+      it "should delegate `#{method_name}` to a new authorizer instance" do
+        AbilityModel.authorizer.stub(:new).and_return(@authorizer)
+        @authorizer.should_receive(method_name).with(@actor)
+        @ability_model.send(method_name, @actor)
+      end
+
+      it "should always create a new authorizer instance when checking `#{method_name}`" do
+        2.times do
+          @ability_model.class.authorizer.should_receive(:new).with(@ability_model).and_return(@authorizer)
+          @ability_model.send(method_name, @actor)
+        end
+      end
+
+    end
+    
+  end
+
+end

data/spec/authority/authorizer_spec.rb

@@ -0,0 +1,42 @@
+require 'spec_helper'
+require 'support/ability_model'
+
+describe Authority::Authorizer do
+
+  before :each do
+    @ability_model = AbilityModel.new
+    @authorizer = Authority::Authorizer.new(@ability_model)
+  end
+
+  it "should take a resource instance in its initializer" do
+    @authorizer.resource.should eq(@ability_model)
+  end
+
+  describe "class methods" do
+
+    Authority::ADJECTIVES.each do |adjective|
+      method_name = "#{adjective}_by?"
+
+      it "should respond to `#{method_name}`" do
+        Authority::Authorizer.should respond_to(method_name)
+      end
+
+    end
+
+  end
+
+  describe "instance methods" do
+
+    Authority::ADJECTIVES.each do |adjective|
+      method_name = "#{adjective}_by?"
+
+      it "should respond to `#{method_name}`" do
+        @authorizer.should respond_to(method_name)
+      end
+
+    end
+
+  end
+
+end
+

data/spec/authority_spec.rb

@@ -0,0 +1,7 @@
+require 'spec_helper'
+
+describe Authority do
+  it "should have a constant of abilities" do
+    Authority::ADJECTIVES.should be_an(Array)
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,7 @@
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+require 'rspec'
+require 'authority'
+
+RSpec.configure do |config|
+  config.mock_with :rspec
+end

data/spec/support/ability_model.rb

@@ -0,0 +1,6 @@
+class AbilityModel
+  include Authority::Abilities
+end
+
+class AbilityModelAuthorizer < Authority::Authorizer
+end

data/spec/support/actor.rb

@@ -0,0 +1,17 @@
+class Actor
+  def can_create?(resource)
+    resource.creatable_by?(self)
+  end
+
+  def can_read?(resource)
+    resource.readable_by?(self)
+  end
+
+  def can_update?(resource)
+    resource.updatable_by?(self)
+  end
+
+  def can_delete?(resource)
+    resource.deletable_by?(self)
+  end
+end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: authority
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Nathan Long
+- Adam Hunter
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-03-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: &2152357800 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: *2152357800
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: &2152357040 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: *2152357040
+description: Gem for managing authorization on model actions in Rails
+email:
+- nathanmlong@gmail.com
+- adamhunter@me.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rvmrc
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- authority.gemspec
+- lib/authority.rb
+- lib/authority/abilities.rb
+- lib/authority/authorizer.rb
+- lib/authority/version.rb
+- spec/authority/abilities_spec.rb
+- spec/authority/authorizer_spec.rb
+- spec/authority_spec.rb
+- spec/spec_helper.rb
+- spec/support/ability_model.rb
+- spec/support/actor.rb
+homepage: https://github.com/nathanl/authority
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.16
+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_spec.rb
+- spec/spec_helper.rb
+- spec/support/ability_model.rb
+- spec/support/actor.rb