rose_quartz 0.1.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9a4ea455229fd1c679e1f03e3af168e2957c7009
-  data.tar.gz: 497bd1c54a984d513e7cef6da66e9229487e4de2
+  metadata.gz: 715723d37a50e4966319aead3e66cf26168a2302
+  data.tar.gz: cbf6814f33a0b4e797f71c13bbfe4deab4c355dc
 SHA512:
-  metadata.gz: 8ef130e0e2cddad380778fd8126491e0e74abd27bcefd0f9fa1f47aca7d2ebe25daf23264eb13e85a65516809dae0f9fbefc198d3bbb39d700e49e4fe56911a7
-  data.tar.gz: f214a522eb35570560431dbd8bfabb7c638aa7d0acae64f4903134a2b8d1087be49297a15aeec66be28eaef67c189673fc10fb5b526b56a20986c2b43133b5a4
+  metadata.gz: e4c51661f7211f4150ba8d89eb1410885d5ba01c3cd79ef72a2be5cc411f088aeb383e0f832c7692a52008d1a3698503aaa10366f1388a2a9eb998daf1128b48
+  data.tar.gz: 43bdea2ee92e8ba06d0d0a3132f17e932bc202ae9716b64b02c70167b6b204b6a6760aa43d911404258f7ade1a6c011dfe096531fb1a0e914db7399b9c76f39e

data/.travis.yml

@@ -3,3 +3,5 @@ language: ruby
 rvm:
   - 2.3.3
   - 2.4.0
+after_success:
+  - bundle exec codeclimate-test-reporter

data/README.md

@@ -1,6 +1,7 @@
 # RoseQuartz
 
 [![Build Status](https://travis-ci.org/little-bobby-tables/rose_quartz.svg?branch=master)](https://travis-ci.org/little-bobby-tables/rose_quartz)
+[![Test Coverage](https://codeclimate.com/github/little-bobby-tables/rose_quartz/badges/coverage.svg)](https://codeclimate.com/github/little-bobby-tables/rose_quartz/coverage)
 
 A gem that adds two-factor authentication (time-based one-time passwords) to [Devise](https://github.com/plataformatec/devise) 
 using the [rotp](https://github.com/mdp/rotp) library.
@@ -8,10 +9,105 @@ using the [rotp](https://github.com/mdp/rotp) library.
 It attempts to stay lightweight by making a lot of assumptions — for example, that 
 you have a single authenticatable resource, `User`, and that you're using `ActiveRecord`.
 
-Highlights of *RoseQuartz* are:
+#### Highlights:
 
-* Zero tampering with the `User` model — no additional fields, no included modules.
-* Separate table that can be updated in future without affecting your codebase and data.
+* Adds optional TOTP (compatible with Google Authenticator) to the sign-in process.
+* Provides a backup code as a fallback option; resets it once it has been used and notifies the user.
+* Does not tamper with the `User` model — no additional fields, no included modules.
+* Employs a separate table that can be updated in future without affecting your codebase and data.
 * Built with Rails 5 and Devise 4 in mind.
 
-The gem is still in development. All tests for core functionality are passing, but UI integration is not implemented yet.
+#### What it does not do:
+
+Use a multiple-page login system (email and password first, two-factor authentication token next).
+This introduces lots of needless complexity, which goes against the purpose of the gem.
+
+#### What it should do, but does not (yet):
+
+* Encrypt the backup code and the secret used to generate OTP.
+
+## Getting Started
+
+First, add *RoseQuartz* to your Gemfile:
+
+```
+gem 'rose_quartz'
+```
+And run:
+```
+bundle install
+```
+
+Next, you need to copy initializers, locales, and add a migration:
+```
+rails g rose_quarts:install
+```
+
+Finally, run the migration:
+```
+rails db:migrate
+```
+
+## Adding views
+
+#### Signing in
+
+You need a special field for one-time password/backup code on the sign-in page (*app/views/devise/sessions/new.html.erb*).
+
+Here's an example:
+
+```
+<%# E-mail and password fields %>
+
+<div class="field">
+  <%= label_tag :otp, 'Two-factor authentication token' %>
+  <%= text_field_tag :otp, '', autocomplete: "off" %>
+</div>
+
+<%# The rest of the form %>
+```
+
+Note that you must leave the parameter name (`otp`) intact.
+
+#### Enabling/disabling two-factor authentication
+
+The gem adds a special extension to Devise that allows you to 
+include two-factor authentication setup in the account editing page
+(*app/views/devise/registrations/edit.html.erb*).
+
+As with other settings there, a password is required to toggle two-factor authentication.
+The user also needs to provide a correct token generated by their TOTP application of choice, 
+which ensures that their device clock is in sync with the server.
+
+Here's a sample implementation:
+
+```
+<div class="field">
+  <%= fields_for :two_factor_authentication do |tfa| %>
+    <% if two_factor_authentication_enabled? %>
+      <%= tfa.label :disable, 'Disable two-factor authentication' %>
+      <%= tfa.check_box :disable %>
+      <p>
+        Your backup code is <strong><%= two_factor_authentication_backup_code %></strong> -
+        save it to access your account if you ever lose your device or don't have it with you.
+      </p>
+      <%= tfa.label :reset_backup_code %>
+      <%= tfa.check_box :reset_backup_code %>
+    <% else %>
+      <%= tfa.hidden_field :secret, value: two_factor_authentication_secret %>
+      <%= image_tag two_factor_authentication_qr_code_uri(size: 200) %>
+      <p>
+        Scan this QR code with your device and enter the token below:
+      </p>
+      <%= tfa.label :token, 'Token' %><br />
+      <%= tfa.text_field :token, value: '' %>
+      <p>
+        Tip: to configure authentication on multiple devices, scan the code using each device.
+      </p>
+    <% end %>
+  <% end %>
+</div>
+```
+
+The following helper methods are available in the view: `two_factor_authentication_enabled?`, 
+`two_factor_authentication_backup_code`, `two_factor_authentication_qr_code_uri`, `two_factor_authentication_secret`.

data/lib/generators/rose_quartz/install_generator.rb

@@ -0,0 +1,24 @@
+module RoseQuartz
+  class InstallGenerator < Rails::Generators::Base
+    include Rails::Generators::Migration
+
+    source_root File.expand_path('../templates', __FILE__)
+
+    def copy_initializer
+      copy_file 'initializer.rb', 'config/initializers/rose_quartz.rb'
+    end
+
+    def copy_locale
+      copy_file 'locale.en.yml', 'config/locales/rose_quartz.en.yml'
+    end
+
+    def copy_migration
+      migration_template 'migration.rb', 'db/migrate/add_two_factor_auth_with_rose_quartz.rb'
+    end
+
+    def self.next_migration_number(path)
+      next_migration_number = current_migration_number(path) + 1
+      ActiveRecord::Migration.next_migration_number(next_migration_number)
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+RoseQuartz.initialize! do |config|
+  # Token issuer is used as a title in user applications (e.g. Google Authenticator).
+  # It is included in the QR code, and changing it won't have an effect on users
+  # that already have two-factor authentication enabled.
+  config.issuer = 'My Rails Application'
+
+  # In addition to +issuer+, client-side applications display an identifier
+  # (usually, this is account's email address).
+  # This setting needs to refer to an existing attribute or method of the authenticatable model.
+  config.user_identifier = :email
+
+  # Some users may have their devices slightly ahead or behind of the actual time.
+  # To counter this, the authenticator will accept tokens that are generated for
+  # timestamps withing the time drift window defined below.
+  config.time_drift = 2.minutes
+end

data/lib/generators/rose_quartz/templates/locale.en.yml

@@ -0,0 +1,4 @@
+en:
+  rose_quartz:
+    backup_code_used: "The backup code you have used to sign in has been reset. Please go to your account settings to copy the new one or temporarily disable two-factor authentication."
+    invalid_token_when_enabling_tfa: "Invalid token. Please make sure that your device has the correct time settings."

data/lib/generators/rose_quartz/templates/migration.rb

@@ -0,0 +1,14 @@
+class AddTwoFactorAuthWithRoseQuartz < ActiveRecord::Migration[5.0]
+  def up
+    create_table :user_authenticators do |t|
+      t.integer :user_id
+      t.string  :secret
+      t.string  :backup_code
+      t.integer :last_authenticated_at
+    end
+  end
+
+  def down
+    drop_table :user_authenticators
+  end
+end

data/lib/rose_quartz.rb

@@ -1,7 +1,11 @@
-# frozen_string_literal: truez
+# frozen_string_literal: true
 require 'devise'
 
 require 'rose_quartz/version'
+
+require 'rose_quartz/hooks'
 require 'rose_quartz/configuration'
 require 'rose_quartz/user_authenticator'
 require 'rose_quartz/devise/strategies/two_factor_authenticatable'
+require 'rose_quartz/devise/controllers/sessions_controller_extensions'
+require 'rose_quartz/devise/controllers/registrations_controller_extensions'

data/lib/rose_quartz/configuration.rb

@@ -8,23 +8,16 @@ module RoseQuartz
 
   def self.initialize!
     yield self.configuration
-    insert_authentication_strategy!
-  end
-
-  def self.insert_authentication_strategy!
-    ::Devise.setup do |c|
-      c.warden do |manager|
-        manager.default_strategies(scope: :user).unshift :two_factor_authenticatable
-      end
-    end
+    Hooks.initialize_hooks!
   end
 
   class Configuration
-    attr_accessor :issuer, :time_drift
+    attr_accessor :issuer, :time_drift, :user_identifier
 
     def initialize
-      @issuer = ''
-      @time_drift = 60.seconds
+      @issuer = 'RoseQuartz'
+      @time_drift = 1.minute
+      @user_identifier = :email
     end
   end
 end

data/lib/rose_quartz/devise/controllers/registrations_controller_extensions.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+require 'i18n'
+require 'rqrcode'
+
+module Devise
+  module RegistrationsControllerExtensions
+    def self.prepended(base)
+      base.class_eval do
+        helper_method :two_factor_authentication_enabled?,
+                      :two_factor_authentication_backup_code,
+                      :two_factor_authentication_qr_code_uri,
+                      :two_factor_authentication_secret
+      end
+    end
+
+    def update_resource(resource, _params)
+      result = super
+      edit_two_factor_authentication(resource) if result
+      result
+    end
+
+    protected
+
+    # View helpers
+
+    def two_factor_authentication_enabled?(user = resource)
+      RoseQuartz::UserAuthenticator.exists? user_id: user.id
+    end
+
+    def two_factor_authentication_backup_code
+      authenticator(resource).backup_code
+    end
+
+    def two_factor_authentication_qr_code_uri(size:)
+      uri = authenticator.provisioning_uri
+      qr = RQRCode::QRCode.new(uri)
+      qr.as_png(size: size).to_data_url
+    end
+
+    def two_factor_authentication_secret
+      authenticator.secret
+    end
+
+    private
+
+    # Internal logic
+
+    def edit_two_factor_authentication(resource)
+      if two_factor_authentication_enabled?
+        disable_two_factor_authentication!(resource) if form_params[:disable] == '1'
+        reset_two_factor_authentication_backup_code!(resource) if form_params[:reset_backup_code] == '1'
+      else
+        enable_two_factor_authentication!(resource)
+      end
+    end
+
+    def disable_two_factor_authentication!(resource)
+      authenticator(resource).disable!
+    end
+
+    def reset_two_factor_authentication_backup_code!(resource)
+      authenticator(resource).reset_backup_code!
+    end
+
+    def enable_two_factor_authentication!(resource)
+      secret, token = form_params.values_at(:secret, :token)
+      authenticator = RoseQuartz::UserAuthenticator.new(user: resource, secret: secret)
+      token_valid = authenticator.authenticate_otp!(token) rescue false
+      if token_valid
+        authenticator.save
+      else
+        resource.errors.add(:base, I18n.t('rose_quartz.invalid_token_when_enabling_tfa'))
+      end
+    end
+
+    def form_params
+      params.require(:two_factor_authentication).permit(:secret, :token, :disable, :reset_backup_code)
+    end
+
+    def authenticator(existing_user = nil)
+      @authenticator ||= if existing_user
+        RoseQuartz::UserAuthenticator.find_by(user_id: resource.id)
+      else
+        RoseQuartz::UserAuthenticator.new(user: resource)
+      end
+    end
+  end
+end

data/lib/rose_quartz/devise/controllers/sessions_controller_extensions.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Devise
+  module SessionsControllerExtensions
+    def create
+      super do |_resource|
+        if request.env['rose_quartz.backup_code_used']
+          flash[:alert] = t('rose_quartz.backup_code_used')
+        end
+      end
+    end
+  end
+end

data/lib/rose_quartz/devise/strategies/two_factor_authenticatable.rb

@@ -7,17 +7,30 @@ module Devise
       def authenticate!
         resource = password.present? && mapping.to.find_for_database_authentication(authentication_hash)
 
-        super if validate(resource) { otp_matches?(resource) }
+        super if validate(resource) { authenticated?(resource) }
       end
 
-      def otp_matches?(resource)
+      def authenticated?(resource)
         authenticator = RoseQuartz::UserAuthenticator.find_by(user_id: resource.id)
-        return true if authenticator.nil? # two-factor authentication is disabled
+        token = params['otp']
 
-        token = params['tf_authentication_token']
+        # Two-factor authentication is disabled
+        return true if authenticator.nil?
+
+        # Token is not provided
         return false if token.nil?
 
-        authenticator.authenticate(token)
+        # Token is a valid OTP
+        return true if authenticator.authenticate_otp!(token)
+
+        # Token is a valid backup code
+        if authenticator.authenticate_backup_code!(token)
+          env['rose_quartz.backup_code_used'] = true
+          return true
+        end
+
+        # Token is not a valid OTP or backup code
+        false
       end
     end
   end

data/lib/rose_quartz/hooks.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+module RoseQuartz
+  module Hooks
+    def self.initialize_hooks!
+      ::Devise.setup do |c|
+        c.warden do |manager|
+          manager.default_strategies(scope: :user).unshift :two_factor_authenticatable
+        end
+      end
+
+      ::Devise::SessionsController.prepend Devise::SessionsControllerExtensions
+      ::Devise::RegistrationsController.prepend Devise::RegistrationsControllerExtensions
+    end
+  end
+end

data/lib/rose_quartz/user_authenticator.rb

@@ -5,22 +5,52 @@ module RoseQuartz
   class UserAuthenticator < ::ActiveRecord::Base
     belongs_to :user
 
-    before_create :set_secret
+    after_initialize :set_secret_and_backup_code, if: :new_record?
 
-    def set_secret
-      self.secret = ROTP::Base32.random_base32
+    def set_secret_and_backup_code
+      self.secret ||= ROTP::Base32.random_base32
+      self.backup_code ||= generate_backup_code
     end
 
-    def authenticator
-      @authenticator ||= ROTP::TOTP.new(secret)
+    def authenticate_otp!(token)
+      authenticated_at = totp.verify_with_drift_and_prior(
+          token, RoseQuartz.configuration.time_drift, last_authenticated_at)
+      if authenticated_at
+        update_columns last_authenticated_at: authenticated_at if persisted?
+        true
+      else
+        false
+      end
     end
 
-    def authenticate(token)
-      authenticated_at = authenticator.verify_with_drift_and_prior(
-          token, RoseQuartz.configuration.time_drift, last_authenticated_at)
-      return false unless authenticated_at
-      update_columns last_authenticated_at: authenticated_at
-      true
+    def authenticate_backup_code!(token)
+      if token == backup_code
+        reset_backup_code!
+        true
+      else
+        false
+      end
+    end
+
+    def reset_backup_code!
+      update_columns backup_code: generate_backup_code
+    end
+
+    def totp
+      @authenticator ||= ROTP::TOTP.new(secret, issuer: RoseQuartz.configuration.issuer)
+    end
+
+    def provisioning_uri
+      totp.provisioning_uri(user.send(RoseQuartz.configuration.user_identifier))
+    end
+
+    alias disable! delete
+
+    private
+
+    # Four groups of 4-character base32 strings joined by dashes, e.g. "gs3w-ntpt-hrse-v23t"
+    def generate_backup_code
+      ROTP::Base32.random_base32(16).scan(/.{1,4}/).join('-')
     end
   end
 end

data/lib/rose_quartz/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module RoseQuartz
-  VERSION = '0.1.0'
+  VERSION = '0.9.0'
 end

data/rose_quartz.gemspec

@@ -16,11 +16,15 @@ Gem::Specification.new do |spec|
   end
   spec.require_paths = ['lib']
 
-  spec.add_runtime_dependency 'rails', '~> 5.0'
-  spec.add_runtime_dependency 'devise', '~> 4.2'
-  spec.add_runtime_dependency 'rotp', '~> 3.3'
+  spec.add_runtime_dependency 'rails', '>= 5.0'
+  spec.add_runtime_dependency 'devise', '>= 4.2'
+  spec.add_runtime_dependency 'rotp', '>= 3.3'
+  spec.add_runtime_dependency 'rqrcode', '>= 0.10'
 
   spec.add_development_dependency 'sqlite3'
+  spec.add_development_dependency 'capybara'
   spec.add_development_dependency 'factory_girl_rails'
   spec.add_development_dependency 'minitest-reporters'
+  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'codeclimate-test-reporter'
 end

metadata

@@ -1,57 +1,71 @@
 --- !ruby/object:Gem::Specification
 name: rose_quartz
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.9.0
 platform: ruby
 authors:
 - little-bobby-tables
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-01-21 00:00:00.000000000 Z
+date: 2017-01-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '5.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '5.0'
 - !ruby/object:Gem::Dependency
   name: devise
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '4.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '4.2'
 - !ruby/object:Gem::Dependency
   name: rotp
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.3'
+- !ruby/object:Gem::Dependency
+  name: rqrcode
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.10'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
@@ -66,6 +80,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: capybara
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: factory_girl_rails
   requirement: !ruby/object:Gem::Requirement
@@ -94,6 +122,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: codeclimate-test-reporter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: 
 email:
 - little-bobby-tables@users.noreply.github.com
@@ -107,9 +163,16 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- lib/generators/rose_quartz/install_generator.rb
+- lib/generators/rose_quartz/templates/initializer.rb
+- lib/generators/rose_quartz/templates/locale.en.yml
+- lib/generators/rose_quartz/templates/migration.rb
 - lib/rose_quartz.rb
 - lib/rose_quartz/configuration.rb
+- lib/rose_quartz/devise/controllers/registrations_controller_extensions.rb
+- lib/rose_quartz/devise/controllers/sessions_controller_extensions.rb
 - lib/rose_quartz/devise/strategies/two_factor_authenticatable.rb
+- lib/rose_quartz/hooks.rb
 - lib/rose_quartz/user_authenticator.rb
 - lib/rose_quartz/version.rb
 - rose_quartz.gemspec