sorcery 0.2.1 → 0.4.2

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

@@ -1,34 +1,151 @@
 = 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.4.2/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:
+
+
+If using bundler, first add 'sorcery' to your Gemfile:
+
+	gem "sorcery"
+
+And run 
+	
+	bundle install
+
+Otherwise simply
+
+	gem install sorcery
+
+
+== Rails 3 Configuration:
+
+
+For Rails 3 create an initializer file using:
+
+    rake sorcery:bootstrap
+
+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:
+
+  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.
+
+
+== 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
+
+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:
 
-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 +185,67 @@ 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
+* Forgot username, maybe as part of the reset_password module
+* Scoping logins (to a subdomain or another arbitrary field)
 * 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:
+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
 
-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
 
+== Backward compatibility
 
-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
+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.
 
-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.
+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. This is important so I don’t break it in a future version unintentionally.
-* 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 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.
 
-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/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.2.1
+0.4.2

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  # 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
+
+      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/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