module Clearance::User

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.

## Callbacks

@!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 [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?(password)

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]