sorcery 0.1.4 → 0.3.0

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

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

@@ -1,6 +1,9 @@
 module Sorcery
   module Controller
     module Submodules
+      # This submodule integrates HTTP Basic authentication into sorcery.
+      # You are provided with a before filter, require_login_from_http_basic, which requests the browser for authentication.
+      # Then the rest of the submodule takes care of logging the user in into the session, so that the next requests will keep him logged in.
       module HttpBasicAuth
         def self.included(base)
           base.send(:include, InstanceMethods)
@@ -31,25 +34,31 @@ module Sorcery
           def require_login_from_http_basic
             (request_http_basic_authentication(realm_name_by_controller) and (session[:http_authentication_used] = true) and return) if (request.authorization.nil? || session[:http_authentication_used].nil?)
             require_login
+            session[:http_authentication_used] = nil unless logged_in?
           end
           
           # given to main controller module as a login source callback
           def login_from_basic_auth
             authenticate_with_http_basic do |username, password|
-              @logged_in_user = (Config.user_class.authenticate(username, password) if session[:http_authentication_used]) || false
-              login_user(@logged_in_user) if @logged_in_user
-              @logged_in_user
+              @current_user = (Config.user_class.authenticate(username, password) if session[:http_authentication_used]) || false
+              login_user(@current_user) if @current_user
+              @current_user
             end
           end
           
+          # Sets the realm name by searching the controller name in the hash given at configuration time.
           def realm_name_by_controller
-            current_controller = self.class
-            while current_controller != ActionController::Base
-              result = Config.controller_to_realm_map[current_controller.controller_name]
-              return result if result
-              current_controller = self.class.superclass
+            if defined?(ActionController::Base)
+              current_controller = self.class
+              while current_controller != ActionController::Base
+                result = Config.controller_to_realm_map[current_controller.controller_name]
+                return result if result
+                current_controller = self.class.superclass
+              end
+              nil
+            else
+              Config.controller_to_realm_map["application"]
             end
-            nil
           end
           
         end

data/lib/sorcery/controller/submodules/oauth/oauth1.rb

@@ -0,0 +1,33 @@
+require 'oauth'
+module Sorcery
+  module Controller
+    module Submodules
+      module Oauth
+        module Oauth1
+          def oauth_version
+            "1.0"
+          end
+          
+          def get_request_token(token=nil,secret=nil)
+            return ::OAuth::RequestToken.new(get_consumer,token,secret) if token && secret
+            get_consumer.get_request_token(:oauth_callback => @callback_url)
+          end
+          
+          def authorize_url(args)
+            get_request_token(args[:request_token],args[:request_token_secret]).authorize_url(:oauth_callback => @callback_url)
+          end
+          
+          def get_access_token(args)
+            get_request_token(args[:request_token],args[:request_token_secret]).get_access_token(:oauth_verifier => args[:oauth_verifier])
+          end
+          
+          protected
+          
+          def get_consumer
+            ::OAuth::Consumer.new(@key, @secret, :site => @site)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sorcery/controller/submodules/oauth/oauth2.rb

@@ -0,0 +1,24 @@
+require 'oauth2'
+module Sorcery
+  module Controller
+    module Submodules
+      module Oauth
+        module Oauth2
+          def oauth_version
+            "2.0"
+          end
+          
+          def authorize_url(*args)
+            client = ::OAuth2::Client.new(@key, @secret, :site => @site)
+            client.web_server.authorize_url(:redirect_uri => @callback_url, :scope => @scope)
+          end
+          
+          def get_access_token(args)
+            client = ::OAuth2::Client.new(@key, @secret, :site => @site)
+            client.web_server.get_access_token(args[:code], :redirect_uri => @callback_url)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sorcery/controller/submodules/oauth/providers/facebook.rb

@@ -0,0 +1,64 @@
+module Sorcery
+  module Controller
+    module Submodules
+      module Oauth
+        module Providers
+          # This module adds support for OAuth with facebook.com.
+          # When included in the 'config.providers' option, it adds a new option, 'config.facebook'.
+          # Via this new option you can configure Facebook specific settings like your app's key and secret.
+          #
+          #   config.facebook.key = <key>
+          #   config.facebook.secret = <secret>
+          #   ...
+          #
+          module Facebook
+            def self.included(base)
+              base.module_eval do
+                class << self
+                  attr_reader :facebook                           # access to facebook_client.
+          
+                  def merge_facebook_defaults!
+                    @defaults.merge!(:@facebook => FacebookClient)
+                  end
+                end
+                merge_facebook_defaults!
+                update!
+              end
+            end
+          
+            module FacebookClient
+              class << self
+                attr_accessor :key,
+                              :secret,
+                              :callback_url,
+                              :site,
+                              :user_info_path,
+                              :scope,
+                              :user_info_mapping
+                            
+                include Oauth2
+            
+                def init
+                  @site           = "https://graph.facebook.com"
+                  @user_info_path = "/me"
+                  @scope          = "email,offline_access"
+                  @user_info_mapping = {}
+                end
+                
+                def get_user_hash(access_token)
+                  user_hash = {}
+                  response = access_token.get(@user_info_path)
+                  user_hash[:user_info] = JSON.parse(response)
+                  user_hash[:uid] = user_hash[:user_info]['id'].to_i
+                  user_hash
+                end
+              end
+              init
+            end
+            
+          end
+        end    
+      end
+    end
+  end
+end

data/lib/sorcery/controller/submodules/oauth/providers/twitter.rb

@@ -0,0 +1,61 @@
+module Sorcery
+  module Controller
+    module Submodules
+      module Oauth
+        module Providers
+          # This module adds support for OAuth with Twitter.com.
+          # When included in the 'config.providers' option, it adds a new option, 'config.twitter'.
+          # Via this new option you can configure Twitter specific settings like your app's key and secret.
+          #
+          #   config.twitter.key = <key>
+          #   config.twitter.secret = <secret>
+          #   ...
+          #
+          module Twitter
+            def self.included(base)
+              base.module_eval do
+                class << self
+                  attr_reader :twitter                           # access to twitter_client.
+
+                  def merge_twitter_defaults!
+                    @defaults.merge!(:@twitter => TwitterClient)
+                  end
+                end
+                merge_twitter_defaults!
+                update!
+              end
+            end
+
+            module TwitterClient
+              class << self
+                attr_accessor :key,
+                              :secret,
+                              :callback_url,
+                              :site,
+                              :user_info_path,
+                              :user_info_mapping
+                
+                include Oauth1
+                
+                def init
+                  @site           = "https://api.twitter.com"
+                  @user_info_path = "/1/account/verify_credentials.json"
+                  @user_info_mapping = {}
+                end
+                
+                def get_user_hash(access_token)
+                  user_hash = {}
+                  response = access_token.get(@user_info_path)
+                  user_hash[:user_info] = JSON.parse(response.body)
+                  user_hash[:uid] = user_hash[:user_info]['id']
+                  user_hash
+                end
+              end  
+              init
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,95 @@
+module Sorcery
+  module Controller
+    module Submodules
+      # This submodule helps you login users from OAuth providers such as Twitter.
+      # This is the controller part which handles the http requests and tokens passed between the app and the provider.
+      # For more configuration options see Sorcery::Model::Oauth.
+      module Oauth
+        def self.included(base)
+          base.send(:include, InstanceMethods)
+          Config.module_eval do
+            class << self
+              attr_reader :oauth_providers                           # oauth providers like twitter.
+                                          
+              def merge_oauth_defaults!
+                @defaults.merge!(:@oauth_providers => [])
+              end
+              
+              def oauth_providers=(providers)
+                providers.each do |provider|
+                  include Providers.const_get(provider.to_s.split("_").map {|p| p.capitalize}.join(""))
+                end
+              end
+            end
+            merge_oauth_defaults!
+          end
+        end
+
+        module InstanceMethods
+          protected
+          
+          # sends user to authenticate at the provider's website.
+          # after authentication the user is redirected to the callback defined in the provider config
+          def auth_at_provider(provider)
+            @provider = Config.send(provider)
+            args = {}
+            if @provider.respond_to?(:get_request_token)
+              req_token = @provider.get_request_token
+              session[:request_token]         = req_token.token
+              session[:request_token_secret]  = req_token.secret
+              args.merge!({:request_token => req_token.token, :request_token_secret => req_token.secret})
+            end
+            redirect_to @provider.authorize_url(args)
+          end
+          
+          # tries to login the user from access token
+          def login_from_access_token(provider)
+            @provider = Config.send(provider)
+            args = {}
+            args.merge!({:oauth_verifier => params[:oauth_verifier], :request_token => session[:request_token], :request_token_secret => session[:request_token_secret]}) if @provider.respond_to?(:get_request_token)
+            args.merge!({:code => params[:code]}) if params[:code]
+            @access_token = @provider.get_access_token(args)
+            @user_hash = @provider.get_user_hash(@access_token)
+            if user = Config.user_class.load_from_provider(provider,@user_hash[:uid])
+              reset_session
+              login_user(user)
+              user
+            end
+          end
+          
+          def get_user_hash(provider)
+            @provider = Config.send(provider)
+            @provider.get_user_hash(@access_token)
+          end
+          
+          # this method automatically creates a new user from the data in the external user hash.
+          # The mappings from user hash fields to user db fields are set at controller config.
+          # If the hash field you would like to map is nested, use slashes. For example, Given a hash like:
+          #
+          #   "user" => {"name"=>"moishe"}
+          #
+          # You will set the mapping:
+          #
+          #   {:username => "user/name"}
+          #
+          # And this will cause 'moishe' to be set as the value of :username field.
+          def create_from_provider!(provider)
+            provider = provider.to_sym
+            @provider = Config.send(provider)
+            @user_hash = get_user_hash(provider)
+            config = Config.user_class.sorcery_config
+            attrs = {}
+            @provider.user_info_mapping.each do |k,v|
+              (varr = v.split("/")).size > 1 ? attrs.merge!(k => varr.inject(@user_hash[:user_info]) {|hsh,v| hsh[v] }) : attrs.merge!(k => @user_hash[:user_info][v])
+            end
+            Config.user_class.transaction do
+              @user = Config.user_class.create!(attrs)
+              Config.user_class.sorcery_config.authentications_class.create!({config.authentications_user_id_attribute_name => @user.id, config.provider_attribute_name => provider, config.provider_uid_attribute_name => @user_hash[:uid]})
+            end
+            @user
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,6 +1,9 @@
 module Sorcery
   module Controller
     module Submodules
+      # The Remember Me submodule takes care of setting the user's cookie so that he will be automatically logged in to the site on every visit,
+      # until the cookie expires.
+      # See Sorcery::Model::Submodules::RememberMe for configuration options.
       module RememberMe
         def self.included(base)
           base.send(:include, InstanceMethods)
@@ -10,29 +13,35 @@ module Sorcery
         end
         
         module InstanceMethods
+          # This method sets the cookie and calls the user to save the token and the expiration to db.
           def remember_me!
-            logged_in_user.remember_me!
-            cookies[:remember_me_token] = { :value => logged_in_user.remember_me_token, :expires => logged_in_user.remember_me_token_expires_at }        
+            current_user.remember_me!
+            cookies[:remember_me_token] = { :value => current_user.remember_me_token, :expires => current_user.remember_me_token_expires_at }        
           end
 
+          # Clears the cookie and clears the token from the db.
           def forget_me!
-            logged_in_user.forget_me!
+            current_user.forget_me!
             cookies[:remember_me_token] = nil
           end
           
           protected
           
+          # calls remember_me! if a third credential was passed to the login method.
+          # Runs as a hook after login.
           def remember_me_if_asked_to(user, credentials)
             remember_me! if credentials.size == 3 && credentials[2]
           end
           
+          # Checks the cookie for a remember me token, tried to find a user with that token and logs the user in if found.
+          # Runs as a login source. See 'current_user' method for how it is used.
           def login_from_cookie
             user = cookies[:remember_me_token] && Config.user_class.find_by_remember_me_token(cookies[:remember_me_token])
             if user && user.remember_me_token?
               cookies[:remember_me_token] = { :value => user.remember_me_token, :expires => user.remember_me_token_expires_at }
-              @logged_in_user = user
+              @current_user = user
             else
-              @logged_in_user = false
+              @current_user = false
             end
           end
         end

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

@@ -1,6 +1,8 @@
 module Sorcery
   module Controller
     module Submodules
+      # This submodule helps you set a timeout to all user sessions.
+      # The timeout can be configured and also you can choose to reset it on every user action.
       module SessionTimeout
         def self.included(base)
           base.send(:include, InstanceMethods)
@@ -23,16 +25,19 @@ module Sorcery
         module InstanceMethods
           protected
           
+          # Registers last login to be used as the timeout starting point.
+          # Runs as a hook after a successful login.
           def register_login_time(user, credentials)
             session[:login_time] = session[:last_action_time] = Time.now.utc
           end
           
+          # Checks if session timeout was reached and expires the current session if so.
           # To be used as a before_filter, before require_login
           def validate_session
             session_to_use = Config.session_timeout_from_last_action ? session[:last_action_time] : session[:login_time]
             if session_to_use && (Time.now.utc - session_to_use > Config.session_timeout)
               reset_session
-              @logged_in_user = false
+              @current_user = false
             else
               session[:last_action_time] = Time.now.utc
             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/engine.rb

@@ -13,8 +13,15 @@ module Sorcery
     
     initializer "extend Controller with sorcery" do |app|
       ActionController::Base.send(:include, Sorcery::Controller)
-      ActionController::Base.helper_method :logged_in_user
+      ActionController::Base.helper_method :current_user
     end
-
+    
+    initializer "attempt to preload user model" do |app|
+      begin
+        require Rails.root + "app/models/user.rb"
+      rescue LoadError
+      end
+    end
+    
   end
 end

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

@@ -1,20 +1,25 @@
 module Sorcery
   module Model
     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 model part of the submodule, which provides configuration options.
       module ActivityLogging
         def self.included(base)
           base.extend(ClassMethods)
           base.sorcery_config.class_eval do
-            attr_accessor :last_login_at_attribute_name,                     # last login attribute name.
-                          :last_logout_at_attribute_name,                    # last logout attribute name.
-                          :last_activity_at_attribute_name,                  # last activity attribute name.
+            attr_accessor :last_login_at_attribute_name,                  # last login attribute name.
+                          :last_logout_at_attribute_name,                 # last logout attribute name.
+                          :last_activity_at_attribute_name,               # last activity attribute name.
                           :activity_timeout                               # how long since last activity is the user defined logged out?
           end
           
           base.sorcery_config.instance_eval do
-            @defaults.merge!(:@last_login_at_attribute_name                   => :last_login_at,
-                             :@last_logout_at_attribute_name                  => :last_logout_at,
-                             :@last_activity_at_attribute_name                => :last_activity_at,
+            @defaults.merge!(:@last_login_at_attribute_name                => :last_login_at,
+                             :@last_logout_at_attribute_name               => :last_logout_at,
+                             :@last_activity_at_attribute_name             => :last_activity_at,
                              :@activity_timeout                            => 10.minutes)
             reset!
           end
@@ -22,11 +27,11 @@ module Sorcery
         
         module ClassMethods
           # get all users with last_activity within timeout
-          def logged_in_users
+          def current_users
             config = sorcery_config
             where("#{config.last_activity_at_attribute_name} IS NOT NULL") \
             .where("#{config.last_logout_at_attribute_name} IS NULL OR #{config.last_activity_at_attribute_name} > #{config.last_logout_at_attribute_name}") \
-            .where("#{config.last_activity_at_attribute_name} > ? ", config.activity_timeout.seconds.ago)
+            .where("#{config.last_activity_at_attribute_name} > ? ", config.activity_timeout.seconds.ago.utc.to_s(:db))
           end
         end
       end