Permissive gives your ActiveRecord models granular permission support

Permissive combines a model-based permissions system with bitmasking to create a flexible approach to maintaining permissions on your ActiveRecord models. It supports an easy-to-use set of methods for accessing and determining permissions, including some fun metaprogramming.

Installation

1. Get yourself some code. You can install as a gem:

   gem install permissive

   or as a plugin:

   script/plugin install git://github.com/flipsasser/permissive.git

2. Generate a migration so you can get some sweet table action:

   script/generate permissive_migration

   rake db:migrate

Usage

First, define a few permissions constants. We'll define them in Rails.root/config/initializers/permissive.rb. The best practice is to name them in a verb format that follows this pattern: "Object can DO_PERMISSION_NAME".

Permission constants need to be int values counting up from zero. We use ints because Permissive uses bit masking to keep permissions data compact and performant.

module Permissive::Permissions
  MANAGE_GAMES = 0
  CONTROL_RIDES = 1
  PUNCH = 2
end

And that's all it takes to configure permissions! Now that we have them, let's grant them to a model or two:

class Employee < ActiveRecord::Base
  acts_as_permissive
  validates_presence_of :first_name, :last_name
end

class Company < ActiveRecord::Base
  validates_presence_of :name
end

Easy-peasy, right? Let's try granting a few permissions:

@james = Employee.create(:first_name => 'James', :last_name => 'Brennan')
@frigo = Employee.create(:first_name => 'Tommy', :last_name => 'Frigo')
@adventureland = Company.create(:name => 'Adventureland')

# Okay, let's do some granting. We'll start by scoping to a specific company.
@james.can!(:manage_games, :on => @adventureland)

# Now let's do some permission checking.
@james.can?(:manage_games, :on => @adventureland) #=> true

# We can also use the metaprogramming syntax:
@james.can_manage_games_on?(@adventureland) #=> true
@james.can_control_rides_on?(@adventureland) #=> false

# We can check for multiple permissions, too:
@james.can?(:manage_games, :control_rides) #=> false
# OR:
@james.can_manage_games_and_control_rides?

# Scoping can be done through any object
@frigo.can!(:punch, :on => @james)
@frigo.can_punch_on?(@james) #=> true

# And the permissions aren't reciprocal
@james.can_punch_on?(@frigo) #=> false

# Of course, we can grant global (non-scoped) permissions, too:
@frigo.can!(:control_rides)
@frigo.can_control_rides? #=> true

# BUT! Global permissions don't override scoped permissions.
@frigo.can_control_rides_on?(@adventureland) #=> false

# Likewise, scoped permissions don't bubble up globally:
@james.can_manage_games? #=> false

# And, last but not least, let's take all of those great permissions away:
@james.revoke(:manage_games, :on => @adventureland)

# We can revoke all permissions, in any scope, too:
@frigo.revoke(:all)

And that's it!

Scoping

Permissive supports scoping at the class-configuration level, which adds relationships to permitted objects:

class Employee < ActiveRecord::Base
  acts_as_permissive :scope => :company
end

@frigo.permissive_companies #=> [Company 1, Company 2]

Replacing Permissions

Sometimes you want to overwrite all previous permissions in a can! method. That's pretty easy: just add :reset => true to the options.

@frigo.can!(:control_rides, :on => @adventureland, :reset => true)

Next Steps

There's a number of things I want to add to the permissive settings. At the moment, Permissive currently support scoping at the class level, BUT all it really does is add a has_many relationship. @employee.can!(:do_anything) will still work, as will @employee.can!(:do_something, :on => @something_that_isnt_a_company). That's pretty confusing to me. Adding more granular permissions might be cooler:

class Employee < ActiveRecord::Base
  has_permissions do
    on :companies
    on :employees
  end
end

which might yield something like

@employee.permissive_companies
# and
@employee.can_control_rides_in_company @adventureland

I'd also like to support a more intelligent grammar:

@james.can_punch? @frigo
@frigo.can!(:control_rides, :in => @adventureland)

Meta-programmed methods for granting and revoking would be cool, too:

@james.can_punch! @frigo
@frigo.cannot_control_rides_in! @adventureland

And while we're on the subject of metaprogramming, let's add some OR-ing to the whole thing:

@james.can_control_rides_or_manage_games_in? @adventureland

I'd also like to enable Permissive::Templates (pre-set permission groups, like roles):

administrator = Permissive::Template.named('Administrator')
@james.acts_like administrator

Next up! I currently use a manual reset to grant permissions through a controller. It would by great to DRY this stuff up and provide some decent path for moving permissions into HTML forms. Right now, it looks something like this:

<%= check_box_tag("employee[permissions][]", Permissive::Permissions::CONTROL_RIDES, @employee.can_control_rides?) %> Control rides

.. and in the controller:

def update
  @employee.can!(params[:employees].delete(:permissions), :revert => true)
  respond_to do |format|
    ...
  end
end

Finally, I'd like to use the grant_mask support that exists on the Permissive::Permission model to control what people can or cannot allow others to do. This would necessitate one of two things - first, a quick way of iterating over a person's granting permissions, e.g.:

<% current_user.grant_permissions.each do |permission| %>
<!-- Do something! -->
<% end %>

and second, write-time checking of grantor permissions. Something like this, maybe:

def update
  current_user.grant(params[:employees][:permissions], :to => @employee)
end

which would allow the Permissive::Permission model to make sure whatever current_user is granting to @employee, they're allowed to grant to @employee.

And that's it! Like all of my projects, I extracted it from some live development - which means it, too, is still in development. So please feel free to contribute!

Copyright (c) 2009 Flip Sasser & Simon Parsons, released under the MIT license