sorcery 0.8.4 → 0.8.6

data/README.md

@@ -0,0 +1,320 @@
+[![Build Status](https://travis-ci.org/NoamB/sorcery.svg?branch=master)](https://travis-ci.org/NoamB/sorcery)
+[![Code Climate](https://codeclimate.com/github/NoamB/sorcery.png)](https://codeclimate.com/github/NoamB/sorcery)
+
+# sorcery
+Magical Authentication for Rails 3 and 4. Supports ActiveRecord,
+DataMapper, Mongoid and MongoMapper.
+
+Inspired by restful_authentication, Authlogic and Devise. Crypto code taken
+almost unchanged from Authlogic. OAuth code inspired by OmniAuth and Ryan
+Bates's railscasts about it.
+
+**Rails 4 status:** [Sorcery 0.8.5](http://rubygems.org/gems/sorcery/versions/0.8.5) is fully tested and ready for Rails 4.0.
+
+**Rails 4.1 status:** Sorcery 0.8.6 (to be released, currently in master branch) works with Rails 4.1
+
+https://github.com/NoamB/sorcery/wiki/Simple-Password-Authentication
+
+## Philosophy
+
+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 - Centralized (1 file), 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:
+
+Railscast: http://railscasts.com/episodes/283-authentication-with-sorcery
+
+Example Rails 3 app using sorcery:
+https://github.com/NoamB/sorcery-example-app
+
+Documentation: http://rubydoc.info/gems/sorcery
+
+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(email, password, remember_me = false)
+    auto_login(user)# login without credentials
+    logout
+    logged_in?      # available to view
+    current_user    # available to view
+    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
+    auto_login(user, should_remember=false)  # login without credentials, optional remember_me
+    remember_me!
+    forget_me!
+
+    # reset password
+    User.load_from_reset_password_token(token)
+    @user.deliver_reset_password_instructions!
+    @user.change_password!(new_password)
+
+    # 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 configuration:
+
+    rails generate sorcery:install
+
+This will generate the core migration file, the initializer file and the
+'User' model class.
+
+    rails generate sorcery:install remember_me reset_password
+
+This will generate the migrations files for remember_me and reset_password
+submodules and will create the initializer file (and add submodules to it),
+and create the 'User' model class.
+
+    rails generate sorcery:install --model Person
+
+This will generate the core migration file, the initializer and change the
+model class (in the initializer and migration files) to the class 'Person'
+(and its pluralized version, 'people')
+
+    rails generate sorcery:install http_basic_auth external remember_me --migrations
+
+This will generate only the migration files for the specified submodules and
+will add them to the initializer file.
+
+Inside the initializer, the comments will tell you what each setting does.
+
+## DelayedJob Integration
+
+By default emails are sent synchronously. You can send them asynchronously by
+using the [delayed_job gem](https://github.com/collectiveidea/delayed_job).
+
+After implementing the `delayed_job` into your project add the code below at
+the end of the `config/initializers/sorcery.rb` file. After that all emails
+will be sent asynchronously.
+
+    module Sorcery
+      module Model
+        module InstanceMethods
+          def generic_send_email(method, mailer)
+            config = sorcery_config
+            mail = config.send(mailer).delay.send(config.send(method), self)
+          end
+        end
+      end
+    end
+
+Sidekiq and Resque integrations are coming soon.
+
+## Single Table Inheritance (STI) Support
+STI is supported via a single setting in config/initializers/sorcery.rb.
+
+## Full Features List by module:
+
+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.
+*   allow multiple fields to serve as username.
+
+
+User Activation (see lib/sorcery/model/submodules/user_activation.rb):
+*   User activation by email with optional success email.
+*   configurable attribute names.
+*   configurable mailer, method name, and attribute name.
+*   configurable temporary token expiration.
+*   Optionally prevent non-active users to login.
+
+
+Reset Password (see lib/sorcery/model/submodules/reset_password.rb):
+*   Reset password with email verification.
+*   configurable mailer, method name, and attribute name.
+*   configurable temporary token expiration.
+*   configurable time between emails (hammering protection).
+
+
+Remember Me (see lib/sorcery/model/submodules/remember_me.rb):
+*   Remember me with configurable expiration.
+*   configurable attribute names.
+
+
+Session Timeout (see lib/sorcery/controller/submodules/session_timeout.rb):
+*   Configurable session timeout.
+*   Optionally session timeout will be calculated from last user action.
+
+
+Brute Force Protection (see
+lib/sorcery/model/submodules/brute_force_protection.rb):
+*   Brute force login hammering protection.
+*   configurable logins before lock and lock duration.
+
+
+Basic HTTP Authentication (see
+lib/sorcery/controller/submodules/http_basic_auth.rb):
+*   A before filter for requesting authentication with HTTP Basic.
+*   automatic login from HTTP Basic.
+*   automatic login is disabled if session key changed.
+
+
+Activity Logging (see lib/sorcery/model/submodules/activity_logging.rb):
+*   automatic logging of last login, last logout, last activity time and IP
+    address for last login.
+*   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.
+
+
+External (see lib/sorcery/controller/submodules/external.rb):
+*   OAuth1 and OAuth2 support (currently: Twitter, Facebook, Github, Google,
+    LinkedIn, VK, LiveID and Xing)
+*   configurable db field names and authentications table.
+
+
+## Next Planned Features:
+
+I've got some thoughts which include (unordered):
+*   Passing a block to encrypt, allowing the developer to define his own mix
+    of salting and encrypting
+*   Forgot username, maybe as part of the reset_password module
+*   Scoping logins (to a subdomain or another arbitrary field)
+*   Allowing storing the salt and crypted password in the same DB field for
+    extra security
+*   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!
+
+## 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.
+
+## DataMapper Support
+
+Important notes:
+
+*   Expected to work with DM adapters: dm-mysql-adapter,
+    dm-redis-adapter.
+*   Submodules DM adapter dependent: activity_logging (dm-mysql-adapter)
+*   Usage: include DataMapper::Resource in user model, follow sorcery
+    instructions (remember to add property id, validators and accessor
+attributes such as password and password_confirmation)
+*   Option downcase__username_before_authenticating and dm-mysql, 
+    http://datamapper.lighthouseapp.com/projects/20609/tickets/1105-add-support-for-definingchanging-default-collation
+
+## Upgrading
+
+Important notes while upgrading:
+
+*   If you are upgrading from <= **0.8.5** and you're using Sorcery test helpers,
+    you need to change the way you include them to following code:
+
+        RSpec.configure do |config|
+          config.include Sorcery::TestHelpers::Rails::Controler, type: [:controller]
+          config.include Sorcery::TestHelpers::Rails::Integration, type: [:feature]
+        end
+
+*   If are upgrading to **0.8.2** and use activity_logging feature with
+    ActiveRecord, you will have to add a new column
+    `last_login_from_ip_address`
+    [#465](https://github.com/NoamB/sorcery/issues/465)
+*   Sinatra support existed until **v0.7.0** (including), but was dropped
+    later due to being a maintenance nightmare.
+*   If upgrading from <= **0.6.1 to >= **0.7.0** you need to change
+    'username_attribute_name' to 'username_attribute_names' in initializer.
+*   If upgrading from <= **v0.5.1** to >= **v0.5.2** you need to explicitly
+    set your user_class model in the initializer file.
+
+        # This line must come after the 'user config' block.
+        config.user_class = User
+
+
+## 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 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.
+
+## Contact
+
+Feel free to ask questions using these contact details:
+
+#### Noam Ben-Ari
+
+email: nbenari@gmail.com ( also for paypal )
+
+twitter: @nbenari
+
+#### Kir Shatrov
+
+email: shatrov@me.com
+
+twitter: @Kiiiir
+
+## Copyright
+
+Copyright (c) 2010 Noam Ben Ari (nbenari@gmail.com). See LICENSE.txt for
+further details.

data/Rakefile

@@ -1,82 +1,6 @@
-# require 'bundler'
-# -- Commented because it's slow
-# begin
-#   Bundler.setup(:default, :development)
-# rescue Bundler::BundlerError => e
-#   $stderr.puts e.message
-#   $stderr.puts "Run `bundle install` to install missing gems"
-#   exit e.status_code
-# end
-# --
+require "bundler/gem_tasks"
 
-require 'rake'
-
-require 'jeweler'
-Jeweler::Tasks.new do |gem|
-  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
-  gem.name = "sorcery"
-  gem.homepage = "http://github.com/NoamB/sorcery"
-  gem.license = "MIT"
-  gem.summary = "Magical authentication for Rails 3 applications"
-  gem.description = "Provides common authentication needs such as signing in/out, activating by email and resetting password."
-  gem.email = "nbenari@gmail.com"
-  gem.authors = ["Noam Ben Ari"]
-  # Include your dependencies below. Runtime dependencies are required when using your gem,
-  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
-  #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
-  #  gem.add_development_dependency 'rspec', '> 1.2.3'
-end
-Jeweler::RubygemsDotOrgTasks.new
-
-require 'rspec/core'
 require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
 
-RSpec::Core::RakeTask.new(:spec) do |spec|
-  spec.pattern = FileList['spec/**/*_spec.rb']
-end
-
-require 'yard'
-YARD::Rake::YardocTask.new
-
-desc 'Default: Run all sorcery specs.'
-task :default => :all_sorcery_specs
-
-desc "Run all sorcery specs"
-task :all_sorcery_specs do
-  # we need to be empty, otherwise bundler will use parent bundler.
-  env = {
-    'BUNDLE_GEMFILE' => nil,
-    'GEM_HOME'       => nil
-  }
-  Dir['spec/**/Rakefile'].each do |rakefile|
-    directory_name = File.dirname(rakefile)
-    system(env, "cd #{directory_name} && bundle && bundle exec rake")
-    abort unless $?.success?
-  end
-end
-
-desc "Bundle all folders"
-task :bundle do
-  sh "bundle"
-  Dir['spec', 'spec/**'].each do |dir|
-    if Dir.exists?(dir) && File.exists?(dir + "/Gemfile")
-      sh <<-CMD
-        cd #{dir}
-        bundle
-      CMD
-    end
-  end
-end
-
-desc "Bundle update all folders"
-task :bundle_update do
-  sh "bundle update"
-  Dir['spec', 'spec/**'].each do |dir|
-    if Dir.exists?(dir) && File.exists?(dir + "/Gemfile")
-      sh <<-CMD
-        cd #{dir}
-        bundle update
-      CMD
-    end
-  end
-end
+task :default => :spec

data/VERSION

@@ -1 +1 @@
-0.8.4
+0.8.5

data/gemfiles/active_record-rails41.gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+gem 'sqlite3'
+gem 'rails', '~> 4.1'
+
+gemspec path: '..'

data/gemfiles/mongo_mapper-rails41.gemfile

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+gem 'rails', '~> 4.1.0'
+
+gem 'mongo_mapper', github: 'mongomapper/mongomapper'
+gem 'sqlite3'
+
+gemspec path: '..'

data/gemfiles/mongoid-rails41.gemfile

@@ -0,0 +1,11 @@
+source 'https://rubygems.org'
+
+gem 'rails', '~> 4.1.0'
+
+gem 'pry'
+
+gem 'mongoid', github: 'mongoid/mongoid'
+gem 'bson_ext'
+gem 'sqlite3'
+
+gemspec path: '..'

data/lib/generators/sorcery/helpers.rb

@@ -0,0 +1,40 @@
+module Sorcery
+  module Generators
+    module Helpers
+      private
+
+      def sorcery_config_path
+        "config/initializers/sorcery.rb"
+      end
+
+      # Either return the model passed in a classified form or return the default "User".
+      def model_class_name
+        options[:model] ? options[:model].classify : "User"
+      end
+
+      def model_path
+        @model_path ||= File.join("app", "models", "#{file_path}.rb")
+      end
+
+      def file_path
+        model_name.underscore
+      end
+
+      def namespace
+        Rails::Generators.namespace if Rails::Generators.respond_to?(:namespace)
+      end
+
+      def namespaced?
+        !!namespace
+      end
+
+      def model_name
+        if namespaced?
+          [namespace.to_s] + [model_class_name]
+        else
+          [model_class_name]
+        end.join("::")
+      end
+    end
+  end
+end

data/lib/generators/sorcery/install_generator.rb

@@ -1,24 +1,26 @@
 require 'rails/generators/migration'
+require 'generators/sorcery/helpers'
 
 module Sorcery
   module Generators
     class InstallGenerator < Rails::Generators::Base
       include Rails::Generators::Migration
-      
+      include Sorcery::Generators::Helpers
+
       source_root File.expand_path('../templates', __FILE__)
-      
+
       argument :submodules, :optional => true, :type => :array, :banner => "submodules"
-      
+
       class_option :model, :optional => true, :type => :string, :banner => "model",
                    :desc => "Specify the model class name if you will use anything other than 'User'"
-                           
+
       class_option :migrations, :optional => true, :type => :boolean, :banner => "migrations",
                    :desc => "Specify if you want to add submodules to an existing model\n\t\t\t     # (will generate migrations files, and add submodules to config file)"
-      
-      
+
+
       # Copy the initializer file to config/initializers folder.
       def copy_initializer_file
-        template "initializer.rb", "config/initializers/sorcery.rb" unless options[:migrations]
+        template "initializer.rb", sorcery_config_path unless options[:migrations]
       end
 
       def configure_initializer_file
@@ -26,19 +28,28 @@ module Sorcery
         if submodules
           submodule_names = submodules.collect{ |submodule| ':' + submodule }
 
-          gsub_file "config/initializers/sorcery.rb", /submodules = \[.*\]/ do |str|
+          gsub_file sorcery_config_path, /submodules = \[.*\]/ do |str|
             current_submodule_names = (str =~ /\[(.*)\]/ ? $1 : '').delete(' ').split(',')
             "submodules = [#{(current_submodule_names | submodule_names).join(', ')}]"
           end
         end
+      end
 
+      def configure_model
         # Generate the model and add 'authenticates_with_sorcery!' unless you passed --migrations
         unless options[:migrations]
           generate "model #{model_class_name} --skip-migration"
-          insert_into_file "app/models/#{model_class_name.underscore}.rb", "  authenticates_with_sorcery!\n", :after => "class #{model_class_name} < ActiveRecord::Base\n"
+
+          inject_sorcery_to_model
         end
       end
 
+      def inject_sorcery_to_model
+        indents = "  " * (namespaced? ? 2 : 1)
+
+        inject_into_class(model_path, model_class_name, "#{indents}authenticates_with_sorcery!\n")
+      end
+
       # Copy the migrations files to db/migrate folder
       def copy_migration_files
         # Copy core migration file in all cases except when you pass --migrations.
@@ -52,10 +63,9 @@ module Sorcery
             end
           end
         end
-        
 
       end
-      
+
       # Define the next_migration_number method (necessary for the migration_template method to work)
       def self.next_migration_number(dirname)
         if ActiveRecord::Base.timestamped_migrations
@@ -65,13 +75,7 @@ module Sorcery
           "%.3d" % (current_migration_number(dirname) + 1)
         end
       end
-      
-      private
 
-      # Either return the model passed in a classified form or return the default "User".
-      def model_class_name
-        options[:model] ? options[:model].classify : "User"
-      end
     end
   end
 end

data/lib/generators/sorcery/templates/initializer.rb

@@ -144,7 +144,7 @@ Rails.application.config.sorcery.configure do |config|
   config.user_config do |user|
     # -- core --
     # specify username attributes, for example: [:username, :email].
-    # Default: `[:username]`
+    # Default: `[:email]`
     #
     # user.username_attribute_names =
 

data/lib/generators/sorcery/templates/migration/activity_logging.rb

@@ -1,19 +1,10 @@
 class SorceryActivityLogging < ActiveRecord::Migration
-  def self.up
+  def change
     add_column :<%= model_class_name.tableize %>, :last_login_at,     :datetime, :default => nil
     add_column :<%= model_class_name.tableize %>, :last_logout_at,    :datetime, :default => nil
     add_column :<%= model_class_name.tableize %>, :last_activity_at,  :datetime, :default => nil
     add_column :<%= model_class_name.tableize %>, :last_login_from_ip_address, :string, :default => nil
-    
-    add_index :<%= model_class_name.tableize %>, [:last_logout_at, :last_activity_at]
-  end
 
-  def self.down
-    remove_index :<%= model_class_name.tableize %>, [:last_logout_at, :last_activity_at]
-    
-    remove_column :<%= model_class_name.tableize %>, :last_login_from_ip_address
-    remove_column :<%= model_class_name.tableize %>, :last_activity_at
-    remove_column :<%= model_class_name.tableize %>, :last_logout_at
-    remove_column :<%= model_class_name.tableize %>, :last_login_at
+    add_index :<%= model_class_name.tableize %>, [:last_logout_at, :last_activity_at]
   end
 end

data/lib/generators/sorcery/templates/migration/brute_force_protection.rb

@@ -1,13 +1,7 @@
 class SorceryBruteForceProtection < ActiveRecord::Migration
-  def self.up
+  def change
     add_column :<%= model_class_name.tableize %>, :failed_logins_count, :integer, :default => 0
     add_column :<%= model_class_name.tableize %>, :lock_expires_at, :datetime, :default => nil
     add_column :<%= model_class_name.tableize %>, :unlock_token, :string, :default => nil
   end
-
-  def self.down
-    remove_column :<%= model_class_name.tableize %>, :lock_expires_at
-    remove_column :<%= model_class_name.tableize %>, :failed_logins_count
-    remove_column :<%= model_class_name.tableize %>, :unlock_token
-  end
 end

data/lib/generators/sorcery/templates/migration/core.rb

@@ -1,16 +1,13 @@
 class SorceryCore < ActiveRecord::Migration
-  def self.up
+  def change
     create_table :<%= model_class_name.tableize %> do |t|
-      t.string :username,         :null => false  # if you use another field 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.string :email,            :null => false
+      t.string :crypted_password, :null => false
+      t.string :salt,             :null => false
 
       t.timestamps
     end
-  end
 
-  def self.down
-    drop_table :<%= model_class_name.tableize %>
+    add_index :<%= model_class_name.tableize %>, :email, unique: true
   end
 end

data/lib/generators/sorcery/templates/migration/external.rb

@@ -1,5 +1,5 @@
 class SorceryExternal < ActiveRecord::Migration
-  def self.up
+  def change
     create_table :authentications do |t|
       t.integer :<%= model_class_name.tableize.singularize %>_id, :null => false
       t.string :provider, :uid, :null => false
@@ -7,8 +7,4 @@ class SorceryExternal < ActiveRecord::Migration
       t.timestamps
     end
   end
-
-  def self.down
-    drop_table :authentications
-  end
 end

data/lib/generators/sorcery/templates/migration/remember_me.rb

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