sorcery 0.3.0 → 0.4.0

data/Gemfile

@@ -9,12 +9,13 @@ 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 "rspec", "~> 2.3.0"
-  gem 'rspec-rails'
+  gem "rspec", "~> 2.5.0"
+  gem 'rspec-rails', "~> 2.5.0"
   gem 'ruby-debug19'
   gem 'sqlite3-ruby', :require => 'sqlite3'
   gem "yard", "~> 0.6.0"
   gem "bundler", "~> 1.0.0"
   gem "jeweler", "~> 1.5.2"
   gem 'simplecov', '>= 0.3.8', :require => false # Will install simplecov-html as a dependency
+  gem 'timecop'
 end

data/Gemfile.lock

@@ -81,19 +81,19 @@ GEM
       rake (>= 0.8.7)
       thor (~> 0.14.4)
     rake (0.8.7)
-    rspec (2.3.0)
-      rspec-core (~> 2.3.0)
-      rspec-expectations (~> 2.3.0)
-      rspec-mocks (~> 2.3.0)
-    rspec-core (2.3.1)
-    rspec-expectations (2.3.0)
+    rspec (2.5.0)
+      rspec-core (~> 2.5.0)
+      rspec-expectations (~> 2.5.0)
+      rspec-mocks (~> 2.5.0)
+    rspec-core (2.5.1)
+    rspec-expectations (2.5.0)
       diff-lcs (~> 1.1.2)
-    rspec-mocks (2.3.0)
-    rspec-rails (2.3.1)
+    rspec-mocks (2.5.0)
+    rspec-rails (2.5.0)
       actionpack (~> 3.0)
       activesupport (~> 3.0)
       railties (~> 3.0)
-      rspec (~> 2.3.0)
+      rspec (~> 2.5.0)
     ruby-debug-base19 (0.11.24)
       columnize (>= 0.3.1)
       linecache19 (>= 0.5.11)
@@ -109,6 +109,7 @@ GEM
     simplecov-html (0.3.9)
     sqlite3-ruby (1.3.2)
     thor (0.14.6)
+    timecop (0.3.5)
     treetop (1.4.9)
       polyglot (>= 0.3.1)
     tzinfo (0.3.23)
@@ -124,9 +125,10 @@ DEPENDENCIES
   oauth (>= 0.4.4)
   oauth2 (>= 0.1.1)
   rails (>= 3.0.0)
-  rspec (~> 2.3.0)
-  rspec-rails
+  rspec (~> 2.5.0)
+  rspec-rails (~> 2.5.0)
   ruby-debug19
   simplecov (>= 0.3.8)
   sqlite3-ruby
+  timecop
   yard (~> 0.6.0)

data/README.rdoc

@@ -6,7 +6,7 @@ Crypto code taken almost unchanged from Authlogic.
 OAuth code inspired by OmniAuth and Ryan Bates's railscasts about it.
 
 
-== Summary
+== Philosophy
 
 
 Sorcery is a stripped-down, bare-bones authentication library, with which you can write your own authentication flow.
@@ -28,11 +28,53 @@ Example Rails 3 app using sorcery: https://github.com/NoamB/sorcery-example-app
 
 Example Sinatra app using sorcery: https://github.com/NoamB/sorcery-example-app-sinatra
 
-Documentation: http://rubydoc.info/gems/sorcery/0.3.0/frames
+Documentation: http://rubydoc.info/gems/sorcery/0.4.0/frames
 
 Check out the tutorials in the github wiki!
 
 
+== API Summary
+
+
+Below is a summary of the library methods. Most method names are self explaining and the rest are commented:
+
+  # core
+  require_login # this is a before filter
+  login(username,password,remember_me = false)
+  logout
+  logged_in?
+  current_user
+  redirect_back_or_to # used when a user tries to access a page while logged out, is asked to login, and we want to return him back to the page he originally wanted.
+  @user.external? # external users, such as facebook/twitter etc.
+  User.authenticates_with_sorcery!
+
+  # activity logging
+  current_users
+
+  # http basic auth
+  require_login_from_http_basic # this is a before filter
+
+  # external
+  login_at(provider) # sends the user to an external service (twitter etc.) to authenticate.
+  login_from(provider) # tries to login from the external provider's callback.
+  create_from(provider) # create the user in the local app db.
+
+  # remember me
+  remember_me!
+  forget_me!
+
+  # reset password
+  User.load_from_reset_password_token(token)
+  @user.deliver_reset_password_instructions!
+  @user.reset_password!(params)
+
+  # user activation
+  User.load_from_activation_token(token)
+  @user.activate!
+
+Please see the tutorials in the github wiki for detailed usage information.
+
+
 == Installation:
 
 
@@ -49,29 +91,15 @@ Otherwise simply
 	gem install sorcery
 
 
-== Configuration:
-
-
-1. config/application.rb
+== Rails 3 Configuration:
 
-	config.sorcery.submodules = [:user_activation, :remember_me] # add the submodules you want to use
-	# You can also configure here any controller and any controller-submodule option here. For example:
-	config.sorcery.session_timeout = 10.minutes
 
-2. app/models/user.rb (or another model of your choice, but a User class is assumed by default)
+For Rails 3 create an initializer file using:
 
-	activate_sorcery! do |config|
-  	  config.user_activation_mailer = MyMailer
-	  config.username_attribute_name = :email
-	end
+    rake sorcery:bootstrap
 
-3. app/controllers/application_controller.rb (OPTIONAL: this is actually needed only in some cases)
-
-	activate_sorcery! do |config|
-  	  config.session_timeout = 10.minutes
-	end
-
-The configuration options vary with the submodules you've chosen to use, so check the documentation or the wiki tutorials regarding the specific submodule.
+This will create the file as config/initializers/sorcery.rb .
+Inside it the comments will tell you everything you need to know.
 
 For your convenience, Sorcery includes a migrations generator for Rails, which can be used like so:
 
@@ -88,10 +116,30 @@ To generate migrations for both the core AND 'remember_me' submodule:
 These migrations use the default fields. You can choose to use these migrations or make your own tables and fields. Sorcery tries not to impose a database structure and naming scheme on your application.
 
 
-== Usage
+== Sinatra Configuration:
+
+
+For Sinatra you'll need to create the initializer manually. You can do it in the main app file or in a separate file you require (see example in example app). The code looks as follows:
 
+    Sorcery::Controller::Config.submodules = [] # specify here the submodules you want to include
+    
+    Sorcery::Controller::Config.configure do |config|
+      config.session_timeout = 10.minutes
+      ...
+      ...
+    
+      config.user_config do |user|
+        user.username_attribute_name                      = :email
+        ...
+    	...
+    	
+      end
+    end
 
-Please see the tutorials in the github wiki.
+Finally, to make all the code above take effect, we'll need to re-include the sorcery controller module:
+
+    include Sorcery::Controller::Adapters::Sinatra
+    include Sorcery::Controller
 
 
 == Full Features List by module:
@@ -137,7 +185,7 @@ 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.
 
-Oauth (see lib/sorcery/controller/submodules/oauth.rb):
+External (see lib/sorcery/controller/submodules/external.rb):
 * OAuth1 and OAuth2 support (currently twitter & facebook)
 * configurable db field names and authentications table.
 
@@ -146,33 +194,51 @@ Oauth (see lib/sorcery/controller/submodules/oauth.rb):
 
 
 I've got many plans which include (by priority):
+* Forgot username, maybe as part of the reset_password module
 * Scoping logins (to a subdomain or another arbitrary field)
-* Simple auth (no user)
-* Switching authentication mode at runtime (Maintenance mode)
 * Mongoid support
-* Configurable Auto login on registration/activation
 * Other reset password strategies (security questions?)
 * Other brute force protection strategies (captcha)
 * Have an idea? Let me know, and it might get into the gem!
 
+Other stuff:
+* Improve specs speed
+* Provide an easy way to run specs after install
+* Improve documentation
+* Tty to reduce the number of library methods, and find better names to some
+
+
+== Backward compatibility
+
+
+While the lib is young and evolving fast I'm breaking backward compatibility quite often.
+I'm constantly finding better ways to do things and throwing away old ways.
+To let you know when things are changing in a non-compatible way, I'm bumping the minor version of the gem.
+The patch version changes are backward compatible.
+
+In short, an app that works with x.3.1 should be able to upgrade to x.3.2 with no code changes.
+The same cannot be said about upgrading to x.4.0 and above, however.
+
 
 == Contributing to sorcery
 
+
 Your feedback is very welcome and will make this gem much much better for you, me and everyone else.
 Besides feedback on code, features, suggestions and bug reports, you may want to actually make an impact on the code.
 For this:
 
-* Fork the project.
-* Make your feature addition or bug fix.
-* Add tests for it. I've used RSpec so far, please remain consistent with it.
-* Commit, do not mess with Rakefiles, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
-* Send me a pull request. Bonus points for topic branches.
+* Fork it.
+* Fix it.
+* Test it.
+* Commit it.
+* Send me a pull request so I'll... Pull it.
 
-If you feel my work has made your life easier, and you would like to thank me through a donation, my paypal email is in the contact details.
+If you feel sorcery has made your life easier, and you would like to express your thanks via a donation, my paypal email is in the contact details.
 
 
 == Contact
 
+
 Feel free to ask questions using these contact details:
 	
 	email: nbenari@gmail.com ( also for paypal )

data/Rakefile

@@ -41,11 +41,11 @@ end
 require 'yard'
 YARD::Rake::YardocTask.new
 
-desc 'Default: Run all specs.'
-task :default => :all_specs
+desc 'Default: Run all sorcery specs.'
+task :default => :all_sorcery_specs
 
-desc "Run all specs"
-task :all_specs do
+desc "Run all sorcery specs"
+task :all_sorcery_specs do
   Dir['spec/**/Rakefile'].each do |rakefile|
     directory_name = File.dirname(rakefile)
     sh <<-CMD

data/VERSION

@@ -1 +1 @@
-0.3.0
+0.4.0

data/lib/generators/sorcery_migration/templates/core.rb

@@ -1,8 +1,8 @@
 class SorceryCore < ActiveRecord::Migration
   def self.up
     create_table :users do |t|
-      t.string :username,         :null => false
-      t.string :email,            :default => nil
+      t.string :username,         :null => false  # if you use another filed as a username, for example email, you can safely remove this field.
+      t.string :email,            :default => nil # if you use this field as a username, you might want to make it :null => false.
       t.string :crypted_password, :default => nil
       t.string :salt,             :default => nil
 

data/lib/generators/sorcery_migration/templates/{oauth.rb → external.rb}

@@ -1,4 +1,4 @@
-class SorceryOauth < ActiveRecord::Migration
+class SorceryExternal < ActiveRecord::Migration
   def self.up
     create_table :authentications do |t|
       t.integer :user_id, :null => false

data/lib/sorcery/controller/submodules/external/protocols/oauth1.rb

@@ -0,0 +1,35 @@
+require 'oauth'
+module Sorcery
+  module Controller
+    module Submodules
+      module External
+        module Protocols
+          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
+end

data/lib/sorcery/controller/submodules/external/protocols/oauth2.rb

@@ -0,0 +1,26 @@
+require 'oauth2'
+module Sorcery
+  module Controller
+    module Submodules
+      module External
+        module Protocols
+          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
+end

data/lib/sorcery/controller/submodules/{oauth → external}/providers/facebook.rb

@@ -1,7 +1,7 @@
 module Sorcery
   module Controller
     module Submodules
-      module Oauth
+      module External
         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'.
@@ -16,7 +16,7 @@ module Sorcery
               base.module_eval do
                 class << self
                   attr_reader :facebook                           # access to facebook_client.
-          
+                  
                   def merge_facebook_defaults!
                     @defaults.merge!(:@facebook => FacebookClient)
                   end
@@ -36,7 +36,7 @@ module Sorcery
                               :scope,
                               :user_info_mapping
                             
-                include Oauth2
+                include Protocols::Oauth2
             
                 def init
                   @site           = "https://graph.facebook.com"
@@ -45,13 +45,31 @@ module Sorcery
                   @user_info_mapping = {}
                 end
                 
-                def get_user_hash(access_token)
+                def get_user_hash
                   user_hash = {}
-                  response = access_token.get(@user_info_path)
+                  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[:uid] = user_hash[:user_info]['id']
                   user_hash
                 end
+                
+                def has_callback?
+                  true
+                end
+                
+                # calculates and returns the url to which the user should be redirected,
+                # to get authenticated at the external provider's site.
+                def login_url(params,session)
+                  self.authorize_url
+                end
+                
+                # tries to login the user from access token
+                def process_callback(params,session)
+                  args = {}
+                  args.merge!({:code => params[:code]}) if params[:code]
+                  @access_token = self.get_access_token(args)
+                end
+                
               end
               init
             end

data/lib/sorcery/controller/submodules/{oauth → external}/providers/twitter.rb

@@ -1,7 +1,7 @@
 module Sorcery
   module Controller
     module Submodules
-      module Oauth
+      module External
         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'.
@@ -15,7 +15,10 @@ module Sorcery
             def self.included(base)
               base.module_eval do
                 class << self
-                  attr_reader :twitter                           # access to twitter_client.
+                  attr_reader :twitter
+                  # def twitter(&blk) # allows block syntax.
+                  #   yield @twitter
+                  # end                           
 
                   def merge_twitter_defaults!
                     @defaults.merge!(:@twitter => TwitterClient)
@@ -25,7 +28,7 @@ module Sorcery
                 update!
               end
             end
-
+            
             module TwitterClient
               class << self
                 attr_accessor :key,
@@ -35,7 +38,7 @@ module Sorcery
                               :user_info_path,
                               :user_info_mapping
                 
-                include Oauth1
+                include Protocols::Oauth1
                 
                 def init
                   @site           = "https://api.twitter.com"
@@ -43,13 +46,35 @@ module Sorcery
                   @user_info_mapping = {}
                 end
                 
-                def get_user_hash(access_token)
+                def get_user_hash
                   user_hash = {}
-                  response = access_token.get(@user_info_path)
+                  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
+                
+                def has_callback?
+                  true
+                end
+                
+                # calculates and returns the url to which the user should be redirected,
+                # to get authenticated at the external provider's site.
+                def login_url(params,session)
+                  req_token = self.get_request_token
+                  session[:request_token]         = req_token.token
+                  session[:request_token_secret]  = req_token.secret
+                  self.authorize_url({:request_token => req_token.token, :request_token_secret => req_token.secret})
+                end
+                
+                # tries to login the user from access token
+                def process_callback(params,session)
+                  args = {}
+                  args.merge!({:oauth_verifier => params[:oauth_verifier], :request_token => session[:request_token], :request_token_secret => session[:request_token_secret]})
+                  args.merge!({:code => params[:code]}) if params[:code]
+                  @access_token = self.get_access_token(args)
+                end
+
               end  
               init
             end

data/lib/sorcery/controller/submodules/{oauth.rb → external.rb}

@@ -1,27 +1,26 @@
 module Sorcery
   module Controller
     module Submodules
-      # This submodule helps you login users from OAuth providers such as Twitter.
+      # This submodule helps you login users from external auth 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
+      module External
         def self.included(base)
           base.send(:include, InstanceMethods)
           Config.module_eval do
             class << self
-              attr_reader :oauth_providers                           # oauth providers like twitter.
+              attr_reader :external_providers                           # external providers like twitter.
                                           
-              def merge_oauth_defaults!
-                @defaults.merge!(:@oauth_providers => [])
+              def merge_external_defaults!
+                @defaults.merge!(:@external_providers => [])
               end
               
-              def oauth_providers=(providers)
+              def external_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!
+            merge_external_defaults!
           end
         end
 
@@ -30,26 +29,20 @@ module Sorcery
           
           # 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)
+          def login_at(provider, args = {})
             @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})
+            if @provider.has_callback?
+              redirect_to @provider.login_url(params,session)
+            else
+              #@provider.login(args)
             end
-            redirect_to @provider.authorize_url(args)
           end
           
-          # tries to login the user from access token
-          def login_from_access_token(provider)
+          # tries to login the user from provider's callback
+          def login_from(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)
+            @provider.process_callback(params,session)
+            @user_hash = @provider.get_user_hash
             if user = Config.user_class.load_from_provider(provider,@user_hash[:uid])
               reset_session
               login_user(user)
@@ -57,11 +50,6 @@ module Sorcery
             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:
@@ -73,10 +61,10 @@ module Sorcery
           #   {:username => "user/name"}
           #
           # And this will cause 'moishe' to be set as the value of :username field.
-          def create_from_provider!(provider)
+          def create_from(provider)
             provider = provider.to_sym
             @provider = Config.send(provider)
-            @user_hash = get_user_hash(provider)
+            @user_hash = @provider.get_user_hash
             config = Config.user_class.sorcery_config
             attrs = {}
             @provider.user_info_mapping.each do |k,v|

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

@@ -9,7 +9,7 @@ module Sorcery
           base.send(:include, InstanceMethods)
           Config.module_eval do
             class << self
-              attr_accessor :controller_to_realm_map            # how many failed logins allowed.
+              attr_accessor :controller_to_realm_map            # What realm to display for which controller name.
                             
               def merge_http_basic_auth_defaults!
                 @defaults.merge!(:@controller_to_realm_map  => {"application" => "Application"})