<commit_before>Grant
=====

Grant is an easy to use Ruby on Rails plugin for securing access to your Rails model objects. It provides a simple way to declaratively specify rules for granting a user permission to perform CRUD operations on model objects. 

Design Philosophy
=================

When designing the model security portion of Grant, we decided that it shouldn't be used to specify which operations were restricted. Instead, it restricts all CRUD operations and unless they're explicitly granted to the user. It also restricts adding or removing items from has_many and has_and_belongs_to_many associations. Only allowing operations explicitly granted forces you to make conscious security decisions.

Examples
========

The following example demonstrates model security. To enable model security you simply include the Grant::ModelSecurity module in your model class. In this example you see three grant statements. The first grants find (aka read) permission to everyone. The second example grants create, update, and destroy permission when the passed block evaluates to true, which in this case happens when the model is editable by the current user. Similarly, the third grant statement permits additions and removals from the tags association when it's block evaluates to true. A Grant::Error is raised if any grant block evaluates to false or nil.

	class Book < ActiveRecord::Base
	  include Grant::ModelSecurity

	  has_many :tags
  
	  grant(:find) { true }
	  grant(:create, :update, :destroy) { |user, model| model.editable_by_user? user }
	  grant(:add => :tags, :remove => :tags) { |user, model, associated_model| model.editable_by_user? user }

	  def editable_by_user? user
	    user.administrator? || user.has_role?(:editor) 
	  end
	end

There's a lot more to the grant statement than shown in the above example. For instance, you can have multiple grant statements for the same action. Ultimate permission to perform the action will not be granted unless all grant blocks evaluate to true.

Copyright (c) 2010 Near Infinity Corporation, released under the MIT license
<commit_msg>Updated the summary level documentation.<commit_after>Grant
=====

Grant is an easy to use Ruby on Rails plugin for securing access to your Rails model objects. It provides a declaratively method to specify rules for granting permission to perform CRUD operations on model objects. 

Grant does not allow you to specify which operations are restricted. Instead, it restricts all CRUD operations unless they're explicitly granted to the user. It also restricts adding or removing items to/from has_many and has_and_belongs_to_many associations. Only allowing operations explicitly granted forces you to make conscious security decisions. Grant will not help you make those decisions, but it won't let you forget to.

Installation
============

Grant is installed as a Rails plugin
  
  script/plugin install git://github.com/nearinfinity/grant.git

Usage
=====

To enable model security you simply include the Grant::ModelSecurity module in your model class. In the example below you see three grant statements. The first grants find (aka read) permission all the time. The second example grants create, update, and destroy permission when the passed block evaluates to true, which in this case happens when the model is editable by the current user. Similarly, the third grant statement permits additions and removals from the tags association when it's block evaluates to true. A Grant::Error is raised if any grant block evaluates to false or nil.

	class Book < ActiveRecord::Base
	  include Grant::ModelSecurity

	  has_many :tags
  
	  grant(:find)
	  grant(:create, :update, :destroy) { |user, model| model.editable_by_user? user }
	  grant(:add => :tags, :remove => :tags) { |user, model, associated_model| model.editable_by_user? user }

	  def editable_by_user? user
	    user.administrator? || user.has_role?(:editor) 
	  end
	end

The valid actions to pass to a grant statement are :find, :create, :update, :destroy, :add, and :remove. The first four options are passed as symbols while :add and :remove are hash keys to association names they protect. Any number of options can be passed to a single grant statement, which is very useful if each of the actions share the same logic for determining access.

Integration
===========

There may be some instances where you need to perform an action on your model object without Grant stepping in and stopping you. In those cases you can include the Grant::Integration module for help.

  class BooksController < ApplicationController
    include Grant::Integration
    
    def update
      book = Book.find(params[:id])
      without_grant { book.update_attributes(params[:book]) } # Grant is disabled for the entire block
    end
  end

Copyright (c) 2010 Near Infinity Corporation, released under the MIT license

{'fraction_non_alphanumeric': 0.05977482088024565, 'fraction_numerical': 0.0016376663254861821, 'mean_word_length': 4.603211009174312, 'pattern_counts': {'":': 0, '<': 6, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7270440', 'n_tokens_mistral': 1202, 'n_tokens_neox': 1116, 'n_words': 660}