sorcery 0.1.4 → 0.2.0

data/Gemfile

@@ -2,11 +2,13 @@ source "http://rubygems.org"
 # Add dependencies required to use your gem here.
 # Example:
 #   gem "activesupport", ">= 2.3.5"
-
+gem "rails", ">= 3.0.0"
+gem 'json', ">= 1.5.1"
+gem 'oauth', ">= 0.4.4"
+gem 'oauth2', ">= 0.1.1"
 # Add dependencies to develop your gem here.
 # Include everything needed to run rake, tests, features, etc.
 group :development do
-  gem "rails", ">= 3.0.0"
   gem "rspec", "~> 2.3.0"
   gem 'rspec-rails'
   gem 'ruby-debug19'

data/Gemfile.lock

@@ -28,29 +28,25 @@ GEM
       activemodel (= 3.0.3)
       activesupport (= 3.0.3)
     activesupport (3.0.3)
+    addressable (2.2.4)
     archive-tar-minitar (0.5.2)
     arel (2.0.6)
     builder (2.1.2)
     columnize (0.3.2)
-    cucumber (0.10.0)
-      builder (>= 2.1.2)
-      diff-lcs (~> 1.1.2)
-      gherkin (~> 2.3.2)
-      json (~> 1.4.6)
-      term-ansicolor (~> 1.0.5)
     diff-lcs (1.1.2)
     erubis (2.6.6)
       abstract (>= 1.0.0)
-    gherkin (2.3.2)
-      json (~> 1.4.6)
-      term-ansicolor (~> 1.0.5)
+    faraday (0.5.5)
+      addressable (~> 2.2.4)
+      multipart-post (~> 1.1.0)
+      rack (>= 1.1.0, < 2)
     git (1.2.5)
     i18n (0.5.0)
     jeweler (1.5.2)
       bundler (~> 1.0.0)
       git (>= 1.2.5)
       rake
-    json (1.4.6)
+    json (1.5.1)
     linecache19 (0.5.11)
       ruby_core_source (>= 0.1.4)
     mail (2.2.13)
@@ -59,6 +55,12 @@ GEM
       mime-types (~> 1.16)
       treetop (~> 1.4.8)
     mime-types (1.16)
+    multi_json (0.0.5)
+    multipart-post (1.1.0)
+    oauth (0.4.4)
+    oauth2 (0.1.1)
+      faraday (~> 0.5.0)
+      multi_json (~> 0.0.4)
     polyglot (0.3.1)
     rack (1.2.1)
     rack-mount (0.6.13)
@@ -106,7 +108,6 @@ GEM
       simplecov-html (>= 0.3.7)
     simplecov-html (0.3.9)
     sqlite3-ruby (1.3.2)
-    term-ansicolor (1.0.5)
     thor (0.14.6)
     treetop (1.4.9)
       polyglot (>= 0.3.1)
@@ -118,9 +119,11 @@ PLATFORMS
 
 DEPENDENCIES
   bundler (~> 1.0.0)
-  cucumber
   jeweler (~> 1.5.2)
-  rails (= 3.0.3)
+  json (>= 1.5.1)
+  oauth (>= 0.4.4)
+  oauth2 (>= 0.1.1)
+  rails (>= 3.0.0)
   rspec (~> 2.3.0)
   rspec-rails
   ruby-debug19

data/README.rdoc

@@ -3,28 +3,45 @@ Magical Authentication for Rails 3.
 
 Inspired by restful_authentication, Authlogic and Devise.
 Crypto code taken almost unchanged from Authlogic.
+OAuth code inspired by OmniAuth.
 
-== Example app using sorcery:
+== Summary
 
-https://github.com/NoamB/sorcery-example-app
+Sorcery aims to make your life easier by giving you an easy API to write your own user authentication flow with.
+It does this with a few goals in mind:
+
+* Less is more - less than 20 simple methods to remember for the entire feature-set make the lib easy to 'get'.
+* No built-in or generated code - use the API inside *your own* MVC structures, and don't fight to fix someone else's.
+* Magic yes, Voodoo no - the lib should be easy to hack for most developers.
+* Configuration over Confusion - Simple & short configuration as possible, not drowning in syntactic sugar.
+* Keep MVC cleanly separated - DB is for models, sessions are for controllers. Models stay unaware of sessions.
+
+Hopefully, I've achieved this. If not, let me know.
+
+== Useful Links:
+
+Example app using sorcery: https://github.com/NoamB/sorcery-example-app
+
+Documentation: http://rubydoc.info/gems/sorcery/0.1.4/frames
 
 == Full Features List by module:
 
 Core (see lib/sorcery/model/model.rb and lib/sorcery/controller/controller.rb): 
-* login/logout, optional redirect on login to where the user tried to reach before, configurable redirect for non-logged-in users.
+* login/logout, optional return user to requested url on login, configurable redirect for non-logged-in users.
 * password encryption, algorithms: bcrypt(default), md5, sha1, sha256, sha512, aes256, custom(yours!), none. Configurable stretches and salt.
 * configurable attribute names for username, password and email.
 
 User Activation (see lib/sorcery/model/submodules/user_activation.rb):
 * User activation by email with optional success email.
 * configurable attribute names.
-* configurable mailer.
+* configurable mailer, method name, and attribute name.
+* configurable temporary token expiration.
 * Optionally prevent non-active users to login.
 
 Reset Password (see lib/sorcery/model/submodules/reset_password.rb):
 * Reset password with email verification.
 * configurable mailer, method name, and attribute name.
-* configurable expiration.
+* configurable temporary token expiration.
 * configurable time between emails (hammering protection).
 
 Remember Me (see lib/sorcery/model/submodules/remember_me.rb):
@@ -49,36 +66,20 @@ Activity Logging (see lib/sorcery/model/submodules/activity_logging.rb):
 * an easy method of collecting the list of currently logged in users.
 * configurable timeout by which to decide whether to include a user in the list of logged in users.
 
-Other:
-* Modular design, load only the modules you need.
-* 100% TDD'd code, 100% test coverage.
+Oauth (see lib/sorcery/controller/submodules/oauth.rb):
+* OAuth1 and OAuth2 support (currently twitter & facebook)
+* configurable db field names and authentications table.
 
 == Next Planned Features:
 
-I've got many plans which include:
+I've got many plans which include (by priority):
+* Sinatra support
+* Mongoid support
 * Configurable Auto login on registration/activation
 * Other reset password strategies (security questions?)
 * Other brute force protection strategies (captcha)
-* Sinatra support
-* Mongoid support
-* OAuth1 and OAuth2 support
 * Have an idea? Let me know, and it might get into the gem!
 
-== Project Goals:
-
-This gem plugin was started out of a few personal goals which are not related to the problem solved by it at all:
-* I wanted to write something 100% TDD from start to finish.
-* I wanted to learn how to write an engine for Rails 3.
-
-In addition to the above goals, when I decided this will be an authentication plugin, and while looking at existing solutions, these goals came up:
-* Simple & short configuration as possible, not drowning in syntactic sugar.
-* Keep MVC cleanly separated - DB is for models, sessions are for controllers. Models stay unaware of sessions.
-* Magic yes, Voodoo no.
-* No generated code polluting the application's code.
-* No built-in controllers, models, mailers, migrations or templates; Real apps will need all of these custom made.
-
-Hopefully, I've achieved this. If not, let me know.
-
 == Installation:
 
 You can either git clone and then 'rake install' to live on the edge (unstable),

data/Rakefile

@@ -1,4 +1,5 @@
 # require 'bundler'
+# -- Commented because it's slow
 # begin
 #   Bundler.setup(:default, :development)
 # rescue Bundler::BundlerError => e
@@ -6,6 +7,8 @@
 #   $stderr.puts "Run `bundle install` to install missing gems"
 #   exit e.status_code
 # end
+# --
+
 require 'rake'
 
 require 'jeweler'
@@ -23,6 +26,8 @@ Jeweler::Tasks.new do |gem|
   #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
   #  gem.add_development_dependency 'rspec', '> 1.2.3'
   gem.add_runtime_dependency 'bcrypt-ruby', '~> 2.1.4'
+  gem.add_runtime_dependency 'oauth', '>= 0.4.4'
+  gem.add_runtime_dependency 'oauth2', '>= 0.1.1'
 end
 Jeweler::RubygemsDotOrgTasks.new
 

data/VERSION

@@ -1 +1 @@
-0.1.4
+0.2.0

data/lib/sorcery.rb

@@ -1,12 +1,14 @@
 module Sorcery
   autoload :Model, 'sorcery/model'
   module Model
+    autoload :TemporaryToken, 'sorcery/model/temporary_token'
     module Submodules
       autoload :UserActivation, 'sorcery/model/submodules/user_activation'
       autoload :ResetPassword, 'sorcery/model/submodules/reset_password'
       autoload :RememberMe, 'sorcery/model/submodules/remember_me'
       autoload :ActivityLogging, 'sorcery/model/submodules/activity_logging'
       autoload :BruteForceProtection, 'sorcery/model/submodules/brute_force_protection'
+      autoload :Oauth, 'sorcery/model/submodules/oauth'
     end
   end
   autoload :Controller, 'sorcery/controller'
@@ -17,6 +19,15 @@ module Sorcery
       autoload :BruteForceProtection, 'sorcery/controller/submodules/brute_force_protection'
       autoload :HttpBasicAuth, 'sorcery/controller/submodules/http_basic_auth'
       autoload :ActivityLogging, 'sorcery/controller/submodules/activity_logging'
+      autoload :Oauth, 'sorcery/controller/submodules/oauth'
+      module Oauth
+        autoload :Oauth1, 'sorcery/controller/submodules/oauth/oauth1'
+        autoload :Oauth2, 'sorcery/controller/submodules/oauth/oauth2'
+        module Providers
+          autoload :Twitter, 'sorcery/controller/submodules/oauth/providers/twitter'
+          autoload :Facebook, 'sorcery/controller/submodules/oauth/providers/facebook'
+        end
+      end
     end
   end
   module CryptoProviders
@@ -27,6 +38,7 @@ module Sorcery
     autoload :SHA256, 'sorcery/crypto_providers/sha256'
     autoload :SHA512, 'sorcery/crypto_providers/sha512'
   end
+  autoload :TestHelpers, 'sorcery/test_helpers'
   
   require 'sorcery/engine' if defined?(Rails) && Rails::VERSION::MAJOR == 3
 end

data/lib/sorcery/controller.rb

@@ -5,7 +5,7 @@ module Sorcery
         extend ClassMethods
         include InstanceMethods
         Config.submodules.each do |mod|
-          begin
+          begin # FIXME: is this protection needed?
             include Submodules.const_get(mod.to_s.split("_").map {|p| p.capitalize}.join("")) 
           rescue NameError
             # don't stop on a missing submodule.
@@ -32,62 +32,74 @@ module Sorcery
       # If all attempts to auto-login fail, the failure callback will be called.
       def require_login
         if !logged_in?
-          session[:user_wanted_url] = request.url if Config.save_user_wanted_url
+          session[:return_to_url] = request.url if Config.save_return_to_url
           self.send(Config.not_authenticated_action) 
         end
       end
       
+      # Takes credentials and returns a user on successful authentication.
+      # Runs hooks after login or failed login.
       def login(*credentials)
         user = Config.user_class.authenticate(*credentials)
         if user
+          return_to_url = session[:return_to_url]
           reset_session # protect from session fixation attacks
+          session[:return_to_url] = return_to_url
           login_user(user)
           after_login!(user, credentials)
-          logged_in_user
+          current_user
         else
           after_failed_login!(credentials)
           nil
         end
       end
       
+      # Resets the session and runs hooks before and after.
       def logout
         if logged_in?
-          before_logout!(logged_in_user)
+          before_logout!(current_user)
           reset_session
           after_logout!
         end
       end
       
       def logged_in?
-        !!logged_in_user
+        !!current_user
       end
       
       # attempts to auto-login from the sources defined (session, basic_auth, cookie, etc.)
       # returns the logged in user if found, false if not (using old restful-authentication trick, nil != false).
-      def logged_in_user
-        @logged_in_user ||= login_from_session || login_from_other_sources unless @logged_in_user == false
+      def current_user
+        @current_user ||= login_from_session || login_from_other_sources unless @current_user == false
       end
       
-      def login_from_other_sources
-        result = nil
-        Config.login_sources.find do |source|
-          result = send(source)
-        end
-        result || false
+      def return_or_redirect_to(url, flash_hash = {})
+        redirect_to(session[:return_to_url] || url, :flash => flash_hash)
       end
       
+      # The default action for denying non-authenticated users.
+      # You can override this method in your controllers.
       def not_authenticated
         redirect_to root_path
       end
       
       protected
       
+      # Tries all available sources (methods) until one doesn't return false.
+      def login_from_other_sources
+        result = nil
+        Config.login_sources.find do |source|
+          result = send(source)
+        end
+        result || false
+      end
+      
       def login_user(user)
         session[:user_id] = user.id
       end
       
       def login_from_session
-        @logged_in_user = (Config.user_class.find_by_id(session[:user_id]) if session[:user_id]) || false
+        @current_user = (Config.user_class.find_by_id(session[:user_id]) if session[:user_id]) || false
       end
       
       def after_login!(user, credentials)
@@ -112,11 +124,11 @@ module Sorcery
       class << self
         attr_accessor :submodules,
         
-                      :user_class,                    # what class to use as the user class.
+                      :user_class,                    # what class to use as the user class. Set automatically when you call activate_sorcery! in the User class.
                       
                       :not_authenticated_action,      # what controller action to call for non-authenticated users.
                       
-                      :save_user_wanted_url,          # when a non logged in user tries to enter a page that requires login, save the URL he wanted to reach, 
+                      :save_return_to_url,            # when a non logged in user tries to enter a page that requires login, save the URL he wanted to reach, 
                                                       # and send him there after login.
                       
                       :login_sources,
@@ -138,7 +150,7 @@ module Sorcery
             :@before_logout                        => [],
             :@after_logout                         => [],
             :@after_config                         => [],
-            :@save_user_wanted_url                 => true
+            :@save_return_to_url                   => true
           }
         end
         

data/lib/sorcery/controller/submodules/activity_logging.rb

@@ -1,6 +1,13 @@
 module Sorcery
   module Controller
     module Submodules
+      # This submodule keeps track of events such as login, logout, and last activity time, per user.
+      # It helps in estimating which users are active now in the site.
+      # This cannot be determined absolutely because a user might be reading a page without clicking anything for a while.
+      
+      # This is the controller part of the submodule, which adds hooks to register user events, 
+      # and methods to collect active users data for use in the app.
+      # see Socery::Model::Submodules::ActivityLogging for configuration options.
       module ActivityLogging
         def self.included(base)
           base.send(:include, InstanceMethods)
@@ -10,33 +17,39 @@ module Sorcery
         end
         
         module InstanceMethods
-          def logged_in_users
-            Config.user_class.logged_in_users
+          # Returns an array of the active users.
+          def current_users
+            Config.user_class.current_users
             # A possible patch here:
-            # we'll add the logged_in_user to the users list if he's not in it (can happen when he was inactive for more than activity timeout):
+            # we'll add the current_user to the users list if he's not in it (can happen when he was inactive for more than activity timeout):
             #
-            #   users.unshift!(logged_in_user) if logged_in? && users.find {|u| u.id == logged_in_user.id}.nil?
+            #   users.unshift!(current_user) if logged_in? && users.find {|u| u.id == current_user.id}.nil?
             #
             # disadvantages: can hurt performance.
           end
           
           protected
           
+          # registers last login time on every login.
+          # This runs as a hook just after a successful login.
           def register_login_time_to_db(user, credentials)
             user.send(:"#{user.sorcery_config.last_login_at_attribute_name}=", Time.now.utc.to_s(:db))
             user.save!(:validate => false)
           end
           
+          # registers last logout time on every logout.
+          # This runs as a hook just before a logout.
           def register_logout_time_to_db(user)
             user.send(:"#{user.sorcery_config.last_logout_at_attribute_name}=", Time.now.utc.to_s(:db))
             user.save!(:validate => false)
           end
           
-          # we do not update activity on logout
+          # Updates last activity time on every request.
+          # The only exception is logout - we do not update activity on logout
           def register_last_activity_time_to_db
             return if !logged_in?
-            logged_in_user.send(:"#{logged_in_user.sorcery_config.last_activity_at_attribute_name}=", Time.now.utc.to_s(:db))
-            logged_in_user.save!(:validate => false)
+            current_user.send(:"#{current_user.sorcery_config.last_activity_at_attribute_name}=", Time.now.utc.to_s(:db))
+            current_user.save!(:validate => false)
           end
         end
       end

data/lib/sorcery/controller/submodules/brute_force_protection.rb

@@ -1,6 +1,9 @@
 module Sorcery
   module Controller
     module Submodules
+      # This module helps protect user accounts by locking them down after too many failed attemps to login were detected.
+      # This is the controller part of the submodule which takes care of updating the failed logins and resetting them.
+      # See Sorcery::Model::Submodules::BruteForceProtection for configuration options.
       module BruteForceProtection
         def self.included(base)
           base.send(:include, InstanceMethods)
@@ -13,13 +16,17 @@ module Sorcery
           
           protected
           
+          # Increments the failed logins counter on every failed login.
+          # Runs as a hook after a failed login.
           def update_failed_logins_count!(credentials)
-            user = User.where("#{User.sorcery_config.username_attribute_name} = ?", credentials[0]).first
+            user = Config.user_class.where("#{Config.user_class.sorcery_config.username_attribute_name} = ?", credentials[0]).first
             user.register_failed_login! if user
           end
           
+          # Resets the failed logins counter.
+          # Runs as a hook after a successful login.
           def reset_failed_logins_count!(user, credentials)
-            user.update_attributes!(User.sorcery_config.failed_logins_count_attribute_name => 0)
+            user.update_attributes!(Config.user_class.sorcery_config.failed_logins_count_attribute_name => 0)
           end
         end
       end