load_and_authorize_resource 0.1.0

data/README.md

@@ -0,0 +1,139 @@
+# Load And Authorize Resource
+
+Auto-loads and authorizes resources in Rails 3 and up.
+
+This was inspired heavily by functionality in the [CanCan](https://github.com/ryanb/cancan) gem, but built to work mostly independent of any authorization library.
+
+## Assumptions
+
+This library assumes your app follows some (fairly common) conventions:
+
+1. Your controller name matches your model name, e.g. "NotesController" for the "Note" model.
+2. You have a method on your (Application)Controller called `current_user` that returns your User model.
+3. Your User model has methods like `can_read?`, `can_update?`, `can_delete?`, etc. (This works great with [Authority](https://github.com/nathanl/authority) gem, but naturally can work with any authorization library, given you/it defines those methods.)
+4. You have a method on your controller that returns the resource parameters, e.g. `note_params`. You're probably already doing this if you're using [StrongParameters](https://github.com/rails/strong_parameters) or Rails 4.
+
+## Loading and Authorizing the Resource
+
+```ruby
+class NotesController < ApplicationController
+  load_and_authorize_resource
+
+  def show
+    # @note is already loaded
+  end
+
+  def new
+    # @note is a new Note instance
+  end
+
+  def create
+    # @note is a new Note instance
+    # with attributes set from note_params
+  end
+end
+```
+
+For each controller action, `current_user.can_<action>?(@note)` is consulted. If false, then an `LoadAndAuthorizeResource::AccessDenied` error is raised.
+
+This works very nicely along with the [Authority](https://github.com/nathanl/authority) gem.
+
+## Loading and Authorizing the Parent Resource
+
+Also loads and authorizes the parent resource(s)... given the following routes:
+
+```ruby
+My::Application.routes.draw do
+  resources :people do
+    resources :notes
+  end
+
+  resources :groups do
+    resources :notes
+  end
+end
+```
+
+... you can do this in your controller:
+
+```ruby
+class NotesController < ApplicationController
+  load_and_authorize_parent :person, :group
+  load_and_authorize_resource
+
+  def show
+    # for /people/1/notes/2
+    # @parent = @person = Person.find(1)
+    # for /groups/1/notes/2
+    # @parent = @group = Group.find(1)
+  end
+end
+```
+
+Further, a private method is defined with the name of the resource that returns an ActiveRecord::Relation scoped to the `@parent` (if present). It basically looks like this:
+
+```ruby
+class NotesController < ApplicationController
+
+  private
+
+  def notes
+    if @parent
+      @parent.notes.scoped
+    else
+      Note.scoped
+    end
+  end
+end
+```
+
+This allows you to easily access the set of notes that make sense given the URL, e.g.:
+
+
+```ruby
+class NotesController < ApplicationController
+  def index
+    # notes is basically equivalent to @group.notes, @person.notes, or just Note,
+    # for the urls /groups/1/notes, /people/1/notes, or /notes (respectively).
+    @notes = notes.order(:created_at).page(params[:page])
+  end
+end
+```
+
+For parent resources, `current_user.can_read?(@parent)` is consulted. If false, then an `LoadAndAuthorizeResource::AccessDenied` error is raised.
+
+If none of the parent IDs are present, e.g. `person_id` and `group_id` are both absent in `params`, then a `LoadAndAuthorizeResource::ParameterMissing` exception is raised.
+
+### Shallow Routes
+
+You can make the parent loading and authorization optional by setting the `shallow` option:
+
+```ruby
+class NotesController < ApplicationController
+  load_and_authorize_parent :person, :group, shallow: true
+end
+```
+
+...this will allow all of the following URLs to work:
+
+* `/people/1/notes/2` - `@person` will be set and authorized for reading
+* `/groups/1/notes/2` - `@group` will be set and authorized for reading
+* `/notes/2` - no parent will be set
+
+## Rescuing Exceptions
+
+You are encouraged to rescue the two possible exceptions in your ApplicationController, like so:
+
+```ruby
+class ApplicationController < ActionController::Base
+  rescue_from 'LoadAndAuthorizeResource::AccessDenied', 'LoadAndAuthorizeResource::ParameterMissing' do |exception|
+    render text: 'not authorized', status: :forbidden
+  end
+end
+```
+
+## Author
+
+Made with ❤ by [Tim Morgan](http://timmorgan.org).
+
+Licensed under MIT license. Please use it, fork it, make it more awesome.

data/lib/load_and_authorize_resource.rb

@@ -0,0 +1,248 @@
+require 'active_support/concern'
+
+module LoadAndAuthorizeResource
+  extend ActiveSupport::Concern
+
+  class ParameterMissing < KeyError; end
+  class AccessDenied < StandardError; end
+
+  METHOD_TO_ACTION_NAMES = {
+    'show'    => 'read',
+    'new'     => 'create',
+    'create'  => 'create',
+    'edit'    => 'update',
+    'update'  => 'update',
+    'destroy' => 'delete'
+  }
+
+  included do
+    class_attribute :nested_resource_options
+  end
+
+  module ClassMethods
+
+    # Macro sets a before filter to load the parent resource.
+    # Pass in one symbol for each potential parent you're nested under.
+    #
+    # For example, if you have routes:
+    #
+    #     resources :people do
+    #       resources :notes
+    #     end
+    #
+    #     resources :groups do
+    #       resources :notes
+    #     end
+    #
+    # ...you can call load_parent like so in your controller:
+    #
+    #     class NotesController < ApplicationController
+    #       load_parent :person, :group
+    #     end
+    #
+    # This will attempt to do the following for each resource, in order:
+    #
+    # 1. look for `params[:person_id]`
+    # 2. if present, call `Person.find(params[:person_id])`
+    # 3. set @person and @parent
+    #
+    # If we've exhausted our list of potential parent resources without
+    # seeing the needed parameter (:person_id or :group_id), then a
+    # LoadAndAuthorizeResource::ParameterMissing error is raised.
+    #
+    # Note: load_parent assumes you've only nested your route a single
+    # layer deep, e.g. /parents/1/children/2
+    # You're on your own if you want to load multiple nested
+    # parents, e.g. /grandfathers/1/parents/2/children/3
+    #
+    # If you wish to also allow shallow routes (no parent), you can
+    # set the `:shallow` option to `true`:
+    #
+    #     class NotesController < ApplicationController
+    #       load_parent :person, :group, shallow: true
+    #     end
+    #
+    # Additionally, a private method is defined with the same name as
+    # the resource. The method looks basically like this:
+    #
+    #     class NotesController < ApplicationController
+    #
+    #       private
+    #
+    #       def notes
+    #         if @parent
+    #           @parent.notes.scoped
+    #         else
+    #           Note.scoped
+    #         end
+    #       end
+    #     end
+    #
+    def load_parent(*names)
+      options = names.extract_options!.dup
+      self.nested_resource_options ||= {}
+      self.nested_resource_options[:load] = {
+        options: {shallow: options.delete(:shallow)},
+        resources: names
+      }
+      before_filter :load_parent, options
+      define_scope_method
+    end
+
+    # Macro sets a before filter to authorize the parent resource.
+    # Assumes there is a `@parent` variable.
+    #
+    #     class NotesController < ApplicationController
+    #       authorize_parent
+    #     end
+    #
+    # If `@parent` is not found, or calling `current_user.can_read?(@parent)` fails,
+    # an exception will be raised.
+    #
+    # If the parent resource is optional, and you only want to check authorization
+    # if it is set, you can set the `:shallow` option to `true`:
+    #
+    #     class NotesController < ApplicationController
+    #       authorize_parent shallow: true
+    #     end
+    #
+    def authorize_parent(options={})
+      self.nested_resource_options ||= {}
+      self.nested_resource_options[:auth] = {
+        options: {shallow: options.delete(:shallow)}
+      }
+      before_filter :authorize_parent, options
+    end
+
+    # A convenience method for calling both `load_parent` and `authorize_parent`
+    def load_and_authorize_parent(*names)
+      load_parent(*names)
+      authorize_parent(names.extract_options!)
+    end
+
+    # Load the resource and set to an instance variable.
+    #
+    # For example:
+    #
+    #     class NotesController < ApplicationController
+    #       load_resource
+    #     end
+    #
+    # ...automatically finds the note for actions
+    # `show`, `edit`, `update`, and `destroy`.
+    #
+    # For the `new` action, simply instantiates a
+    # new resource. For `create`, instantiates and
+    # sets attributes to `<resource>_params`.
+    #
+    def load_resource(options={})
+      unless options[:only] or options[:except]
+        options.reverse_merge!(only: [:show, :new, :create, :edit, :update, :destroy])
+      end
+      before_filter :load_resource, options
+      define_scope_method
+    end
+
+    # Checks authorization on resource by calling one of:
+    #
+    # * `current_user.can_read?(@note)`
+    # * `current_user.can_create?(@note)`
+    # * `current_user.can_update?(@note)`
+    # * `current_user.can_delete?(@note)`
+    #
+    def authorize_resource(options={})
+      unless options[:only] or options[:except]
+        options.reverse_merge!(only: [:show, :new, :create, :edit, :update, :destroy])
+      end
+      before_filter :authorize_resource, options
+    end
+
+    # A convenience method for calling both `load_resource` and `authorize_resource`
+    def load_and_authorize_resource(options={})
+      load_resource(options)
+      authorize_resource(options)
+    end
+
+    protected
+
+    # Defines a method with the same name as the resource (`notes` for the NotesController)
+    # that returns a scoped relation, either @parent.notes, or Note itself.
+    def define_scope_method
+      define_method(controller_name) do
+        if @parent
+          @parent.send(controller_name).scoped
+        else
+          controller_name.classify.constantize.scoped
+        end
+      end
+      private(controller_name)
+    end
+  end
+
+  protected
+
+  # Loop over each parent resource, and try to find a matching parameter.
+  # Then lookup the resource using the supplied id.
+  def load_parent
+    keys = self.class.nested_resource_options[:load][:resources]
+    parent = keys.detect do |key|
+      if id = params["#{key}_id".to_sym]
+        @parent = key.to_s.classify.constantize.find(id)
+        instance_variable_set "@#{key}", @parent
+      end
+    end
+    verify_shallow_route! unless @parent
+  end
+
+  # Loads/instantiates the resource object.
+  def load_resource
+    scope = send(controller_name)
+    if ['new', 'create'].include?(params[:action].to_s)
+      resource = scope.new
+      if 'create' == params[:action].to_s
+        resource.attributes = send("#{controller_name.singularize}_params")
+      end
+    elsif params[:id]
+      resource = scope.find(params[:id])
+    else
+      resource = nil
+    end
+    instance_variable_set("@#{resource_name}", resource)
+  end
+
+  # Verify the current user is authorized to view the parent resource.
+  # Assumes that `load_parent` has already been run and that `@parent` is set.
+  # If `@parent` is empty and the `shallow` option is enabled, don't
+  # perform any authorization check.
+  def authorize_parent
+    if not @parent and not self.class.nested_resource_options[:auth][:options][:shallow]
+      raise ParameterMissing.new('parent resource not found')
+    end
+    if @parent
+      authorize_resource(@parent, :read)
+    end
+  end
+
+  # Asks the current_user if he/she is authorized to perform the given action.
+  def authorize_resource(resource=nil, action=nil)
+    resource ||= instance_variable_get("@#{controller_name.singularize}")
+    action ||= METHOD_TO_ACTION_NAMES[params[:action].to_s]
+    raise ArgumentError unless resource and action
+    unless current_user.send("can_#{action}?", resource)
+      raise AccessDenied.new("#{current_user} cannot #{action} #{resource}")
+    end
+  end
+
+  # Verify this shallow route is allowed, otherwise raise an exception.
+  def verify_shallow_route!
+    return if self.class.nested_resource_options[:load][:options][:shallow]
+    expected = self.class.nested_resource_options[:load][:resources].map { |n| ":#{n}_id" }
+    raise ParameterMissing.new(
+      "must supply one of #{expected.join(', ')}"
+    )
+  end
+
+  def resource_name
+    controller_name.singularize
+  end
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: load_and_authorize_resource
+version: !ruby/object:Gem::Version
+  prerelease: 
+  version: 0.1.0
+platform: ruby
+authors:
+- Tim Morgan
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-07-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  prerelease: false
+  type: :runtime
+  name: rails
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  prerelease: false
+  type: :development
+  name: rspec-rails
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  prerelease: false
+  type: :development
+  name: yard
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  prerelease: false
+  type: :development
+  name: redcarpet
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email: tim@timmorgan.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/load_and_authorize_resource.rb
+homepage: https://github.com/seven1m/load_and_authorize_resource
+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.25
+signing_key: 
+specification_version: 3
+summary: Auto-loads and authorizes resources in your controllers in Rails 3 and up.
+test_files: []
+has_rdoc: yard