devise-two-factor 1.0.0

data/lib/devise_two_factor/models.rb

@@ -0,0 +1,2 @@
+require 'devise_two_factor/models/two_factor_authenticatable'
+require 'devise_two_factor/models/two_factor_backupable'

data/lib/devise_two_factor/models/two_factor_authenticatable.rb

@@ -0,0 +1,62 @@
+require 'active_model'
+require 'attr_encrypted'
+require 'rotp'
+
+module Devise
+  module Models
+    module TwoFactorAuthenticatable
+      extend ActiveSupport::Concern
+      include Devise::Models::DatabaseAuthenticatable
+
+      included do
+        attr_encrypted :otp_secret, :key  => self.otp_secret_encryption_key,
+                                    :mode => :per_attribute_iv_and_salt
+
+        attr_accessor :otp_attempt
+      end
+
+      def self.required_fields(klass)
+        [:encrypted_otp_secret, :encrypted_otp_secret_iv, :encrypted_otp_secret_salt]
+      end
+
+      # This defaults to the model's otp_secret
+      # If this hasn't been generated yet, pass a secret as an  option
+      def valid_otp?(code, options = {})
+        otp_secret = options[:otp_secret] || self.otp_secret
+        return false unless otp_secret.present?
+
+        totp = self.otp(otp_secret)
+        totp.verify_with_drift(code, self.class.otp_allowed_drift)
+      end
+
+      def otp(otp_secret = self.otp_secret)
+        ROTP::TOTP.new(otp_secret)
+      end
+
+      def current_otp
+        otp.at(Time.now)
+      end
+
+      def otp_provisioning_uri(account, options = {})
+        otp_secret = options[:otp_secret] || self.otp_secret
+        ROTP::TOTP.new(otp_secret, options).provisioning_uri(account)
+      end
+
+      def clean_up_passwords
+        self.otp_attempt = nil
+      end
+
+    protected
+
+      module ClassMethods
+        Devise::Models.config(self, :otp_secret_length,
+                                    :otp_allowed_drift,
+                                    :otp_secret_encryption_key)
+
+        def generate_otp_secret(otp_secret_length = self.otp_secret_length)
+          ROTP::Base32.random_base32(otp_secret_length)
+        end
+      end
+    end
+  end
+end

data/lib/devise_two_factor/models/two_factor_backupable.rb

@@ -0,0 +1,66 @@
+require 'active_model'
+
+module Devise
+  module Models
+    # TwoFactorBackupable allows a user to generate backup codes which
+    # provide one-time access to their account in the event that they have
+    # lost access to their two-factor device
+    module TwoFactorBackupable
+      extend ActiveSupport::Concern
+
+      def self.required_fields(klass)
+        [:otp_backup_codes]
+      end
+
+      # 1) Invalidates all existing backup codes
+      # 2) Generates otp_number_of_backup_codes backup codes
+      # 3) Stores the hashed backup codes in the database
+      # 4) Returns a plaintext array of the generated backup codes
+      def generate_otp_backup_codes!
+        codes           = []
+        number_of_codes = self.class.otp_number_of_backup_codes
+        code_length     = self.class.otp_backup_code_length
+
+        number_of_codes.times do
+          codes << SecureRandom.hex(code_length / 2) # Hexstring has length 2*n
+        end
+
+        hashed_codes = codes.map { |code| Devise.bcrypt self.class, code }
+        self.otp_backup_codes = hashed_codes
+
+        codes
+      end
+
+      # Returns true and invalidates the given code
+      # iff that code is a valid backup code.
+      def invalidate_otp_backup_code!(code)
+        codes = self.otp_backup_codes || []
+
+        codes.each do |backup_code|
+          # We hashed the code with Devise.bcrypt, so if Devise changes that
+          # method, we'll have to adjust our comparison here to match it
+          # TODO Fork Devise and encapsulate this logic in a helper
+          bcrypt      = ::BCrypt::Password.new(backup_code)
+          hashed_code = ::BCrypt::Engine.hash_secret("#{code}#{self.class.pepper}",
+                                                     bcrypt.salt)
+
+          next unless Devise.secure_compare(hashed_code, backup_code)
+
+          codes.delete(backup_code)
+          self.otp_backup_codes = codes
+          return true
+        end
+
+        false
+      end
+
+    protected
+
+      module ClassMethods
+        Devise::Models.config(self, :otp_backup_code_length,
+                                    :otp_number_of_backup_codes,
+                                    :pepper)
+      end
+    end
+  end
+end

data/lib/devise_two_factor/spec_helpers.rb

@@ -0,0 +1,2 @@
+require 'devise_two_factor/spec_helpers/two_factor_authenticatable_shared_examples'
+require 'devise_two_factor/spec_helpers/two_factor_backupable_shared_examples'

data/lib/devise_two_factor/spec_helpers/two_factor_authenticatable_shared_examples.rb

@@ -0,0 +1,76 @@
+shared_examples 'two_factor_authenticatable' do
+  before :each do
+    subject.otp_secret = subject.class.generate_otp_secret
+  end
+
+  describe 'required_fields' do
+    it 'should have the attr_encrypted fields for otp_secret' do
+      Devise::Models::TwoFactorAuthenticatable.required_fields(subject.class).should =~ ([:encrypted_otp_secret, :encrypted_otp_secret_iv, :encrypted_otp_secret_salt])
+    end
+  end
+
+  describe '#otp_secret' do
+    it 'should be of the configured length' do
+      subject.otp_secret.length.should eq(subject.class.otp_secret_length)
+    end
+
+    it 'stores the encrypted otp_secret' do
+      subject.encrypted_otp_secret.should_not be_nil
+    end
+
+    it 'stores an iv for otp_secret' do
+      subject.encrypted_otp_secret_iv.should_not be_nil
+    end
+
+    it 'stores a salt for otp_secret' do
+      subject.encrypted_otp_secret_salt.should_not be_nil
+    end
+  end
+
+  describe '#valid_otp?' do
+    let(:otp_secret) { '2z6hxkdwi3uvrnpn' }
+
+    before :each do
+      Timecop.freeze(Time.current)
+      subject.otp_secret = otp_secret
+    end
+
+    after :each do
+      Timecop.return
+    end
+
+    it 'validates a precisely correct OTP' do
+      otp = ROTP::TOTP.new(otp_secret).at(Time.now)
+      subject.valid_otp?(otp).should be_true
+    end
+
+    it 'validates an OTP within the allowed drift' do
+      otp = ROTP::TOTP.new(otp_secret).at(Time.now + subject.class.otp_allowed_drift, true)
+      subject.valid_otp?(otp).should be_true
+    end
+
+    it 'does not validate an OTP above the allowed drift' do
+      otp = ROTP::TOTP.new(otp_secret).at(Time.now + subject.class.otp_allowed_drift * 2, true)
+      subject.valid_otp?(otp).should be_false
+    end
+
+    it 'does not validate an OTP below the allowed drift' do
+      otp = ROTP::TOTP.new(otp_secret).at(Time.now - subject.class.otp_allowed_drift * 2, true)
+      subject.valid_otp?(otp).should be_false
+    end
+  end
+
+  describe '#otp_provisioning_uri' do
+    let(:otp_secret_length) { subject.class.otp_secret_length }
+    let(:account)           { Faker::Internet.email }
+    let(:issuer)            { "Tinfoil" }
+
+    it "should return uri with specified account" do
+      subject.otp_provisioning_uri(account).should match(%r{otpauth://totp/#{account}\?secret=\w{#{otp_secret_length}}})
+    end
+
+    it 'should return uri with issuer option' do
+      subject.otp_provisioning_uri(account, issuer: issuer).should match(%r{otpauth://totp/#{account}\?issuer=#{issuer}&secret=\w{#{otp_secret_length}}$})
+    end
+  end
+end

data/lib/devise_two_factor/spec_helpers/two_factor_backupable_shared_examples.rb

@@ -0,0 +1,89 @@
+shared_examples 'two_factor_backupable' do
+  describe 'required_fields' do
+    it 'has the attr_encrypted fields for otp_backup_codes' do
+      Devise::Models::TwoFactorBackupable.required_fields(subject.class).should =~ [:otp_backup_codes]
+    end
+  end
+
+  describe '#generate_otp_backup_codes!' do
+    context 'with no existing recovery codes' do
+      before do
+        @plaintext_codes = subject.generate_otp_backup_codes!
+      end
+
+      it 'generates the correct number of new recovery codes' do
+        subject.otp_backup_codes.length.should
+          eq(subject.class.otp_number_of_backup_codes)
+      end
+
+      it 'generates recovery codes of the correct length' do
+        @plaintext_codes.each do |code|
+          code.length.should eq(subject.class.otp_backup_code_length)
+        end
+      end
+
+      it 'generates distinct recovery codes' do
+        @plaintext_codes.uniq.should =~ @plaintext_codes
+      end
+
+      it 'stores the codes as BCrypt hashes' do
+        subject.otp_backup_codes.each do |code|
+          # $algorithm$cost$(22 character salt + 31 character hash)
+          code.should =~ /\A\$[0-9a-z]{2}\$[0-9]{2}\$[A-Za-z0-9\.\/]{53}\z/
+        end
+      end
+    end
+
+    context 'with existing recovery codes' do
+      let(:old_codes)        { Faker::Lorem.words }
+      let(:old_codes_hashed) { old_codes.map { |x| Devise.bcrypt subject.class, x } }
+
+      before do
+        subject.otp_backup_codes = old_codes_hashed
+        @plaintext_codes = subject.generate_otp_backup_codes!
+      end
+
+      it 'invalidates the existing recovery codes' do
+        (subject.otp_backup_codes & old_codes_hashed).should =~ []
+      end
+    end
+  end
+
+  describe '#invalidate_otp_backup_code!' do
+    before do
+      @plaintext_codes = subject.generate_otp_backup_codes!
+    end
+
+    context 'given an invalid recovery code' do
+      it 'returns false' do
+        subject.invalidate_otp_backup_code!('password').should be_false
+      end
+    end
+
+    context 'given a valid recovery code' do
+      it 'returns true' do
+        @plaintext_codes.each do |code|
+          subject.invalidate_otp_backup_code!(code).should be_true
+        end
+      end
+
+      it 'invalidates that recovery code' do
+        code = @plaintext_codes.sample
+
+        subject.invalidate_otp_backup_code!(code)
+        subject.invalidate_otp_backup_code!(code).should be_false
+      end
+
+      it 'does not invalidate the other recovery codes' do
+        code = @plaintext_codes.sample
+        subject.invalidate_otp_backup_code!(code)
+
+        @plaintext_codes.delete(code)
+
+        @plaintext_codes.each do |code|
+          subject.invalidate_otp_backup_code!(code).should be_true
+        end
+      end
+    end
+  end
+end

data/lib/devise_two_factor/strategies.rb

@@ -0,0 +1,2 @@
+require 'devise_two_factor/strategies/two_factor_authenticatable'
+require 'devise_two_factor/strategies/two_factor_backupable'

data/lib/devise_two_factor/strategies/two_factor_authenticatable.rb

@@ -0,0 +1,26 @@
+module Devise
+  module Strategies
+    class TwoFactorAuthenticatable < Devise::Strategies::DatabaseAuthenticatable
+
+      def authenticate!
+        resource = mapping.to.find_for_database_authentication(authentication_hash)
+        # We authenticate in two cases:
+        # 1. The password and the OTP are correct
+        # 2. The password is correct, and OTP is not required for login
+        # We check the OTP, then defer to DatabaseAuthenticatable
+        if validate(resource) { !resource.otp_required_for_login ||
+                                resource.valid_otp?(params[scope]['otp_attempt']) }
+          super
+        end
+
+        fail(:not_found_in_database) unless resource
+
+        # We want to cascade to the next strategy if this one fails,
+        # but database authenticatable automatically halts on a bad password
+        @halted = false if @result == :failure
+      end
+    end
+  end
+end
+
+Warden::Strategies.add(:two_factor_authenticatable, Devise::Strategies::TwoFactorAuthenticatable)

data/lib/devise_two_factor/strategies/two_factor_backupable.rb

@@ -0,0 +1,25 @@
+module Devise
+  module Strategies
+    class TwoFactorBackupable < Devise::Strategies::DatabaseAuthenticatable
+
+      def authenticate!
+        resource = mapping.to.find_for_database_authentication(authentication_hash)
+
+        if validate(resource) { resource.invalidate_otp_backup_code!(params[scope]['otp_attempt']) }
+          # Devise fails to authenticate invalidated resources, but if we've
+          # gotten here, the object changed (Since we deleted a recovery code)
+          resource.save!
+          super
+        end
+
+        fail(:not_found_in_database) unless resource
+
+        # We want to cascade to the next strategy if this one fails,
+        # but database authenticatable automatically halts on a bad password
+        @halted = false if @result == :failure
+      end
+    end
+  end
+end
+
+Warden::Strategies.add(:two_factor_backupable, Devise::Strategies::TwoFactorBackupable)

data/lib/devise_two_factor/version.rb

@@ -0,0 +1,3 @@
+module DeviseTwoFactor
+   VERSION = '1.0.0'.freeze
+end

data/lib/generators/devise_two_factor/devise_two_factor_generator.rb

@@ -0,0 +1,79 @@
+require 'rails/generators'
+
+module DeviseTwoFactor
+  module Generators
+    class DeviseTwoFactorGenerator < Rails::Generators::NamedBase
+      argument :encryption_key_env, :type => :string, :required => true
+
+      desc 'Creates a migration to add the required attributes to NAME, and ' \
+           'adds the necessary Devise directives to the model'
+
+      def install_devise_two_factor
+        create_devise_two_factor_migration
+        inject_strategies_into_warden_config
+        inject_devise_directives_into_model
+      end
+
+    private
+
+      def create_devise_two_factor_migration
+        migration_arguments = [
+                                "add_devise_two_factor_to_#{plural_name}",
+                                "encrypted_otp_secret:string",
+                                "encrypted_otp_secret_iv:string",
+                                "encrypted_otp_secret_salt:string",
+                                "otp_required_for_login:boolean"
+                              ]
+
+        Rails::Generators.invoke('active_record:migration', migration_arguments)
+      end
+
+      def inject_strategies_into_warden_config
+        config_path = File.join('config', 'initializers', 'devise.rb')
+
+        content = "  config.warden do |manager|\n" \
+                  "    manager.default_strategies(:scope => :#{singular_table_name}).unshift :two_factor_authenticatable\n" \
+                  "  end\n\n"
+
+        inject_into_file(config_path, content, after: "Devise.setup do |config|\n")
+      end
+
+      def inject_devise_directives_into_model
+        model_path = File.join('app', 'models', "#{file_path}.rb")
+
+        class_path = if namespaced?
+          class_name.to_s.split("::")
+        else
+          [class_name]
+        end
+
+        indent_depth = class_path.size
+
+        content = [
+                    "devise :two_factor_authenticatable,",
+                    "       :otp_secret_encryption_key => ENV['#{encryption_key_env}']\n"
+                  ]
+
+        content << "attr_accessible :otp_attempt\n" if needs_attr_accessible?
+        content = content.map { |line| "  " * indent_depth + line }.join("\n") << "\n"
+
+        inject_into_class(model_path, class_path.last, content)
+
+        # Remove :database_authenticatable from the list of loaded models
+        gsub_file(model_path, /(devise.*):(, )?database_authenticatable(, )?/, '\1\2')
+      end
+
+      def needs_attr_accessible?
+        !strong_parameters_enabled? && mass_assignment_security_enabled?
+      end
+
+      def strong_parameters_enabled?
+        defined?(ActionController::StrongParameters)
+      end
+
+      def mass_assignment_security_enabled?
+        defined?(ActiveModel::MassAssignmentSecurity)
+      end
+    end
+  end
+end