quo_vadis 1.4.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: fd5c30c44899810a95d8d3316ad1955d080883ef
-  data.tar.gz: 15b805d818d9878a348ad52f81ef34906b5c5b02
+SHA256:
+  metadata.gz: 4f8acc907c43d19fcc6f9be59854be5e848add025d427f78ec608b2e24677e73
+  data.tar.gz: efab0ab6fc83535466f6bb6e31bb056016c5220ef227155629601e5c17aff5b6
 SHA512:
-  metadata.gz: '058b7b734fb667976cd4eba65106c7e963b5c32c0846d576c4ba37fda86344ddd5b21df2e8d1e17dfbce259417a9d44e288e5a363cf231c869c64a373f9f1e6c'
-  data.tar.gz: ff28b1d215e0573fa639394b62c032ad21deb88b5d9a108c0edb4084b391d4d25bc5635bd6ec56150177da8589be8fbf7b521110db97d78a408699ff9e7785d3
+  metadata.gz: 8d34c8922431d4234650c50718a29b71a328b070582bb5b7fac74d4b1e2b6847bc2b130a197d6dcc05d93d2c0dab882a90fecf9faa3e1620f36acb48b9be3778
+  data.tar.gz: 4f471b97ff2a2dc0461ddac1f68c1e9f263ac5c188ab89daf2974f3c8f2e85c5e2b586da72b8c798d5f696acf3a2a7079aef57fb689f8f75f8113a38d56b2c2d

data/.gitignore

@@ -1,8 +1,12 @@
-pkg/*
-*.gem
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/test/dummy/log/
+/test/dummy/tmp/
+/test/dummy/db/*.sqlite3
 Gemfile.lock
-.bundle
-test/dummy/log/*
-test/dummy/tmp/*
-rdoc/*
-NOTES

data/CHANGELOG.md

@@ -1,6 +1,37 @@
 # CHANGELOG
 
 
+## 2.1.0 (25 June 2021)
+
+* Fix incorrect assignment of built association.
+* Add i18n translations for log actions.
+* Use model instance in change-password form.
+* Ensure password-reset flash notice not displayed when emailed link is clicked.
+* Use model instance in password-reset form.
+* Give no indication of unknown account on request of password reset email.
+* Use 422 status code for form submission error responses.
+* Make default cookie name depend on Rails environment.
+
+
+## 2.0.2 (24 May 2021)
+
+* Account confirmation: enable updating of email address.
+* Account confirmation: enable direct resending of email.
+* Log unknown identifier in metadata.
+
+
+## 2.0.1 (18 May 2021)
+
+* Remove Gemfile.lock from repo.
+* Move runtime dependencies into gemspec.
+* Include test files in gem package (so views can be installed).
+
+
+## 2.0.0 (14 May 2021)
+
+* Total rewrite from scratch.
+
+
 ## 1.4.0 (12 October 2016)
 
 * Internationalise emails' subject lines.

data/Gemfile

@@ -1,3 +1,13 @@
-source "http://rubygems.org"
+# frozen_string_literal: true
 
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in quo_vadis.gemspec
 gemspec
+
+gem "rake", "~> 13.0"
+
+gem 'sqlite3'
+gem 'capybara'
+
+# gem "minitest", "~> 5.0"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Andy Stewart
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -1,211 +1,539 @@
-# Quo Vadis?
+# Quo Vadis
 
-Quo Vadis adds simple username/password authentication to Rails 3 applications.
+Multifactor authentication for your Rails 6 app.
 
-Why bother with yet another authentication gem?  Well, I find all the others over-engineered.  Code should be easy to use and easy to read.  As far as I'm concerned, none of the others ticks both boxes.
+Designed in accordance with the [OWASP Application Security Verification Standard](https://owasp.org/www-project-application-security-verification-standard/) and relevant [OWASP Cheatsheets](https://cheatsheetseries.owasp.org).
 
-Features:
+Simple to integrate into your application.  The main task is customising the example views' markup to match your look-and-feel.
 
-* Minimal effort to add authentication to your app: get up and running in 5 minutes.
-* No surprises: it does what you expect.
-* Easy to customise.
-* Uses BCrypt to encrypt passwords.
-* Sign in, sign out, forgotten password, authenticate actions, remember user between browser sessions, user activation.
-* Block accounts.
-* Let you choose which model(s) to authenticate (defaults to `User`).
 
-Forthcoming features:
+## Features
 
-* Generate the views for you (for now, copy the examples given below).
-* Let you choose the identification field (currently `username`).
-* HTTP basic/digest authentication (probably).
-* Generate model plus migration if it doesn't exist.
-* Detect presence of `has_secure_password` (see below) and adapt appropriately.
+### General features
 
-What it doesn't and won't do:
+- Works with any model, e.g. `User` or `Person`.
+- Works with any identifier, e.g. `:username` or `:email`.
+- Minimal footprint in your models and controllers.
+- Does not touch your existing database tables.
+- Secrets (password, TOTP secret, 2FA recovery codes) are encrypted at rest.
 
-* Authorisation.
-* Work outside Rails 3.
-* OpenID, OAuth, LDAP, CAS, etc.
-* Separate identity from authentication services (cf OmniAuth).
-* Allow you to have multiple models/scope signed in simultaneously (cf Devise).
-* Offer so much flexibility that it takes more than 10 minutes to wrap your head around it (cf Devise, Authlogic).
+### Authentication features
 
+- Authentication by password.
+- Two-factor authentication (2FA) by TOTP with recovery codes as a backup factor.  Can be optional or mandatory.
+- Change password.
+- Reset password.
+- Account confirmation (optional).
+- Tokens (account confirmation, password reset), TOTPs, and recovery codes are all one-time-only.
+- Sessions expired after lifetime or idle time exceeded.
+- Session replaced after any privilege change.
+- View active sessions, log out of any of them.
+- Email-notifications of updates to authentication details.
+- Audit trail.
 
-## Quick Start
 
-If this takes you more than 5 minutes, you can have your money back ;)
+## Installation
 
-Install and run the generator: add `gem 'quo_vadis'` to your Gemfile, run `bundle install`, then `rails generate quo_vadis:install [MODEL_NAME]` (where model name is optional and defaults to `User`).
+Add the gem to your Gemfile:
 
-Edit and run the generated migration to add the authentication columns: `rake db:migrate`.  Note the migration (currently) assumes you already have a table for your model.
+```ruby
+gem 'quo_vadis', '~> 2.0'
+```
 
-In your `User` (or whichever) model, add `authenticates`:
+Then run `bundle install`.
 
-    class User < ActiveRecord::Base
-      authenticates
-    end
+Next, add the database tables:
 
-Note Quo Vadis validates the presence and uniqueness of the username, and the presence of the password, but it's up to you to add any other validations you want.
+```
+rails quo_vadis:install:migrations && rails db:migrate
+```
 
-Use `:authenticate` in a `before_filter` to protect your controllers' actions.  For example:
+All the database tables are prefixed with `qv_`.
 
-    class ArticlesController < ActionController::Base
-      before_filter :authenticate, :except => [:index, :show]
-    end
+Finally, copy the example views across:
 
-Write the sign-in view.  Your sign-in form must:
+```
+rails generate quo_vadis:install
+```
 
-* be in `app/views/sessions/new.html.:format`
-* POST the parameters `:username` and `:password` to `sign_in_url`
 
-You have to write the view yourself because you'd inevitably want to change whatever markup I generated for you.  You can find an example in the [test app](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/sessions/new.html.erb).
+## Usage
 
-Remember to serve your sign in form over HTTPS -- to avoid [the credentials being stolen](http://blog.jgc.org/2011/01/code-injected-to-steal-passwords-in.html).
 
-In your layout, use `current_user` to retrieve the signed-in user; and `sign_in_path`, `sign_out_path`, and `forgotten_sign_in_path` as appropriate.  You can also use `authenticated?`.
+### Model
 
+Your model must have an `:email` attribute.  All authentication-related emails will be sent to this address.
 
-## Forgotten Password
+Your model must have an identifier, e.g. `:email` (default) or `:username`, with a uniqueness validation.
 
-Here's the workflow:
+All you need do is add a call to `authenticates`, somewhere after your identifier's uniqueness validation.
 
-1. [Sign in page] The user clicks the "I've forgotten my password" link.
-2. [Forgotten password page] The user enters their username in the form and submits it.
-3. Quo Vadis emails the user a message with a change-password link.  The link is valid for 3 hours.
-4. [The email] The user clicks the link.
-5. [Change password page] The user types in a new password and saves it.
-6. Quo Vadis changes the user's password and signs the user in.
+For example, let's say you have a `User` model and the identifier is `:email`:
 
-It'll take you about 5 minutes to implement this.
+```ruby
+class User < ApplicationRecord
+  validates :email, uniqueness: {case_sensitive: false}
+  authenticates
+end
+```
 
-On your sign-in page, link to the forgotten-password view at `forgotten_sign_in_url`.
+If instead you had a `Person` model with a `:username` identifier:
 
-Write the forgotten-password view ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/sessions/forgotten.html.erb)).  The form must:
+```ruby
+class Person < ApplicationRecord
+  validates :username, uniqueness: {case_sensitive: false}
+  authenticates identifier: :username
+end
+```
 
-* be in `app/views/sessions/forgotten.html.:format`
-* POST the parameter `:username` to `forgotten_sign_in_url`
+You can create and update your models as before.  When you want to set a password for the first time, just include `:password` and, optionally, `:password_confirmation` in the attributes to `#create` or `#update`.
 
-Now write the mailer view, i.e. the email which will be sent to your forgetful users ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/quo_vadis/notifier/change_password.text.erb)).  The view must:
+If you want to change an existing password, use the Change Password feature (see below).  If you update a model (that already has a password) with a `:password` attribute, it will raise a `QuoVadis::PasswordExistsError`.
 
-* be at `app/views/quo_vadis/notifier/change_password.text.erb`
-* render `@url` somewhere (this is the link the user clicks to go to the change-password page)
+The minimum password length is configured by `QuoVadis.password_minimum_length` (12 by default).
 
-You can also refer to `@username` in the email view.
 
-Configure the email's from address in `config/initializers/quo_vadis.rb`.
+### Controllers
 
-Configure the default host so ActionMailer can generate the URL.  In `config/environments/<env>.rb`:
+You can use these methods in your controllers.
 
-    config.action_mailer.default_url_options = {:host => 'yourdomain.com'}
+__`require_password_authentication`__
 
-Finally, write the change-password page ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/sessions/edit.html.erb)).  The form must:
+Use this to restrict actions to password-authenticated users.  It is aliased to `:require_authentication` for convenience.
 
-* be in `app/views/sessions/edit.html.:format`
-* PUT the parameter `:password` to `change_password_url(params[:token])`
+```ruby
+class FoosController < ApplicationController
+  before_action :require_password_authentication
+end
+```
 
+__`require_two_factor_authentication`__
 
-## Sign up (directly, without activation)
+Use this to restrict actions to users authenticated with both a password and a second factor.  (You do not need to use `:require_password_authentication` for these actions.)
 
-When you create a user, you need to sign them in.  Do this by calling `sign_in(user)` in your controller.  For example:
+```ruby
+class BarsController < ApplicationController
+  before_action :require_two_factor_authentication
+end
+```
 
-    # In your app
-    class UsersController < ApplicationController
-      def create
-        @user = User.new params[:user]
-        if @user.save
-          sign_in @user    # <-- NOTE: sign in your user here
-        else
-          render 'new'
-        end
-      end
-    end
+__`login(model, browser_session = true)`__
+
+To log in a user who has authenticated with a password, call `#login(model, browser_session = true)`.  For the `browser_session` argument, pass `true` to log in for the duration of the browser session, or `false` to log in for `QuoVadis.session_lifetime` (which could be the browser session anyway).
+
+__`request_confirmation(model)`__
+
+This is used to sent an account confirmation email to the user.  See the Account Confirmation feature below for details.
+
+__`authenticated_model`__
+
+Call this to get the authenticated user.  Feel free to alias this to `:current_user` or set it into an `ActiveSupport::CurrentAttributes` class.
+
+Available in controllers and views.
+
+__`logged_in?`__
+
+Call this to find out whether a user has authenticated with a password.
+
+Available in controllers and views.
+
+
+### Views
+
+You can use `authenticated_model` and `logged_in?` in your views.  For example:
 
-The `sign_in(user)` method will redirect the user appropriately (you can configure this in `config/initializers/quo_vadis.rb`), as well as running any sign-in hook you may have defined in the initializer.
+```erb
+<% if logged_in? %>
+  <%= link_to 'My profile', authenticated_model %>
+<% end %>
+```
 
+In your own views, you must prefix QuoVadis's routes with `quo_vadis.`.  For example:
 
-## Sign up (with activation)
+```ruby
+link_to 'Log in', quo_vadis.login_path
+```
 
-To create a user who must activate their account (via email) before they can sign in, do this:
+When you are customising QuoVadis's views, you must prefix your app's routes with `main_app.`.  For example:
 
-    # In your app
-    class UsersController < ApplicationController
-      def create
-        @user = User.new_for_activation params[:user]    # <-- NOTE: different constructor
-        if @user.save
-          QuoVadis::SessionsController.new.invite_to_activate @user    # <-- NOTE: email user here
-          redirect_to root_path, notice: "Emailed sign-in instructions to #{@user.name}"  # or whatever
-        else
-          render 'new'
-        end
-      end
+```ruby
+link_to 'Home', main_app.root_path
+```
+
+
+## Features
+
+The example views show the forms and fields you need.  You should only need to adapt the markup to suit your app's appearance.
+
+In the snippets below we assume a `User` model whose identifier is `:email`.  You can of course use anything you like.
+
+
+### Sign up
+
+Your new user sign-up form ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/users/new.html.erb)) must include:
+
+- a `:password` field;
+- optionally a `:password_confirmation` field;
+- a field for their identifier;
+- an `:email` field if the identifier is not their email.
+
+In your controller, use the `#login` method to log in your new user.  The optional second argument sets the length of the session (defaults to the browser session) - see the description above in the Controllers section).
+
+After logging in the user, redirect them to `qv.path_after_authentication` which resolves to a route named `:after_login`, if you have one, or your root route.
+
+```ruby
+class UsersController < ApplicationController
+  def create
+    @user = User.new user_params
+    if @user.save
+      login @user
+      redirect_to qv.path_after_authentication
+    else
+      # ...
     end
+  end
+
+  private
 
-The user will receive an email with a link which takes them to a page (which you must write) where they can choose a username and password for themselves.  When they submit the form their new credentials are stored and they are signed in.
+  def user_params
+    params.require(:user).permit(:name, :email, :password, :password_confirmation)
+  end
+end
+```
+
+```ruby
+# config/routes.rb
+get '/dashboard', as: 'after_login'
+```
+
+
+### Sign up with account confirmation
 
 Here's the workflow:
 
-1. [New user page, without username/password fields] You or user fills in and submits form.
-2. [Users controller] Create user and invite to activate.  See code snippet above.
-3. Quo Vadis emails the user a message with an invitation link.  The link is valid for 3 hours.
-4. [The email] The user clicks the link.
-5. [Invitation page] The user fills in their new username and password.
-6. Quo Vadis sets the user's username and password and signs the user in.
+1. [Sign up page] The user fills in their details.
+2. [Your controller] Your code tells QuoVadis to email the user a confirmation link.  The link is valid for `QuoVadis.account_confirmation_token_lifetime`.
+3. [The email] The user clicks the link.
+4. [Account-confirmation confirmation page] The user clicks a button to confirm their account.  (This step is to prevent any link prefetching in the user's mail client from confirming them unintentionally.)
+5. QuoVadis confirms the user's account and logs them in.
+
+Your new user sign-up form ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/sign_ups/new.html.erb)) must include:
+
+- a `:password` field;
+- optionally a `:password_confirmation` field;
+- a field for their identifier;
+- an `:email` field if the identifier is not their email.
+
+In your controller, call `#request_confirmation`:
+
+```ruby
+class UsersController < ApplicationController
+  def create
+    @user = User.new user_params
+    if @user.save
+      request_confirmation @user
+      redirect_to quo_vadis.confirmations_path  # a page where you advise the user to check their email
+    else
+      # ...
+    end
+  end
+
+  private
+
+  def user_params
+    params.require(:user).permit(:name, :email, :password, :password_confirmation)
+  end
+end
+```
+
+QuoVadis will send the user an email with a link.  Write the email view ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/quo_vadis/mailer/account_confirmation.text.erb)).  It must be in `app/views/quo_vadis/mailer/account_confirmation.{text,html}.erb` and output the `@url` variable.
+
+See the Configuration section below for how to set QuoVadis's emails' from addresses, headers, etc.
+
+Now write the page to where the user is redirected while they wait for the email ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/quo_vadis/confirmations/index.html.erb)).  It must be in `app/views/quo_vadis/confirmations/index.html.:format`.
+
+On that page you can show the user the address the email was sent to, enable them to update their email address if they make a mistake on the sign-up form, and provide a button to resend another email directly.  If the sign-up occurred in a different browser session, you can instead link to `new_confirmation_path` where the user can request another email if need be.
+
+Next, write the page to which the link in the email points ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/quo_vadis/confirmations/edit.html.erb)).  It must be in `app/views/quo_vadis/confirmations/edit.html.:format`.
+
+Next, write the page where the user can amend their email address if they made a mistake when signing up ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/quo_vadis/confirmations/edit_email.html.erb)).  It must be in `app/views/quo_vadis/confirmations/edit_email.html.:format`.
+
+Finally, write the page where people can put in their identifier (not their email, unless the identifier is email) again to request another confirmation email ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/quo_vadis/confirmations/new.html.erb)).  It must be in `app/views/quo_vadis/confirmations/new.html.:format`.
+
+After the user has confirmed their account, they will be logged in and redirected to the first of these that exists:
+
+- a route named `:after_login`;
+- your root route.
+
+So add whichever works best for you.
+
+
+### Login
+
+Use `before_action :require_password_authentication` or `before_action :require_authentication` in your controllers.
+
+Write the login view ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/quo_vadis/sessions/new.html.erb)).  Your login form must be in `app/views/quo_vadis/sessions/new.html.:format`.  Note it must capture the user's identifier (not email, unless the identifier is email).
+
+If you include a `remember` checkbox in your login form:
+
+- if the user checks it, they will be logged in for `QuoVadis.session_lifetime`;
+- if the user does not check it, they will be logged in for the browser session.
+
+If you do not include a `remember` checkbox, the user will be logged in for `QuoVadis.session_lifetime`.
+
+After authenticating the user will be redirected to the first of these that exists:
+
+- the page they tried to view before they were redirected to the login page;
+- a route named `after_login`, if any;
+- your root route.
+
+
+### Two-factor authentication (2FA) or Two-step verification (2SV)
+
+If you do not want 2FA at all, set `QuoVadis.two_factor_authentication_mandatory false` in your configuration and skip the rest of this section.
+
+If you do want 2FA, you can choose whether it is optional or mandatory for your users by setting `QuoVadis.two_factor_authentication_mandatory <true|false>` in your configuration.
+
+Use `before_action :require_two_factor_authentication` in your controllers (which supersedes `:require_password_authentication`).  This will require the user, after authenticating with their password, to authenticate with 2FA – when 2FA is mandatory, or when it is optional and the user has set up 2FA.
+
+Here's the workflow for a user setting up optional 2FA:
+
+1. User visits their 2FA overview page.
+2. [2FA overview page] User clicks a link to set up 2FA (TOTP for now).
+3. [TOTP setup page] User scans the QR code with their authenticator and enters the 6-digit one-time password.
+4. QuoVadis verifies the one-time password, generates 5 backup recovery codes, and redirects the user to the recovery codes page (or back to step 3 if the OTP is invalid).
+5. [Recovery code page] User views and hopefully saves their 5 recovery codes.
+
+When 2FA is mandatory the workflow starts automatically at step 3 after password authentication.
+
+In your views, have a link where users can manage their 2FA:
+
+```ruby
+link_to '2FA', quo_vadis.twofa_path
+```
+
+Write the 2FA overview page ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/quo_vadis/twofas/show.html.erb)).  It must be in `app/views/quo_vadis/twofas/show.html.:format`.  This page allows the user to set up 2FA, deactivate or reset it, and generate new recovery codes.
 
-It'll take you about 3 minutes to implement this.
+Next, write the TOTP setup page ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/quo_vadis/totps/new.html.erb)).  It must be in `app/views/quo_vadis/totps/new.html.:format`.  This page shows the user a QR code (and the key as text) which they scan with their authenticator.
 
-Update your user controller's `create` action as above.
+Next, write the recovery codes page ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/quo_vadis/recovery_codes/index.html.erb)).  It must be in `app/views/quo_vadis/recovery_codes/index.html.:format`.  This shows the recovery codes immediately after TOTP is setup, and immediately after generating fresh recovery codes, but not otherwise.
 
-Write the mailer view, i.e. the email which will be sent to your new users ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/quo_vadis/notifier/invite.text.erb)).  The view must:
+Next, write the TOTP challenge page where a user inputs their 6-digit TOTP ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/quo_vadis/totps/challenge.html.erb)).  It must be in `app/views/quo_vadis/totps/challenge.html.:format`.  It's a good idea to link to the recovery code page (`challenge_recovery_codes_path`) for any user who has lost their authenticator.
 
-* be at `app/views/quo_vadis/notifier/invite.text.erb`
-* render `@url` somewhere (this is the link the user clicks to go to the invitation page)
+Finally, write the recovery code challenge page where a user inputs one of their recovery codes ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/quo_vadis/recovery_codes/challenge.html.erb)).  It must be in `app/views/quo_vadis/recovery_codes/challenge.html.:format`.  A recovery code can only be used once, and using one deactivates TOTP – so the user will have to set it up again next time.
 
-You can also refer to `@user` in the email view, as well as any other data you pass to `invite_to_activate`.  Note that passing `:from` and/or `:subject` in the hash to `invite_to_activate` overrides the default `QuoVadis.from` and/or `I18n.t('quo_vadis.notifier.invite.subject')` respectively.
 
-Configure the email's from address in `config/initializers/quo_vadis.rb` (or pass in the data hash to `invite_to_activate`).
+### Change password
 
-Configure the default host so ActionMailer can generate the URL.  In `config/environments/<env>.rb`:
+To change their password, the user must provide their current one as well as the new one.
 
-    config.action_mailer.default_url_options = {:host => 'yourdomain.com'}
+Write the change-password form ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/quo_vadis/passwords/edit.html.erb)).  It must be in `app/views/quo_vadis/passwords/edit.html.:format`.
 
-Finally, write the invitation page ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/sessions/invite.html.erb)).  The form must:
+After the password has been changed, the user is redirected to the first of:
 
-* be in `app/views/sessions/invite.html.:format`
-* POST the parameters `:username` and `:password` to `activation_url(params[:token])`
+- your route named `:after_password_change`, if any;
+- your root route.
 
-If the token expires and you need to generate a new one, re-invite the user with: `invite_to_activate @user`.
+A successful password change logs out any other sessions the user has (e.g. on other devices).
 
 
-## Customisation
+### Reset password
 
-You can customise the flash messages and mailer from/subject in `config/locales/quo_vadis.en.yml`.
+The user can reset their password if they lose it.  The flow is:
 
-You can customise the sign-in and sign-out redirects in `config/initializers/quo_vadis.rb`; they both default to the root route.  You can also hook into the sign-in and sign-out process if you need to run any other code.
+1. [Request password-reset page] User enters their identifier (not their email unless the identifier is email).
+2. QuoVadis emails the user a link.  The link is valid for `QuoVadis.password_reset_token_lifetime`.
+3. [The email] The user clicks the link.
+4. [Password-reset confirmation page] The user enters their new password and clicks a button.
+5. QuoVadis sets the user's password and logs them in.
 
-If you want to add other session management type features, go right ahead: create a `SessionsController` as normal and carry on.
+First, write the page where the user requests a password-reset ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/quo_vadis/password_resets/new.html.erb)).  It must be in `app/views/quo_vadis/password_resets/new.html.:format`.  Note it must capture the user's identifier (not email, unless the identifier is email).
 
-You can skip the validation of authentication attributes (password etc) by overriding `should_authenticate?` in your model.  Perhaps only some of the users should be able to sign in, so you don't want to force them to have a password.
+See the Configuration section below for how to set QuoVadis's emails' from addresses, headers, etc.
 
+Now write the page to where the user is redirected while they wait for the email ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/quo_vadis/password_resets/index.html.erb)).  It must be in `app/views/quo_vadis/password_resets/index.html.:format`.
 
-## See also
+It's a good idea for that page to link to `new_password_reset_path` where the user can request another email if need be.
+
+Now write the email view ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/quo_vadis/mailer/reset_password.text.erb)).  It must be in `app/views/quo_vadis/mailer/reset_password.{text,html}.erb` and output the `@url` variable.
+
+Next, write the page to which the link in the email points ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/quo_vadis/password_resets/edit.html.erb)).  It must be in `app/views/quo_vadis/password_resets/edit.html.:format`.
+
+After the user has reset their password, they will be logged in and redirected to the first of these that exists:
+
+- a route named `:after_login`;
+- your root route.
+
+
+### Sessions
+
+A logged-in session lasts for either the browser session or `QuoVadis.session_lifetime`.  As well as having a lifetime, a session will also expire after it has been inactive for `QuoVadis.session_idle_timeout`.
+
+A user can view their active sessions and log out of any of them.
+
+Write the view showing the sessions ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/quo_vadis/sessions/index.html.erb)).  It must be in `app/views/quo_vadis/sessions/index.html.:format`.
+
+
+### Audit trail
+
+An audit trail is kept of authentication events.  You can see the full list in the [`Log`](https://github.com/airblade/quo_vadis/blob/master/app/models/quo_vadis/log.rb) class.
+
+Write the view showing the events ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/quo_vadis/logs/index.html.erb)).  It must be in `app/views/quo_vadis/logs/index.html.:format`.
+
+
+### Notifications
+
+QuoVadis notifies users by email whenever their authentication details are changed or something suspicious happens.
+
+Write the corresponding mailer views:
+
+- change of email ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/quo_vadis/mailer/email_change_notification.text.erb))
+- change of identifier (unless the identifier is email) ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/quo_vadis/mailer/identifier_change_notification.text.erb))
+- change of password ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/quo_vadis/mailer/password_change_notification.text.erb))
+- reset of password ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/quo_vadis/mailer/password_reset_notification.text.erb))
+- TOTP setup ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/quo_vadis/mailer/totp_setup_notification.text.erb))
+- TOTP code used a second time ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/quo_vadis/mailer/totp_reuse_notification.text.erb))
+- 2FA deactivated ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/quo_vadis/mailer/twofa_deactivated_notification.text.erb))
+- recovery codes generated ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/quo_vadis/mailer/recovery_codes_generation_notification.text.erb))
+
+They must be in `app/views/quo_vadis/mailer/NAME.{text,html}.erb`.
+
+
+## Configuration
+
+This is QuoVadis' [default configuration](https://github.com/airblade/quo_vadis/blob/master/lib/quo_vadis/defaults.rb):
+
+```ruby
+QuoVadis.configure do
+  password_minimum_length               12
+  mask_ips                              false
+  cookie_name                           (Rails.env.production? ? '__Host-qv' : 'qv')
+  session_lifetime                      :session
+  session_lifetime_extend_to_end_of_day false
+  session_idle_timeout                  :lifetime
+  password_reset_token_lifetime         10.minutes
+  accounts_require_confirmation         false
+  account_confirmation_token_lifetime   10.minutes
+  mail_headers                          ({ from: 'Example App <support@example.com>' })
+  enqueue_transactional_emails          true
+  app_name                              Rails.app_class.to_s.deconstantize  # for the TOTP QR code
+  two_factor_authentication_mandatory   true
+  mount_point                           '/'
+end
+```
+
+You can override any of it with a similarly structured file in `config/initializers/quo_vadis.rb`.
+
+Here are the options in detail:
+
+__`password_minimum_length`__ (integer)
+
+The minimum number of characters for a password.
+
+__`mask_ips`__ (boolean)
+
+Whether to mask the IP address in the sessions list and the audit trail.
+
+Masking means setting the last octet (IPv4) or the last 80 bits (IPv6) to 0.
+
+__`cookie_name`__ (string)
+
+The name of the cookie QuoVadis uses to store the session identifier.  The `__Host-` prefix is [recommended](https://developer.mozilla.org/en-US/docs/Web/API/document/cookie) in an SSL environment (but cannot be used in a non-SSL environment).
+
+__`session_lifetime`__ (`:session` | `ActiveSupport::Duration` | integer)
+
+The lifetime of a logged-in session.  Use `:session` for the browser session, or a `Duration` or number of seconds.
+
+__`session_lifetime_extend_to_end_of_day`__ (boolean)
+
+Whether to extend the session's lifetime to the end of the day it will expire on.
+
+Set `true` to reduce the chance of a user being logged out while actively using your application.
+
+__`session_idle_timeout`__ (`:lifetime` | `ActiveSupport::Duration` | integer)
+
+The logged-in session is expired if the user isn't seen for this `Duration` or number of seconds.  Use `:lifetime` to set the idle timeout to the session's lifetime (i.e. to turn off the idle timeout).
+
+__`password_reset_token_lifetime`__ (`ActiveSupport::Duration` | integer)
+
+The `Duration` or number of seconds for which a password-reset token is valid.
+
+__`accounts_require_confirmation`__ (boolean)
+
+Whether new users must confirm their account before they can log in.
+
+__`account_confirmation_token_lifetime`__ (`ActiveSupport::Duration` | integer)
+
+The `Duration` or number of seconds for which an account-confirmation token is valid.
+
+__`mail_headers`__ (hash)
+
+Mail headers which QuoVadis' emails should have.
+
+__`enqueue_transactional_emails`__ (boolean)
+
+Set `true` if account-confirmation and password-reset emails should be queued for later delivery (`#deliver_later`) or `false` if they should be sent inline (`#deliver_now`).
+
+__`app_name`__ (string)
+
+Used in the provisioning URI for the TOTP QR code.
+
+__`two_factor_authentication_mandatory`__ (boolean)
+
+Whether users must set up and use a second authentication factor.
+
+__`mount_point`__ (string)
+
+The path prefix for QuoVadis's routes.
+
+For example, the default login path is at `/login`.  If you set `mount_point` to `/auth`, the login path would be `/auth/login`.
+
+#### Rails configuration
+
+__Mailer URLs__
+
+You must also configure the mailer host so URLs are generated correctly in emails:
+
+```ruby
+config.action_mailer.default_url_options: { host: 'example.com' }
+```
+
+__Layouts__
+
+You can specify QuoVadis's controllers' layouts in a `#to_prepare` block in your application configuration.  For example:
+
+```ruby
+# config/application.rb
+module YourApp
+  class Application < Rails::Application
+    config.to_prepare do
+      QuoVadis::ConfirmationsController.layout 'your_layout'
+    end
+  end
+end
+```
 
-* Rails 3 edge's [ActiveModel::SecurePassword](https://github.com/rails/rails/blob/master/activemodel/lib/active_model/secure_password.rb).  It's `has_secure_password` class method is similar to Quo Vadis's `authenticates` class method.
-* [RailsCast 250: Authentication from Scratch](http://railscasts.com/episodes/250-authentication-from-scratch).
+__Routes__
 
+You can set up your post-authentication and post-password-change routes.  If you don't, you must have a root route.  For example:
 
-## What's up with the name?
+```ruby
+# config/routes.rb
+get '/dashboard', to: 'dashboards#show', as: 'after_login'
+get '/profile',   to: 'profiles#show',   as: 'after_password_change'
+```
 
-Roman sentries used to challenge intruders with, "Halt!  Who goes there?"; quo vadis is Latin for "Who goes there?".  At least that's what my Latin teacher told us, but I was 8 years old then so I may not be remembering this entirely accurately.
+### I18n
 
+All QuoVadis' flash messages are set via [i18n](https://github.com/airblade/quo_vadis/blob/master/config/locales/quo_vadis.en.yml).
 
-## Questions, Problems, Feedback
+You can override any of the messages with your own locale file at `config/locales/quo_vadis.en.yml`.
 
-Please use the GitHub [issue tracker](https://github.com/airblade/quo_vadis/issues) or email me.
+If you don't want a specific flash message at all, give the key an empty value in your locale file.
 
 
-## Intellectual property
+## Intellectual Property
 
-Copyright 2011 Andy Stewart (boss@airbladesoftware.com).
+Copyright 2011-2021 Andrew Stewart (boss@airbladesoftware.com).
 
 Released under the MIT licence.