clearance 1.17.0 → 2.2.0

data/README.md

@@ -19,7 +19,7 @@ monitored by contributors.
 
 ## Getting Started
 
-Clearance is a Rails engine tested against Rails `>= 3.2` and Ruby `>= 1.9.3`.
+Clearance is a Rails engine tested against Rails `>= 5.0` and Ruby `>= 2.4.0`.
 
 You can add it to your Gemfile with:
 
@@ -31,8 +31,8 @@ Run the bundle command to install it.
 
 After you install Clearance, you need to run the generator:
 
-```sh
-$ rails generate clearance:install
+```shell
+rails generate clearance:install
 ```
 
 The Clearance install generator:
@@ -59,17 +59,14 @@ Clearance.configure do |config|
   config.mailer_sender = "reply@example.com"
   config.password_strategy = Clearance::PasswordStrategies::BCrypt
   config.redirect_url = "/"
-  config.rotate_csrf_on_sign_in = false
+  config.rotate_csrf_on_sign_in = true
   config.secure_cookie = false
   config.sign_in_guards = []
-  config.user_model = User
+  config.user_model = "User"
+  config.parent_controller = "ApplicationController"
 end
 ```
 
-The install generator will set `rotate_csrf_on_sign_in` to `true`, so new
-installations will get this behavior from the start. This helps avoid session
-fixation attacks, and will become the default in Clearance 2.0.
-
 ## Use
 
 ### Access Control
@@ -130,6 +127,18 @@ Clearance.configure do |config|
 end
 ```
 
+### Multiple Domain Support
+
+You can support multiple domains, or other special domain configurations by
+optionally setting `cookie_domain` as a callable object. The first argument
+passed to the method is an ActionDispatch::Request object.
+
+```ruby
+Clearance.configure do |config|
+  config.cookie_domain = lambda { |request| request.host }
+end
+```
+
 ### Integrating with Rack Applications
 
 Clearance adds its session to the Rack environment hash so middleware and other
@@ -161,15 +170,16 @@ As of Clearance 1.5 it is recommended that you disable Clearance routes and take
 full control over routing and URL design. This ensures that your app's URL design
 won't be affected if the gem's routes and URL design are changed.
 
-To disable the routes, change the `routes` configuration option to false: 
+To disable the routes, change the `routes` configuration option to false:
 
 ```ruby
 Clearance.configure do |config|
   config.routes = false
 end
 ```
-You can optionally run `rails generate clearance:routes` to dump a copy of the default routes into your
-application for modification.
+
+You can optionally run `rails generate clearance:routes` to dump a copy of the
+default routes into your application for modification.
 
 ### Controllers
 
@@ -188,22 +198,29 @@ class UsersController < Clearance::UsersController
 
 ### Redirects
 
-All of these controller methods redirect to
+The post-action redirects in Clearance are simple methods which can be
+overridden one by one, or configured globally.
+
+These "success" methods are called for signed in users, and redirect to
 `Clearance.configuration.redirect_url` (which is `/` by default):
 
-```
-passwords#url_after_update
-sessions#url_after_create
-sessions#url_for_signed_in_users
-users#url_after_create
-application#url_after_denied_access_when_signed_in
-```
+- `passwords#url_after_update`
+- `sessions#url_after_create`
+- `sessions#url_for_signed_in_users`
+- `users#url_after_create`
+- `application#url_after_denied_access_when_signed_in`
 
 To override them all at once, change the global configuration of `redirect_url`.
-To change individual URLs, override the appropriate method.
+To change individual URLs, override the appropriate method in your subclassed
+controller.
 
-`application#url_after_denied_access_when_signed_out` defaults to `sign_in_url`.
-Override this method to change this.
+These "failure" methods are called for signed out sessions:
+
+- `application#url_after_denied_access_when_signed_out`
+- `sessions#url_after_destroy`
+
+They both default to `sign_in_url`. Override this method to change both of their
+behavior, or override them individually to just change one.
 
 ### Views
 
@@ -226,7 +243,7 @@ You can use the Clearance views generator to copy the default views to your
 application for modification.
 
 ```shell
-$ rails generate clearance:views
+rails generate clearance:views
 ```
 
 ### Layouts
@@ -245,8 +262,10 @@ end
 
 ### Translations
 
-All flash messages and email subject lines are stored in [i18n translations](http://guides.rubyonrails.org/i18n.html). Override them like any other
-translation.
+All flash messages and email subject lines are stored in [i18n translations].
+Override them like any other translation.
+
+[i18n translations]: http://guides.rubyonrails.org/i18n.html
 
 See [config/locales/clearance.en.yml](/config/locales/clearance.en.yml) for the
 default behavior.
@@ -259,6 +278,13 @@ for access to additional, user-contributed translations.
 See [lib/clearance/user.rb](/lib/clearance/user.rb) for the default behavior.
 You can override those methods as needed.
 
+Note that there are some model-level validations (see above link for detail)
+which the `Clearance::User` module will add to the configured model class and
+which may conflict with or duplicate already present validations on the `email`
+and `password` attributes. Over-riding the `email_optional?` or
+`skip_password_validation?` methods to return `true` will disable those
+validations from being added.
+
 ### Deliver Email in Background Job
 
 Clearance has a password reset mailer. If you are using Rails 4.2 and Clearance
@@ -307,7 +333,7 @@ Here's an example custom guard to handle email confirmation:
 
 ```ruby
 Clearance.configure do |config|
-  config.sign_in_guards = [EmailConfirmationGuard]
+  config.sign_in_guards = ["EmailConfirmationGuard"]
 end
 ```
 
@@ -377,7 +403,7 @@ feature specs, will also require `factory_bot_rails`.
 To Generate the clearance specs, run:
 
 ```shell
-$ rails generate clearance:specs
+rails generate clearance:specs
 ```
 
 ### Controller Test Helpers

data/app/controllers/clearance/base_controller.rb

@@ -1,2 +1,9 @@
-class Clearance::BaseController < ApplicationController
+module Clearance
+  # Top-level base class that all Clearance controllers inherit from.
+  # Inherits from `ApplicationController` by default and can be overridden by
+  # setting a new value with {Configuration#parent_controller=}.
+  # @!parse
+  #   class BaseController < ApplicationController; end
+  class BaseController < Clearance.configuration.parent_controller
+  end
 end

data/app/controllers/clearance/passwords_controller.rb

@@ -1,22 +1,12 @@
 require 'active_support/deprecation'
 
 class Clearance::PasswordsController < Clearance::BaseController
-  if respond_to?(:before_action)
-    skip_before_action :require_login,
-      only: [:create, :edit, :new, :update],
-      raise: false
-    skip_before_action :authorize,
-      only: [:create, :edit, :new, :update],
-      raise: false
-    before_action :ensure_existing_user, only: [:edit, :update]
-  else
-    skip_before_filter :require_login,
-      only: [:create, :edit, :new, :update],
-      raise: false
-    skip_before_filter :authorize,
-      only: [:create, :edit, :new, :update],
-      raise: false
-    before_filter :ensure_existing_user, only: [:edit, :update]
+  before_action :ensure_existing_user, only: [:edit, :update]
+  before_action :ensure_email_present, only: [:create]
+  skip_before_action :require_login, only: [:create, :edit, :new, :update], raise: false
+
+  def new
+    render template: "passwords/new"
   end
 
   def create
@@ -24,7 +14,8 @@ class Clearance::PasswordsController < Clearance::BaseController
       user.forgot_password!
       deliver_email(user)
     end
-    render template: 'passwords/create'
+
+    render template: "passwords/create"
   end
 
   def edit
@@ -34,24 +25,20 @@ class Clearance::PasswordsController < Clearance::BaseController
       session[:password_reset_token] = params[:token]
       redirect_to url_for
     else
-      render template: 'passwords/edit'
+      render template: "passwords/edit"
     end
   end
 
-  def new
-    render template: 'passwords/new'
-  end
-
   def update
     @user = find_user_for_update
 
-    if @user.update_password password_reset_params
+    if @user.update_password(password_from_password_reset_params)
       sign_in @user
       redirect_to url_after_update
       session[:password_reset_token] = nil
     else
       flash_failure_after_update
-      render template: 'passwords/edit'
+      render template: "passwords/edit"
     end
   end
 
@@ -59,21 +46,11 @@ class Clearance::PasswordsController < Clearance::BaseController
 
   def deliver_email(user)
     mail = ::ClearanceMailer.change_password(user)
-
-    if mail.respond_to?(:deliver_later)
-      mail.deliver_later
-    else
-      mail.deliver
-    end
+    mail.deliver_later
   end
 
-  def password_reset_params
-    if params.has_key? :user
-      ActiveSupport::Deprecation.warn %{Since locales functionality was added, accessing params[:user] is no longer supported.}
-      params[:user][:password]
-    else
-      params[:password_reset][:password]
-    end
+  def password_from_password_reset_params
+    params.dig(:password_reset, :password)
   end
 
   def find_user_by_id_and_confirmation_token
@@ -81,12 +58,16 @@ class Clearance::PasswordsController < Clearance::BaseController
     token = params[:token] || session[:password_reset_token]
 
     Clearance.configuration.user_model.
-      find_by_id_and_confirmation_token params[user_param], token.to_s
+      find_by(id: params[user_param], confirmation_token: token.to_s)
+  end
+
+  def email_from_password_params
+    params.dig(:password, :email)
   end
 
   def find_user_for_create
     Clearance.configuration.user_model.
-      find_by_normalized_email params[:password][:email]
+      find_by_normalized_email(email_from_password_params)
   end
 
   def find_user_for_edit
@@ -97,6 +78,13 @@ class Clearance::PasswordsController < Clearance::BaseController
     find_user_by_id_and_confirmation_token
   end
 
+  def ensure_email_present
+    if email_from_password_params.blank?
+      flash_failure_when_missing_email
+      render template: "passwords/new"
+    end
+  end
+
   def ensure_existing_user
     unless find_user_by_id_and_confirmation_token
       flash_failure_when_forbidden
@@ -105,19 +93,21 @@ class Clearance::PasswordsController < Clearance::BaseController
   end
 
   def flash_failure_when_forbidden
-    flash.now[:notice] = translate(:forbidden,
+    flash.now[:alert] = translate(:forbidden,
       scope: [:clearance, :controllers, :passwords],
-      default: t('flashes.failure_when_forbidden'))
+      default: t("flashes.failure_when_forbidden"))
   end
 
   def flash_failure_after_update
-    flash.now[:notice] = translate(:blank_password,
+    flash.now[:alert] = translate(:blank_password,
       scope: [:clearance, :controllers, :passwords],
-      default: t('flashes.failure_after_update'))
+      default: t("flashes.failure_after_update"))
   end
 
-  def url_after_create
-    sign_in_url
+  def flash_failure_when_missing_email
+    flash.now[:alert] = translate(:missing_email,
+      scope: [:clearance, :controllers, :passwords],
+      default: t("flashes.failure_when_missing_email"))
   end
 
   def url_after_update

data/app/controllers/clearance/sessions_controller.rb

@@ -1,21 +1,6 @@
 class Clearance::SessionsController < Clearance::BaseController
-  if respond_to?(:before_action)
-    before_action :redirect_signed_in_users, only: [:new]
-    skip_before_action :require_login,
-      only: [:create, :new, :destroy],
-      raise: false
-    skip_before_action :authorize,
-      only: [:create, :new, :destroy],
-      raise: false
-  else
-    before_filter :redirect_signed_in_users, only: [:new]
-    skip_before_filter :require_login,
-      only: [:create, :new, :destroy],
-      raise: false
-    skip_before_filter :authorize,
-      only: [:create, :new, :destroy],
-      raise: false
-  end
+  before_action :redirect_signed_in_users, only: [:new]
+  skip_before_action :require_login, only: [:create, :new, :destroy], raise: false
 
   def create
     @user = authenticate(params)
@@ -24,7 +9,7 @@ class Clearance::SessionsController < Clearance::BaseController
       if status.success?
         redirect_back_or url_after_create
       else
-        flash.now.notice = status.failure_message
+        flash.now.alert = status.failure_message
         render template: "sessions/new", status: :unauthorized
       end
     end

data/app/controllers/clearance/users_controller.rb

@@ -1,13 +1,6 @@
 class Clearance::UsersController < Clearance::BaseController
-  if respond_to?(:before_action)
-    before_action :redirect_signed_in_users, only: [:create, :new]
-    skip_before_action :require_login, only: [:create, :new], raise: false
-    skip_before_action :authorize, only: [:create, :new], raise: false
-  else
-    before_filter :redirect_signed_in_users, only: [:create, :new]
-    skip_before_filter :require_login, only: [:create, :new], raise: false
-    skip_before_filter :authorize, only: [:create, :new], raise: false
-  end
+  before_action :redirect_signed_in_users, only: [:create, :new]
+  skip_before_action :require_login, only: [:create, :new], raise: false
 
   def new
     @user = user_from_params
@@ -27,14 +20,6 @@ class Clearance::UsersController < Clearance::BaseController
 
   private
 
-  def avoid_sign_in
-    warn "[DEPRECATION] Clearance's `avoid_sign_in` before_filter is " +
-      "deprecated. Use `redirect_signed_in_users` instead. " +
-      "Be sure to update any instances of `skip_before_filter :avoid_sign_in`" +
-      " or `skip_before_action :avoid_sign_in` as well"
-    redirect_signed_in_users
-  end
-
   def redirect_signed_in_users
     if signed_in?
       redirect_to Clearance.configuration.redirect_url

data/clearance.gemspec

@@ -1,14 +1,14 @@
 $LOAD_PATH.push File.expand_path('../lib', __FILE__)
 require 'clearance/version'
-require 'date'
 
 Gem::Specification.new do |s|
-  s.add_dependency 'bcrypt'
-  s.add_dependency 'email_validator', '~> 1.4'
-  s.add_dependency 'railties', '>= 3.1'
-  s.add_dependency 'activemodel', '>= 3.1'
-  s.add_dependency 'activerecord', '>= 3.1'
-  s.add_dependency 'actionmailer', '>= 3.1'
+  s.add_dependency 'bcrypt', '>= 3.1.1'
+  s.add_dependency 'argon2', '~> 2.0', '>= 2.0.2'
+  s.add_dependency 'email_validator', '~> 2.0'
+  s.add_dependency 'railties', '>= 5.0'
+  s.add_dependency 'activemodel', '>= 5.0'
+  s.add_dependency 'activerecord', '>= 5.0'
+  s.add_dependency 'actionmailer', '>= 5.0'
   s.authors = [
     'Dan Croak',
     'Eugene Bolshakov',
@@ -29,7 +29,13 @@ Gem::Specification.new do |s|
     'Galen Frechette',
     'Josh Steiner'
   ]
-  s.description = 'Rails authentication & authorization with email & password.'
+  s.description = <<-DESCRIPTION
+    Clearance is built to support authentication and authorization via an
+    email/password sign-in mechanism in applications.
+
+    It provides some core classes commonly used for these features, along with
+    some opinionated defaults - but is intended to be easy to override.
+  DESCRIPTION
   s.email = 'support@thoughtbot.com'
   s.extra_rdoc_files = %w(LICENSE README.md)
   s.files = `git ls-files`.split("\n")
@@ -38,7 +44,7 @@ Gem::Specification.new do |s|
   s.name = %q{clearance}
   s.rdoc_options = ['--charset=UTF-8']
   s.require_paths = ['lib']
-  s.required_ruby_version = Gem::Requirement.new('>= 1.9.2')
+  s.required_ruby_version = Gem::Requirement.new('>= 2.4.0')
   s.summary = 'Rails authentication & authorization with email & password.'
   s.test_files = `git ls-files -- {spec}/*`.split("\n")
   s.version = Clearance::VERSION

data/config/locales/clearance.en.yml

@@ -17,6 +17,7 @@ en:
     failure_when_forbidden: Please double check the URL or try submitting
       the form again.
     failure_when_not_signed_in: Please sign in to continue.
+    failure_when_missing_email: Email can't be blank.
   helpers:
     label:
       password: