Authorize
=========
authorize is a Ruby on Rails plugin providing a sophisticated Role-Based Access Control (RBAC) system.  It started as a 
spinoff of Bill Katz's Authorization plugin, but has been substantially tested, debugged and enhanced since then.  
Current functionality highlights include:

 * Polymorphic association of ActiveRecord subject models.
 * Polymorphic association of ActiveRecord trustee models.
 * Flexible identity mappings to support Group-based roles.
 * Syntax to support a single ActiveRecord model being both a subject and a trustee.
 * Dynamic methods on subjects and trustees support domain-specific syntax: user.is_owner_of(widget)? and 
 widget.is_owned_by?(user)
 * Class-level role support (user.is_moderator_of?(Post)
 * Generic/global-level role support (user.is_administrator?) 
 * Performance-optimized Domain-Specific Language (DSL) for more sophisticated predicates (available in ActionController 
 at controller and action level).

For more information on the theory of RBAC, see http://en.wikipedia.org/wiki/Role-based_access_control, but note that 
the term "subject" is used where this plugin uses the term "trustee".

----------------

The authorize plugin extends ActionController with the ability to check permissions and react accordingly.  There are 
two approaches:
a simple boolean check (permit?) and a more sophisticated predicated block (permit) with exception handling.  In both 
cases, the method accepts
a permissions description string expressed in a domain-specific language.  The simplest version of this language is just 
the name of the required 
global/generic role.  For example, using the boolean version:

  permit? "adminstrator"

More complex expressions typically involve requiring a particular role over a particular model instance.  For example:

  permit? "owner of :widget"  

The authorize plugin extends ActiveRecord with two methods: acts_as_subject and acts_as_trustee.  A given model may 
invoke
either or both, depending on requirements.  The follow narrative shows the methods added to models for management of 
role-based authorization.
 
ActiveRecord-provided associations (see AR documentation for complete list of related methods)
  Trustee (User or Group, for example)
    authorizations
          Returns array of authorizations belonging to trustee
          Deprecated equivalent: roles
    subjected_<subjected_models>   # Note the use of the plural model name
          Returns authorized model objects
          Not yet implemented
  Subject (Widget, for example)
    subjections  # Synonym for authorizations -must be distinct to permit model as both trustee and subject.
          Returns array of authorizations over acts_as_subject objects.
          Deprecated equivalent: accepted_roles
    authorized_<trustee_models>
          Returns array of trustees with an authorization over the acts_as_subject object.
          Not yet implemented
  Authorization
    trustee
          Returns the authorized trustee
    subject
          Returns the object of the authorization
    subjected_<subjected_model>     # Note the use of the singular model name
          Returns subjected model object of named class.  NB: This association is only safe with UUID-keyed models!
          Disabled
    authorized_<authorized_model>      # Note the use of the singular model name
          Returns authorized trustee object of named class.  NB: This association is only safe with UUID-keyed trustees!

                    Disabled
Standard plugin methods:
  Trustee
    authorize <Role>, <Subject Instance or Class>
          Creates an authorization for the trustee as <Role> over the subject Instance or Class.  If neither an instance 
          nor a class is specified,
          the trustee is granted a generic/global authorization.
    unauthorize <Role>, <Subject Instance or Class>
          Removes any authorization for the trustee as <Role> over the subject Instance or Class.  Leave off the 
          instance or class to remove a
          generic authorization.
    authorized? <Role>, <Subject Instance or Class>
          Boolean condition for the trustee being authorized as the <Role> over the subject Instance or Class.  Leave 
          off the instance or class to
          check for a generic/global authorization.
  Subject (Authorizable Class or Instance)
    subject <Role>, <Trustee>
          Subjects the model instance or class to the authority of trustee as the named role.
    unsubject <Role>, <Trustee>
          Removes any authorization for the trustee as the named role over the model instance or class
    subjected? <Role>, <Trustee>
          Boolean condition for the the model Instance or Class being subjected to the authority of trustee as the named 
          role.
Identity Mixin methods:
  Trustee
    is_<Role>_for_what
          Returns array of subjects for which trustee as <Role> is authorized
    is_<Role>_<Preposition>?(<Authorizable object>)
          Boolean condition for trustee as <Role> being authorized for the specified subject.
    is_<Role>[_<Preposition> <Authorizable object>]
          Creates authorization for trustee as <Role> either generically or over the specified subject (model or class)
    is_<Role>
          Creates generic authorization to trustee as <Role>
  Subject
    has_<Role>
          Returns array of trustees having specified role over the subject.
    has_<Role>?
          Boolean conditioned upon at least one trustee having <Role> over the subject.