sorcery 0.2.1 → 0.3.1

data/README.rdoc

@@ -1,34 +1,137 @@
 = sorcery
-Magical Authentication for Rails 3.
+Magical Authentication for Rails 3 and Sinatra.
 
 Inspired by restful_authentication, Authlogic and Devise.
 Crypto code taken almost unchanged from Authlogic.
-OAuth code inspired by OmniAuth.
+OAuth code inspired by OmniAuth and Ryan Bates's railscasts about it.
 
-== Summary
 
-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:
+== Philosophy
 
-* 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.
+
+Sorcery is a stripped-down, bare-bones authentication library, with which you can write your own authentication flow.
+It was built with a few goals in mind:
+
+* Less is more - less than 20 public methods to remember for the entire feature-set make the lib easy to 'get'.
+* No built-in or generated code - use the library's methods 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.2.0/frames
+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.1/frames
 
 Check out the tutorials in the github wiki!
 
+
+== Installation:
+
+
+If using bundler, first add 'sorcery' to your Gemfile:
+
+	gem "sorcery"
+
+And run 
+	
+	bundle install
+
+Otherwise simply
+
+	gem install sorcery
+
+
+== Configuration:
+
+
+1. config/application.rb
+
+	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)
+
+	activate_sorcery! do |config|
+  	  config.user_activation_mailer = MyMailer
+	  config.username_attribute_name = :email
+	end
+
+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.
+
+For your convenience, Sorcery includes a migrations generator for Rails, which can be used like so:
+
+  rails g sorcery_migration [list of submodules]
+
+For example, for only the core functionality use:
+
+  rails g sorcery_migration core
+
+To generate migrations for both the core AND 'remember_me' submodule:
+
+  rails g sorcery_migration core remember_me
+
+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.
+
+
+== 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.
+
+  # 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.
+
+
 == Full Features List by module:
 
-Core (see lib/sorcery/model/model.rb and lib/sorcery/controller/controller.rb): 
+
+Core (see lib/sorcery/model.rb and lib/sorcery/controller.rb): 
 * 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.
@@ -68,88 +171,53 @@ 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.
 
+
 == Next Planned Features:
 
+
 I've got many plans which include (by priority):
-* Sinatra support
+* 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!
 
-== Installation:
-
-You can either git clone and then 'rake install' to live on the edge (unstable),
-
-Or simply (stable):
-
-	gem install sorcery
-
-== Configuration:
-
-First add 'sorcery' to your Gemfile:
-
-	gem "sorcery"
-
-And run 
-	
-	bundle install
-
-There are 2 required places to configure the plugin, and an optional one:
-1. config/application.rb
-
-	config.sorcery.submodules = [:user_activation, :remember_me] # add the modules 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)
-
-	activate_sorcery! do |config|
-  	  config.user_activation_mailer = MyMailer
-	  config.username_attribute_name = :email
-	end
-
-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
-
-Also check the migrations in the example app to see what database fields are expected.
-
-The configuration options vary with the modules you've chosen to use.
+Other stuff:
+* Improve documentation
+* Tty to reduce the number of library methods, and find better names to some
 
 
 == 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. This is important so I don’t break it in a future version unintentionally.
+* 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.
 
 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.
 
+
 == Contact
 
+Feel free to ask questions using these contact details:
+	
 	email: nbenari@gmail.com ( also for paypal )
 	twitter: @nbenari
 	
+	
 == Copyright
 
-Copyright (c) 2010 Noam Ben Ari (nbenari@gmail.com). See LICENSE.txt for further details.
-Released with permission from Kontera (http://www.kontera.com), where I work.
 
+Copyright (c) 2010 Noam Ben Ari (nbenari@gmail.com). See LICENSE.txt for further details.

data/VERSION

@@ -1 +1 @@
-0.2.1
+0.3.1

data/lib/generators/sorcery_migration/sorcery_migration_generator.rb

@@ -0,0 +1,24 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+
+class SorceryMigrationGenerator < Rails::Generators::Base
+  include Rails::Generators::Migration
+  
+  source_root File.join(File.dirname(__FILE__), 'templates')
+  argument :submodules, :type => :array, :required => true
+  
+  def self.next_migration_number(dirname)
+    if ActiveRecord::Base.timestamped_migrations
+      Time.new.utc.strftime("%Y%m%d%H%M%S")
+    else
+      "%.3d" % (current_migration_number(dirname) + 1)
+    end
+  end
+  
+  def create_migration_file
+    self.submodules.each do |submodule|
+      migration_template "#{submodule}.rb", "db/migrate/sorcery_#{submodule}.rb"
+      sleep 1 # for the timestamp to change
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+class SorceryActivityLogging < ActiveRecord::Migration
+  def self.up
+    add_column :users, :last_login_at,     :datetime, :default => nil
+    add_column :users, :last_logout_at,    :datetime, :default => nil
+    add_column :users, :last_activity_at,  :datetime, :default => nil
+    
+    add_index :users, [:last_logout_at, :last_activity_at]
+  end
+
+  def self.down
+    remove_index :users, [:last_logout_at, :last_activity_at]
+    
+    remove_column :users, :last_activity_at
+    remove_column :users, :last_logout_at
+    remove_column :users, :last_login_at
+  end
+end

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

@@ -0,0 +1,11 @@
+class SorceryBruteForceProtection < ActiveRecord::Migration
+  def self.up
+    add_column :users, :failed_logins_count, :integer, :default => 0
+    add_column :users, :lock_expires_at, :datetime, :default => nil
+  end
+
+  def self.down
+    remove_column :users, :lock_expires_at
+    remove_column :users, :failed_logins_count
+  end
+end

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

@@ -0,0 +1,16 @@
+class SorceryCore < ActiveRecord::Migration
+  def self.up
+    create_table :users do |t|
+      t.string :username,         :null => false
+      t.string :email,            :default => nil
+      t.string :crypted_password, :default => nil
+      t.string :salt,             :default => nil
+
+      t.timestamps
+    end
+  end
+
+  def self.down
+    drop_table :users
+  end
+end

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

@@ -0,0 +1,14 @@
+class SorceryExternal < ActiveRecord::Migration
+  def self.up
+    create_table :authentications do |t|
+      t.integer :user_id, :null => false
+      t.string :provider, :uid, :null => false
+
+      t.timestamps
+    end
+  end
+
+  def self.down
+    drop_table :authentications
+  end
+end

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

@@ -0,0 +1,15 @@
+class SorceryRememberMe < ActiveRecord::Migration
+  def self.up
+    add_column :users, :remember_me_token, :string, :default => nil
+    add_column :users, :remember_me_token_expires_at, :datetime, :default => nil
+    
+    add_index :users, :remember_me_token
+  end
+
+  def self.down
+    remove_index :users, :remember_me_token
+    
+    remove_column :users, :remember_me_token_expires_at
+    remove_column :users, :remember_me_token
+  end
+end

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

@@ -0,0 +1,13 @@
+class SorceryResetPassword < ActiveRecord::Migration
+  def self.up
+    add_column :users, :reset_password_token, :string, :default => nil
+    add_column :users, :reset_password_token_expires_at, :datetime, :default => nil
+    add_column :users, :reset_password_email_sent_at, :datetime, :default => nil
+  end
+
+  def self.down
+    remove_column :users, :reset_password_email_sent_at
+    remove_column :users, :reset_password_token_expires_at
+    remove_column :users, :reset_password_token
+  end
+end

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

@@ -0,0 +1,17 @@
+class SorceryUserActivation < ActiveRecord::Migration
+  def self.up
+    add_column :users, :activation_state, :string, :default => nil
+    add_column :users, :activation_token, :string, :default => nil
+    add_column :users, :activation_token_expires_at, :datetime, :default => nil
+    
+    add_index :users, :activation_token
+  end
+
+  def self.down
+    remove_index :users, :activation_token
+    
+    remove_column :users, :activation_token_expires_at
+    remove_column :users, :activation_token
+    remove_column :users, :activation_state
+  end
+end

data/lib/sorcery/controller/adapters/sinatra.rb

@@ -0,0 +1,97 @@
+module Sorcery
+  module Controller
+    module Adapters
+      # This module does the magic of translating Rails commands to Sinatra.
+      # This way the Rails code doesn't change, but it actually now calls Sinatra calls.
+      module Sinatra
+        def self.included(base)
+          base.class_eval do
+            class << self
+              # prepend a filter
+              def prepend_filter(type, path = nil, options = {}, &block)
+                return filters[type].unshift block unless path
+                path, options = //, path if path.respond_to?(:each_pair)
+                block, *arguments = compile!(type, path, block, options)
+                prepend_filter(type) do
+                  process_route(*arguments) { instance_eval(&block) }
+                end
+              end
+              
+              def after_filter(filter)
+                after do
+                  send(filter)
+                end
+              end
+            end
+          end
+          
+          ::Sinatra::Request.class_eval do
+            def authorization
+              env['HTTP_AUTHORIZATION']   ||
+              env['X-HTTP_AUTHORIZATION'] ||
+              env['X_HTTP_AUTHORIZATION'] ||
+              env['REDIRECT_X_HTTP_AUTHORIZATION'] || nil
+            end
+          end
+          
+          base.send(:include, InstanceMethods)
+          base.extend(ClassMethods)
+        end
+        
+        module InstanceMethods
+          def reset_session
+            session.clear
+          end
+        
+          def redirect_to(*args)
+            args.pop if args.last.is_a?(Hash)
+            redirect(*args)
+          end
+        
+          def root_path
+            '/'
+          end
+          
+          helpers do
+            def request_http_basic_authentication(realm)
+              response.header['WWW-Authenticate'] = %(Basic realm="#{realm}")
+              response.status = 401
+            end
+            
+            def authenticate_with_http_basic(&blk)
+              @auth ||=  Rack::Auth::Basic::Request.new(request.env)
+              yield @auth.credentials if ( @auth.provided? && @auth.basic? && @auth.credentials )
+            end
+          end
+          
+          def cookies
+            @cookie_proxy ||= CookieProxy.new(request,response)
+          end
+        end
+        
+        class CookieProxy
+          def initialize(request,response)
+            @request = request
+            @response = response
+          end
+          
+          def [](key)
+            @request.cookies[key.to_s]
+          end
+          
+          def []=(key, value)
+            @response.set_cookie(key, value)
+          end
+        end
+        
+        module ClassMethods
+          def prepend_before_filter(filter)
+            prepend_filter(:before) do
+              send(filter)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# module Sorcery
+#   module Controller
+#     module Submodules
+#       # This module allows you to authenticate to the site using a mail server.
+#       # Let's say your organization is called blup, and everyone has someklutz@blup.com,
+#       # Instead of registering a new username and password for an internal web application,
+#       # why not simply reuse your email credentials?
+#       # Of course this means that if the mail server is down, nobody can authenticate to your app.
+#       # I might add a fallback for that in the future.
+#       module Email
+#         def self.included(base)
+#           base.send(:include, InstanceMethods)
+#           Config.module_eval do
+#             class << self
+#               attr_reader :email_protocols                           # email protocols like pop3, IMAP etc.
+#                                           
+#               def merge_mail_defaults!
+#                 @defaults.merge!(:@email_protocols => [])
+#               end
+#               
+#               def email_protocols=(protocols)
+#                 protocols.each do |protocol|
+#                   include Protocols.const_get(protocol.to_s.split("_").map {|p| p.capitalize}.join(""))
+#                 end
+#               end
+#             end
+#             merge_mail_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 login_at(protocol)
+# 
+#           end
+# 
+#         end
+#       end
+#     end
+#   end
+# end

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