quo_vadis 2.1.10 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f75e1f5d40a86773e5cec5133d3822431d8ed76e581d7e712912481ae56ec29a
-  data.tar.gz: 3789a04b43d20d1c3b4e4aaf6e5c8b88f53c4bc97fce5ee4b546063e1bfa9801
+  metadata.gz: 5e9808f4e29d96b1c9deac895bb45ebacbeb046928f22851fe618593abb49fa4
+  data.tar.gz: 38980863633e441f4c5d28c2fe03e5d8e6357afc4f4ddd4546f4492205aee48c
 SHA512:
-  metadata.gz: ac21c181a2339c6d515ae2c7defe20ced03c103ac9e144ca4edcf3169d0ea4bafa18f4a2011912c611310e0adf5736285f7d8b2dff5b031468e735940bcbc3b0
-  data.tar.gz: 432bb81c9d8de26a659a718a533579bdd982c4565ae5df96511dc5ec60bf84c4d4665c694e1db9b0837434b6a9d5d43a9db7006b6e278a1b9d1c9d8cf2f54c2e
+  metadata.gz: cb68d8909ca3343ed508dbe5c0510860a358cb39398d2bb5b91f999c6a74935e8bb09d41a27de5bcdc1a3061cb280865ce146fa168fa88690fc37f030cd83a78
+  data.tar.gz: 6b5e022eab6f659dd4620117595c9ff9b9527f532d6963b732d149db4316f833626cca40f5e89cd7b8071ebea7e87ff64462c71c8104628b033447debec7a2a2

data/CHANGELOG.md

@@ -4,6 +4,20 @@
 ## HEAD
 
 
+## 2.2.0 (17 April 2023)
+
+* Improve the readme with internal links and more section headings.
+* Rename `password_reset_token_lifetime` to `password_reset_otp_lifetime`.
+* Use OTP instead of link for password reset.
+* Rename `account_confirmation_token_lifetime` to `account_confirmation_otp_lifetime`.
+* Use OTP instead of link for account confirmation.
+
+
+## 2.1.11 (14 September 2022)
+
+* Introduce common controller superclass.
+
+
 ## 2.1.10 (14 September 2022)
 
 * Enable configuration of mailer superclass.

data/README.md

@@ -1,6 +1,6 @@
 # Quo Vadis
 
-Multifactor authentication for your Rails 6 or Rails 7 app.
+Multifactor authentication for your Rails app (Rails 7 and Rails 6).
 
 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).
 
@@ -23,8 +23,8 @@ Simple to integrate into your application.  The main task is customising the exa
 - 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.
+- Account confirmation (a.k.a. email verification) (optional).
+- OTPs (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.
@@ -86,7 +86,7 @@ end
 
 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`.
 
-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`.
+If you want to change an existing password, use the [Change Password](#change-password) feature.  If you update a model (that already has a password) with a `:password` attribute, it will raise a `QuoVadis::PasswordExistsError`.
 
 The minimum password length is configured by `QuoVadis.password_minimum_length` (12 by default).
 
@@ -95,7 +95,7 @@ The minimum password length is configured by `QuoVadis.password_minimum_length`
 
 You can use these methods in your controllers.
 
-__`require_password_authentication`__
+#### `require_password_authentication`
 
 Use this to restrict actions to password-authenticated users.  It is aliased to `:require_authentication` for convenience.
 
@@ -105,7 +105,7 @@ class FoosController < ApplicationController
 end
 ```
 
-__`require_two_factor_authentication`__
+#### `require_two_factor_authentication`
 
 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.)
 
@@ -115,21 +115,17 @@ class BarsController < ApplicationController
 end
 ```
 
-__`login(model, browser_session = true)`__
+#### `login(model, browser_session = true, metadata: {})`
 
-To log in a user who has authenticated with a password, call `#login(model, browser_session = true, metadata: {})`.  For the `browser_session` argument, optionally 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).  Any metadata are stored in the log entry for the login.
+Use this to log in a user who has authenticated with a password.  For the optional `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).  Any metadata are stored in the log entry for the login.
 
-__`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`__
+#### `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?`__
+#### `logged_in?`
 
 Call this to find out whether a user has authenticated with a password.
 
@@ -175,7 +171,7 @@ Your new user sign-up form ([example](https://github.com/airblade/quo_vadis/blob
 - 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).
+In your controller, use the [`#login`](#loginmodel-browser_session-%3D-true) method to log in your new user.  The optional second argument specifies for how long the user should be logged in, and any metadata you supply is logged in the audit log.
 
 After logging in the user, redirect them wherever you like.  You can use `qv.path_after_signup` which resolves to the first of these routes that exists: `:after_signup`, `:after_login`, the root route.
 
@@ -207,60 +203,19 @@ get '/dashboard', as: 'after_login'
 
 ### Sign up with account confirmation
 
-Here's the workflow:
+Follow the steps above for sign-up.
 
-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.
+After you have logged in the user and redirected them (to any page which requires being logged in), QuoVadis detects that they need to confirm their account.  QuoVadis emails them a 6-digit confirmation code and redirects them to the confirmation page where they can enter that code.
 
-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:
+The confirmation code is valid for `QuoVadis.account_confirmation_otp_lifetime`.
 
-- a `:password` field;
-- optionally a `:password_confirmation` field;
-- a field for their identifier;
-- an `:email` field if the identifier is not their email.
+Once the user has confirmed their account, they will be redirected to `qv.path_after_signup` which resolves to the first of these routes that exists: `:after_signup`, `:after_login`, the root route.  Add whichever works best for you.
 
-In your controller, call `#request_confirmation`:
+You need to write the email view ([example](https://github.com/airblade/quo_vadis/blob/master/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 `@otp` variable.  See the [Configuration](#configuration) section for how to set QuoVadis's emails' from addresses, headers, etc.
 
-```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
+Now write the confirmation page where the user types in the confirmation code from the email ([example](https://github.com/airblade/quo_vadis/blob/master/app/views/quo_vadis/confirmations/new.html.erb)).  It must be in `app/views/quo_vadis/confirmations/new.html.:format` and must POST the `otp` field to `confirm_path`.  You can provide a button to send a new confirmation code (perhaps the original email didn't arrive, or the user didn't have time to act on it before it expired) – it should POST to `send_confirmation_path`.
 
-  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/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/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/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/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/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 `qv.path_after_signup` which resolves to the first of these routes that exists: `:after_signup`, `:after_login`, the root route.
-
-So add whichever works best for you.
+If the user closes their browser after signing up but before they have confirmed their account, when they next access a page which requires being logged in they will be sent a new confirmation code and redirected to the confirmation page, as if they had just signed up.
 
 
 ### Login
@@ -334,31 +289,27 @@ A successful password change logs out any other sessions the user has (e.g. on o
 
 ### Reset password
 
-The user can reset their password if they lose it.  The flow is:
+The user can reset their password if they lose it and cannot log in.  The flow is:
 
 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.
+2. QuoVadis emails the user a 6-digit reset code, which is valid for `QuoVadis.password_reset_otp_lifetime`, and redirects to the password-reset page.
+3. [The email] The user reads the code.
+4. [Password-reset page] The user enters the 6-digt code and their new password and clicks the save button.
 5. QuoVadis sets the user's password and logs them in.
 
-First, write the page where the user requests a password-reset ([example](https://github.com/airblade/quo_vadis/blob/master/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).
+First, write the page where the user requests a password-reset ([example](https://github.com/airblade/quo_vadis/blob/master/app/views/quo_vadis/password_resets/new.html.erb)).  It must be in `app/views/quo_vadis/password_resets/new.html.:format`.  It must POST the user's identifier (not email, unless the identifier is email) to `password_reset_path`.
 
-See the Configuration section below for how to set QuoVadis's emails' from addresses, headers, etc.
+Now write the email view ([example](https://github.com/airblade/quo_vadis/blob/master/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 `@otp` variable.  See the [Configuration](#configuration) section 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/app/views/quo_vadis/password_resets/index.html.erb)).  It must be in `app/views/quo_vadis/password_resets/index.html.:format`.
-
-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/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/app/views/quo_vadis/password_resets/edit.html.erb)).  It must be in `app/views/quo_vadis/password_resets/edit.html.:format`.
+Now write the page where the user types in the reset code from the email and their new password ([example](https://github.com/airblade/quo_vadis/blob/master/app/views/quo_vadis/password_resets/edit.html.erb)).  It must be in `app/views/quo_vadis/password_resets/edit.html.:format` and must PUT the `otp`, `password`, and `password_confirmation` fields to `password_reset_path`.
 
 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.
 
+When the user resets their password, they are logged out of any other sessions they may have, for example on other devices.
+
 
 ### Sessions
 
@@ -411,9 +362,9 @@ QuoVadis.configure do
   session_lifetime                      :session
   session_lifetime_extend_to_end_of_day false
   session_idle_timeout                  :lifetime
-  password_reset_token_lifetime         10.minutes
+  password_reset_otp_lifetime           10.minutes
   accounts_require_confirmation         false
-  account_confirmation_token_lifetime   10.minutes
+  account_confirmation_otp_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
@@ -426,75 +377,75 @@ You can override any of it with a similarly structured file in `config/initializ
 
 Here are the options in detail:
 
-__`password_minimum_length`__ (integer)
+#### `password_minimum_length` (integer)
 
 The minimum number of characters for a password.
 
-__`mask_ips`__ (boolean)
+#### `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)
+#### `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)
+#### `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)
+#### `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)
+#### `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)
+#### `password_reset_otp_lifetime` (`ActiveSupport::Duration` | integer)
 
-The `Duration` or number of seconds for which a password-reset token is valid.
+The `Duration` or number of seconds for which a password-reset code is valid.
 
-__`accounts_require_confirmation`__ (boolean)
+#### `accounts_require_confirmation` (boolean)
 
 Whether new users must confirm their account before they can log in.
 
-__`account_confirmation_token_lifetime`__ (`ActiveSupport::Duration` | integer)
+#### `account_confirmation_otp_lifetime` (`ActiveSupport::Duration` | integer)
 
-The `Duration` or number of seconds for which an account-confirmation token is valid.
+The `Duration` or number of seconds for which an account-confirmation code is valid.
 
-__`mailer_superclass`__ (string)
+#### `mailer_superclass` (string)
 
 The class from which QuoVadis's mailer inherits.
 
-__`mail_headers`__ (hash)
+#### `mail_headers` (hash)
 
 Mail headers which QuoVadis' emails should have.
 
-__`enqueue_transactional_emails`__ (boolean)
+#### `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)
+#### `app_name` (string)
 
 Used in the provisioning URI for the TOTP QR code.
 
-__`two_factor_authentication_mandatory`__ (boolean)
+#### `two_factor_authentication_mandatory` (boolean)
 
 Whether users must set up and use a second authentication factor.
 
-__`mount_point`__ (string)
+#### `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
+### Rails configuration
 
-__Mailer URLs__
+#### Mailer URLs
 
 You must also configure the mailer host so URLs are generated correctly in emails:
 
@@ -502,7 +453,7 @@ You must also configure the mailer host so URLs are generated correctly in email
 config.action_mailer.default_url_options: { host: 'example.com' }
 ```
 
-__Layouts__
+#### Layouts
 
 You can specify QuoVadis's controllers' layouts in a `#to_prepare` block in your application configuration.  For example:
 
@@ -517,7 +468,7 @@ module YourApp
 end
 ```
 
-__Routes__
+#### Routes
 
 You can set up your post-signup, post-authentication, and post-password-change routes.  If you don't, you must have a root route.  For example:
 

data/app/controllers/quo_vadis/confirmations_controller.rb

@@ -1,101 +1,66 @@
 # frozen_string_literal: true
 
 module QuoVadis
-  class ConfirmationsController < ApplicationController
+  class ConfirmationsController < QuoVadisController
 
-    # holding page
-    def index
+    def new
       @account = find_pending_account_from_session
-    end
 
-
-    # form for requesting new confirmation email
-    def new
+      unless @account
+        redirect_to qv.path_after_signup, alert: QuoVadis.translate('flash.confirmation.unknown')
+      end
     end
 
 
-    # send new confirmation email form submits here
     def create
-      account = QuoVadis.find_account_by_identifier_in_params params
+      @account = find_pending_account_from_session
 
-      unless account
-        redirect_to new_confirmation_path, alert: QuoVadis.translate('flash.confirmation.identifier') and return
+      unless @account
+        redirect_to qv.path_after_signup, alert: QuoVadis.translate('flash.confirmation.unknown')
+        return
       end
 
-      request_confirmation account.model
-      redirect_to confirmations_path
-    end
+      expiry = session[:account_confirmation_expires_at]
 
-
-    # emailed confirmation link points here
-    def edit
-      account = AccountConfirmationToken.find_account params[:token]
-
-      unless account  # expired or already confirmed
-        redirect_to new_confirmation_path, alert: QuoVadis.translate('flash.confirmation.unknown') and return
+      if Time.current.to_i > expiry
+        redirect_to confirm_path, alert: QuoVadis.translate('flash.confirmation.expired')
+        return
       end
-    end
 
+      confirmed = @account.confirm(params[:otp], expiry)
 
-    # confirm the account (and login)
-    def update
-      account = AccountConfirmationToken.find_account params[:token]
-
-      unless account  # expired or already confirmed
-        redirect_to new_confirmation_path, alert: QuoVadis.translate('flash.confirmation.unknown') and return
+      if !confirmed
+        redirect_to confirm_path, alert: QuoVadis.translate('flash.confirmation.invalid')
+        return
       end
 
-      account.confirmed!
-      qv.log account, Log::ACCOUNT_CONFIRMATION
+      qv.log @account, Log::ACCOUNT_CONFIRMATION
 
       session.delete :account_pending_confirmation
+      session.delete :account_confirmation_expires_at
 
-      login account.model, true
       redirect_to qv.path_after_signup, notice: QuoVadis.translate('flash.confirmation.confirmed')
     end
 
 
-    def edit_email
-      account = find_pending_account_from_session
-
-      unless account
-        redirect_to confirmations_path, alert: QuoVadis.translate('flash.confirmation.unknown') and return
-      end
-
-      @email = account.model.email
-    end
-
-
-    def update_email
-      account = find_pending_account_from_session
-
-      unless account
-        redirect_to confirmations_path, alert: QuoVadis.translate('flash.confirmation.unknown') and return
-      end
-
-      account.model.update email: params[:email]
-
-      request_confirmation account.model
-      redirect_to confirmations_path
-    end
-
-
     def resend
-      account = find_pending_account_from_session
+      @account = find_pending_account_from_session
 
-      unless account
-        redirect_to confirmations_path, alert: QuoVadis.translate('flash.confirmation.unknown') and return
+      unless @account
+        redirect_to qv.path_after_signup, alert: QuoVadis.translate('flash.confirmation.unknown')
       end
 
-      request_confirmation account.model
-      redirect_to confirmations_path
+      qv.request_confirmation @account.model
+      redirect_to confirm_path, notice: QuoVadis.translate('flash.confirmation.sent')
     end
 
 
     private
 
     def find_pending_account_from_session
-      Account.find(session[:account_pending_confirmation]) if session[:account_pending_confirmation]
+      if session[:account_pending_confirmation]
+        Account.unconfirmed.find(session[:account_pending_confirmation])
+      end
     end
 
   end

data/app/controllers/quo_vadis/logs_controller.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module QuoVadis
-  class LogsController < ApplicationController
+  class LogsController < QuoVadisController
     before_action :require_password_authentication
 
     PER_PAGE = 25

data/app/controllers/quo_vadis/password_resets_controller.rb

@@ -1,68 +1,100 @@
 # frozen_string_literal: true
 
 module QuoVadis
-  class PasswordResetsController < ApplicationController
-
-    # holding page for after the create action
-    def index
-    end
-
+  class PasswordResetsController < QuoVadisController
 
+    # form where user enters their identifier
     def new
     end
 
 
+    # generate and email an otp
     def create
       account = QuoVadis.find_account_by_identifier_in_params params
 
-      if account
-        token = QuoVadis::PasswordResetToken.generate account
-        QuoVadis.deliver :reset_password, {email: account.model.email, url: quo_vadis.password_reset_url(token)}
+      # The recommendation is to show the user the same message whether
+      # or not their account was found.  This favours privacy over
+      # helpfulness and is the default.
+      #
+      # If you would prefer helpfulness over privacy -- perhaps the user
+      # simply typo'd their identifier -- set the `unknown` flash message
+      # to something helpful.
+      message_known   = QuoVadis.translate('flash.password_reset.create')
+      message_unknown = QuoVadis.translate('flash.password_reset.unknown')
+
+      if message_known == message_unknown
+        flash[:notice] = message_known
+      elsif account
+        flash[:notice] = message_known
+      else
+        flash[:alert] = message_unknown
       end
 
-      redirect_to password_resets_path, notice: QuoVadis.translate('flash.password_reset.create')
-    end
+      if account
+        session[:account_resetting_password] = account.id
 
+        expiration = QuoVadis.password_reset_otp_lifetime.from_now.to_i
+        session[:password_reset_expires_at] = expiration
 
-    # emailed password-reset link points here
-    def edit
-      account = PasswordResetToken.find_account params[:token]
+        otp = account.otp_for_password_reset(expiration)
 
-      unless account  # expired or password already changed
-        redirect_to new_password_reset_path, alert: QuoVadis.translate('flash.password_reset.unknown') and return
+        QuoVadis.deliver :reset_password, {email: account.model.email, otp: otp}
       end
 
-      # Ensure the flash notice set in the create action does not appear when the user clicks the
-      # link in the email they were sent.
-      flash.delete :notice
+      redirect_to edit_password_reset_path
+    end
+
 
+    # form for otp and new password
+    def edit
       @password = QuoVadis::Password.new
     end
 
 
-    # really reset the password
+    # update password if otp and password are valid
     def update
-      account = PasswordResetToken.find_account params[:token]
+      account = find_account_resetting_password_from_session
 
-      unless account  # expired or password already changed
-        redirect_to new_password_reset_path, alert: QuoVadis.translate('flash.password_reset.unknown') and return
+      unless account
+        redirect_to new_password_reset_path
+        return
       end
 
-      @password = account.password
-      if @password.reset params[:password][:password], params[:password][:password_confirmation]
-        # Logout account's sessions because password has changed.
-        # Note model is not logged in here.
-        @password.account.sessions.destroy_all
+      expiry = session[:password_reset_expires_at]
 
-        qv.log @password.account, Log::PASSWORD_RESET
-        QuoVadis.notify :password_reset_notification, email: @password.account.model.email
+      if Time.current.to_i > expiry
+        redirect_to new_password_reset_path, alert: QuoVadis.translate('flash.password_reset.expired')
+        return
+      end
 
-        login @password.account.model, true
-        redirect_to qv.path_after_authentication, notice: QuoVadis.translate('flash.password_reset.reset')
-      else
+      unless account.verify_password_reset(params[:password][:otp], expiry)
+        redirect_to new_password_reset_path, alert: QuoVadis.translate('flash.password_reset.invalid')
+        return
+      end
+
+      @password = account.password
+      unless @password.reset(params[:password][:password], params[:password][:password_confirmation])
         render :edit, status: :unprocessable_entity
+        return
       end
+
+      session.delete :account_resetting_password
+      session.delete :password_reset_expires_at
+
+      qv.log account, Log::PASSWORD_RESET
+      QuoVadis.notify :password_reset_notification, email: account.model.email
+
+      login account.model, true
+
+      redirect_to qv.path_after_authentication, notice: QuoVadis.translate('flash.password_reset.reset')
     end
 
+    private
+
+    def find_account_resetting_password_from_session
+      if session[:account_resetting_password]
+        Account.find(session[:account_resetting_password])
+      end
+    end
   end
 end

data/app/controllers/quo_vadis/passwords_controller.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module QuoVadis
-  class PasswordsController < ApplicationController
+  class PasswordsController < QuoVadisController
 
     before_action :require_authentication
 

data/app/controllers/quo_vadis/quo_vadis_controller.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module QuoVadis
+  class QuoVadisController < ApplicationController
+  end
+end

data/app/controllers/quo_vadis/recovery_codes_controller.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module QuoVadis
-  class RecoveryCodesController < ApplicationController
+  class RecoveryCodesController < QuoVadisController
     before_action :require_password_authentication