minimalist_authentication 1.2.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bda0fef1ab5c360af94e908ec11ba51059788808
-  data.tar.gz: f691883871f612e2ed2f709736f3fb3eebf68d8b
+  metadata.gz: c706bf1ccf629eedb3a910b68a983ae2d4869f4d
+  data.tar.gz: 8d5f220c4f4ac6d91c445c3a946fc913ba5d1cbd
 SHA512:
-  metadata.gz: 3fb4e425254e581abdf5e2fc9a7e461a4c5208513bcc122447acdf2db79e8dfd3db9b1595d58758b2c274ed667711863533e298ca469676c51091802273eb7bc
-  data.tar.gz: b782a7c2a6070fa446636a040ac60b969014a17500e22d68fdca2332426163759dedb58843107b358096ff5896a3e2047c32c5ceaca120fed4e4cb3771a61c5a
+  metadata.gz: aeb1bfee96f489dd77baa1c3fa9059fdcc3e335cc9b50e387be72c5efd6f859f92c4827783e4a51722bf6482edfd0c1f961e43d6c65b93dd6f2467786aebb3d2
+  data.tar.gz: a0e7282735c59607dc0373a8940885659b8df6981ffeefe6e47535f99cc23b0058ea4084a9a9233f73562811179a208f29628b744afdefdd593e468b1760d33e

data/README.md

@@ -16,12 +16,12 @@ $ bundle
 
 Create a user model with **email** for an identifier:
 ```bash
-bin/rails generate model user active:boolean email:string crypted_password:string salt:string last_logged_in_at:datetime
+bin/rails generate model user active:boolean email:string password_hash:string last_logged_in_at:datetime
 ```
 
 OR create a user model with **username** for an identifier:
 ```bash
-bin/rails generate model user active:boolean username:string crypted_password:string salt:string last_logged_in_at:datetime
+bin/rails generate model user active:boolean username:string password_hash:string last_logged_in_at:datetime
 ```
 
 
@@ -61,15 +61,47 @@ class ActiveSupport::TestCase
 end
 ```
 
-## Example
+## Configuration
 Customize the configuration with an initializer. Create a **minimalist_authentication.rb** file in /Users/baldwina/git/brightways/config/initializers.
 ```ruby
 MinimalistAuthentication.configure do |configuration|
   configuration.user_model_name   = 'CustomModelName'     # default is '::User'
   configuration.session_key       = :custom_session_key   # default is ':user_id'
+  validate_email                  = true                  # default is true
+  validate_email_presence         = true                  # default is true
 end
 ```
 
+
+## Fixtures
+Use **MinimalistAuthentication::Password.create** to create a password for
+fixture users.
+```yaml
+example_user:
+  email:          user@example.com
+  password_hash:  <%= MinimalistAuthentication::Password.create('password') %>
+```
+
+
+## Conversions
+Pre 2.0 versions of MinimalistAuthentication supported multiple hash algorithms
+and stored the hashed password and salt as separate fields in the database
+(crypted_password and salt). The current version of MinimalistAuthentication
+uses BCrypt to hash passwords and stores the result in the **password_hash** field.
+
+To convert from a pre 2.0 version add the **password_hash** to your user model
+and run the conversion routine.
+```bash
+bin/rails generate migration AddPasswordHashToUsers password_hash:string
+```
+```ruby
+MinimalistAuthentication::Conversions::MergePasswordHash.run!
+```
+
+When the conversion is complete the **crypted_password**, **salt**, and
+**using_digest_version** fields can safely be removed.
+
+
 ## Build
 [![Build Status](https://travis-ci.org/wwidea/minimalist_authentication.svg?branch=master)](https://travis-ci.org/wwidea/minimalist_authentication)
 

data/lib/minimalist_authentication.rb

@@ -1,7 +1,9 @@
 require 'minimalist_authentication/engine'
 require 'minimalist_authentication/configuration'
 require 'minimalist_authentication/user'
+require 'minimalist_authentication/password'
 require 'minimalist_authentication/null_password'
 require 'minimalist_authentication/controller'
 require 'minimalist_authentication/sessions'
 require 'minimalist_authentication/test_helper'
+require 'minimalist_authentication/conversions/merge_password_hash'

data/lib/minimalist_authentication/configuration.rb

@@ -23,9 +23,20 @@ module MinimalistAuthentication
     # Defaults to '::User'
     attr_accessor :user_model_name
 
+    # Toggle all email validations.
+    # Defaults to true.
+    attr_accessor :validate_email
+
+    # Toggle email presence validation.
+    # Defaults to true.
+    # Note: validate_email_presence is only checked if validate_email is true.
+    attr_accessor :validate_email_presence
+
     def initialize
-      self.user_model_name  = '::User'
-      self.session_key      = :user_id
+      self.user_model_name          = '::User'
+      self.session_key              = :user_id
+      self.validate_email           = true
+      self.validate_email_presence  = true
     end
 
     # Returns the user_model class

data/lib/minimalist_authentication/conversions/merge_password_hash.rb

@@ -0,0 +1,38 @@
+module MinimalistAuthentication
+  module Conversions
+    class MergePasswordHash
+
+      class << self
+        def run!
+          user_model.where(using_digest_version: 3, password_hash: nil).each do |user|
+            new(user).update!
+          end
+        end
+
+        private
+
+        def user_model
+          MinimalistAuthentication.configuration.user_model
+        end
+      end
+
+      attr_accessor :user
+
+      delegate :salt, :crypted_password, to: :user
+
+      def initialize(user)
+        self.user = user
+      end
+
+      def update!
+        user.update_column(:password_hash, merged_password_hash)
+      end
+
+      private
+
+      def merged_password_hash
+        "#{salt}#{crypted_password}"
+      end
+    end
+  end
+end

data/lib/minimalist_authentication/password.rb

@@ -0,0 +1,46 @@
+module MinimalistAuthentication
+  class Password
+    class << self
+      # Create a bcrypt password hash with a calibrated cost factor.
+      def create(secret)
+        new ::BCrypt::Engine.hash_secret(secret, BCrypt::Engine.generate_salt(cost))
+      end
+
+      # Cache the calibrated bcrypt cost factor.
+      def cost
+        @bcrypt_cost ||= calibrate_cost
+      end
+
+      private
+
+      # Calibrates cost so that new user passwords can automatically take
+      # advantage of faster server hardware in the future.
+      # Sets cost to BCrypt::Engine::MIN_COST in the test environment
+      def calibrate_cost
+        ::Rails.env.test? ? ::BCrypt::Engine::MIN_COST : ::BCrypt::Engine.calibrate(750)
+      end
+    end
+
+    attr_accessor :bcrypt_password
+
+    # Returns a password object wrapping a valid BCrypt password or a NullPassword
+    def initialize(password_hash)
+      begin
+        self.bcrypt_password = ::BCrypt::Password.new(password_hash)
+      rescue ::BCrypt::Errors::InvalidHash
+        self.bcrypt_password = NullPassword.new
+      end
+    end
+
+    # Delegate methods to bcrypt_password
+    delegate :==, :to_s, :cost, to: :bcrypt_password
+
+    # Temporary access to checksum and salt for backwards compatibility
+    delegate :checksum, :salt,  to: :bcrypt_password
+
+    # Checks if the password_hash cost factor is less than the current cost.
+    def stale?
+      cost < self.class.cost
+    end
+  end
+end

data/lib/minimalist_authentication/test_helper.rb

@@ -4,7 +4,6 @@ module MinimalistAuthentication
       post session_path, params: { user: { email: users(user_fixture_name).email, password: password } }
     end
 
-
     def current_user
       @current_user ||= load_user_from_session
     end

data/lib/minimalist_authentication/user.rb

@@ -7,58 +7,65 @@ module MinimalistAuthentication
     GUEST_USER_EMAIL = 'guest'
     EMAIL_REGEX = /\A([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})\Z/i
 
-    # Recalibrates cost when class is loaded so that new user passwords
-    # can automatically take advantage of faster server hardware in the
-    # future for better encryption.
-    # sets cost to BCrypt::Engine::MIN_COST in the test environment
-    CALIBRATED_BCRYPT_COST = (::Rails.env.test? ? ::BCrypt::Engine::MIN_COST : ::BCrypt::Engine.calibrate(750))
-
     included do
+      # Stores the plain text password.
       attr_accessor :password
-      before_save :encrypt_password
 
-      # email validations
+      # Hashes and stores the password on save.
+      before_save :hash_password
+
+      # Email validations
       validates_presence_of     :email,                                       if: :validate_email_presence?
       validates_uniqueness_of   :email, allow_blank: true,                    if: :validate_email?
       validates_format_of       :email, allow_blank: true, with: EMAIL_REGEX, if: :validate_email?
 
-      # password validations
-      validates_presence_of     :password,                  if: :password_required?
-      validates_confirmation_of :password,                  if: :password_required?
-      validates_length_of       :password, within: 6..40,   if: :password_required?
+      # Password validations
+      validates_presence_of     :password,                  if: :validate_password?
+      validates_confirmation_of :password,                  if: :validate_password?
+      validates_length_of       :password, within: 8..40,   if: :validate_password?
 
+      # Active scope
       scope :active, ->(active = true) { where active: active }
     end
 
     module ClassMethods
+      # Authenticates a user form the params provied. Expects a params hash with
+      # email or username and passwod keys.
+      # Params examples:
+      # { email: 'user@example.com', password: 'abc123' }
+      # { username: 'user', password: 'abc123' }
+      # Returns user upon successful authentcation.
+      # Otherwise returns nil.
       def authenticate(params)
+        # extract email or username and the associated value
         field, value = params.to_h.select { |key, value| %w(email username).include?(key.to_s) && value.present? }.first
+        # return nil if field, value, or password is blank
         return if field.blank? || value.blank? || params[:password].blank?
+        # attempt to find the user using field and value
         user = active.where(field => value).first
+        # check if a user was found and if they can be authenticated
         return unless user && user.authenticated?(params[:password])
+        # return the authenticated user
         return user
       end
 
-      def password_hash(password)
-        ::BCrypt::Password.create(password, cost: calibrated_bcrypt_cost)
-      end
-
-      def calibrated_bcrypt_cost
-        CALIBRATED_BCRYPT_COST
-      end
-
+      # Returns a frozen user with the email set to GUEST_USER_EMAIL.
       def guest
-        new(email: GUEST_USER_EMAIL)
+        new(email: GUEST_USER_EMAIL).freeze
       end
     end
 
+    # Returns true if the user is active.
     def active?
       active
     end
 
+    # Return true if password matches the hashed_password.
+    # If successful checks for an outdated password_hash and updates if
+    # necessary.
     def authenticated?(password)
-      if bcrypt_password == password
-        update_encryption(password) if bcrypt_password.cost < self.class.calibrated_bcrypt_cost
+      if password_object == password
+        update_hash!(password) if password_object.stale?
         return true
       end
 
@@ -70,54 +77,49 @@ module MinimalistAuthentication
       update_column(:last_logged_in_at, Time.current)
     end
 
+    # Check if user is a guest based on their email attribute
     def is_guest?
       email == GUEST_USER_EMAIL
     end
 
     private
 
-    def password_required?
-      active? && (crypted_password.blank? || !password.blank?)
-    end
-
-    def update_encryption(password)
+    # Set self.password to password, hash, and save
+    def update_hash!(password)
       self.password = password
-      encrypt_password
+      hash_password
       save
     end
 
-    def encrypt_password
+    # Hash password and store in hash_password unless password is blank.
+    def hash_password
       return if password.blank?
-      password_hash         = self.class.password_hash(password)
-      self.salt             = password_hash.salt
-      self.crypted_password = password_hash.checksum
-    end
-
-    def bcrypt_password
-      valid_hash? ? ::BCrypt::Password.new(password_hash) : null_password
-    end
-
-    def valid_hash?
-      ::BCrypt::Password.valid_hash?(password_hash)
+      self.password_hash = Password.create(password)
     end
 
-    def password_hash
-      "#{salt}#{crypted_password}"
+    # Retuns a MinimalistAuthentication::Password object.
+    def password_object
+      Password.new(password_hash)
     end
 
-    def null_password
-      MinimalistAuthentication::NullPassword.new
+    # Requre password for active users that either do no have a password hash
+    # stored OR are attempting to set a new password.
+    def validate_password?
+      active? && (password_hash.blank? || password.present?)
     end
 
-    # email validation
+    # Validate email for active users.
+    # Applications can turn off email validation by setting the validate_email
+    # configuration attribute to false.
     def validate_email?
-      # allows applications to turn off all email validation
-      active?
+      MinimalistAuthentication.configuration.validate_email && active?
     end
 
+    # Validate email presence for active users.
+    # Applications can turn offf email presence validation by setting
+    # validate_email_presence configuration attribute to false.
     def validate_email_presence?
-      # allows applications to turn off email presence validation
-      validate_email?
+      MinimalistAuthentication.configuration.validate_email_presence && validate_email?
     end
   end
 end

data/lib/minimalist_authentication/version.rb

@@ -1,3 +1,3 @@
 module MinimalistAuthentication
-  VERSION = '1.2.0'
+  VERSION = '2.0.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: minimalist_authentication
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Aaron Baldwin
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-09-14 00:00:00.000000000 Z
+date: 2017-09-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -77,8 +77,10 @@ files:
 - lib/minimalist_authentication.rb
 - lib/minimalist_authentication/configuration.rb
 - lib/minimalist_authentication/controller.rb
+- lib/minimalist_authentication/conversions/merge_password_hash.rb
 - lib/minimalist_authentication/engine.rb
 - lib/minimalist_authentication/null_password.rb
+- lib/minimalist_authentication/password.rb
 - lib/minimalist_authentication/sessions.rb
 - lib/minimalist_authentication/test_helper.rb
 - lib/minimalist_authentication/user.rb