nbrew-simple_access_control 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+.DS_Store
+.svn
+pkg
+nbrew-simple_access_control.gemspec

data/README

@@ -0,0 +1,162 @@
+SimpleAccessControl
+===================
+
+Acknowledgements: I give all credit to Ezra and Technoweenie for their two plugins which
+inspired the interface design and a lot of the code for this one.
+
+SimpleAccessControl is a streamlined, intuitive authorisation system. It derives heavily from
+acl_system2 and has made clear some problems which plagued me when first using it. Some
+fixes to acl_system2's design:
+
+      * a normal Rails syntax:
+            access_rule 'admin', :only => :index
+            access_rule '(moderator || admin)', :only => :new
+      * error handling for helper methods (permit? bombed when current_user == nil)
+      * one-line parser, easy to replace or alter
+      * proper before_filter usage, meaning access rules are parsed only when needed
+      * no overrideable default (which I found counter-intuitive in the end)
+
+Also, it has two methods, access_control and permit?, for those moving from acl_system2.
+
+But, let me stress, everyone likes a slightly different system, so this one may not be
+your style. I find it synchronises very well with the interface of Acts as Authenticated (even
+though I have modified it so much that it's now called Authenticated Cookie).
+
+INSTALLATION
+============
+
+Create the following migration:
+
+  create_table "roles", :force => true do |t|
+    t.column "title", :string
+  end
+  create_table "roles_users", :id => false, :force => true do |t|
+    t.column "role_id", :integer
+    t.column "user_id", :integer
+  end
+
+In your User model, you must have:
+
+  has_and_belongs_to_many :roles
+
+In your Roles model, you must have:
+
+  has_and_belongs_to_many :users
+
+Your controllers must have the following two methods or variants of them:
+
+  # Returns a User object
+  def current_user
+    @current_user
+  end
+
+  # Returns true or false if a User object exists for this session
+  def logged_in?
+    @current_user.is_a? User
+  end
+
+
+SPECIAL NEEDS
+=============
+
+If you want to permit anonymous users without demanding that they are logged in, first you
+must ensure that logged_in? returns true in all cases, otherwise permission will be denied.
+The following approach should work:
+
+1. Create the 'guest' and 'user' roles, e.g.:
+
+  guest = Role.create(:title => 'guest')
+  user = Role.create(:title => 'user')
+
+2. In your registration/user creation area, ensure all real users have the 'user' role, e.g.:
+
+  @user = User.create(params[:user])
+  unless @user.roles.any? { |r| r.title == 'user' }
+    @user.roles << Role.find_by_title('user')
+  end
+  @user.save
+
+[At this point you have two options: a real or virtual anonymous account]
+
+First Approach: Real Anonymous User
+
+  3a. Create an anonymous user, e.g.:
+
+    @anonymous = User.create(:login => 'anonymous', :password => '*', :activated => true)
+
+  4a. Add the role to the Anonymous user (in a migration or in script/console), e.g.:
+
+    anonymous.roles << Role.find_by_title('guest')
+    anonymous.save
+
+  5a. In your ApplicationController, set unauthenticated users as 'anonymous', e.g.:
+
+    before_filter :default_to_guest
+
+    def default_to_guest
+      self.current_user = User.find_by_login('anonymous', :include => :roles) unless logged_in?
+    end
+
+
+Second Approach: Virtual Anonymous User
+
+  3a. In your ApplicationController, create a virtual anonymous account if unauthenticated:
+
+    before_filter :default_to_virtual_guest
+    def default_to_virtual_guest
+      self.current_user = self.anonymous_user unless logged_in?
+    end
+
+    def anonymous_user
+      anonymous = User.new(:login => 'anonymous', :name => 'Guest')
+      anonymous.roles << Role.new(:title => 'guest')
+      anonymous.readonly!
+      anonymous
+    end
+
+
+USAGE
+=====
+
+The plugin is automatically hooked into ActionController::Base.
+
+In your controllers, add access rules like so:
+
+  access_rule 'admin', :only => :destroy
+  access_rule 'user || admin', :only => [:new, :create, :edit, :update]
+
+Note the use of Ruby-style operators. These strings are real conditionals and should be treated as
+such. Every grouping of non-operator characters will be considered a role title.
+
+In your views, you can use the following:
+
+  <% restrict_to 'admin || moderator' do %>
+    <%= link_to "Admin Area", admin_area_url %>
+  <% end %>
+
+AND
+
+  <%= link_to("Admin Area", admin_area_url) if has_permission?('admin || moderator') %>
+
+There are also transitional methods which help you move from acl_system2 to this plugin -- I do this
+not to denegrate acl_system2 but because I did this for myself and decided to include it. The two
+systems are rather similar.
+
+Also, there are two callbacks, permission_granted and permission_denied, which may define in your
+controllers to customise their response. For example:
+
+  def permission_granted
+    logger.info("[authentication] Permission granted to %s at %s for %s" %
+      [(logged_in? ? current_user.login : 'guest'), Time.now, request.request_uri])
+  end
+
+  def permission_denied
+    logger.info("[authentication] Permission denied to %s at %s for %s" %
+      [(logged_in? ? current_user.login : 'guest'), Time.now, request.request_uri])
+  end
+
+
+That's it!
+
+
+VARIATION BY MABS29

data/Rakefile

@@ -0,0 +1,43 @@
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "nbrew-simple_access_control"
+    gem.summary = %Q{Simple role-based access control plugin for Rails controllers and views.}
+    gem.description = %Q{Simple access controls for use with ActsAsAuthenticated, RestfulAuthentication, etc. A clone of Mathew Abonyi's (mabs29) repo: http://mabs29.googlecode.com/svn/trunk/plugins/simple_access_control}
+    gem.email = "nhyde@bigdrift.com"
+    gem.homepage = "http://github.com/nbrew/simple_access_control"
+    gem.authors = ["Mathew Abonyi"]
+    gem.add_development_dependency "shoulda", ">= 0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+
+desc 'Default: run unit tests.'
+task :test => :check_dependencies
+task :default => :test
+
+desc 'Test the simple_access_control plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the simple_access_control plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'SimpleAccessControl'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/install.rb

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

data/lib/simple_access_control.rb

@@ -0,0 +1,128 @@
+# SimpleAccessControl
+#
+# Acknowledgements: I give all credit to Ezra and Technoweenie for their two plugins which
+# inspired the interface design and a lot of the code for this one.
+#
+# SimpleAccessControl is a streamlined, intuitive authorisation system. It derives heavily from
+# acl_system2 and has made clear some problems which plagued the author when first using it. Some
+# fixes to acl_system2's design:
+#
+#       * a normal Rails syntax:
+#             access_rule 'admin', :only => :index
+#             access_rule '(moderator || admin)', :only => :new
+#       * error handling for helper methods (permit? bombs out with current_user == nil)
+#       * one-line parser, easy to replace or alter
+#       * proper before_filter usage, meaning access rules are parsed only when needed
+#       * no overrideable default (which I found counter-intuitive in the end)
+# 
+# Also, it has two methods, access_control and permit?, for those moving from acl_system2.
+#
+# But, let me stress, everyone likes a slightly different system, so this one may not be
+# your style. I find it synchronises very well with the interface of Acts as Authenticated (even
+# though I have modified it so much that it's now called Authenticated Cookie).
+#
+module SimpleAccessControl
+
+  def self.included(base)
+    base.extend(ClassMethods)
+    if base.respond_to?(:helper_method)
+      base.send :helper_method, :restrict_to
+      base.send :helper_method, :has_permission?
+      base.send :helper_method, :permit?
+    end
+  end
+  
+  module ClassMethods
+
+    # Support for acl_system2 migration
+    def access_control(ruleset = {})
+      ruleset.each do |actions, rule|
+        case actions
+        when :DEFAULT
+          access_rule rule
+        when Array, Symbol, String
+          access_rule rule, :only => actions
+        end
+      end
+    end
+
+    # This is the core of the filtering system and it couldn't be simpler:
+    #     access_rule '(admin || moderator)', :only => [:edit, :update]
+    def access_rule(rule, filter_options = {})
+      before_filter (filter_options||{}) { |c| c.send :permission_required, rule }
+    end
+  end
+  
+  protected
+
+  # As in AAA you have login_required, here you have permission_required. Pass it a
+  # rule and it will use SimpleAccessControl#has_permission? to evaluate against the
+  # current user. Use SimpleAccessControl#has_permission? if you are not guarding an
+  # action or whole controller. An empty or nil rule will always return true.
+  #     permission_required('admin')
+  def permission_required(rule = nil)
+    if respond_to?(:logged_in?) && logged_in? && has_permission?(rule)
+      send(:permission_granted) if respond_to?(:permission_granted)
+      true
+    else
+      send(:permission_denied) if respond_to?(:permission_denied)
+      false
+    end
+  end
+
+  # For use in both controllers and views.
+  #     has_permission?('role')
+  #     has_permission?('admin', other_user)
+  def has_permission?(rule, user = nil)
+    user ||= (send(:current_user) if respond_to?(:current_user)) || nil
+    access_controller.process(rule, user)
+  end
+  
+  # For those of you converting from acl_system2
+  def permit?(rule, context = {})
+    has_permission?(rule, (context && context[:user] ? context[:user] : nil))
+  end
+
+  # A much shortened version of Ezra's acl_system2 version.
+  #     restrict_to "admin | moderator" do
+  #       link_to "foo"
+  #     end
+  def restrict_to(rule, user = nil)
+    yield if block_given? && has_permission?(rule, user)
+  end
+
+  def access_controller #:nodoc:
+    @access_controller ||= AccessControlHandler.new
+  end
+
+  # A dramatically simpler version than that found in acl_system2
+  # It is SLOWER because it uses instance_eval to analyse the conditional, but it's DRY.
+  class AccessControlHandler
+
+    # Takes a string (which may be a complex conditional string or a single word as a string
+    # or symbol) and checks if the user has those roles
+    def process(string, user)
+      return(check('', user)) if string.blank?
+      if string =~ /^([^()\|&!]+)$/ then check($1, user) # it is simple enough to just pump through
+      else instance_eval("!! (#{parse(string)})") # give it the going-over
+      end
+    end
+
+    # Super-simple parsing, turning single or multiple & and | into && and ||. Wraps all the roles
+    # in a check call to be evaluated.
+    def parse(string)
+      string.gsub(/(\|+|\&+)/) { $1[0,1]*2 }.gsub(/([^()|&! ]+)/) { "check('#{$1}', user)" }
+    end
+
+    # The heart of the system, all credit to Ezra for the original algorithm
+    # Defaults to false if there is no user or that user does not have a roles association
+    # Defaults to true if the role is blank
+    def check(role, user)
+      return(false) if user.blank? || !user.respond_to?(:roles)
+      return(true) if role.blank?
+      user.roles.map{ |r| r.title.downcase }.include? role.downcase
+    end
+
+  end
+
+end

data/lib/tasks/simple_access_control_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :simple_access_control do
+#   # Task goes here
+# end

data/rails/init.rb

@@ -0,0 +1,3 @@
+require_dependency 'simple_access_control'
+
+ActionController::Base.send :include, SimpleAccessControl

data/test/helper.rb

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'simple_access_control'
+
+class Test::Unit::TestCase
+end

data/test/simple_access_control_test.rb

@@ -0,0 +1,8 @@
+require 'test/helper'
+
+class SimpleAccessControlTest < Test::Unit::TestCase
+  # Replace this with your real tests.
+  should "probably rename this file and start testing for real" do
+    flunk "hey buddy, you should probably rename this file and start testing for real"
+  end
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification 
+name: nbrew-simple_access_control
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Mathew Abonyi
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-07-12 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: shoulda
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+description: "Simple access controls for use with ActsAsAuthenticated, RestfulAuthentication, etc. A clone of Mathew Abonyi's (mabs29) repo: http://mabs29.googlecode.com/svn/trunk/plugins/simple_access_control"
+email: nhyde@bigdrift.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- .gitignore
+- README
+- Rakefile
+- VERSION
+- install.rb
+- lib/simple_access_control.rb
+- lib/tasks/simple_access_control_tasks.rake
+- rails/init.rb
+- test/helper.rb
+- test/simple_access_control_test.rb
+has_rdoc: true
+homepage: http://github.com/nbrew/simple_access_control
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Simple role-based access control plugin for Rails controllers and views.
+test_files: 
+- test/helper.rb
+- test/simple_access_control_test.rb