devise-two-factor 4.1.1 → 6.4.0

data/UPGRADING.md

@@ -1,4 +1,220 @@
-# Guide to upgrading from 2.x to 3.x
+# Upgrading
+
+## Upgrading from 5.x to 6.x
+
+### save!
+
+`consume_otp!` and `invalidate_otp_backup_code!` now call `save!` instead of `save` (or nothing at all in the case of `invalidate_otp_backup_code!`). If you manually called `save`/`save!` after calling `invalidate_otp_backup_code!` you may be able to remove it.
+
+### Secret Lengths
+
+The `otp_secret_length` and `otp_backup_code_length` options have changed to be the number of random bytes that are generated.
+If you had configured these values you may want to change them if you wish to keep the same output length.
+
+`otp_secret_length` now has a default value of 20, generating a 160 bit secret key with an output length length of 32 bytes.
+
+`otp_backup_code_length` now has a default value of 16, generating a 32 byte backup code.
+
+## Upgrading from 4.x to 5.x
+
+### Background
+
+#### Database columns in version 4.x and older
+
+Versions 4.x and older stored the OTP secret in an attribute called `encrypted_otp_secret` using the [attr_encrypted](https://github.com/attr-encrypted/attr_encrypted) gem. This gem is currently unmaintained which is part of the motivation for moving to Rails encrypted attributes. This attribute was backed by three database columns:
+
+```
+encrypted_otp_secret
+encrypted_otp_secret_iv
+encrypted_otp_secret_salt
+```
+
+Two other columns were also created:
+
+```
+consumed_timestep
+otp_required_for_login
+```
+
+A fresh install of 4.x would create all five of the database columns above.
+
+#### Database columns in version 5.x and later
+
+Versions 5+ of this gem uses a single [Rails 7+ encrypted attribute](https://edgeguides.rubyonrails.org/active_record_encryption.html) named `otp_secret`to store the OTP secret in the database table (usually `users` but will be whatever model you picked).
+
+A fresh install of 5+ will add the following columns to your `users` table:
+
+```bash
+otp_secret # this replaces encrypted_otp_secret, encrypted_otp_secret_iv, encrypted_otp_secret_salt
+consumed_timestep
+otp_required_for_login
+```
+
+We have attempted to make the upgrade as painless as possible but unfortunately because of the secret storage change, it cannot be as simple as `bundle update devise-two-factor` :heart:
+
+### Assumptions
+
+This guide assumes you are upgrading an existing Rails 6 app (with `devise` and `devise-two-factor`) to Rails 7.
+
+This gem must be upgraded **as part of a Rails 7 upgrade**. See [the official Rails upgrading guide](https://guides.rubyonrails.org/upgrading_ruby_on_rails.html) for an overview of upgrading Rails.
+
+### Phase 1: Upgrading devise-two-factor as part of Rails 7 upgrade
+
+1. Update the version constraint for Rails in your `Gemfile` to your desired version e.g. `gem "rails", "~> 7.0.3"`
+1. Run `bundle install` and resolve any issues with dependencies.
+1. Update the version constraint for `devise-two-factor` in your `Gemfile` to the the latest version (must be at least 5.x e.g. `~> 5.0`
+1. Run `./bin/rails app:update` as per the [Rails upgrade guide](https://guides.rubyonrails.org/upgrading_ruby_on_rails.html) and tweak the output as required for your app.
+1. Run `./bin/rails db:migrate` to update your DB based on the changes made by `app:update`
+1. Add a new `otp_secret` attribute to your user model
+    ```bash
+    # TODO: replace 'User' in the migration name with the name of your user model
+    ./bin/rails g migration AddOtpSecretToUser otp_secret:string
+    ./bin/rails db:migrate
+    ```
+1. Add a `legacy_otp_secret` method to your user model e.g. `User`.
+  * This method is used by the gem to find and decode the OTP secret from the legacy database columns.
+  * The implementation shown below works if you set up devise-two-factor with the settings suggested in the [OLD README](https://github.com/devise-two-factor/devise-two-factor/blob/8d74f5ee45594bf00e60d5d49eb6fcde82c2d2ba/README.md).
+  * If you have customised the encryption scheme used to store the OTP secret then you will need to update this method to match.
+  * If you are unsure, you should try the method below as is, and if you can still sign in users with OTP enabled then all is well.
+    ```ruby
+    class User
+      # ...
+
+      private
+
+      ##
+      # Decrypt and return the `encrypted_otp_secret` attribute which was used in
+      # prior versions of devise-two-factor
+      # @return [String] The decrypted OTP secret
+      def legacy_otp_secret
+        return nil unless self[:encrypted_otp_secret]
+        return nil unless self.class.otp_secret_encryption_key
+
+        hmac_iterations = 2000 # a default set by the Encryptor gem
+        key = self.class.otp_secret_encryption_key
+        salt = Base64.decode64(encrypted_otp_secret_salt)
+        iv = Base64.decode64(encrypted_otp_secret_iv)
+
+        raw_cipher_text = Base64.decode64(encrypted_otp_secret)
+        # The last 16 bytes of the ciphertext are the authentication tag - we use
+        # Galois Counter Mode which is an authenticated encryption mode
+        cipher_text = raw_cipher_text[0..-17]
+        auth_tag =  raw_cipher_text[-16..-1]
+
+        # this algorithm lifted from
+        # https://github.com/attr-encrypted/encryptor/blob/master/lib/encryptor.rb#L54
+
+        # create an OpenSSL object which will decrypt the AES cipher with 256 bit
+        # keys in Galois Counter Mode (GCM). See
+        # https://ruby.github.io/openssl/OpenSSL/Cipher.html
+        cipher = OpenSSL::Cipher.new('aes-256-gcm')
+
+        # tell the cipher we want to decrypt. Symmetric algorithms use a very
+        # similar process for encryption and decryption, hence the same object can
+        # do both.
+        cipher.decrypt
+
+        # Use a Password-Based Key Derivation Function to generate the key actually
+        # used for encryption from the key we got as input.
+        cipher.key = OpenSSL::PKCS5.pbkdf2_hmac_sha1(key, salt, hmac_iterations, cipher.key_len)
+
+        # set the Initialization Vector (IV)
+        cipher.iv = iv
+
+        # The tag must be set after calling Cipher#decrypt, Cipher#key= and
+        # Cipher#iv=, but before calling Cipher#final. After all decryption is
+        # performed, the tag is verified automatically in the call to Cipher#final.
+        #
+        # If the auth_tag does not verify, then #final will raise OpenSSL::Cipher::CipherError
+        cipher.auth_tag = auth_tag
+
+        # auth_data must be set after auth_tag has been set when decrypting See
+        # http://ruby-doc.org/stdlib-2.0.0/libdoc/openssl/rdoc/OpenSSL/Cipher.html#method-i-auth_data-3D
+        # we are not adding any authenticated data but OpenSSL docs say this should
+        # still be called.
+        cipher.auth_data = ''
+
+        # #update is (somewhat confusingly named) the method which actually
+        # performs the decryption on the given chunk of data. Our OTP secret is
+        # short so we only need to call it once.
+        #
+        # It is very important that we call #final because:
+        #
+        # 1. The authentication tag is checked during the call to #final
+        # 2. Block based cipher modes (e.g. CBC) work on fixed size chunks. We need
+        #    to call #final to get it to process the last chunk properly. The output
+        #    of #final should be appended to the decrypted value. This isn't
+        #    required for streaming cipher modes but including it is a best practice
+        #    so that your code will continue to function correctly even if you later
+        #    change to a block cipher mode.
+        cipher.update(cipher_text) + cipher.final
+      end
+    end
+    ```
+2. Set up [Rails encrypted secrets](https://edgeguides.rubyonrails.org/active_record_encryption.html)
+    ```bash
+    ./bin/rails db:encryption:init
+    # capture the output and put in encrypted credentials via
+    ./bin/rails credentials:edit
+    ```
+3. Complete your Rails 7 upgrade (making whatever other changes are required)
+
+You can now deploy your upgraded application and devise-two-factor should work as before.
+
+This gem will fall back to **reading** the OTP secret from the legacy columns if it cannot find one in the new `otp_secret` column. When you **write** a new OTP secret it will always be written to the new `otp_secret` column.
+
+### Phase 2: Clean up
+
+This "clean up" phase can happen at the same time as your initial deployment but teams managing existing apps will likely want to do clean-up as separate, later deployments.
+
+1. Create a rake task to copy the OTP secret for each user from the legacy column to the new `otp_secret` column. This prepares the way for us to remove the legacy columns in a later step.
+    ```ruby
+    # lib/tasks/devise_two_factor_migration.rake
+
+    # Use this as a starting point for your task to migrate your user's OTP secrets.
+    namespace :devise_two_factor do
+      desc "Copy devise_two_factor OTP secret from old format to new format"
+      task copy_otp_secret_to_rails7_encrypted_attr: [:environment] do
+        # TODO: change User to your user model
+        User.find_each do |user| # find_each finds in batches of 1,000 by default
+          otp_secret = user.otp_secret # read from otp_secret column, fall back to legacy columns if new column is empty
+          puts "Processing #{user.email}"
+          user.update!(otp_secret: otp_secret)
+        end
+      end
+    end
+    ```
+1. Remove the `#legacy_otp_secret` method from your user model (e.g. `User`) because it is no longer required.
+1. Remove the now unused legacy columns from the database. This assumes you have run a rake task as in the previous step to migrate all the legacy stored secrets to the new storage.
+    ```bash
+    # TODO: replace 'Users' in migration name with the name of your user model
+    ./bin/rails g migration RemoveLegacyDeviseTwoFactorSecretsFromUsers
+    ```
+    which generates
+    ```ruby
+    class RemoveLegacyDeviseTwoFactorSecretsFromUsers < ActiveRecord::Migration[7.0]
+      def change
+        # TODO: change :users to whatever your users table is
+
+        # WARNING: Only run this when you are confident you have copied the OTP
+        # secret for ALL users from `encrypted_otp_secret` to `otp_secret`!
+        remove_column :users, :encrypted_otp_secret
+        remove_column :users, :encrypted_otp_secret_iv
+        remove_column :users, :encrypted_otp_secret_salt
+      end
+    end
+    ```
+1. Remove `otp_secret_encryption_key` from the model setup. This also assumes you successfully ran the rake task in step 1.
+    ```ruby
+    # from this:
+    devise :two_factor_authenticatable,
+        otp_secret_encryption_key: ENV['YOUR_ENCRYPTION_KEY_HERE']
+
+    # to this:
+    devise :two_factor_authenticatable
+    ```
+
+## Upgrading from 2.x to 3.x
 
 Pull request #76 allows for compatibility with `attr_encrypted` 3.0, which should be used due to a security vulnerability discovered in 2.0.
 
@@ -18,7 +234,7 @@ class User < ActiveRecord::Base
          :otp_secret_encryption_key => ENV['DEVISE_TWO_FACTOR_ENCRYPTION_KEY']
 ```
 
-# Guide to upgrading from 1.x to 2.x
+## Upgrading from 1.x to 2.x
 
 Pull request #43 added a new field to protect against "shoulder-surfing" attacks. If upgrading, you'll need to add the `:consumed_timestep` column to your `Users` model.
 

data/devise-two-factor.gemspec

@@ -5,26 +5,19 @@ Gem::Specification.new do |s|
   s.name        = 'devise-two-factor'
   s.version     = DeviseTwoFactor::VERSION.dup
   s.platform    = Gem::Platform::RUBY
-  s.licenses    = ['MIT']
+  s.license     = 'MIT'
   s.summary     = 'Barebones two-factor authentication with Devise'
-  s.email       = 'engineers@tinfoilsecurity.com'
-  s.homepage    = 'https://github.com/tinfoil/devise-two-factor'
-  s.description = 'Barebones two-factor authentication with Devise'
-  s.authors     = ['Shane Wilton']
+  s.homepage    = 'https://github.com/devise-two-factor/devise-two-factor'
+  s.description = 'Devise-Two-Factor is a minimalist extension to Devise which offers support for two-factor authentication through the TOTP scheme.'
+  s.authors     = ['Quinn Wilton']
 
-  s.cert_chain  = [
-                    'certs/tinfoil-cacert.pem',
-                    'certs/tinfoilsecurity-gems-cert.pem'
-                  ]
-  s.signing_key = File.expand_path("~/.ssh/tinfoilsecurity-gems-key.pem") if $0 =~ /gem\z/
   s.files         = `git ls-files`.split("\n").delete_if { |x| x.match('demo/*') }
   s.test_files    = `git ls-files -- spec/*`.split("\n")
   s.require_paths = ['lib']
 
-  s.add_runtime_dependency 'railties',       '~> 7.0'
-  s.add_runtime_dependency 'activesupport',  '~> 7.0'
-  s.add_runtime_dependency 'attr_encrypted', '>= 1.3', '< 5', '!= 2'
-  s.add_runtime_dependency 'devise',         '~> 4.0'
+  s.add_runtime_dependency 'railties',       '>= 7.2', '< 8.2'
+  s.add_runtime_dependency 'activesupport',  '>= 7.2', '< 8.2'
+  s.add_runtime_dependency 'devise',         '>= 4.0', '< 6.0'
   s.add_runtime_dependency 'rotp',           '~> 6.0'
 
   s.add_development_dependency 'activemodel'
@@ -32,5 +25,5 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'bundler',    '> 1.0'
   s.add_development_dependency 'rspec',      '> 3'
   s.add_development_dependency 'simplecov'
-  s.add_development_dependency 'faker'
+  s.add_development_dependency 'rake', '~> 13'
 end

data/gemfiles/{rails_4.2.gemfile → rails_7.2.gemfile}

@@ -2,7 +2,7 @@
 
 source "https://rubygems.org"
 
-gem "railties", "~> 4.2"
-gem "activesupport", "~> 4.2"
+gem "railties", "~> 7.2.0"
+gem "activesupport", "~> 7.2.0"
 
 gemspec path: "../"

data/gemfiles/{rails_5.0.gemfile → rails_8.0.gemfile}

@@ -2,7 +2,7 @@
 
 source "https://rubygems.org"
 
-gem "railties", "~> 5.0"
-gem "activesupport", "~> 5.0"
+gem "railties", "~> 8.0.0"
+gem "activesupport", "~> 8.0.0"
 
 gemspec path: "../"

data/gemfiles/{rails_4.1.gemfile → rails_8.1.gemfile}

@@ -2,7 +2,7 @@
 
 source "https://rubygems.org"
 
-gem "railties", "~> 4.1"
-gem "activesupport", "~> 4.1"
+gem "railties", "8.1.0"
+gem "activesupport", "8.1.0"
 
 gemspec path: "../"

data/lib/devise-two-factor.rb

@@ -1,22 +1,29 @@
+require 'logger'
 require 'devise'
 require 'devise_two_factor/models'
 require 'devise_two_factor/strategies'
 
 module Devise
-  # The length of generated OTP secrets
+  # The length of randomly generated OTP shared secret (in bytes).
+  # The secrets will be base32-encoded and have a length 1.6 times the configured value.
   mattr_accessor :otp_secret_length
-  @@otp_secret_length = 24
+  @@otp_secret_length = 20
 
   # The number of seconds before and after the current
   # time for which codes will be accepted
   mattr_accessor :otp_allowed_drift
   @@otp_allowed_drift = 30
 
-  # The key used to encrypt OTP secrets in the database
+  # The key used to encrypt OTP secrets in the database in legacy installs.
   mattr_accessor :otp_secret_encryption_key
   @@otp_secret_encryption_key = nil
 
-  # The length of all generated OTP backup codes
+  # These options are passed to the Rails 7+ encrypted attribute
+  mattr_accessor :otp_encrypted_attribute_options
+  @@otp_encrypted_attribute_options = {}
+
+  # The length of randomly generated OTP backup codes (in bytes).
+  # The codes will be hex-encoded and have a length twice the configured value.
   mattr_accessor :otp_backup_code_length
   @@otp_backup_code_length = 16
 
@@ -27,7 +34,7 @@ module Devise
 end
 
 Devise.add_module(:two_factor_authenticatable, :route => :session, :strategy => true,
-                  :controller => :sessions, :model  => true)
+                  :controller => :sessions, :model  => true, :insert_at => 0)
 
 Devise.add_module(:two_factor_backupable, :route => :session, :strategy => true,
                   :controller => :sessions, :model  => true)

data/lib/devise_two_factor/models/two_factor_authenticatable.rb

@@ -7,25 +7,28 @@ module Devise
       include Devise::Models::DatabaseAuthenticatable
 
       included do
-        unless %i[otp_secret otp_secret=].all? { |attr| method_defined?(attr) }
-          require 'attr_encrypted'
-
-          unless singleton_class.ancestors.include?(AttrEncrypted)
-            extend AttrEncrypted
-          end
-
-          unless attr_encrypted?(:otp_secret)
-            attr_encrypted :otp_secret,
-              :key  => self.otp_secret_encryption_key,
-              :mode => :per_attribute_iv_and_salt unless self.attr_encrypted?(:otp_secret)
-          end
-        end
-
+        encrypts :otp_secret, **splattable_encrypted_attr_options
         attr_accessor :otp_attempt
       end
 
+      def otp_secret
+        # return the OTP secret stored as a Rails encrypted attribute if it
+        # exists. Otherwise return OTP secret stored by the `attr_encrypted` gem
+        return self[:otp_secret] if self[:otp_secret]
+
+        legacy_otp_secret
+      end
+
+      ##
+      # Decrypt and return the `encrypted_otp_secret` attribute which was used in
+      # prior versions of devise-two-factor
+      # See: # https://github.com/tinfoil/devise-two-factor/blob/main/UPGRADING.md
+      def legacy_otp_secret
+        nil
+      end
+
       def self.required_fields(klass)
-        [:encrypted_otp_secret, :encrypted_otp_secret_iv, :encrypted_otp_secret_salt, :consumed_timestep]
+        [:otp_secret, :consumed_timestep]
       end
 
       # This defaults to the model's otp_secret
@@ -38,12 +41,11 @@ module Devise
 
         if self.consumed_timestep
           # reconstruct the timestamp of the last consumed timestep
-          after_timestamp = self.consumed_timestep * otp.interval
+          after_timestamp = self.consumed_timestep * totp.interval
         end
 
-        if totp.verify(code.gsub(/\s+/, ""), drift_behind: self.class.otp_allowed_drift, drift_ahead: self.class.otp_allowed_drift, after: after_timestamp)
-          return consume_otp!
-        end
+        timestamp = totp.verify(code.gsub(/\s+/, ""), drift_behind: self.class.otp_allowed_drift, drift_ahead: self.class.otp_allowed_drift, after: after_timestamp)
+        return consume_otp!(totp, timestamp) if timestamp
 
         false
       end
@@ -56,11 +58,6 @@ module Devise
         otp.at(Time.now)
       end
 
-      # ROTP's TOTP#timecode is private, so we duplicate it here
-      def current_otp_timestep
-         Time.now.utc.to_i / otp.interval
-      end
-
       def otp_provisioning_uri(account, options = {})
         otp_secret = options[:otp_secret] || self.otp_secret
         ROTP::TOTP.new(otp_secret, options).provisioning_uri(account)
@@ -75,10 +72,14 @@ module Devise
 
       # An OTP cannot be used more than once in a given timestep
       # Storing timestep of last valid OTP is sufficient to satisfy this requirement
-      def consume_otp!
-        if self.consumed_timestep != current_otp_timestep
-          self.consumed_timestep = current_otp_timestep
-          return save(validate: false)
+      def consume_otp!(otp, timestamp)
+        timestep = timestamp / otp.interval
+
+        if self.consumed_timestep != timestep
+          self.consumed_timestep = timestep
+          save!(validate: false)
+
+          return true
         end
 
         false
@@ -87,10 +88,21 @@ module Devise
       module ClassMethods
         Devise::Models.config(self, :otp_secret_length,
                                     :otp_allowed_drift,
+                                    :otp_encrypted_attribute_options,
                                     :otp_secret_encryption_key)
 
+        # Generates an OTP secret of the specified length, returning it after Base32 encoding.
         def generate_otp_secret(otp_secret_length = self.otp_secret_length)
-          ROTP::Base32.random_base32(otp_secret_length)
+          ROTP::Base32.random(otp_secret_length)
+        end
+
+        # Return value will be splatted with ** so return a version of the
+        # encrypted attribute options which is always a Hash.
+        # @return [Hash]
+        def splattable_encrypted_attr_options
+          return {} if otp_encrypted_attribute_options.nil?
+
+          otp_encrypted_attribute_options
         end
       end
     end

data/lib/devise_two_factor/models/two_factor_backupable.rb

@@ -20,7 +20,7 @@ module Devise
         code_length     = self.class.otp_backup_code_length
 
         number_of_codes.times do
-          codes << SecureRandom.hex(code_length / 2) # Hexstring has length 2*n
+          codes << SecureRandom.hex(code_length)
         end
 
         hashed_codes = codes.map { |code| Devise::Encryptor.digest(self.class, code) }
@@ -30,15 +30,19 @@ module Devise
       end
 
       # Returns true and invalidates the given code
-      # iff that code is a valid backup code.
+      # if that code is a valid backup code.
       def invalidate_otp_backup_code!(code)
         codes = self.otp_backup_codes || []
 
+        # Should we still have some other kind of non iterable result, terminate.
+        raise TypeError.new("`otp_backup_codes` is expected to be an Array, got #{codes.class.name}. Hint: If your database does not support arrays, does your model correctly `serialize :otp_backup_codes, Array`?") unless codes.is_a?(Array)
+
         codes.each do |backup_code|
           next unless Devise::Encryptor.compare(self.class, backup_code, code)
 
           codes.delete(backup_code)
           self.otp_backup_codes = codes
+          save!(validate: false)
           return true
         end
 

data/lib/devise_two_factor/spec_helpers/two_factor_authenticatable_shared_examples.rb

@@ -8,25 +8,13 @@ RSpec.shared_examples 'two_factor_authenticatable' do
 
   describe 'required_fields' do
     it 'should have the attr_encrypted fields for otp_secret' do
-      expect(Devise::Models::TwoFactorAuthenticatable.required_fields(subject.class)).to contain_exactly(:encrypted_otp_secret, :encrypted_otp_secret_iv, :encrypted_otp_secret_salt, :consumed_timestep)
+      expect(Devise::Models::TwoFactorAuthenticatable.required_fields(subject.class)).to contain_exactly(:otp_secret, :consumed_timestep)
     end
   end
 
   describe '#otp_secret' do
-    it 'should be of the configured length' do
-      expect(subject.otp_secret.length).to eq(subject.class.otp_secret_length)
-    end
-
-    it 'stores the encrypted otp_secret' do
-      expect(subject.encrypted_otp_secret).to_not be_nil
-    end
-
-    it 'stores an iv for otp_secret' do
-      expect(subject.encrypted_otp_secret_iv).to_not be_nil
-    end
-
-    it 'stores a salt for otp_secret' do
-      expect(subject.encrypted_otp_secret_salt).to_not be_nil
+    it 'should be of the expected length' do
+      expect(subject.otp_secret.length).to eq(subject.class.otp_secret_length*8/5)
     end
   end
 
@@ -137,15 +125,15 @@ RSpec.shared_examples 'two_factor_authenticatable' do
 
   describe '#otp_provisioning_uri' do
     let(:otp_secret_length) { subject.class.otp_secret_length }
-    let(:account)           { Faker::Internet.email }
+    let(:account)           { 'user@host.example' }
     let(:issuer)            { 'Tinfoil' }
 
     it 'should return uri with specified account' do
-      expect(subject.otp_provisioning_uri(account)).to match(%r{otpauth://totp/#{CGI.escape(account)}\?secret=\w{#{otp_secret_length}}})
+      expect(subject.otp_provisioning_uri(account)).to match(%r{otpauth://totp/#{CGI.escape(account)}\?secret=\w{#{otp_secret_length*8/5}}})
     end
 
     it 'should return uri with issuer option' do
-      expect(subject.otp_provisioning_uri(account, issuer: issuer)).to match(%r{otpauth://totp/#{issuer}:#{CGI.escape(account)}\?.*secret=\w{#{otp_secret_length}}(&|$)})
+      expect(subject.otp_provisioning_uri(account, issuer: issuer)).to match(%r{otpauth://totp/#{issuer}:#{CGI.escape(account)}\?.*secret=\w{#{otp_secret_length*8/5}}(&|$)})
       expect(subject.otp_provisioning_uri(account, issuer: issuer)).to match(%r{otpauth://totp/#{issuer}:#{CGI.escape(account)}\?.*issuer=#{issuer}(&|$)})
     end
   end

data/lib/devise_two_factor/spec_helpers/two_factor_backupable_shared_examples.rb

@@ -17,7 +17,7 @@ RSpec.shared_examples 'two_factor_backupable' do
 
       it 'generates recovery codes of the correct length' do
         @plaintext_codes.each do |code|
-          expect(code.length).to eq(subject.class.otp_backup_code_length)
+          expect(code.length).to eq(subject.class.otp_backup_code_length*2)
         end
       end
 
@@ -34,7 +34,7 @@ RSpec.shared_examples 'two_factor_backupable' do
     end
 
     context 'with existing recovery codes' do
-      let(:old_codes)        { Faker::Lorem.words }
+      let(:old_codes)        { ['adam', 'betty', 'charles'] }
       let(:old_codes_hashed) { old_codes.map { |x| Devise::Encryptor.digest(subject.class, x) } }
 
       before do
@@ -49,38 +49,67 @@ RSpec.shared_examples 'two_factor_backupable' do
   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
-        expect(subject.invalidate_otp_backup_code!('password')).to be false
-      end
-    end
 
-    context 'given a valid recovery code' do
-      it 'returns true' do
-        @plaintext_codes.each do |code|
-          expect(subject.invalidate_otp_backup_code!(code)).to be true
+  describe "#invalidate_otp_backup_code!" do
+      context "with no backup codes" do
+        it "does nothing" do
+          expect(subject.invalidate_otp_backup_code!("foo")).to be false
         end
       end
 
-      it 'invalidates that recovery code' do
-        code = @plaintext_codes.sample
+      context "with an array of backup codes, newly generated" do
+        before do
+          @plaintext_codes = subject.generate_otp_backup_codes!
+        end
+
+        context 'given an invalid recovery code' do
+          it 'returns false' do
+            expect(subject.invalidate_otp_backup_code!('password')).to be false
+          end
+        end
+
+        context 'given a valid recovery code' do
+          it 'returns true' do
+            @plaintext_codes.each do |code|
+              expect(subject.invalidate_otp_backup_code!(code)).to be true
+            end
+          end
 
-        subject.invalidate_otp_backup_code!(code)
-        expect(subject.invalidate_otp_backup_code!(code)).to be false
+          it 'invalidates that recovery code' do
+            code = @plaintext_codes.sample
+
+            subject.invalidate_otp_backup_code!(code)
+            expect(subject.invalidate_otp_backup_code!(code)).to 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|
+              expect(subject.invalidate_otp_backup_code!(code)).to be true
+            end
+          end
+        end
       end
 
-      it 'does not invalidate the other recovery codes' do
-        code = @plaintext_codes.sample
-        subject.invalidate_otp_backup_code!(code)
+      context "with backup codes as a string" do
+        before do
+          @plaintext_codes = subject.generate_otp_backup_codes!
 
-        @plaintext_codes.delete(code)
+          # Simulates database adapters that don't understand `t.string :otp_backup_codes, type: array` properly
+          # such as SQL Server; and have just returned the serialized string still.
+          # and the user not having done:
+          # `serialize :otp_backup_codes, Array` in their model
+          subject.otp_backup_codes = subject.otp_backup_codes.to_json
+        end
 
-        @plaintext_codes.each do |code|
-          expect(subject.invalidate_otp_backup_code!(code)).to be true
+        # Do not run when DB adapter handles array assignment correctly
+        it "raises a meaningful error", unless: -> { subject.otp_backup_codes.is_a?(Array) } do
+          expect { subject.invalidate_otp_backup_code!("flork") }.to raise_error(TypeError)
         end
       end
     end