clearance 1.8.0 → 1.16.0

data/lib/clearance/user.rb

@@ -3,23 +3,139 @@ require 'email_validator'
 require 'clearance/token'
 
 module Clearance
+  # Required to be included in your configued user class, which is `User` by
+  # default, but can be changed with {Configuration#user_model=}.
+  #
+  #     class User
+  #       include Clearance::User
+  #
+  #       # ...
+  #     end
+  #
+  # This will also include methods exposed by your password strategy, which can
+  # be configured with {Configuration#password_strategy=}. By default, this is
+  # {PasswordStrategies::BCrypt}.
+  #
+  # ## Validations
+  #
+  # These validations are added to the class that the {User} module is mixed
+  # into.
+  #
+  # * If {#email_optional?} is false, {#email} is validated for presence,
+  #   uniqueness and email format (using the `email_validator` gem in strict
+  #   mode).
+  # * If {#skip_password_validation?} is false, {#password} is validated
+  #   for presence.
+  #
+  # ## Callbacks
+  #
+  # * {#normalize_email} will be called on `before_validation`
+  # * {#generate_remember_token} will be called on `before_create`
+  #
+  # @!attribute email
+  #   @return [String] The user's email.
+  #
+  # @!attribute encrypted_password
+  #   @return [String] The user's encrypted password.
+  #
+  # @!attribute remember_token
+  #   @return [String] The value used to identify this user in their {Session}
+  #     cookie.
+  #
+  # @!attribute confirmation_token
+  #   @return [String] The value used to identify this user in the password
+  #     reset link.
+  #
+  # @!attribute password_changing
+  #   @deprecated Dirty tracking is now handled automatically.
+  #
+  # @!attribute [r] password
+  #   @return [String] Transient (non-persisted) attribute that is set when
+  #     updating a user's password. Only the {#encrypted_password} is persisted.
+  #
+  # @!method password=
+  #   Sets the user's encrypted_password by using the configured Password
+  #   Strategy's `password=` method. By default, this will be
+  #   {PasswordStrategies::BCrypt#password=}, but can be changed with
+  #   {Configuration#password_strategy}.
+  #
+  #   @see PasswordStrategies
+  #   @return [void]
+  #
+  # @!method authenticated?
+  #   Check's the provided password against the user's encrypted password using
+  #   the configured password strategy. By default, this will be
+  #   {PasswordStrategies::BCrypt#authenticated?}, but can be changed with
+  #   {Configuration#password_strategy}.
+  #
+  #   @see PasswordStrategies
+  #   @param [String] password
+  #     The password to check.
+  #   @return [Boolean]
+  #     True if the password provided is correct for the user.
+  #
+  # @!method self.authenticate
+  #   Finds the user with the given email and authenticates them with the
+  #   provided password. If the email corresponds to a user and the provided
+  #   password is correct for that user, this method will return that user.
+  #   Otherwise it will return nil.
+  #
+  #   @return [User, nil]
+  #
+  # @!method self.find_by_normalized_email
+  #   Finds the user with the given email. The email with be normalized via
+  #   {#normalize_email}.
+  #
+  #   @return [User, nil]
+  #
+  # @!method self.normalize_email
+  #   Normalizes the provided email by downcasing and removing all spaces.
+  #   This is used by {find_by_normalized_email} and is also called when
+  #   validating a user to ensure only normalized emails are stored in the
+  #   database.
+  #
+  #   @return [String]
+  #
   module User
     extend ActiveSupport::Concern
 
     included do
-      attr_accessor :password_changing
       attr_reader :password
 
       include Validations
       include Callbacks
       include password_strategy
+
+      def password=(value)
+        encrypted_password_will_change!
+        super
+      end
+
+      def password_changing
+        warn "#{Kernel.caller.first}: [DEPRECATION] " \
+          "The `password_changing` attribute is deprecated. Clearance uses " \
+          "the dirty state of the `encrypted_password` field to track this " \
+          "automatically."
+
+        @password_changing
+      end
+
+      def password_changing=(value)
+        warn "#{Kernel.caller.first}: [DEPRECATION] " \
+          "The `password_changing` attribute is deprecated. Clearance uses " \
+          "the dirty state of the `encrypted_password` field to track this " \
+          "automatically."
+
+        @password_changing = value
+      end
     end
 
+    # @api private
     module ClassMethods
       def authenticate(email, password)
         if user = find_by_normalized_email(email)
           if password.present? && user.authenticated?(password)
-            return user
+            user
           end
         end
       end
@@ -39,6 +155,7 @@ module Clearance
       end
     end
 
+    # @api private
     module Validations
       extend ActiveSupport::Concern
 
@@ -53,6 +170,7 @@ module Clearance
       end
     end
 
+    # @api private
     module Callbacks
       extend ActiveSupport::Concern
 
@@ -62,18 +180,48 @@ module Clearance
       end
     end
 
+    # Generates a {#confirmation_token} for the user, which allows them to reset
+    # their password via an email link.
+    #
+    # Calling `forgot_password!` will cause the user model to be saved without
+    # validations. Any other changes you made to this user instance will also
+    # be persisted, without validation. It is inteded to be called on an
+    # instance with no changes (`dirty? == false`).
+    #
+    # @return [Boolean] Was the save successful?
     def forgot_password!
       generate_confirmation_token
       save validate: false
     end
 
+    # Generates a new {#remember_token} for the user, which will have the effect
+    # of signing all of the user's current sessions out. This is called
+    # internally by {Session#sign_out}.
+    #
+    # Calling `reset_remember_token!` will cause the user model to be saved
+    # without validations. Any other changes you made to this user instance will
+    # also be persisted, without validation. It is inteded to be called on an
+    # instance with no changes (`dirty? == false`).
+    #
+    # @return [Boolean] Was the save successful?
     def reset_remember_token!
       generate_remember_token
       save validate: false
     end
 
+    # Sets the user's password to the new value, using the `password=` method on
+    # the configured password strategy. By default, this is
+    # {PasswordStrategies::BCrypt#password=}.
+    #
+    # This also has the side-effect of blanking the {#confirmation_token} and
+    # rotating the `#remember_token`.
+    #
+    # Validations will be run as part of this update. If the user instance is
+    # not valid, the password change will not be persisted, and this method will
+    # return `false`.
+    #
+    # @return [Boolean] Was the save successful?
     def update_password(new_password)
-      self.password_changing = true
       self.password = new_password
 
       if valid?
@@ -86,28 +234,58 @@ module Clearance
 
     private
 
+    # Sets the email on this instance to the value returned by
+    # {.normalize_email}
+    #
+    # @return [String]
     def normalize_email
       self.email = self.class.normalize_email(email)
     end
 
+    # Always false. Override this method in your user model to allow for other
+    # forms of user authentication (username, Facebook, etc).
+    #
+    # @return [false]
     def email_optional?
       false
     end
 
+    # Always false. Override this method in your user model to allow for other
+    # forms of user authentication (username, Facebook, etc).
+    #
+    # @return [false]
     def password_optional?
       false
     end
 
+    # True if {#password_optional?} is true or if the user already has an
+    # {#encrypted_password} that is not changing.
+    #
+    # @return [Boolean]
     def skip_password_validation?
-      password_optional? || (encrypted_password.present? && !password_changing)
+      password_optional? ||
+        (encrypted_password.present? && !encrypted_password_changed?)
     end
 
+    # Sets the {#confirmation_token} on the instance to a new value generated by
+    # {Token.new}. The change is not automatically persisted. If you would like
+    # to generate and save in a single method call, use {#forgot_password!}.
+    #
+    # @return [String] The new confirmation token
     def generate_confirmation_token
       self.confirmation_token = Clearance::Token.new
     end
 
+    # Sets the {#remember_token} on the instance to a new value generated by
+    # {Token.new}. The change is not automatically persisted. If you would like
+    # to generate and save in a single method call, use
+    # {#reset_remember_token!}.
+    #
+    # @return [String] The new remember token
     def generate_remember_token
       self.remember_token = Clearance::Token.new
     end
+
+    private_constant :Callbacks, :ClassMethods, :Validations
   end
 end

data/lib/clearance/version.rb

@@ -1,3 +1,3 @@
 module Clearance
-  VERSION = "1.8.0"
+  VERSION = "1.16.0".freeze
 end

data/lib/clearance.rb

@@ -10,6 +10,8 @@ require 'clearance/password_strategies'
 require 'clearance/constraints'
 
 module Clearance
+  # @deprecated Use `Gem::Specification` API if you need to access Clearance's
+  #   Gem root.
   def self.root
     warn "#{Kernel.caller.first}: [DEPRECATION] `Clearance.root` is " +
       "deprecated and will be removed in the next major release. If you need " +

data/lib/generators/clearance/install/install_generator.rb

@@ -23,11 +23,12 @@ module Clearance
         if File.exist? "app/models/user.rb"
           inject_into_file(
             "app/models/user.rb",
-            "include Clearance::User\n\n",
-            after: "class User < ActiveRecord::Base\n"
+            "  include Clearance::User\n\n",
+            after: "class User < #{models_inherit_from}\n",
           )
         else
-          copy_file 'user.rb', 'app/models/user.rb'
+          @inherit_from = models_inherit_from
+          template("user.rb.erb", "app/models/user.rb")
         end
       end
 
@@ -61,7 +62,7 @@ module Clearance
           migration_template(
             "db/migrate/#{migration_name}",
             "db/migrate/#{migration_name}",
-            config
+            config.merge(migration_version: migration_version),
           )
         end
       end
@@ -101,7 +102,11 @@ module Clearance
       end
 
       def users_table_exists?
-        ActiveRecord::Base.connection.table_exists?(:users)
+        if ActiveRecord::Base.connection.respond_to?(:data_source_exists?)
+          ActiveRecord::Base.connection.data_source_exists?(:users)
+        else
+          ActiveRecord::Base.connection.table_exists?(:users)
+        end
       end
 
       def existing_users_columns
@@ -116,6 +121,20 @@ module Clearance
       def self.next_migration_number(dir)
         ActiveRecord::Generators::Base.next_migration_number(dir)
       end
+
+      def migration_version
+        if Rails.version >= "5.0.0"
+          "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+        end
+      end
+
+      def models_inherit_from
+        if Rails.version >= "5.0.0"
+          "ApplicationRecord"
+        else
+          "ActiveRecord::Base"
+        end
+      end
     end
   end
 end

data/lib/generators/clearance/install/templates/clearance.rb

@@ -1,3 +1,4 @@
 Clearance.configure do |config|
   config.mailer_sender = "reply@example.com"
+  config.rotate_csrf_on_sign_in = true
 end

data/lib/generators/clearance/install/templates/db/migrate/add_clearance_to_users.rb

@@ -1,6 +1,6 @@
-class AddClearanceToUsers < ActiveRecord::Migration
+class AddClearanceToUsers < ActiveRecord::Migration<%= migration_version %>
   def self.up
-    change_table :users  do |t|
+    change_table :users do |t|
 <% config[:new_columns].values.each do |column| -%>
       <%= column %>
 <% end -%>
@@ -24,7 +24,7 @@ class AddClearanceToUsers < ActiveRecord::Migration
   def self.down
     change_table :users do |t|
 <% if config[:new_columns].any? -%>
-      t.remove <%= new_columns.keys.map { |column| ":#{column}" }.join(",") %>
+      t.remove <%= new_columns.keys.map { |column| ":#{column}" }.join(", ") %>
 <% end -%>
     end
   end

data/lib/generators/clearance/install/templates/db/migrate/create_users.rb

@@ -1,6 +1,6 @@
-class CreateUsers < ActiveRecord::Migration
+class CreateUsers < ActiveRecord::Migration<%= migration_version %>
   def change
-    create_table :users  do |t|
+    create_table :users do |t|
       t.timestamps null: false
       t.string :email, null: false
       t.string :encrypted_password, limit: 128, null: false

data/lib/generators/clearance/install/templates/user.rb.erb

@@ -0,0 +1,3 @@
+class User < <%= @inherit_from %>
+  include Clearance::User
+end

data/lib/generators/clearance/routes/routes_generator.rb

@@ -9,6 +9,14 @@ module Clearance
         route(clearance_routes)
       end
 
+      def disable_clearance_internal_routes
+        inject_into_file(
+          "config/initializers/clearance.rb",
+          "  config.routes = false\n",
+          after: "Clearance.configure do |config|\n",
+        )
+      end
+
       private
 
       def clearance_routes
@@ -18,6 +26,21 @@ module Clearance
       def routes_file_path
         File.expand_path(find_in_source_paths('routes.rb'))
       end
+
+      def route(routing_code)
+        log :route, "all clearance routes"
+        sentinel = /\.routes\.draw do\s*\n/m
+
+        in_root do
+          inject_into_file(
+            "config/routes.rb",
+            routing_code,
+            after: sentinel,
+            verbose: false,
+            force: true,
+          )
+        end
+      end
     end
   end
 end

data/lib/generators/clearance/routes/templates/routes.rb

@@ -1,12 +1,12 @@
-resources :passwords, controller: 'clearance/passwords', only: [:create, :new]
-  resource :session, controller: 'clearance/sessions', only: [:create]
+  resources :passwords, controller: "clearance/passwords", only: [:create, :new]
+  resource :session, controller: "clearance/sessions", only: [:create]
 
-  resources :users, controller: 'clearance/users', only: [:create] do
+  resources :users, controller: "clearance/users", only: [:create] do
     resource :password,
-      controller: 'clearance/passwords',
+      controller: "clearance/passwords",
       only: [:create, :edit, :update]
   end
 
-  get '/sign_in' => 'clearance/sessions#new', as: 'sign_in'
-  delete '/sign_out' => 'clearance/sessions#destroy', as: 'sign_out'
-  get '/sign_up' => 'clearance/users#new', as: 'sign_up'
+  get "/sign_in" => "clearance/sessions#new", as: "sign_in"
+  delete "/sign_out" => "clearance/sessions#destroy", as: "sign_out"
+  get "/sign_up" => "clearance/users#new", as: "sign_up"

data/lib/generators/clearance/specs/templates/features/clearance/user_signs_out_spec.rb.tt

@@ -1,7 +1,7 @@
 require "<%= @helper_file %>"
 require "support/features/clearance_helpers"
 
-feature "User signs out" do
+RSpec.feature "User signs out" do
   scenario "signs out" do
     sign_in
     sign_out

data/lib/generators/clearance/specs/templates/features/clearance/visitor_resets_password_spec.rb.tt

@@ -1,8 +1,17 @@
 require "<%= @helper_file %>"
 require "support/features/clearance_helpers"
 
-feature "Visitor resets password" do
+RSpec.feature "Visitor resets password" do
   before { ActionMailer::Base.deliveries.clear }
+<% if defined?(ActiveJob) -%>
+
+  around do |example|
+    original_adapter = ActiveJob::Base.queue_adapter
+    ActiveJob::Base.queue_adapter = :inline
+    example.run
+    ActiveJob::Base.queue_adapter = original_adapter
+  end
+<% end -%>
 
   scenario "by navigating to the page" do
     visit sign_in_path
@@ -47,7 +56,8 @@ feature "Visitor resets password" do
     message = ActionMailer::Base.deliveries.any? do |email|
       email.to == [recipient] &&
         email.subject =~ /#{subject}/i &&
-        email.body =~ /#{body}/
+        email.html_part.body =~ /#{body}/ &&
+        email.text_part.body =~ /#{body}/
     end
 
     expect(message).to be

data/lib/generators/clearance/specs/templates/features/clearance/visitor_signs_in_spec.rb.tt

@@ -1,7 +1,7 @@
 require "<%= @helper_file %>"
 require "support/features/clearance_helpers"
 
-feature "Visitor signs in" do
+RSpec.feature "Visitor signs in" do
   scenario "with valid email and password" do
     create_user "user@example.com", "password"
     sign_in_with "user@example.com", "password"

data/lib/generators/clearance/specs/templates/features/clearance/visitor_signs_up_spec.rb.tt

@@ -1,7 +1,7 @@
 require "<%= @helper_file %>"
 require "support/features/clearance_helpers"
 
-feature "Visitor signs up" do
+RSpec.feature "Visitor signs up" do
   scenario "by navigating to the page" do
     visit sign_in_path
 

data/lib/generators/clearance/specs/templates/features/clearance/visitor_updates_password_spec.rb.tt

@@ -1,7 +1,7 @@
 require "<%= @helper_file %>"
 require "support/features/clearance_helpers"
 
-feature "Visitor updates password" do
+RSpec.feature "Visitor updates password" do
   scenario "with valid password" do
     user = user_with_reset_password
     update_password user, "newpassword"

data/spec/acceptance/clearance_installation_spec.rb

@@ -10,6 +10,7 @@ describe "Clearance Installation" do
 
   it "can successfully run specs" do
     app_name = "testapp"
+
     generate_test_app(app_name)
 
     Dir.chdir(app_name) do
@@ -28,7 +29,8 @@ describe "Clearance Installation" do
        --skip-git \
        --skip-javascript \
        --skip-sprockets \
-       --skip-keeps"
+       --skip-keeps \
+       --no-rc"
 
     FileUtils.rm_f("public/index.html")
     FileUtils.rm_f("app/views/layouts/application.html.erb")
@@ -70,6 +72,7 @@ describe "Clearance Installation" do
     end
 
     return_value = system("#{command} #{silencer}")
+
     expect(return_value).to eq true
   end
 end

data/spec/app_templates/app/models/rails5/user.rb

@@ -0,0 +1,5 @@
+class User < ApplicationRecord
+  def previously_existed?
+    true
+  end
+end

data/spec/app_templates/config/initializers/clearance.rb

@@ -0,0 +1,2 @@
+Clearance.configure do |config|
+end

data/spec/app_templates/testapp/app/controllers/home_controller.rb

@@ -1,5 +1,9 @@
 class HomeController < ApplicationController
   def show
-    render text: "", layout: "application"
+    if Rails::VERSION::MAJOR >= 5
+      render html: "", layout: "application"
+    else
+      render text: "", layout: "application"
+    end
   end
 end

data/spec/app_templates/testapp/config/initializers/action_mailer.rb

@@ -1,3 +1 @@
-Rails.application.config.action_mailer.default_url_options = {
-  host: "localhost"
-}
+ActionMailer::Base.default_url_options[:host] = "localhost"

data/spec/clearance/back_door_spec.rb

@@ -1,8 +1,8 @@
-require 'spec_helper'
+require "spec_helper"
 
 describe Clearance::BackDoor do
-  it 'signs in as a given user' do
-    user_id = '123'
+  it "signs in as a given user" do
+    user_id = "123"
     user = double("user")
     allow(User).to receive(:find).with(user_id).and_return(user)
     env = env_for_user_id(user_id)
@@ -14,7 +14,7 @@ describe Clearance::BackDoor do
     expect(result).to eq mock_app.call(env)
   end
 
-  it 'delegates directly without a user' do
+  it "delegates directly without a user" do
     env = env_without_user_id
     back_door = Clearance::BackDoor.new(mock_app)
 
@@ -24,8 +24,22 @@ describe Clearance::BackDoor do
     expect(result).to eq mock_app.call(env)
   end
 
+  it "can set the user via a block" do
+    env = env_for_username("foo")
+    user = double("user")
+    allow(User).to receive(:find_by).with(username: "foo").and_return(user)
+    back_door = Clearance::BackDoor.new(mock_app) do |username|
+      User.find_by(username: username)
+    end
+
+    result = back_door.call(env)
+
+    expect(env[:clearance]).to have_received(:sign_in).with(user)
+    expect(result).to eq mock_app.call(env)
+  end
+
   def env_without_user_id
-    env_for_user_id('')
+    env_for_user_id("")
   end
 
   def env_for_user_id(user_id)
@@ -33,7 +47,12 @@ describe Clearance::BackDoor do
     Rack::MockRequest.env_for("/?as=#{user_id}").merge(clearance: clearance)
   end
 
+  def env_for_username(username)
+    clearance = double("clearance", sign_in: true)
+    Rack::MockRequest.env_for("/?as=#{username}").merge(clearance: clearance)
+  end
+
   def mock_app
-    lambda { |env| [200, {}, ['okay']] }
+    lambda { |env| [200, {}, ["okay"]] }
   end
 end

data/spec/clearance/controller_spec.rb

@@ -0,0 +1,11 @@
+require "spec_helper"
+
+describe Clearance::Controller, type: :controller do
+  controller(ActionController::Base) do
+    include Clearance::Controller
+  end
+
+  it "exposes no action methods" do
+    expect(controller.action_methods).to be_empty
+  end
+end

data/spec/clearance/rack_session_spec.rb

@@ -2,21 +2,21 @@ require 'spec_helper'
 
 describe Clearance::RackSession do
   it 'injects a clearance session into the environment' do
-    expected_session = 'the session'
-    allow(expected_session).to receive(:add_cookie_to_headers)
-    allow(Clearance::Session).to receive(:new).and_return(expected_session)
     headers = { 'X-Roaring-Lobster' => 'Red' }
-
     app = Rack::Builder.new do
       use Clearance::RackSession
       run lambda { |env| Rack::Response.new(env[:clearance], 200, headers).finish }
     end
 
     env = Rack::MockRequest.env_for('/')
+    expected_session = "the session"
+    allow(expected_session).to receive(:add_cookie_to_headers)
+    allow(Clearance::Session).to receive(:new).
+      with(env).
+      and_return(expected_session)
 
     response = Rack::MockResponse.new(*app.call(env))
 
-    expect(Clearance::Session).to have_received(:new).with(env)
     expect(response.body).to eq expected_session
     expect(expected_session).to have_received(:add_cookie_to_headers).
       with(hash_including(headers))