checkin 0.4.4 → 0.4.5

data/README.md

@@ -1,6 +1,19 @@
 # Checkin
 
-**Checkin** is an authorization gem for Ruby on Rails
+**Checkin** is an authorization gem for Ruby on Rails. 
+
+## Features
+
+* Handy [DSL](http://en.wikipedia.org/wiki/Domain-specific_language) to define roles and permissions with a declarative approach
+* Check authorization for CRUD operations automatically
+* Standard way to rescue from Authorization errors
+* Authorization subject decoupled from model (compatible with any autentication system)
+* Role-based authorization decoupled from role system (compatible with any role system)
+* Decorator for `current_user` and other subject objects
+* Scoped authorization rules
+* Cascading authorization rules
+* Simple: even complex authorization behaviour is understandable at glimpse and easily predictable
+* Support for controller based mass assignment protection (*Coming Soon* – already implemented but still not tested and not documented)
 
 ## Installation
 
@@ -11,10 +24,26 @@ Put this in your Gemfile
 and update your bundle
   
     bundle install
+    
+    
+## Generate  a `*Subject` class
+
+``` 
+rails g checkin:subject SUBJECTNAME
+```
+
+_eg._
+
+```
+rails g checkin:subject user
+```
 
 ## Usage
 
-Create a **subject class** in your load path
+### Define a subject class
+
+Create a **subject class** in your load path (you can use the `checkin:subject` generator as described above). A subject class is a decorator
+around the role and authentication system in which you can define *roles* and *permissions* for a given subject with a simple [DSL](http://en.wikipedia.org/wiki/Domain-specific_language).
 
 _ex._
 
@@ -29,114 +58,121 @@ class UserSubject < Checkin::Subject
           !!subject_model
       end
 
-      role :owner, :require => [:logged_in, :author], :method => :own do |object|
-          object && object.respond_to?(:author) && ( subject_model == object.author )
-      end
-
       role :author, :require => :logged_in do
-          subject_model.has_role?(:contributor) || subject_model.has_role?(:author)
+          subject_model.has_role?(:author)
       end
 
-      role :editor, :require => :logged_in do
-          subject_model.has_role?(:editor)
+      role :owner, :require => [:author], :method => :own do |object|
+          object && object.respond_to?(:author) && ( subject_model == object.author )
       end
 
       role :administrator, :require => :logged_in, :alias => :admin do
           subject_model.has_role?(:administrator)
       end
 
-      role :mantainer, :require => :logged_in do
-          subject_model.has_role?(:mantainer)
-      end
-
-      role :staff, :require => :logged_in do
-       subject_model.has_role?(:administrator) ||
-       subject_model.has_role?(:mantainer) ||
-       subject_model.has_role?(:editor) ||
-       subject_model.has_role?(:author) ||
-       subject_model.has_role?(:contributor) ||
-       subject_model.has_role?(:photographer)
-      end
-
-      role :tester, :require => :logged_in do
-        subject_model.has_role?(:tester)
-      end
-
-      role :nexta_supervisor, :require => :logged_in do
-        subject_model.has_role?(:nexta)
-      end
-
-      role :self, :require  => :logged_in do |object|
-          object && object.is_a?(User) && subject_model == object
-      end
-
       #
       # Permissions
       #
 
-      scope :site do
-        permissions :for => [:messages, :replies] do
-          allow :logged_in
-          allow :guests, :to => [:show, :index]
-          deny  :guests
-        end
-        permissions :for => :network do
-          allow [:administrators, :nexta_supervisors], :to => [:see]
-          deny
-        end
-      end
-
-      # Admin
       scope :admin do
         permissions do
-          allow :administrators, :mantainers
+          allow :administrators
+          allow :owners,  :to => [:edit, :update]
           deny
         end
       end
+      
+end
+```
 
-      scope :api do
-        allow :staff
-        deny
-      end
+Now you can instantiate a `UserSubject` to decorate any subject model. **NOTE**: you won't need to do this directly since the `checkin` method
+will do this for you (see the section below).
 
-      # Mantainer
-      scope :mantainer do
-        permissions do
-          allow :mantainers
-          deny
-        end
-      end
+``` rb
+subject = UserSubject.new(User.first, :scope => :admin)
+```
 
-      # Staff
-      scope :staff do
-        permissions do
-          allow :administrators, :mantainers
-          allow :editors, :to => [:edit, :update]
-          allow :authors, :to => [:new, :create]
-          allow :owners,  :to => [:edit, :update]
-          deny
-        end
+#### Checking role membership
 
-        permissions :for => :guides do
-          allow :administrators, :mantainers
-          allow :logged_in, :to => [:index, :show]
-          deny
-        end
+According to the definitions included in the subject class the subject decorator will provide some methods to check role memberships.
 
-        permissions :for => :drafts do
-          allow :authors, :to => :submit
-        end
+_ex._
 
-        permissions_to_set :published do
-          allow :editors, :administrators, :mantainers
-          deny
-        end
+``` rb
+subject.logged_in?
+subject.guest?
+subject.own?(Post.first)
+```
 
-      end
+#### Checking permissions
+
+similarly the decorator allows you to check the permissions of the subject
+
+``` rb
+subject.can_edit?(Post.first)
+```
+
+### Subject DSL reference
+
+#### Defining roles
+
+A role can be defined through the method `role`.
+
+* `role(name, options = {}, &block)`<br/>
+  Define a role named `name` and specify how to test the membership of a subject to this role with the `block` procedure. A role can be relative also to an object. _eg._ `owner` depends on `object.author`. **NOTE** keep in mind that roles are tested also in situations where `subject` and `object` are `nil`.
+  <br/><br/>
+  **Options**
+  * `:require` : Specify other memberships that are required to belong to this role
+  * `:alias` _or_ `:aliases` : Specify aliases that can be used in permissions to refer this role. _eg_ `connected` for `logged_in`
+  * `:method` : Specify the method that will be defined in the decorator to check the membership to this role. _eg_ `own?` for `owner`
+
+
+#### Defining permissions
+
+To define a permission you can use the `permissions` block. Inside the permission block you can call `allow` to define a rule that if satisfied immediately allow the subject to perform the related action and `deny` to define a rule that if satisfied immediately deny the subject to perform the related action.
+
+Permissions can be both _scoped_ or _global_. To define a scope you can use the `scope` method. You can also define permissions for a specific resource or for a set of resources through passing a `:for` option to the `permissions` method.
+
+Permissions blocks are evaluated in the same order they are written skipping them for scopes and resources that are not affected.
+
+_eg._
+``` rb
+permissions :for => :comments do
+  allow :administrators, :mantainers
+  allow :logged_in, :to => [:create]
+  deny
 end
 ```
 
-Use in controller
+Inside a permissions block `allow` and `deny` rules are checked consecutively. The checking process will immediately return if any rule is matched and the subject is allowed or denied according to the kind of the rule. If no rule are matched then the subject is allowed.
+
+##### References
+
+* `permissions(options = {}, &block)`<br/>
+    Define a permissions block<br/><br/>
+  **Options**<br/>
+    * `:for` : specify a resource or a set of resources for which these permissions are applied. If no `:for` option is specified the block is applied to any resource.
+* `allow(*roles, options = {})`<br/>
+    Allow a subject that has a mebership to `roles` to perform an action specified by the `:to` option. If no `roles` are specified this rule **any role** is allowed. Similarly if no `:to` option is specified **any action** can be performed.<br/><br/>
+    **Options**<br/>
+      * `:to` : specify an action or a set of actions that the subject is allowed to perform if belonging to `*roles`.
+* `deny(*roles, options = {})`<br/>
+    Deny a subject that has a mebership to `roles` to perform an action specified by the `:to` option. If no `roles` are specified this rule **no role** is allowed. Similarly if no `:to` option is specified **no action** can be performed. 
+    <br/><br/>
+    **Options**
+      * `:to` : specify an action or a set of actions that the subject is allowed to perform if belonging to `*roles`.
+* `scope(name)`<br/>
+    Defines a scope in which the permissions are applied
+
+## Integration with the application
+
+The `checkin` method define a before filter to a controller that is responsible to instantiate a subject decorator to the current subject model, to instantiate the current resource for crud actions that has one, and then to check permissions for the *current subject* to perform the *current action* on the *current resource* in the *current scope*.
+
+If the check fails a `Checkin::AccessDenied` exception is raised.
+
+The `checkin` method defines also some other methods available in controller and views to access the subject decorator and the resource object, by default `#subject` and `#object` (see the reference section below).
+
+**NOTE** The resource object is instantiated and checked only if a `params[:id]` is present for the current action.
 
 _ex._
 
@@ -159,8 +195,70 @@ class ApplicationController < ActionController::Base
 end
 ```
 
+##### References
+
+* `checkin(options = {})`<br/>
+  Define the checkin before filter in the controller in which is invoked
+  **Options**
+  * `:scope` : Specify the current scope
+  * `:subject` : Specify the [underscored](http://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-underscore) subject class name. Default to :user_subject
+  * `:as` : Specify the method name for the generated accessor to the subject decorator, default to `:subject`
+  * `:subject_model` : Specify the method that return the current subject model, default to `:current_user`
+  * `:object` : Specify a method accessible in the controller scope that returns the current resource, if none is specified such method is automatically generated by the `checkin` method
+  * `:find_object` : Specify a way to fetch the resource object passing a `String` or `Symbol` corresponding to a method name or a `Proc` that returns the resoruce. Default to `Proc.new {  model_class.find(params[:id]) }`
+  * `:skip_authorization` : Specify to skip the authorization process
+  * `:rescue_with` : Specify a procedure that is invoked to rescue from `Checkin::AccessDenied` exceptions
+
+_eg._
+
+``` rb
+checkin(:subject => :user_subject, :scope => nil, :skip_authorization => false, :object => :object, rescue_with => lambda {
+  if subject.guest?
+    redirect_to new_user_session_path
+  else
+   render :text => "Not Authorized", :status => 403
+  end
+})
+```
+
+
+### Helpers
+
+The `subject` and `object` methods (or what they are configured to be named) are also invokable from views. Since the `#subject` method returns the subject decorator it's safe to call test methods on it even if no subject is logged in. So you can replace `current_user.try(:administrator?)` with `subject.administrator?`. Also thanks to the dependencies expressed with the role definition DSL you can easily test complex situation with a single method. _eg._
+
+``` rb
+  # user_subject.rb
+  role :owner, :require => :author, :method => :own do |object|
+      object && object.respond_to?(:author) && ( subject_model == object.author )
+  end 
+``` 
+
+`subject.own?(Post.new)` is the same of `current_user && current_user.has_role?(:author) && object && object.respond_to?(:author) && current_user == object.author`
+
+
+##  Permission to change attributes (in-controller mass assignment protection)
+
+**NOTE** This feature is implemented but not tested yet (please help me to do that if you wish!)
+
+You can define permission to set attributes through the method `permissions_to_set`
+
+``` rb
+  # user_subject
+  permissions_to_set :published do
+    allow :editors, :administrators
+    deny
+  end
+```
+
+``` rb
+  editor.allowed_to_set?(:published, :on => post)
+```
+
+Denied params will be automatically removed from `params` hash in the `checkin` before filter
 
+## Explaining and logging
 
+The subject decorator has two methods `explain!` and `stop_explaining!` to enable/disable the logging of the details of the authorization process. By default `explain!` is automatically called in the development runtime.
 
 ---
 

data/VERSION

@@ -1 +1 @@
-0.4.4
+0.4.5

data/checkin.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "checkin"
-  s.version = "0.4.4"
+  s.version = "0.4.5"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["mcasimir"]
-  s.date = "2012-05-07"
+  s.date = "2012-05-25"
   s.description = "Checkin is an authorization gem for Ruby on Rails"
   s.email = "maurizio.cas@gmail.com"
   s.extra_rdoc_files = [
@@ -33,6 +33,8 @@ Gem::Specification.new do |s|
     "lib/checkin/role.rb",
     "lib/checkin/rule.rb",
     "lib/checkin/subject.rb",
+    "lib/generators/checkin/subject_generator.rb",
+    "lib/generators/checkin/templates/subject.rb",
     "test/helper.rb",
     "test/test_checkin.rb"
   ]

data/lib/checkin/filters.rb

@@ -3,9 +3,9 @@ module Checkin
     extend ActiveSupport::Concern
   
     module ClassMethods
-      # checkin(:subject => :user, :scope => nil, :skip_authorization => false, :object => :object, rescue_with => lambda {
+      # checkin(:subject => :user_subject, :scope => nil, :skip_authorization => false, :object => :object, rescue_with => lambda {
       #   if subject.guest?
-      #     redirect_to new_user_session_path, :notice => "Accedi per completare l'operazione"
+      #     redirect_to new_user_session_path
       #   else
       #     render :text => "Not Authorized", :status => 403
       #   end

data/lib/generators/checkin/subject_generator.rb

@@ -0,0 +1,12 @@
+module Checkin
+  module Generators
+    class SubjectGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('../templates', __FILE__)
+      
+      def generate_subject
+        template 'subject.rb', File.join('app/models', class_path, "#{file_name}_subject.rb")
+      end
+      
+    end
+  end
+end

data/lib/generators/checkin/templates/subject.rb

@@ -0,0 +1,32 @@
+class <%= class_name %>Subject < Checkin::Subject
+
+      role :guest, :alias => :anonymous do
+          !subject_model
+      end
+
+      role :logged_in, :alias => [:connected] do
+          !!subject_model
+      end
+
+      # role :owner, :require => [:logged_in, :author], :method => :own do |object|
+      #     object && object.respond_to?(:author) && ( subject_model == object.author )
+      # end
+      # 
+      # role :administrator, :require => :logged_in, :alias => :admin do
+      #     subject_model.has_role?(:administrator)
+      # end
+
+      #
+      # Permissions
+      #
+
+      # Admin
+
+      # scope :admin do
+      #   permissions do
+      #     allow :administrators
+      #     deny
+      #   end
+      # end
+
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: checkin
 version: !ruby/object:Gem::Version
-  version: 0.4.4
+  version: 0.4.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-07 00:00:00.000000000 Z
+date: 2012-05-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jeweler
@@ -51,6 +51,8 @@ files:
 - lib/checkin/role.rb
 - lib/checkin/rule.rb
 - lib/checkin/subject.rb
+- lib/generators/checkin/subject_generator.rb
+- lib/generators/checkin/templates/subject.rb
 - test/helper.rb
 - test/test_checkin.rb
 homepage: http://github.com/mcasimir/checkin
@@ -68,7 +70,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3829181454465002286
+      hash: -2281754506523548066
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: