stffn-declarative_authorization 0.2.1 → 0.2.3

data/CHANGELOG

@@ -1,3 +1,5 @@
+* Added handling of Authorization::AuthorizationInController::ClassMethods.filter_access_to parameters that are of the form [:show, :update] instead of just :show, :update. [jeremyf]
+
 * Added a authorization rules browser.  See README for more information [sb]
 
 * Added Model.using_access_control? to check if a model has model security activated [sb]

data/Rakefile

@@ -33,3 +33,11 @@ desc "clone the garlic repo (for running ci tasks)"
 task :get_garlic do
   sh "git clone git://github.com/ianwhite/garlic.git garlic"
 end
+
+desc "Expand filelist in src gemspec"
+task :build_gemspec do
+  gemspec_data = File.read("declarative_authorization.gemspec.src")
+  gemspec_data.gsub!(/\.files = (.*)/) {|m| ".files = #{eval($1).inspect}"}
+  File.open("declarative_authorization.gemspec", "w") {|f| f.write(gemspec_data)}
+end
+

data/app/controllers/authorization_rules_controller.rb

@@ -0,0 +1,103 @@
+if Authorization::activate_authorization_rules_browser?
+
+begin
+  # for nice auth_rules output:
+  require "parse_tree"
+  require "parse_tree_extensions"
+  require "ruby2ruby"
+rescue LoadError; end
+
+class AuthorizationRulesController < ApplicationController
+  filter_access_to :all, :require => :read
+  def index
+    respond_to do |format|
+      format.html do
+        @auth_rules_script = File.read("#{RAILS_ROOT}/config/authorization_rules.rb")
+      end
+    end
+  end
+
+  def graph
+    if params[:format] == "svg"
+      render :text => dot_to_svg(auth_to_dot(graph_options)),
+          :content_type => "image/svg+xml"
+    end
+  end
+
+  private
+  def auth_to_dot (options = {})
+    options = {
+      :effective_role_privs => true,
+      :privilege_hierarchy => false,
+      :filter_roles => nil,
+      :filter_contexts => nil,
+      :highlight_privilege => nil
+    }.merge(options)
+
+    @highlight_privilege = options[:highlight_privilege]
+    @roles = authorization_engine.roles
+    @roles = @roles.select {|r| r == options[:filter_roles] } if options[:filter_roles]
+    @role_hierarchy = authorization_engine.role_hierarchy
+    @privilege_hierarchy = authorization_engine.privilege_hierarchy
+    
+    @contexts = authorization_engine.auth_rules.
+                    collect {|ar| ar.contexts.to_a}.flatten.uniq
+    @contexts = @contexts.select {|c| c == options[:filter_contexts] } if options[:filter_contexts]
+    @context_privs = {}
+    @role_privs = {}
+    authorization_engine.auth_rules.each do |auth_rule|
+      @role_privs[auth_rule.role] ||= []
+      auth_rule.contexts.
+            select {|c| options[:filter_contexts].nil? or c == options[:filter_contexts]}.
+            each do |context|
+        @context_privs[context] ||= []
+        @context_privs[context] += auth_rule.privileges.to_a
+        @context_privs[context].uniq!
+        @role_privs[auth_rule.role] += auth_rule.privileges.collect {|p| [context, p, auth_rule.attributes.empty?, auth_rule.to_long_s]}
+      end
+    end
+    
+    if options[:effective_role_privs]
+      @roles.each do |role|
+        @role_privs[role] ||= []
+        (@role_hierarchy[role] || []).each do |lower_role|
+          @role_privs[role].concat(@role_privs[lower_role]).uniq!
+        end
+      end
+    end
+    
+    if options[:privilege_hierarchy]
+      @context_privs.each do |context, privs|
+        privs.each do |priv|
+          context_lower_privs = (@privilege_hierarchy[priv] || []).
+                                  select {|p,c| c.nil? or c == context}.
+                                  collect {|p,c| p}
+          privs.concat(context_lower_privs).uniq!
+        end
+      end
+    end
+    
+    render_to_string :template => 'authorization_rules/graph.dot.erb', :layout => false
+  end
+  
+  def dot_to_svg (dot_data)
+    gv = IO.popen("/usr/bin/dot -q -Tsvg", "w+")
+    gv.puts dot_data
+    gv.close_write
+    gv.read
+  rescue IOError, Errno::EPIPE => e
+    raise Exception, "Error in call to graphviz: #{e}"
+  end
+  
+  def graph_options
+    {
+      :effective_role_privs => !params[:effective_role_privs].blank?,
+      :privilege_hierarchy => !params[:privilege_hierarchy].blank?,
+      :filter_roles => params[:filter_roles].blank? ? nil : params[:filter_roles].to_sym,
+      :filter_contexts => params[:filter_contexts].blank? ? nil : params[:filter_contexts].to_sym,
+      :highlight_privilege => params[:highlight_privilege].blank? ? nil : params[:highlight_privilege].to_sym
+    }
+  end
+end
+
+end # activate_authorization_rules_browser?

data/app/controllers/authorization_usages_controller.rb

@@ -0,0 +1,19 @@
+if Authorization::activate_authorization_rules_browser?
+
+require File.join(File.dirname(__FILE__), %w{.. .. lib maintenance})
+
+class AuthorizationUsagesController < ApplicationController
+  helper :authorization_rules
+  filter_access_to :all, :require => :read
+  # TODO set context?
+
+  def index
+    respond_to do |format|
+      format.html do
+        @auth_usages_by_controller = Authorization::Maintenance::Usage.usages_by_controller
+      end
+    end
+  end
+end
+
+end # activate_authorization_rules_browser?

data/app/helpers/authorization_rules_helper.rb

@@ -0,0 +1,84 @@
+module AuthorizationRulesHelper
+  def syntax_highlight (rules)
+    regexps = {
+      :constant => [/(:)(\w+)/], 
+      :proc => ['role', 'authorization', 'privileges'],
+      :statement => ['has_permission_on', 'if_attribute', 'includes', 'privilege', 'to'],
+      :operator => ['is', 'contains'],
+      :special => ['user', 'true', 'false'],
+      :preproc => ['do', 'end', /()(=>)/, /()(\{)/, /()(\})/, /()(\[)/, /()(\])/],
+      :comment => [/()(#.*$)/]#,
+      #:privilege => [:read],
+      #:context => [:conferences]
+    }
+    regexps.each do |name, res|
+      res.each do |re|
+        rules.gsub!(
+          re.is_a?(String) ? Regexp.new("(^|[^:])\\b(#{Regexp.escape(re)})\\b") :
+             (re.is_a?(Symbol) ? Regexp.new("()(:#{Regexp.escape(re.to_s)})\\b") : re), 
+          "\\1<span class=\"#{name}\">\\2</span>")
+      end
+    end
+    rules
+  end
+  
+  def link_to_graph (title, options = {})
+    type = options[:type] || ''
+    link_to_function title, "$$('object')[0].data = '#{url_for :action => 'index', :format => 'svg', :type => type}'"
+  end
+  
+  def navigation
+    link_to("Rules", authorization_rules_path) << ' | ' <<
+    link_to("Graphical view", graph_authorization_rules_path) << ' | ' <<
+    link_to("Usages", authorization_usages_path) #<< ' | ' <<
+  #  'Edit | ' <<
+  #  link_to("XACML export", :action => 'index', :format => 'xacml')
+  end
+  
+  def role_color (role, fill = false)
+    fill_colors = %w{#ffdddd #ddffdd #ddddff #ffffdd #ffddff #ddffff}
+    colors = %w{#dd0000 #00dd00 #0000dd #dddd00 #dd00dd #00dddd}
+    @@role_colors ||= {}
+    @@role_colors[role] ||= begin
+      idx = @@role_colors.length % colors.length
+      [colors[idx], fill_colors[idx]]
+    end
+    @@role_colors[role][fill ? 1 : 0]
+  end
+  
+  def role_fill_color (role)
+    role_color(role, true)
+  end
+
+  def auth_usage_info_classes (auth_info)
+    classes = []
+    if auth_info[:controller_permissions]
+      if auth_info[:controller_permissions][0]
+        classes << "catch-all" if auth_info[:controller_permissions][0].actions.include?(:all)
+        classes << "default-privilege" unless auth_info[:controller_permissions][0].privilege
+        classes << "default-context" unless auth_info[:controller_permissions][0].context
+        classes << "no-attribute-check" unless auth_info[:controller_permissions][0].attribute_check
+      end
+    else
+      classes << "unprotected"
+    end
+    classes * " "
+  end
+
+  def auth_usage_info_title (auth_info)
+    titles = []
+    if auth_usage_info_classes(auth_info) =~ /unprotected/
+      titles << "No filter_access_to call protects this action"
+    end
+    if auth_usage_info_classes(auth_info) =~ /no-attribute-check/
+      titles << "Action is not protected with attribute check"
+    end
+    if auth_usage_info_classes(auth_info) =~ /default-privilege/
+      titles << "Privilege set automatically from action name by :all rule"
+    end
+    if auth_usage_info_classes(auth_info) =~ /default-context/
+      titles << "Context set automatically from controller name by filter_access_to call without :context option"
+    end
+    titles * ". "
+  end
+end

data/app/views/authorization_rules/graph.dot.erb

@@ -0,0 +1,49 @@
+
+digraph rules {
+  compound = true
+  edge [arrowhead=open]
+  node [shape=box,fontname="sans-serif",fontsize="16"]
+  fontname="sans-serif";fontsize="16"
+  ranksep = "0.3"
+  //concentrate = true
+  rankdir = TB
+  {
+    node [shape=ellipse,style=filled]
+    //rank = source
+    <% @roles.each do |role| %>
+    "<%= role.inspect %>" [fillcolor="<%= role_fill_color(role) %>"]
+    // ,URL="javascript:set_filter({roles: '<%= role %>'})"
+    <% end %>
+    <% @roles.each do |role| %>
+        <% (@role_hierarchy[role] || []).each do |lower_role| %>
+            "<%= role.inspect %>" -> "<%= lower_role.inspect %>" [constraint=false,arrowhead=empty]
+        <% end %>
+    <% end %>
+  }
+
+  <% @contexts.each do |context| %>
+    subgraph cluster_<%= context %>  {
+      label = "<%= context.inspect %>"
+      style=filled; fillcolor="#eeeeee"
+      node[fillcolor=white,style=filled]
+      <% (@context_privs[context] || []).each do |priv| %>
+      <%= priv %>_<%= context %> [label="<%= priv.inspect %>"<%= ',fontcolor="#ff0000"' if @highlight_privilege == priv %>]
+      <% end %>
+      <% (@context_privs[context] || []).each do |priv| %>
+        <% (@privilege_hierarchy[priv] || []).
+                select {|p,c| (c.nil? or c == context) and @context_privs[context].include?(p)}.
+                each do |lower_priv, c| %>
+      <%= priv %>_<%= context %> -> <%= lower_priv %>_<%= context %> [arrowhead=empty]
+        <% end %>
+      <% end %>
+      //read_conferences -> update_conferences [style=invis]
+      //create_conferences -> delete_conferences [style=invis]
+    }
+  <% end %>
+
+  <% @roles.each do |role| %>
+    <% (@role_privs[role] || []).each do |context, privilege, unconditionally, attribute_string| %>
+  "<%= role.inspect %>" -> <%=  privilege %>_<%= context %> [color="<%= role_color(role) %>", minlen=3<%= ", arrowhead=opendot, URL=\"javascript:\", edgetooltip=\"#{attribute_string.gsub('"','')}\"" unless unconditionally %>]
+    <% end %>
+  <% end %>
+}

data/app/views/authorization_rules/graph.html.erb

@@ -0,0 +1,39 @@
+<h1>Authorization Rules Graph</h1>
+<p>Currently active rules in this application.</p>
+<p><%= navigation %></p>
+
+<% javascript_tag do %>
+    function update_graph (form) {
+        base_url = "<%= url_for :format => 'svg' %>";
+        $('graph').data = base_url + '?' + form.serialize();
+    }
+
+    function set_filter (filter) {
+        for (f in filter) {
+            var select = $("filter_" + f);
+            if (select) {
+                var opt = select.down("option[value='"+ filter[f] + "']");
+                if (opt) {
+                    opt.selected = true;
+                    update_graph(select.form);
+                }
+            }
+        }
+    }
+<% end %>
+<p>
+  <% form_tag do %>
+  <%#= link_to_graph "Rules" %>
+  <%#= link_to_graph "Privilege hierarchy", :type => 'priv_hierarchy' %>
+  
+  <%= select_tag "filter_roles", options_for_select([["All roles",'']] + controller.authorization_engine.roles), :onchange => 'update_graph(this.form)' %>
+  <%= select_tag "filter_contexts", options_for_select([["All contexts",'']] + controller.authorization_engine.auth_rules.collect {|ar| ar.contexts.to_a}.flatten.uniq), :onchange => 'update_graph(this.form)' %>
+  <%= check_box_tag "effective_role_privs", "1", false, :onclick => 'update_graph(this.form)'  %> <%= label_tag "effective_role_privs", "Effective privileges"  %>
+  <%= check_box_tag "privilege_hierarchy", "1", false, :onclick => 'update_graph(this.form)'  %> <%= label_tag "privilege_hierarchy", "Show full privilege hierarchy"  %>
+  <% end %>
+</p>
+<div style="margin: 1em;border:1px solid #ccc;max-width:95%">
+<object id="graph" data="<%= url_for :format => 'svg' %>" type="image/svg+xml" style="max-width:100%"/>
+</div>
+<%= button_to_function "Zoom in", '$("graph").style.maxWidth = "";$(this).toggle();$(this).next().toggle()' %>
+<%= button_to_function "Zoom out", '$("graph").style.maxWidth = "100%";$(this).toggle();$(this).previous().toggle()', :style => 'display:none' %>

data/app/views/authorization_rules/index.html.erb

@@ -0,0 +1,15 @@
+<h1>Authorization Rules</h1>
+<p>Currently active rules in this application.</p>
+<p><%= navigation %></p>
+<style type="text/css">
+  pre .constant {color: #a00;}
+  pre .special {color: red;}
+  pre .operator {color: red;}
+  pre .statement {color: #00a;}
+  pre .proc {color: #0a0;}
+  pre .privilege, pre .context {font-weight: bold}
+  pre .preproc, pre .comment, pre .comment span {color: grey !important;}
+</style>
+<pre>
+<%= syntax_highlight(h(@auth_rules_script)) %>
+</pre>

data/app/views/authorization_usages/index.html.erb

@@ -0,0 +1,45 @@
+<h1>Authorization Usage</h1>
+<div style="margin: 1em;border:1px solid #ccc;max-width:50%;position:fixed;right:0;display:none">
+<object id="graph" data="<%= url_for :format => 'svg' %>" type="image/svg+xml" style="max-width:100%"/>
+</div>
+<p>Filter rules in actions by controller:</p>
+<p><%= navigation %></p>
+<style type="text/css">
+  .auth-usages th { text-align: left; padding-top: 1em }
+  .auth-usages td { padding-right: 1em }
+  .auth-usages tr.action  { cursor: pointer }
+  .auth-usages tr.unprotected  { background: #FFA399 }
+  .auth-usages tr.no-attribute-check { background: #FFE599 }
+  /*.auth-usages tr.catch-all td.privilege,*/
+  .auth-usages tr.default-privilege td.privilege,
+  .auth-usages tr.default-context td.context { color: #888888 }
+</style>
+<% javascript_tag do %>
+    function show_graph (privilege, context) {
+        base_url = "<%= graph_authorization_rules_path('svg') %>";
+        $('graph').data = base_url + '?privilege_hierarchy=1&highlight_privilege=' +
+            privilege + '&filter_contexts=' + context;
+        $('graph').up().show();
+    }
+<% end %>
+<table class="auth-usages">
+  <% @auth_usages_by_controller.keys.sort {|c1, c2| c1.name <=> c2.name}.each do |controller| %>
+    <% default_context = controller.controller_name.to_sym rescue nil %>
+    <tr>
+      <th colspan="3"><%= h controller.controller_name %></th>
+    </tr>
+    <% @auth_usages_by_controller[controller].keys.sort {|c1, c2| c1.to_s <=> c2.to_s}.each do |action| %>
+      <% auth_info = @auth_usages_by_controller[controller][action] %>
+      <% first_permission = auth_info[:controller_permissions] && auth_info[:controller_permissions][0] %>
+      <tr class="action <%= auth_usage_info_classes(auth_info) %>" title="<%= auth_usage_info_title(auth_info) %>" onclick="show_graph('<%= auth_info[:privilege] || action %>','<%= auth_info[:context] || default_context %>')">
+        <td><%= h action %></td>
+        <% if first_permission %>
+          <td class="privilege"><%= h auth_info[:privilege] || action %></td>
+          <td class="context"><%= h auth_info[:context] || default_context %></td>
+        <% else %>
+          <td></td><td></td>
+        <% end %>
+      </tr>
+    <% end %>
+  <% end %>
+</table>

data/config/routes.rb

@@ -0,0 +1,6 @@
+ActionController::Routing::Routes.draw do |map|
+  if Authorization::activate_authorization_rules_browser?
+    map.resources :authorization_rules, :only => :index, :collection => {:graph => :get}
+    map.resources :authorization_usages, :only => :index
+  end
+end

data/lib/authorization.rb

@@ -0,0 +1,514 @@
+# Authorization
+require File.dirname(__FILE__) + '/reader.rb'
+require "set"
+
+
+module Authorization
+  # An exception raised if anything goes wrong in the Authorization realm
+  class AuthorizationError < StandardError ; end
+  # NotAuthorized is raised if the current user is not allowed to perform
+  # the given operation possibly on a specific object.
+  class NotAuthorized < AuthorizationError ; end
+  # AttributeAuthorizationError is more specific than NotAuthorized, signalling
+  # that the access was denied on the grounds of attribute conditions.
+  class AttributeAuthorizationError < NotAuthorized ; end
+  # AuthorizationUsageError is used whenever a situation is encountered
+  # in which the application misused the plugin.  That is, if, e.g.,
+  # authorization rules may not be evaluated.
+  class AuthorizationUsageError < AuthorizationError ; end
+  # NilAttributeValueError is raised by Attribute#validate? when it hits a nil attribute value.
+  # The exception is raised to ensure that the entire rule is invalidated.
+  class NilAttributeValueError < AuthorizationError; end
+  
+  AUTH_DSL_FILE = "#{RAILS_ROOT}/config/authorization_rules.rb"
+  
+  # Controller-independent method for retrieving the current user.
+  # Needed for model security where the current controller is not available.
+  def self.current_user
+    Thread.current["current_user"] || GuestUser.new
+  end
+  
+  # Controller-independent method for setting the current user.
+  def self.current_user=(user)
+    Thread.current["current_user"] = user
+  end
+  
+  @@ignore_access_control = false
+  # For use in test cases only
+  def self.ignore_access_control (state = nil) # :nodoc:
+    false
+  end
+
+  def self.activate_authorization_rules_browser? # :nodoc:
+    ::RAILS_ENV == 'development'
+  end
+  
+  # Authorization::Engine implements the reference monitor.  It may be used
+  # for querying the permission and retrieving obligations under which
+  # a certain privilege is granted for the current user.
+  #
+  class Engine
+    attr_reader :roles, :role_titles, :role_descriptions, :privileges,
+      :privilege_hierarchy, :auth_rules, :role_hierarchy, :rev_priv_hierarchy
+    
+    # If +reader+ is not given, a new one is created with the default
+    # authorization configuration of +AUTH_DSL_FILE+.  If given, may be either
+    # a Reader object or a path to a configuration file.
+    def initialize (reader = nil)
+      if reader.nil?
+        begin
+          reader = Reader::DSLReader.load(AUTH_DSL_FILE)
+        rescue SystemCallError
+          reader = Reader::DSLReader.new
+        end
+      elsif reader.is_a?(String)
+        reader = Reader::DSLReader.load(reader)
+      end
+      @privileges = reader.privileges_reader.privileges
+      # {priv => [[priv, ctx],...]}
+      @privilege_hierarchy = reader.privileges_reader.privilege_hierarchy
+      @auth_rules = reader.auth_rules_reader.auth_rules
+      @roles = reader.auth_rules_reader.roles
+      @role_hierarchy = reader.auth_rules_reader.role_hierarchy
+
+      @role_titles = reader.auth_rules_reader.role_titles
+      @role_descriptions = reader.auth_rules_reader.role_descriptions
+      
+      # {[priv, ctx] => [priv, ...]}
+      @rev_priv_hierarchy = {}
+      @privilege_hierarchy.each do |key, value|
+        value.each do |val| 
+          @rev_priv_hierarchy[val] ||= []
+          @rev_priv_hierarchy[val] << key
+        end
+      end
+    end
+    
+    # Returns true if privilege is met by the current user.  Raises
+    # AuthorizationError otherwise.  +privilege+ may be given with or
+    # without context.  In the latter case, the :+context+ option is
+    # required.
+    #  
+    # Options:
+    # [:+context+]
+    #   The context part of the privilege.
+    #   Defaults either to the +table_name+ of the given :+object+, if given.
+    #   That is, either :+users+ for :+object+ of type User.  
+    #   Raises AuthorizationUsageError if
+    #   context is missing and not to be infered.
+    # [:+object+] An context object to test attribute checks against.
+    # [:+skip_attribute_test+]
+    #   Skips those attribute checks in the 
+    #   authorization rules. Defaults to false.
+    # [:+user+] 
+    #   The user to check the authorization for.
+    #   Defaults to Authorization#current_user.
+    #
+    def permit! (privilege, options = {})
+      return true if Authorization.ignore_access_control
+      options = {
+        :object => nil,
+        :skip_attribute_test => false,
+        :context => nil
+      }.merge(options)
+      
+      # Make sure we're handling all privileges as symbols.
+      privilege = privilege.is_a?( Array ) ?
+                  privilege.flatten.collect { |priv| priv.to_sym } :
+                  privilege.to_sym
+      
+      #
+      # If the object responds to :proxy_reflection, we're probably working with
+      # an association proxy.  Use 'new' to leverage ActiveRecord's builder
+      # functionality to obtain an object against which we can check permissions.
+      #
+      # Example: permit!( :edit, :object => user.posts )
+      #
+      if options[:object].respond_to?( :proxy_reflection )
+        options[:object] = options[:object].new
+      end
+      
+      options[:context] ||= options[:object] && options[:object].class.table_name.to_sym rescue NoMethodError
+      
+      user, roles, privileges = user_roles_privleges_from_options(privilege, options)
+
+      # find a authorization rule that matches for at least one of the roles and 
+      # at least one of the given privileges
+      attr_validator = AttributeValidator.new(self, user, options[:object])
+      rules = matching_auth_rules(roles, privileges, options[:context])
+      if rules.empty?
+        raise NotAuthorized, "No matching rules found for #{privilege} for #{user.inspect} " +
+          "(roles #{roles.inspect}, privileges #{privileges.inspect}, " +
+          "context #{options[:context].inspect})."
+      end
+      
+      # Test each rule in turn to see whether any one of them is satisfied.
+      grant_permission = rules.any? do |rule|
+        begin
+          options[:skip_attribute_test] or
+            rule.attributes.empty? or
+            rule.attributes.any? do |attr|
+              begin
+                attr.validate?( attr_validator )
+              rescue NilAttributeValueError => e
+                nil # Bumping up against a nil attribute value flunks the rule.
+              end
+            end
+        end
+      end
+      unless grant_permission
+        raise AttributeAuthorizationError, "#{privilege} not allowed for #{user.inspect} on #{options[:object].inspect}."
+      end
+      true
+    end
+    
+    # Calls permit! but rescues the AuthorizationException and returns false
+    # instead.  If no exception is raised, permit? returns true and yields
+    # to the optional block.
+    def permit? (privilege, options = {}, &block) # :yields:
+      permit!(privilege, options)
+      yield if block_given?
+      true
+    rescue NotAuthorized
+      false
+    end
+    
+    # Returns the obligations to be met by the current user for the given 
+    # privilege as an array of obligation hashes in form of 
+    #   [{:object_attribute => obligation_value, ...}, ...]
+    # where +obligation_value+ is either (recursively) another obligation hash
+    # or a value spec, such as
+    #   [operator, literal_value]
+    # The obligation hashes in the array should be OR'ed, conditions inside
+    # the hashes AND'ed.
+    # 
+    # Example
+    #   {:branch => {:company => [:is, 24]}, :active => [:is, true]}
+    # 
+    # Options
+    # [:+context+]  See permit!
+    # [:+user+]  See permit!
+    # 
+    def obligations (privilege, options = {})
+      options = {:context => nil}.merge(options)
+      user, roles, privileges = user_roles_privleges_from_options(privilege, options)
+      attr_validator = AttributeValidator.new(self, user)
+      matching_auth_rules(roles, privileges, options[:context]).collect do |rule|
+        obligation = rule.attributes.collect {|attr| attr.obligation(attr_validator) }
+        obligation.empty? ? [{}] : obligation
+      end.flatten
+    end
+    
+    # Returns the description for the given role.  The description may be
+    # specified with the authorization rules.  Returns +nil+ if none was
+    # given.
+    def description_for (role)
+      role_descriptions[role]
+    end
+    
+    # Returns the title for the given role.  The title may be
+    # specified with the authorization rules.  Returns +nil+ if none was
+    # given.
+    def title_for (role)
+      role_titles[role]
+    end
+
+    # Returns the role symbols of the given user.
+    def roles_for (user)
+      raise AuthorizationUsageError, "User object doesn't respond to roles" \
+        if !user.respond_to?(:role_symbols) and !user.respond_to?(:roles)
+
+      RAILS_DEFAULT_LOGGER.info("The use of user.roles is deprecated.  Please add a method " +
+          "role_symbols to your User model.") if defined?(RAILS_DEFAULT_LOGGER) and !user.respond_to?(:role_symbols)
+
+      roles = user.respond_to?(:role_symbols) ? user.role_symbols : user.roles
+
+      raise AuthorizationUsageError, "User.#{user.respond_to?(:role_symbols) ? 'role_symbols' : 'roles'} " +
+        "doesn't return an Array of Symbols (#{roles.inspect})" \
+            if !roles.is_a?(Array) or (!roles.empty? and !roles[0].is_a?(Symbol))
+
+      (roles.empty? ? [:guest] : roles)
+    end
+    
+    # Returns an instance of Engine, which is created if there isn't one
+    # yet.  If +dsl_file+ is given, it is passed on to Engine.new and 
+    # a new instance is always created.
+    def self.instance (dsl_file = nil)
+      if dsl_file or ENV['RAILS_ENV'] == 'development'
+        @@instance = new(dsl_file)
+      else
+        @@instance ||= new
+      end
+    end
+    
+    class AttributeValidator # :nodoc:
+      attr_reader :user, :object, :engine
+      def initialize (engine, user, object = nil)
+        @engine = engine
+        @user = user
+        @object = object
+      end
+      
+      def evaluate (value_block)
+        # TODO cache?
+        instance_eval(&value_block)
+      end
+    end
+    
+    private
+    def user_roles_privleges_from_options(privilege, options)
+      options = {
+        :user => nil,
+        :context => nil
+      }.merge(options)
+      user = options[:user] || Authorization.current_user
+      privileges = privilege.is_a?(Array) ? privilege : [privilege]
+      
+      raise AuthorizationUsageError, "No user object given (#{user.inspect})" \
+        unless user
+
+      roles = flatten_roles(roles_for(user))
+      privileges = flatten_privileges privileges, options[:context]
+      [user, roles, privileges]
+    end
+    
+    def flatten_roles (roles)
+      # TODO caching?
+      flattened_roles = roles.clone.to_a
+      flattened_roles.each do |role|
+        flattened_roles.concat(@role_hierarchy[role]).uniq! if @role_hierarchy[role]
+      end
+    end
+    
+    # Returns the privilege hierarchy flattened for given privileges in context.
+    def flatten_privileges (privileges, context = nil)
+      # TODO caching?
+      #if context.nil?
+      #  context = privileges.collect { |p| p.to_s.split('_') }.
+      #                       reject { |p_p| p_p.length < 2 }.
+      #                       collect { |p_p| (p_p[1..-1] * '_').to_sym }.first
+      #  raise AuthorizationUsageError, "No context given or inferable from privileges #{privileges.inspect}" unless context
+      #end
+      raise AuthorizationUsageError, "No context given or inferable from object" unless context
+      #context_regex = Regexp.new "_#{context}$"
+      # TODO work with contextless privileges
+      #flattened_privileges = privileges.collect {|p| p.to_s.sub(context_regex, '')}
+      flattened_privileges = privileges.clone #collect {|p| p.to_s.end_with?(context.to_s) ?
+                                              #       p : [p, "#{p}_#{context}".to_sym] }.flatten
+      flattened_privileges.each do |priv|
+        flattened_privileges.concat(@rev_priv_hierarchy[[priv, nil]]).uniq! if @rev_priv_hierarchy[[priv, nil]]
+        flattened_privileges.concat(@rev_priv_hierarchy[[priv, context]]).uniq! if @rev_priv_hierarchy[[priv, context]]
+      end
+    end
+    
+    def matching_auth_rules (roles, privileges, context)
+      @auth_rules.select {|rule| rule.matches? roles, privileges, context}
+    end
+  end
+  
+  class AuthorizationRule
+    attr_reader :attributes, :contexts, :role, :privileges
+    
+    def initialize (role, privileges = [], contexts = nil)
+      @role = role
+      @privileges = Set.new(privileges)
+      @contexts = Set.new((contexts && !contexts.is_a?(Array) ? [contexts] : contexts))
+      @attributes = []
+    end
+    
+    def append_privileges (privs)
+      @privileges.merge(privs)
+    end
+    
+    def append_attribute (attribute)
+      @attributes << attribute
+    end
+    
+    def matches? (roles, privs, context = nil)
+      roles = [roles] unless roles.is_a?(Array)
+      @contexts.include?(context) and roles.include?(@role) and 
+        not (@privileges & privs).empty?
+    end
+
+    def to_long_s
+      attributes.collect {|attr| attr.to_long_s } * "; "
+    end
+  end
+  
+  class Attribute
+    # attr_conditions_hash of form
+    # { :object_attribute => [operator, value_block], ... }
+    # { :object_attribute => { :attr => ... } }
+    def initialize (conditions_hash)
+      @conditions_hash = conditions_hash
+    end
+    
+    def validate? (attr_validator, object = nil, hash = nil)
+      object ||= attr_validator.object
+      return false unless object
+      
+      (hash || @conditions_hash).all? do |attr, value|
+        attr_value = object_attribute_value(object, attr)
+        if value.is_a?(Hash)
+          if attr_value.is_a?(Array)
+            raise AuthorizationUsageError, "Unable evaluate multiple attributes " +
+              "on a collection.  Cannot use '=>' operator on #{attr.inspect} " +
+              "(#{attr_value.inspect}) for attributes #{value.inspect}."
+          elsif attr_value.nil?
+            raise NilAttributeValueError, "Attribute #{attr.inspect} is nil in #{object.inspect}."
+          end
+          validate?(attr_validator, attr_value, value)
+        elsif value.is_a?(Array) and value.length == 2
+          evaluated = if value[1].is_a?(Proc)
+                        attr_validator.evaluate(value[1])
+                      else
+                        value[1]
+                      end
+          case value[0]
+          when :is
+            attr_value == evaluated
+          when :is_not
+            attr_value != evaluated
+          when :contains
+            attr_value.include?(evaluated)
+          when :does_not_contain
+            !attr_value.include?(evaluated)
+          when :is_in
+            evaluated.include?(attr_value)
+          when :is_not_in
+            !evaluated.include?(attr_value)
+          else
+            raise AuthorizationError, "Unknown operator #{value[0]}"
+          end
+        else
+          raise AuthorizationError, "Wrong conditions hash format"
+        end
+      end
+    end
+    
+    # resolves all the values in condition_hash
+    def obligation (attr_validator, hash = nil)
+      hash = (hash || @conditions_hash).clone
+      hash.each do |attr, value|
+        if value.is_a?(Hash)
+          hash[attr] = obligation(attr_validator, value)
+        elsif value.is_a?(Array) and value.length == 2
+          hash[attr] = [value[0], attr_validator.evaluate(value[1])]
+        else
+          raise AuthorizationError, "Wrong conditions hash format"
+        end
+      end
+      hash
+    end
+
+    def to_long_s (hash = nil)
+      if hash
+        hash.inject({}) do |memo, key_val|
+          key, val = key_val
+          memo[key] = case val
+                      when Array then "#{val[0]} { #{val[1].respond_to?(:to_ruby) ? val[1].to_ruby.gsub(/^proc \{\n?(.*)\n?\}$/m, '\1') : "..."} }"
+                      when Hash then to_long_s(val)
+                      end
+          memo
+        end
+      else
+        "if_attribute #{to_long_s(@conditions_hash).inspect}"
+      end
+    end
+
+    protected
+    def object_attribute_value (object, attr)
+      begin
+        object.send(attr)
+      rescue ArgumentError, NoMethodError => e
+        raise AuthorizationUsageError, "Error when calling #{attr} on " +
+         "#{object.inspect} for validating attribute: #{e}"
+      end
+    end
+  end
+
+  # An attribute condition that uses existing rules to decide validation
+  # and create obligations.
+  class AttributeWithPermission < Attribute
+    # E.g. privilege :read, attr_or_hash either :attribute or
+    # { :attribute => :deeper_attribute }
+    def initialize (privilege, attr_or_hash, context = nil)
+      @privilege = privilege
+      @context = context
+      @attr_hash = attr_or_hash
+    end
+
+    def validate? (attr_validator, object = nil, hash_or_attr = nil)
+      object ||= attr_validator.object
+      hash_or_attr ||= @attr_hash
+      return false unless object
+
+      case hash_or_attr
+      when Symbol
+        attr_value = object_attribute_value(object, hash_or_attr)
+        attr_validator.engine.permit? @privilege, :object => attr_value, :user => attr_validator.user
+      when Hash
+        hash_or_attr.all? do |attr, sub_hash|
+          attr_value = object_attribute_value(object, attr)
+          if attr_value.nil?
+            raise AuthorizationError, "Attribute #{attr.inspect} is nil in #{object.inspect}."
+          end
+          validate?(attr_validator, attr_value, sub_hash)
+        end
+      else
+        raise AuthorizationError, "Wrong conditions hash format: #{hash_or_attr.inspect}"
+      end
+    end
+
+    # may return an array of obligations to be OR'ed
+    def obligation (attr_validator, hash_or_attr = nil)
+      hash_or_attr ||= @attr_hash
+      case hash_or_attr
+      when Symbol
+        obligations = attr_validator.engine.obligations(@privilege,
+                          :context => @context || hash_or_attr.to_s.pluralize.to_sym,
+                          :user    => attr_validator.user)
+        obligations.collect {|obl| {hash_or_attr => obl} }
+      when Hash
+        obligations_array_attrs = []
+        obligations =
+            hash_or_attr.inject({}) do |all, pair|
+              attr, sub_hash = pair
+              all[attr] = obligation(attr_validator, sub_hash)
+              if all[attr].length > 1
+                obligations_array_attrs << attr
+              else
+                all[attr] = all[attr].first
+              end
+              all
+            end
+        obligations = [obligations]
+        obligations_array_attrs.each do |attr|
+          next_array_size = obligations.first[attr].length
+          obligations = obligations.collect do |obls|
+            (0...next_array_size).collect do |idx|
+              obls_wo_array = obls.clone
+              obls_wo_array[attr] = obls_wo_array[attr][idx]
+              obls_wo_array
+            end
+          end.flatten
+        end
+        obligations
+      else
+        raise AuthorizationError, "Wrong conditions hash format: #{hash_or_attr.inspect}"
+      end
+    end
+
+    def to_long_s
+      "if_permitted_to #{@privilege.inspect}, #{@attr_hash.inspect}"
+    end
+  end
+  
+  # Represents a pseudo-user to facilitate guest users in applications
+  class GuestUser
+    attr_reader :role_symbols
+    def initialize (roles = [:guest])
+      @role_symbols = roles
+    end
+  end
+end