canner 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b38821b91d8d2e75bd9c8128ebccec6c7df8e4a4
-  data.tar.gz: a4e8c7d7d932d44e0de2e961233515b703b5bde4
+  metadata.gz: 7b7de0bc3ce06cfa8e719a5b4cd3da5d8847007b
+  data.tar.gz: 25cb560b1410ca7661df5ef6c1baf77c0c5dba7e
 SHA512:
-  metadata.gz: 0fe967328a50168959e3271f728fef82f6ce94d00ab912a377cc3e2275559efb342786f8776a27a71162dba42423aaca200765b62b2b252d8344308f79f8709d
-  data.tar.gz: 7b0520fb887872d41334349a22d7239f27392e92af24fff476339db26582afea3013fc6269a05baefe8f7820d17ca832db8c01eb3fa12a0b951ffab412e3d4d5
+  metadata.gz: e70bd029306bb3c7a4a6d4666d9452320dc7e43c284492173b243e1fbf0d860c0466e7ddc437a6827959a7a5d9e7f173cbf694817380f0f0ec5ff83a688c4aab
+  data.tar.gz: 4e70d8b65ab9f19a2665235dc9f7ed856e002a098648b900ddd9b60288b01f0885b058b0c14fc2175f2e52a0d42037087d34033fb990b893d1281d8ed0295392

data/README.md

@@ -2,6 +2,7 @@
 
 [![Code Climate](https://codeclimate.com/github/jacklin10/canner/badges/gpa.svg)](https://codeclimate.com/github/jacklin10/canner)
 [![Build Status](https://travis-ci.org/jacklin10/canner.svg?branch=master)](https://travis-ci.org/jacklin10/canner)
+[![Gem Version](https://badge.fury.io/rb/canner.svg)](http://badge.fury.io/rb/canner)
 
 Canner is an authorization gem heavily modeled after Pundit.  
 
@@ -130,7 +131,7 @@ Also if your policy changes at some point its a one place fix.
 
 ### can?
 
-You use the can method to determine if the current_user is able to access an action or resource.
+You use the can? method to determine if the current_user is able to access an action or resource.
 
 The example above uses a straightforward case statement to determine if the current_user can
 access the current action or resource.
@@ -166,6 +167,70 @@ end
 
 in your base_policy's `can?` method
 
+### instance_can? 
+
+You use the instance_can? method to determine if the current_user is able to modify a particular instance
+of an object.  
+
+For example, if a user who belongs to company A wants to edit a particular item they maybe end up here:  
+
+```
+/items/3/edit
+```
+
+Normal stuff.  The user changes the item price and moves on.  
+
+But now we have another user who decides they want to see what happens when they manually change the url: 
+
+```
+/items/13/edit
+```
+
+If you don't defend against this the user would be granted access to edit item with id=13 which 
+belongs to a different company.  
+
+The instance_can? method helps in these situations.  
+
+In your items controller for the **edit, update and destroy** methods add something like:  
+
+``` ruby
+@item = Item.find params[:id]
+instance_can? :manage, :item, @item
+```
+
+Your item_policy.rb will have something like:  
+
+``` ruby
+def instance_can?(item)
+  case @method
+  when :manage
+    return @current_user.company == item.company
+  else
+    false
+  end
+end
+```
+
+Now if a user attempts to edit an item for another company they will see the canner access denied message.  
+
+Your policy can be more complex if needed.  Canner is just a framework so you can get as creative as you want
+just so long as you eventually return true or false.  
+
+For example, maybe your admin user is allowed to edit any items?  You could do something like this:  
+``` ruby
+def instance_can?(item)
+  case @method
+  when :manage
+    return has_role?(:admin) ? true : @current_user.company == item.company
+  else
+    false
+  end
+end
+```
+
+You can enforce that your methods check for this just like you can for canner_scope or can?.  
+See 'Forcing Controller Authorization'  
+
 ### Forcing Controller Authorization
 
 You are able to force the use of controller authorization with canner.  
@@ -186,13 +251,17 @@ after_action :ensure_scope, only: :index
 Note the use of only here.  You usually won't need the canner_scope on anything except
 for the index to be strictly enforced.
 
-If you would like to skip for a particular controller just add:
+And finally, if you want to enforce that you are using instance_can? use something like: 
 ``` ruby
-skip_filter :ensure_scope
+after_action :ensure_instance_checking, only: [:edit, :destroy, :update]
 ```
-And / Or
+
+If you would like to skip one of the enforcements for a specific controller add one or all of these:
+
 ``` ruby
+skip_filter :ensure_scope
 skip_filter :ensure_auth
+skip_filter :ensure_instance_checking
 ```
 
 ### Handle Canner Authorization Failures

data/lib/canner/version.rb

@@ -1,3 +1,3 @@
 module Canner
-  VERSION = "0.2.2"
+  VERSION = "0.3.0"
 end

data/lib/canner.rb

@@ -22,6 +22,7 @@ module Canner
 
   class AuthNotUsedError < StandardError; end
   class ScopeNotUsedError < StandardError; end
+  class InstanceNotProtectedError < StandardError; end
 
   def auth_used
     @auth_used ||= false
@@ -31,12 +32,17 @@ module Canner
     @scope_used ||= false
   end
 
+  def instance_checked
+    @instance_checked ||= false
+  end
+
   # method_name - The controller action method that you are concerned with access
   # target_model - Name of the object you are limiting access to. ( :user, :pet, :customer )
   # target_obj   - The instance obj for what you want to test.  ( does user 1 have access to company 1?)
   def instance_can?(method_name, target_model, target_obj)
+    @instance_checked = true
     policy = canner_policy(method_name, target_model)
-    raise NotAuthorizedError.new("You do not have access to this #{target_model.capitalize}") unless policy.instance_can?(target_obj)
+    raise NotAuthorizedError.new("You do not have access to this #{target_model.to_s.humanize.capitalize}") unless policy.instance_can?(target_obj)
     true
   end
 
@@ -79,6 +85,12 @@ module Canner
     true
   end
 
+  def ensure_instance_checking
+    return if devise_controller? rescue false
+    raise AuthNotUsedError.new("Must use instance_can? method or exclude this action from the after_action") unless instance_checked
+    true
+  end
+
   def canner_policy(method_name, target_model)
     derive_class_name(target_model).constantize.new(canner_user, method_name, canner_branch)
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: canner
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Joe Acklin
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-12-09 00:00:00.000000000 Z
+date: 2015-04-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -158,11 +158,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.2
+rubygems_version: 2.4.6
 signing_key: 
 specification_version: 4
 summary: Rails Auth
 test_files:
 - spec/canner_spec.rb
 - spec/spec_helper.rb
-has_rdoc: