authorize 0.0.1

data/.gitignore

@@ -0,0 +1,5 @@
+.settings
+rdoc
+pkg/*
+*.gem
+.bundle

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,42 @@
+PATH
+  remote: .
+  specs:
+    authorize (0.0.1)
+      redis (~> 2.1)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    actionmailer (2.3.10)
+      actionpack (= 2.3.10)
+    actionpack (2.3.10)
+      activesupport (= 2.3.10)
+      rack (~> 1.1.0)
+    activerecord (2.3.10)
+      activesupport (= 2.3.10)
+    activeresource (2.3.10)
+      activesupport (= 2.3.10)
+    activesupport (2.3.10)
+    mocha (0.9.10)
+      rake
+    rack (1.1.0)
+    rails (2.3.10)
+      actionmailer (= 2.3.10)
+      actionpack (= 2.3.10)
+      activerecord (= 2.3.10)
+      activeresource (= 2.3.10)
+      activesupport (= 2.3.10)
+      rake (>= 0.8.3)
+    rake (0.8.7)
+    redis (2.1.1)
+    sqlite3 (1.3.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  authorize!
+  mocha (~> 0.9)
+  rails (~> 2.3)
+  redis (~> 2.1)
+  sqlite3 (~> 1.3)

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2007-2009 Christopher Cyrus Hapgood
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,155 @@
+Authorize
+=========
+Authorize is a Ruby on Rails plugin providing a sophisticated Role-Based Access Control (RBAC) system.  Current functionality highlights include:
+
+ * Polymorphic association of ActiveRecord models as authorizable resources.
+ * Three-level (global, class, instance) authorizations over resources.
+ * "Acts" to support a single ActiveRecord model being both an authorizable subject and trustee.
+ * Hierarchical role tree supporting rich modelling of role assignment. 
+ * High-performance resolution of effective roles using Redis key-value database as a graph database.
+
+For more information on the theory of RBAC, see http://en.wikipedia.org/wiki/Role-based_access_control
+
+----------------
+ActionPack
+The Authorize plugin extends ActionController and ActionView 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 a configurable callback.  In both cases, the method accepts
+a permissions description hash.  For example, using the boolean version:
+
+	permit?(:update => widget)
+
+More complex expressions typically involve checking for permissions to multiple model instances.  The following predicate, for example,
+is true if the current roles include the :all permission over foo OR the :read permission over bar:
+
+	permit?({:all => foo, :read => bar})  
+
+Clean hooks are available for identifying the appropriate roles for the current request.  No "User" class is assumed, only a
+ApplicationController#roles method that returns an enumeration of the roles for the current request.  A simple implementation might
+work something like this:
+
+	class ApplicationController << ActionController::Base
+	  def roles
+	    User.current.role.roles
+	  end
+	end
+
+----------------
+ActiveRecord
+The Authorize plugin extends ActiveRecord with two methods: authorizable_resource and authorizable_trustee.  A given model may invoke
+either or both, depending on requirements.  Models are thus extended with additional capabilities as follows:
+
+Trustee
+A #role association is defined that links a trustee to a "primary" or "identity" role (Authorize::Role).  This role serves as the entry
+point for traversing the role hierarchy and determining the effective set of roles (identity role plus its children) for a given trustee.
+
+Resource
+A #permissions association is defined that links a resource to the set of permissions (Authorize::Permission) that define the available
+access modes to the resource.
+
+In addition to the macro methods described above, two ActiveRecord::Base subclasses are defined:
+
+Authorize::Permission
+Permissions link roles to resources along with a defined access mode.  Access modes are limited to the classics (read, update, delete, etc.),
+but interpretation of them is application-specific (but see the note below about the list mode).  Permissions apply to resources at one of
+three levels:
+
+	Instance (e.g. update permission for the Widget instance with id 6324)
+	Class (e.g. list permission for all instances of Widget)
+	Global (e.g. read permission for all instances of every model class)
+
+NOTE: To maximize performance, the list access mode is assumed to be included in EVERY instance of Authorize::Permission.  This allows
+efficient SQL joins with model tables (widgets, for example) and the permissions table (authorize_permissions).  The permissions table
+can grow quite large, and this implied mode obviates the need to index the mask field and add complex conditions to permissions queries.  
+	
+Authorize::Role
+Roles allow flexible modelling of application-specific functions.  The Role class is rather thin and mainly serves to identify a role
+instance and polymorphically associate it, where appropriate, to a trustee.  Critically, it has the sole interface (#roles) into the 
+role graph (a DAG) stored in the Redis database. 
+----------------
+
+A Note on Performance
+
+Performance of the <Subject Class>.authorized named scope is critical to effective use of this plugin.  However, it is difficult to optimize across multiple
+database systems for multiple use cases.  Empirically, it seems to be best to use a UNION of the three cases that can yield an authorization: global, class-
+based and instance based.  Alternatives using moderately complex nested or expanded OR clauses fail to optimize correctly on MySQL 5.0 and degrade terribly 
+with substantial authorization and subject volume.  Not surprisingly, COALESCE also fails to optimize nicely.  A JOIN-based solution was considered, but the
+semantics of a JOIN are such that duplicate subject records are returned.  The duplicates could be eliminated with :group and :having options, but at the cost
+of transparency of the #authorized named scope.
+
+Indexing of the authorization table is very important.  See the test application's schema for an reasonable set of indices.
+
+Code examples of alternatives:
+
+          # Baseline with nested booleans
+          c1 = Authorize::Permission.sanitize_sql_hash_for_conditions(:subject_type => nil)
+          c2 = Authorize::Permission.sanitize_sql_hash_for_conditions(:subject_type => base_class.name)
+          c3l = "%s.%s" % [reflection.quoted_table_name, connection.quote_column_name(reflection.primary_key_name)]
+          c3r = "%s.%s" % [connection.quote_table_name(table_name), connection.quote_column_name(primary_key)]
+          c4 = Authorize::Permission.sanitize_sql_hash_for_conditions(:subject_id => nil)
+          subject_condition_clause = "#{c1} OR (#{c2} AND (#{c3l} = #{c3r} OR #{c4}))"
+          named_scope :a0, lambda {|tokens, roles|
+            scope = Authorize::Permission.scoped(:conditions => subject_condition_clause).with(tokens).as(roles)
+            c = scope.construct_finder_sql({:select => 1, :from => "#{reflection.quoted_table_name} a"}).gsub(/#{reflection.quoted_table_name}\./, 'a.')
+            {:conditions => "EXISTS (%s)" % c}
+          }
+
+          # Baseline with booleans expanded into three ORs
+          c1 = Authorize::Permission.sanitize_sql_hash_for_conditions(:subject_type => nil)
+          c2 = Authorize::Permission.sanitize_sql_hash_for_conditions(:subject_type => base_class.name)
+          c3l = "%s.%s" % [reflection.quoted_table_name, connection.quote_column_name(reflection.primary_key_name)]
+          c3r = "%s.%s" % [connection.quote_table_name(table_name), connection.quote_column_name(primary_key)]
+          c4 = Authorize::Permission.sanitize_sql_hash_for_conditions(:subject_id => nil)
+          subject_condition_clause = "#{c1} OR (#{c2} AND #{c3l} = #{c3r}) OR (#{c1} AND #{c4})"
+          named_scope :a1, lambda {|tokens, roles|
+            scope = Authorize::Permission.scoped(:conditions => subject_condition_clause).with(tokens).as(roles)
+            c = scope.construct_finder_sql({:select => 1, :from => "#{reflection.quoted_table_name} a"}).gsub(/#{reflection.quoted_table_name}\./, 'a.')
+            {:conditions => "EXISTS (%s)" % c}
+          }
+
+          # COALESCE replacing OR (and a subtle but harmless semantic shift)
+          auth_fk = "#{reflection.quoted_table_name}.#{connection.quote_column_name(reflection.primary_key_name)}"
+          subject_pk = "#{connection.quote_table_name(table_name)}.#{connection.quote_column_name(primary_key)}"
+          auth_fk_type = "#{reflection.quoted_table_name}.#{connection.quote_column_name(Authorize::Permission.reflections[:subject].options[:foreign_type])}"
+          subject_condition_clause = "%s = COALESCE(#{auth_fk_type}, %s) AND #{subject_pk} = COALESCE(#{auth_fk}, #{subject_pk})" % ([connection.quote(base_class.name)] * 2)
+          named_scope :a2, lambda {|tokens, roles|
+            scope = Authorize::Permission.scoped(:conditions => subject_condition_clause).with(tokens).as(roles)
+            c = scope.construct_finder_sql({:select => 1, :from => "#{reflection.quoted_table_name} a"}).gsub(/#{reflection.quoted_table_name}\./, 'a.')
+            {:conditions => "EXISTS (%s)" % c}
+          }
+
+          # Correlated subquery with COALESCE
+          auth_fk = "#{reflection.quoted_table_name}.#{connection.quote_column_name(reflection.primary_key_name)}"
+          subject_pk = "#{connection.quote_table_name(table_name)}.#{connection.quote_column_name(primary_key)}"
+          auth_fk_type = "#{reflection.quoted_table_name}.#{connection.quote_column_name(Authorize::Permission.reflections[:subject].options[:foreign_type])}"
+          subject_condition_clause = "%s = COALESCE(#{auth_fk_type}, %s)" % ([connection.quote(base_class.name)] * 2)
+          select_clause = "COALESCE(#{auth_fk}, #{subject_pk})"
+          named_scope :a3, lambda {|tokens, roles|
+            scope = Authorize::Permission.scoped(:conditions => subject_condition_clause).with(tokens).as(roles)
+            c = scope.construct_finder_sql({:select => select_clause})
+            {:conditions => "#{subject_pk} IN (#{c})"}
+          }
+
+          # Three-way union - nice performance but UGLY query
+          auth_fk = "#{reflection.quoted_table_name}.#{connection.quote_column_name(reflection.primary_key_name)}"
+          subject_pk = "#{connection.quote_table_name(table_name)}.#{connection.quote_column_name(primary_key)}"
+          named_scope :a4, lambda {|tokens, roles|
+            scope = Authorize::Permission.with(tokens).as(roles)
+            sq0 = scope.construct_finder_sql({:select => true, :conditions => {:subject_id => nil, :subject_type => nil}})
+            sq1 = scope.construct_finder_sql({:select => true, :conditions => {:subject_type => base_class.name, :subject_id => nil}})
+            sq2 = scope.scoped(:conditions => "#{auth_fk} = #{subject_pk}").construct_finder_sql({:select => true, :conditions => {:subject_type => base_class.name}})
+            {:conditions => "EXISTS (#{sq0} UNION #{sq1} UNION #{sq2})"}
+          }
+
+          # Join - possible to get nice performance, but semantics collapse
+          auth_fk = "#{reflection.quoted_table_name}.#{connection.quote_column_name(reflection.primary_key_name)}"
+          subject_pk = "#{connection.quote_table_name(table_name)}.#{connection.quote_column_name(primary_key)}"
+          auth_fk_type = "#{reflection.quoted_table_name}.#{connection.quote_column_name(Authorize::Permission.reflections[:subject].options[:foreign_type])}"
+          subject_condition_clause = "%s = COALESCE(#{auth_fk_type}, %s) AND #{subject_pk} = COALESCE(#{auth_fk}, #{subject_pk})" % ([connection.quote(base_class.name)] * 2)
+          named_scope :a9, lambda {|tokens, roles|
+            ascope = Authorize::Permission.with(tokens).as(roles).current_scoped_methods[:find][:conditions]
+            {:joins => "JOIN authorizations ON #{subject_condition_clause}", :conditions => {:authorizations => ascope}}
+          }
+
+TODO:
+ * Flexible configuration of permission bits
+ 

data/Rakefile

@@ -0,0 +1,25 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'bundler'
+
+Bundler::GemHelper.install_tasks
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the authorize plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test/test'
+  t.pattern = 'test/test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the authorize plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Authorize'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/TODO.txt

@@ -0,0 +1,9 @@
+Aggregate at the database: bit_or for MySQL, custom function for SQLite3 (http://snippets.dzone.com/posts/show/3717)
+Per-model permission operations
+Index into roles has_many association with relation string
+Scrap name attribute and let I18N handle Role#to_s with relation string and reference (I18n.t 'role.MOD', :thing => "Sabre 36")
+REDIS: ModelArray and ModelHash (key, value, key/value) like ModelSet
+REDIS: Deprecate exists? class and instance methods -the semantics are fishy for degenerate objects, particularly degenerate containers.
+GRAPH: Add UndirectedEdge to make UndirectedGraph's edges more efficient and semantically clean (with one set of properties, not two).
+GRAPH: Streamline Fixtures to only use new once.
+Eliminate reliance on ActiveSupport dependency loader.

data/authorize.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "authorize/version"
+
+Gem::Specification.new do |s|
+  s.name        = "authorize"
+  s.version     = Authorize::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Chris Hapgood"]
+  s.email       = ["cch1@hapgoods.com"]
+  s.homepage    = ""
+  s.summary     = %q{A fast and flexible RBAC for Rails}
+  s.description = %q{Authorize implements a full-blown Role-based Access Control (RBAC) system for Ruby on Rails}
+
+  s.rubyforge_project = "authorize"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+  s.add_development_dependency('mocha', '~>0.9')
+  s.add_development_dependency('sqlite3', '~>1.3')
+  s.add_development_dependency('rails', '~>2.3')
+  s.add_runtime_dependency('redis', '~>2.1')
+end

data/generators/authorize/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Generates a migration for the authorizations table suitable for use with the Authorize plugin.
+
+Example:
+    ./script/generate authorize authorizations
+
+    This will create:
+        db/migrate/<timestamp>_create_authorizations.rb

data/generators/authorize/authorize_generator.rb

@@ -0,0 +1,7 @@
+class AuthorizeGenerator < Rails::Generator::NamedBase
+  def manifest
+    record do |m|
+      m.migration_template "migrate/create_authorizations.rb", "db/migrate", {:migration_file_name => 'create_authorizations'}
+    end
+  end
+end

data/generators/authorize/templates/migrate/create_authorizations.rb

@@ -0,0 +1,26 @@
+class CreateAuthorizations < ActiveRecord::Migration
+  def self.up
+    create_table :authorize_permissions, :force => true do |t|
+      t.references :role, :null => false
+      t.references :resource, :polymorphic => true
+      t.integer :mask, :limit => 255, :default => 1, :null => false
+      t.datetime :updated_at
+    end
+    add_index :authorize_permissions, [:role_id, :resource_id, :resource_type], :unique => true, :name => "index_authorize_permissions_on_role_id_and_resource"
+    add_index :authorize_permissions, [:resource_id, :resource_type, :role_id], :unique => true, :name => "index_authorize_permissions_on_resource_and_role_id"
+
+    create_table :authorize_roles, :force => true do |t|
+      t.references :resource, :polymorphic => true
+      t.string :name
+      t.string :relation, :limit => 3
+      t.datetime :updated_at
+    end
+    add_index :authorize_roles, [:resource_id, :resource_type, :relation], :unique => true, :name => "index_authorize_roles_on_resource_and_role_id"
+  end
+
+  def self.down
+    drop_table :authorize_roles
+    drop_table :authorize_permissions
+  end
+end
+

data/install.rb

@@ -0,0 +1 @@
+# Install hook code here

data/lib/authorize.rb

@@ -0,0 +1,2 @@
+module Authorize
+end

data/lib/authorize/action_controller.rb

@@ -0,0 +1,59 @@
+module Authorize
+  module ActionController
+    def self.included(recipient)
+      if recipient.respond_to?(:rescue_responses)
+        recipient.rescue_responses['Authorize::AuthorizationError'] = :forbidden
+      end
+      recipient.extend(ClassMethods)
+      recipient.class_eval do
+        include InstanceMethods
+        helper_method :permit?
+        helper_method :permit
+        helper_method :handle_authorization_failure
+      end
+    end
+
+    module ClassMethods
+      # Allow action-level authorization check with an appended before_filter.
+      def permit(authorization_expression, options = {})
+        auth_options = options.slice!(:only, :except)
+        append_before_filter(options) do |controller|
+          controller.permit(authorization_expression, auth_options)
+        end
+      end
+    end
+
+    module InstanceMethods
+      # Simple predicate for authorization.
+      def permit?(authorization_hash, options = {})
+        authorization_hash.any? do |(modes, resource)|
+          request_mask = Authorize::Permission::Mask[modes]
+          roles = options[:roles] || self.roles
+          Authorize::Permission.over(resource).as(roles).permit?(request_mask).tap do |authorized|
+            Rails.logger.debug("Authorization check: #{authorized ? '✔' : '✖'} #{request_mask}")
+          end
+        end
+      end
+
+      # Allow method-level authorization checks.
+      # permit (without a trailing question mark) invokes the callback "handle_authorization_failure" by default.
+      # Specify :callback => false to turn off callbacks.
+      def permit(authorization_hash, options = {})
+        options = {:callback => :handle_authorization_failure}.merge(options)
+        callback = options.delete(:callback)
+        if permit?(authorization_hash, options)
+          yield if block_given?
+        else
+          __send__(callback) if callback
+        end
+      end
+
+      private
+      # Handle authorization failure within permit.  Override this callback in your ApplicationController
+      # for custom behavior.  This method typically returns the value for the around_filter
+      def handle_authorization_failure
+        raise Authorize::AuthorizationError, 'You are not authorized for the requested operation.'
+      end
+    end
+  end
+end

data/lib/authorize/action_view.rb

@@ -0,0 +1,4 @@
+module Authorize
+  module ActionView
+  end
+end

data/lib/authorize/active_record.rb

@@ -0,0 +1,37 @@
+module Authorize
+  module ActiveRecord
+    def self.included(recipient)
+      recipient.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def authorizable_trustee
+        include Authorize::Trustee
+        # The "identity" role -the single role that represents this trustee.  It is also the root vertex for collecting
+        # the set of roles belonging to the trustee.
+        has_one :role, :class_name => "Authorize::Role", :as => :resource, :conditions => {:relation => nil}, :dependent => :destroy
+        after_create {|trustee| trustee.create_role(:name => to_s)}
+      end
+
+      def authorizable_resource
+        include Authorize::Resource
+        has_many :permissions, :class_name => "Authorize::Permission", :as => :resource, :dependent => :delete_all
+        # The roles that represent relations/associations of a resource
+        has_many :roles, :class_name => "Authorize::Role", :as => :resource
+        reflection = reflections[:permissions]
+        auth_fk = "#{reflection.quoted_table_name}.#{connection.quote_column_name(reflection.primary_key_name)}"
+        resource_pk = "#{connection.quote_table_name(table_name)}.#{connection.quote_column_name(primary_key)}"
+        # See README file for a discussion of the performance of this named scope
+        named_scope :permitted, lambda {|*args|
+          roles, modes = *args
+          scope = Permission.as(roles)
+          scope = scope.to_do(Authorize::Permission::Mask[modes]) if modes
+          sq0 = scope.construct_finder_sql({:select => 1, :conditions => {:resource_id => nil, :resource_type => nil}})
+          sq1 = scope.construct_finder_sql({:select => 1, :conditions => {:resource_type => base_class.name, :resource_id => nil}})
+          sq2 = scope.scoped(:conditions => "#{auth_fk} = #{resource_pk}").construct_finder_sql({:select => 1, :conditions => {:resource_type => base_class.name}})
+          {:conditions => "EXISTS (#{sq0} UNION #{sq1} UNION #{sq2})"}
+        }
+      end
+    end
+  end
+end