lockdown 1.6.5 → 2.0.0

data/.gitignore

@@ -1,5 +1,6 @@
 *.DS_Store
 *.swp
+.yardoc/**
 pkg/**
 doc/**
 email.txt

data/README.txt

@@ -1,10 +1,13 @@
-lockdown
-    by Andrew Stone
-    http://stonean.com
-
 == DESCRIPTION:
 
-Lockdown is an authorization system for RubyOnRails (ver >= 2.1).
+Lockdown is an authorization system for RubyOnRails (ver >= 3.0).
+
+
+Version 3.0 of Lockdown will be a Rails 3 compatible rewrite.  I'm going to take some of the discoveries from Monty (my Rack based authorization project) and roll them into Lockdown.
+
+The model level interaction will be redone completely.  It sucks right now.
+
+Follow me on Twitter (@stonean) to keep up to date.
 
 == INSTALL:
 

data/Rakefile

@@ -1,38 +1,55 @@
 require 'rubygems'
 require 'rake'
-require 'rcov'
-require 'spec/rake/spectask'
 
-require 'lib/lockdown.rb'
-task :default => 'rcov'
+require File.join(File.dirname(__FILE__), "lib", "lockdown")
 
-desc "Flog your code for Justice!"
-task :flog do
-    sh('flog lib/**/*.rb')
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "lockdown"
+    gem.version = Lockdown.version
+    gem.rubyforge_project = "lockdown"
+    gem.summary = "Authorization system for Rails 2.x"
+    gem.description = "Restrict access to your controller actions.  Supports basic model level restrictions as well"
+    gem.email = "andy@stonean.com"
+    gem.homepage = "http://stonean.com/wiki/lockdown"
+    gem.authors = ["Andrew Stone"]
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
 end
 
-desc "Run all specs and rcov in a non-sucky way"
-Spec::Rake::SpecTask.new(:rcov) do |t|
-  t.spec_opts = IO.readlines("spec/spec.opts").map {|l| l.chomp.split " "}.flatten
-  t.spec_files = FileList['spec/**/*_spec.rb']
-  t.rcov = true
-  t.rcov_opts = IO.readlines("spec/rcov.opts").map {|l| l.chomp.split " "}.flatten
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new do |t|
+    t.files   = FileList['lib/**/*.rb']
+    t.options = ['-r'] # optional
+  end
+rescue LoadError
+  task :yard do
+    abort "YARD is not available. In order to run yard, you must: sudo gem install yard"
+  end
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
 end
 
 begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gemspec|
-    gemspec.name = "lockdown"
-    gemspec.version = Lockdown.version
-    gemspec.rubyforge_project = "lockdown"
-    gemspec.summary = "Authorization system for Rails 2.x"
-    gemspec.description = "Restrict access to your controller actions.  Supports basic model level restrictions as well"
-    gemspec.email = "andy@stonean.com"
-    gemspec.homepage = "http://stonean.com/wiki/lockdown"
-    gemspec.authors = ["Andrew Stone"]
-    gemspec.add_development_dependency('rspec')
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
   end
-  Jeweler::GemcutterTasks.new
 rescue LoadError
-  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install rcov"
+  end
 end
+
+task :default => 'test'

data/lib/lockdown/access.rb

@@ -0,0 +1,108 @@
+# encoding: utf-8
+
+module Lockdown
+  module Access
+    # Define permision that defines how your application is accessed. 
+    #     # All methods on the site resource will be open to users who have
+    #     # this permission.
+    #     permission :public_pages do
+    #       resource :site
+    #     end
+    #
+    #     # Can use multiple resource statements
+    #     permission :public_pages do
+    #       resource :site
+    #       resource :posts
+    #     end
+    #
+    #     # Only methods show, edit and update on the users resource will 
+    #     # be open to users who have this permission.
+    #     permission :my_account_pages do
+    #       resource :users  do
+    #         only :show, :edit, :update
+    #       end
+    #     end
+    #
+    #     # All methods except destroy on the users resource will be 
+    #     # open to users who have this permission.
+    #     permission :manage_users do
+    #       resource :users  do
+    #         except :destroy
+    #       end
+    #     end
+    #
+    # @param [String,Symbol] name permission reference. 
+    # @yield [Lockdown::Permission.new(name)] new permission object
+    def permission(name, &block)
+      permission =  Lockdown::Permission.new(name)   
+      if block_given?
+        permission.instance_eval(&block) 
+      else
+        permission.resource(permission.name)
+      end
+
+      unless Lockdown::Configuration.has_permission?(permission)
+        Lockdown::Configuration.permissions << permission 
+      end
+
+      permission
+    end
+
+    # Define which permissions are accessible to everyone
+    #   public_access :site, :user_registration
+    #
+    # @param *[String,Symbol] permissions that are accessible to everyone
+    def public_access(*permissions)
+      permissions.each do |name|
+        Lockdown::Configuration.make_permission_public(name)
+      end
+
+      Lockdown::Configuration.public_access = regexes(permissions)
+    end
+
+    # Define which permissions are accessible to everyone
+    #   protected_access :my_account, :site_administration
+    #
+    # @param *[String,Symbol] permissions that are accessbile to authenticated users
+    def protected_access(*permissions)
+      permissions.each do |name|  
+        Lockdown::Configuration.make_permission_protected(name)
+      end
+
+      Lockdown::Configuration.protected_access = regexes(permissions)
+    end
+
+    # Create user group by giving it a name and a list of permission names.
+    # @param [String, Array] user group name, permission names
+    def user_group(name, *permissions)
+      return if permissions.empty?
+      name = name.to_s
+      ug = Lockdown::Configuration.find_or_create_user_group(name)
+
+      permissions.each do |name|
+        if (perm = Lockdown::Configuration.permission(name))
+          ug.permissions << perm unless ug.permissions.include?(perm)
+        end
+      end
+
+      Lockdown::Configuration.maybe_add_user_group(ug)
+    end
+
+    # Method called by Lockdown::Delivery to trigger parsing of class methods
+    def configure
+      unless Lockdown::Configuration.configured
+        Lockdown::Database.sync_with_db unless Lockdown::Configuration.skip_sync?
+        Lockdown::Configuration.configured = true
+      end
+    end
+
+    private
+
+    def regexes(permissions)
+      permissions.collect!{|p| p.to_s}
+      perms = Lockdown::Configuration.permissions.select{|p| permissions.include?(p.name)}
+      perms.collect{|p| p.regex_pattern}.join("|")
+    end
+
+  end # Access
+end # Lockdown

data/lib/lockdown/configuration.rb

@@ -0,0 +1,201 @@
+# encoding: utf-8
+
+module Lockdown
+  module Configuration
+    class << self
+      # Flag to determine if configuration method has been executed
+      # Default false
+      attr_accessor :configured
+      # Regex string of paths that are publicly accessible. 
+      # Default "\/"
+      attr_accessor :public_access
+      # Array of paths that are restricted to an authenticated user.
+      # Default ""
+      attr_accessor :protected_access
+      # Array of permission objects that defines the access to the application.
+      # Default []
+      attr_accessor :permissions
+      # Array of user group objects
+      # Default []
+      attr_accessor :user_groups
+      # Method used to get the id of the user responsible for 
+      # the current action.
+      # Default :current_user_id
+      attr_accessor :who_did_it
+      # User id to associate to system actions
+      # Default 1
+      attr_accessor :default_who_did_it
+      # Path to redirect to if access is denied.
+      # Default: '/'
+      attr_accessor :access_denied_path
+      # Redirect to path on successful login
+      # Default "/"
+      attr_accessor :successful_login_path
+      # Logout user if attempt to access restricted resource
+      # Default false
+      attr_accessor :logout_on_access_violation
+      # When using the links helper, this character will be 
+      # used to separate the links.
+      # Default "|"
+      attr_accessor :link_separator
+      # The model used to represent the grouping of permisssion. Common
+      # choices are 'Role' and 'UserGroup'.
+      # Default "UserGroup"
+      attr_accessor :user_group_model
+      # The model used to represent the user. Common choices 
+      # are 'User' and 'Person'.
+      # Default "User"
+      attr_accessor :user_model
+      # Which environments Lockdown should not sync with db
+      # Default ['test']
+      attr_accessor :skip_db_sync_in
+      # Set defaults.
+      def reset
+        @configured                   = false
+        @public_access                = ""
+        @protected_access             = ""
+        @permissions                  = []
+        @user_groups                  = []
+
+        @who_did_it                   = :current_user_id
+        @default_who_did_it           = 1
+
+        @access_denied_path           = "/"
+        @successful_login_path        = "/"
+        @logout_on_access_violation   = false
+
+        @link_separator               = "|"
+
+        @user_group_model             = "UserGroup"
+        @user_model                   = "User"
+
+        @skip_db_sync_in              = ['test']
+      end
+
+      # @return [String] concatentation of public_access + "|" + protected_access
+      def authenticated_access
+        public_access + "|" + protected_access
+      end
+
+      # @param [String,Symbol] name permission name
+      # @return Lockdown::Permission object 
+      def permission(name)
+        name = name.to_s
+        perm = permissions.detect{|perm| name == perm.name}
+        raise Lockdown::PermissionNotFound.new("Permission: #{name} not found") unless perm
+        perm
+      end
+
+      # Defines the permission as public
+      # @param [String,Symbol] name permission name
+      def make_permission_public(name)
+        permission(name).is_public
+      end
+
+      # Defines the permission as protected
+      # @param [String,Symbol] name permission name
+      def make_permission_protected(name)
+        permission(name).is_protected
+      end
+
+      # @return Array of permission names
+      def permission_names
+        permissions.collect{|p| p.name}
+      end
+
+      # @param [Lockdown::Permission] permission Lockdown::Permission object
+      # @return [true|false] true if object exists with same name
+      def has_permission?(permission)
+        permissions.any?{|p| permission.name == p.name}
+      end
+
+      # @param [String|Symbol] name permission name
+      # @return [true|false] true if permission is either public or protected
+      def permission_assigned_automatically?(name)
+        name = name.to_s
+
+        perm = permission(name)
+
+        perm.public? || perm.protected?
+      end
+
+      # @param [String,Symbol] name user group name
+      # @return [Lockdown::UserGroup] object 
+      def user_group(name)
+        name = name.to_s
+        user_groups.detect{|ug| name == ug.name}
+      end
+
+      def maybe_add_user_group(group)
+        @user_groups << group unless user_group_names.include?(group.name)
+      end
+
+      # @return [Lockdown::UserGroup] 
+      def find_or_create_user_group(name)
+        name = name.to_s
+        user_group(name) || Lockdown::UserGroup.new(name)
+      end
+
+      # @return [Array] names
+      def user_group_names
+        user_groups.collect{|ug| ug.name}
+      end
+
+      # @param [String] name user group name
+      # @return [Array] permissions names 
+      def user_group_permissions_names(name)
+        user_group(name).permissions.collect{|p| p.name}
+      end
+
+      # @return [True|False] true if user has 'Administrators' group 
+      def administrator?(user)
+        user_has_user_group?(user, Lockdown.administrator_group_name)
+      end
+
+      # @param [User] user User object you want to make an administrator
+      def make_user_administrator(user)
+        user_groups = user.send(Lockdown.user_groups_hbtm_reference)
+        user_groups << Lockdown.user_group_class.
+          find_or_create_by_name(Lockdown.administrator_group_name)
+      end
+
+
+      # @param [User, String] user,name  user model, name of user group
+      # @return [True|False] true if user has user group with name
+      def user_has_user_group?(user, name)
+        user_groups = user.send(Lockdown.user_groups_hbtm_reference)
+        user_groups.any?{|ug| name == ug.name}
+      end
+
+      # @return [Regex] 
+      def access_rights_for_user(user)
+        return unless user
+        return Lockdown::Resource.regex if administrator?(user)
+
+        user_groups = user.send(Lockdown.user_groups_hbtm_reference)
+
+        permission_names = []
+
+        user_groups.each do |ug|
+          ug.permissions.each do |p|
+            permission_names << p.name
+          end
+        end
+
+        authenticated_access + "|" + access_rights_for_permissions(*permission_names)
+      end
+
+      # @param [Array(String)] names permission names
+      # @return [String] combination of regex_patterns from permissions
+      def access_rights_for_permissions(*names)
+        names.collect{|name| "(#{permission(name).regex_pattern})"}.join('|')
+      end
+
+      def skip_sync?
+        true
+      end
+    end # class block
+
+    self.reset
+  end # Configuration
+end # Lockdown

data/lib/lockdown/database.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 module Lockdown
   class Database
     class << self
@@ -6,32 +8,29 @@ module Lockdown
       # an interface for each the different orm implementations. 
       # We'll see how it works...
       def sync_with_db
-
-        @permissions = Lockdown::System.get_permissions
-        @user_groups = Lockdown::System.get_user_groups
+        @permissions = Lockdown::Configuration.permission_names
+        @user_groups = Lockdown::Configuration.user_group_names
 
         unless ::Permission.table_exists? && Lockdown.user_group_class.table_exists?
           Lockdown.logger.info ">> Lockdown tables not found.  Skipping database sync."
           return
         end
+
         create_new_permissions
 
         delete_extinct_permissions
       
         maintain_user_groups
-      rescue Exception => e
-        Lockdown.logger.error ">> Lockdown sync failed: #{e.backtrace.join("\n")}" 
       end
 
       # Create permissions not found in the database
       def create_new_permissions
-        @permissions.each do |key|
-          next if Lockdown::System.permission_assigned_automatically?(key)
-          str = Lockdown.get_string(key)
-          p = ::Permission.find(:first, :conditions => ["name = ?", str])
+        @permissions.each do |name|
+          next if Lockdown::Configuration.permission_assigned_automatically?(name)
+          p = ::Permission.find(:first, :conditions => ["name = ?", name])
           unless p
-            Lockdown.logger.info ">> Lockdown: Permission not found in db: #{str}, creating."
-            ::Permission.create(:name => str)
+            Lockdown.logger.info ">> Lockdown: Permission not found in db: #{name}, creating."
+            ::Permission.create(:name => name)
           end
         end
       end
@@ -40,7 +39,7 @@ module Lockdown
       def delete_extinct_permissions
         db_perms = ::Permission.find(:all).dup
         db_perms.each do |dbp|
-          unless @permissions.include?(Lockdown.get_symbol(dbp.name))
+          unless @permissions.include?(dbp.name)
             Lockdown.logger.info ">> Lockdown: Permission no longer in init.rb: #{dbp.name}, deleting."
           ug_table = Lockdown.user_groups_hbtm_reference.to_s
           if "permissions" < ug_table
@@ -56,33 +55,32 @@ module Lockdown
 
       def maintain_user_groups
         # Create user groups not found in the database
-        @user_groups.each do |key|
-          str = Lockdown.get_string(key)
-          unless ug = Lockdown.user_group_class.find(:first, :conditions => ["name = ?", str])
-            create_user_group(str, key)
+        @user_groups.each do |name|
+          unless ug = Lockdown.user_group_class.find(:first, :conditions => ["name = ?", name])
+            create_user_group(name)
           else
             # Remove permissions from user group not found in init.rb
-            remove_invalid_permissions(ug, key)
+            remove_invalid_permissions(ug)
 
             # Add in permissions from init.rb not found in database
-            add_valid_permissions(ug, key)
+            add_valid_permissions(ug)
           end
         end
       end
 
-      def create_user_group(name_str, key)
-        Lockdown.logger.info ">> Lockdown: #{Lockdown::System.fetch(:user_group_model)} not in the db: #{name_str}, creating."
-        ug = Lockdown.user_group_class.create(:name => name_str)
+      def create_user_group(name)
+        Lockdown.logger.info ">> Lockdown: #{Lockdown::Configuration.user_group_model} not in the db: #{name}, creating."
+        ug = Lockdown.user_group_class.create(:name => name)
         #Inefficient, definitely, but shouldn't have any issues across orms.
         #
-        Lockdown::System.permissions_for_user_group(key).each do |perm|
+        Lockdown::Configuration.user_group_permissions_names(name).each do |perm|
 
-          if Lockdown::System.permission_assigned_automatically?(perm)
-            Lockdown.logger.info  ">> Permission #{perm} cannot be assigned to #{name_str}.  Already belongs to built in user group (public or protected)."
+          if Lockdown::Configuration.permission_assigned_automatically?(perm)
+            Lockdown.logger.info  ">> Permission #{perm} cannot be assigned to #{name}.  Already belongs to built in user group (public or protected)."
             raise  InvalidPermissionAssignment, "Invalid permission assignment"
           end
 
-          p = ::Permission.find(:first, :conditions => ["name = ?", Lockdown.get_string(perm)]) 
+          p = ::Permission.find(:first, :conditions => ["name = ?", perm]) 
 
           ug_table = Lockdown.user_groups_hbtm_reference.to_s
           if "permissions" < ug_table
@@ -94,29 +92,26 @@ module Lockdown
         end
       end
 
-      def remove_invalid_permissions(ug, key)
+      def remove_invalid_permissions(ug)
         ug.permissions.each do |perm|
-          perm_sym = Lockdown.get_symbol(perm)
-          perm_string = Lockdown.get_string(perm)
-          unless Lockdown::System.permissions_for_user_group(key).include?(perm_sym)
-            Lockdown.logger.info ">> Lockdown: Permission: #{perm_string} no longer associated to User Group: #{ug.name}, deleting."
+          unless Lockdown::Configuration.user_group_permissions_names(ug.name).include?(perm.name)
+            Lockdown.logger.info ">> Lockdown: Permission: #{perm.name} no longer associated to User Group: #{ug.name}, deleting."
             ug.permissions.delete(perm)
           end
         end
       end
 
-      def add_valid_permissions(ug, key)
-        Lockdown::System.permissions_for_user_group(key).each do |perm|
-          perm_string = Lockdown.get_string(perm)
+      def add_valid_permissions(ug)
+        Lockdown::Configuration.user_group_permissions_names(ug.name).each do |perm_name|
           found = false
           # see if permission exists
           ug.permissions.each do |p|
-            found = true if Lockdown.get_string(p) == perm_string 
+            found = true if p.name == perm_name
           end
           # if not found, add it
           unless found
-            Lockdown.logger.info ">> Lockdown: Permission: #{perm_string} not found for User Group: #{ug.name}, adding it."
-            p = ::Permission.find(:first, :conditions => ["name = ?", perm_string])
+            Lockdown.logger.info ">> Lockdown: Permission: #{perm_name} not found for User Group: #{ug.name}, adding it."
+            p = ::Permission.find(:first, :conditions => ["name = ?", perm_name])
             ug.permissions << p
           end
         end

data/lib/lockdown/delivery.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+
+module Lockdown
+  class Delivery
+    class << self
+      # @return [true|false] if the given path is allowed
+      def allowed?(path, access_rights = nil)
+        return true if path == '/'
+
+        begin
+          ::Authorization.configure
+        rescue NameError
+        end
+
+        access_rights ||= Lockdown::Configuration.public_access
+
+        access_rights_regex = Lockdown.regex(access_rights)
+
+        path += "/" unless path =~ /\/$/
+        path = "/" + path unless path =~ /^\//
+        
+        access_rights_regex =~ path ? true : false
+      end
+    end # class block
+  end # Delivery
+end # Lockdown

data/lib/lockdown/errors.rb

@@ -1,11 +1,7 @@
-module Lockdown
-  class InvalidRuleAssignment < StandardError; end
-
-  class InvalidRuleContext < StandardError; end
+# encoding: utf-8
 
-  class PermissionScopeCollision < StandardError; end
+module Lockdown
+  class PermissionNotFound < StandardError; end
 
   class InvalidPermissionAssignment < StandardError; end
-
-  class GroupUndefinedError < StandardError; end
 end