rodauth 1.21.0 → 2.2.0

data/doc/release_notes/2.1.0.txt

@@ -0,0 +1,31 @@
+= New Features
+
+* A check_csrf configuration method has been added for checking
+  the CSRF token.  This is useful in cases where the CSRF protection
+  is provided by something other than the Roda route_csrf plugin.
+
+= Other Improvements
+
+* When using the http_basic_auth feature, logged_in? now checks for
+  Basic authentication if the session is not already authenticated
+  and Basic authentication has not yet been checked.  This increases
+  compatibility for applications that were using the http_basic_auth
+  feature in Rodauth 1.
+
+* When creating accounts, the password field now correctly uses the
+  new-password autocomplete attribute instead of the current-password
+  autocomplete attribute.
+
+* When using the jwt feature, Rodauth no longer checks CSRF tokens
+  in requests to Rodauth routes if the request submitted is a JSON
+  request, includes a JWT, or Rodauth has been configured in JSON-only
+  mode.
+
+* When using the verify_account_grace_period feature, if there is an
+  unverified account without a password, do not consider the account
+  open.  Attempting to login into the account in such a case now
+  shows a message letting the user know to verify the account.
+
+* The json_response_body configuration method is now used consistently
+  in the jwt feature for all JSON responses.  Previously, there were
+  some cases that did not use it.

data/doc/release_notes/2.2.0.txt

@@ -0,0 +1,39 @@
+= New Features
+
+* When using the jwt_refresh feature, you can remove the current
+  refresh token when logging out by submitting the refresh token
+  in the logout request, the same as when submitting the refresh
+  token to obtain a new refresh token.  You can also use a value
+  of "all" instead of the refresh token to remove all refresh
+  tokens when logging out.
+
+* A rodauth.otp_last_use method has been added to the otp feature,
+  allowing you to determine when the otp was last used.
+
+= Other Improvements
+
+* When using multifactor authentication, rodauth.authenticated? and
+  rodauth.require_authentication now cache values in the session and
+  do not perform queries every time they are called.
+
+* Many guides for common scenarios have been added to the
+  documentation.  These augment Rodauth's existing comprehensive
+  feature documentation, which is aimed to be more of a reference
+  and less of a guide.
+
+* When the verify_account_grace_period and email_auth features are
+  used with a multifactor authentication feature, and the
+  verify_account_set_password? configuration method is set to true,
+  Rodauth no longer raises a NoMethodError when checking if the
+  session was authenticated.
+
+* In the verify_account feature, if verify_account_email_resend
+  returns false indicating no email was sent, an error message
+  is now used, instead of a success message.
+
+* In the password_complexity feature, the password_dictionary
+  configuration method was previously ignored if the default
+  password dictionary file existed.
+
+* Rodauth and all features that ship with it now have 100% branch
+  coverage.

data/doc/remember.rdoc

@@ -1,99 +1,75 @@
 = Documentation for Remember Feature
 
-The remember feature allows for token-based autologin for users. It records
-which sessions were autologged in via a token, and allows you to request
-password confirmation later for such sessions if they are accessing a
-section requiring more security.  The remember feature depends on the
-logout feature.
+The remember feature allows for token-based autologin for users. Calling
++rodauth.remember_login+ for an authenticated session will create a token for
+the current account and store it in a cookie. You can then add the following
+code to your routing block to automatically login users from that token if the
+session has expired:
+
+  rodauth.load_memory
 
 By default, the remember feature just supports a form that the user can use
 to change their remember settings for the current browser.  They can either
 enable remembering for the browser, forget it for the browser, or disable
 it completely so that any remembering for other browsers is removed as well.
 
-In some cases, you may want to force remembering on users if you don't want
-to force them to turn it on manually.  For example, if you want to force
-remembering on login, you can do that via:
+In some cases, you may want to automatically remember users and not require
+users to turn it on manually.  If you want to automatically remember users
+on login:
 
   after_login do
     remember_login
   end
 
+The remember feature records which sessions were autologged in via the
+remember cookie. If you have sections where you want to add more security,
+you can use the confirm password feature to request password authentication
+for sessions autologged in via a remember token:
+
+  rodauth.require_password_authentication
+
 == Auth Value Methods
 
-extend_remember_deadline? :: Whether to extend the remember token deadline
-                             when the user is autologged in via token.
-raw_remember_token_deadline :: A deadline before which to allow a raw remember
-                               token to be used. Allows for graceful transition
-                               for when +hmac_secret+ is first set.
-remember_additional_form_tags :: HTML fragment containing additional
-                                 form tags to use on the change remember 
-                                 setting form.
+extend_remember_deadline? :: Whether to extend the remember token deadline when the user is autologged in via remember token.
+raw_remember_token_deadline :: A deadline before which to allow a raw remember token to be used. Allows for graceful transition for when +hmac_secret+ is first set.
+remember_additional_form_tags :: HTML fragment containing additional form tags to use on the change remember setting form.
 remember_button :: The text to use for the change remember settings button.
 remember_cookie_key :: The cookie name to use for the remember token.
 remember_cookie_options :: Any options to set for the remember cookie.
-remember_deadline_column :: The column name in the remember keys table storing
-                            the deadline after which the token will be
-                            ignored.
-remember_deadline_interval :: The amount of time for which to remember accounts,
-                              14 days by default.  Only used if set_deadline_values?
-                              is true.
+remember_deadline_column :: The column name in the +remember_table+ storing the deadline after which the token will be ignored.
+remember_deadline_interval :: The amount of time for which to remember accounts, 14 days by default.  Only used if +set_deadline_values?+ is true.
 remember_disable_label :: The label for disabling remembering.
 remember_disable_param_value :: The parameter value for disabling remembering.
-remember_error_flash :: The flash error to show if there is an error changing a
-                        remember setting.
+remember_error_flash :: The flash error to show if there is an error changing a remember setting.
 remember_forget_label :: The label for turning off remembering.
 remember_forget_param_value :: The parameter value for turning off remembering.
-remember_id_column :: The id column in the remember keys table, should be a
-                      foreign key referencing the accounts table.
-remember_key_column :: The remember key/token column in the remember keys table.
-remember_notice_flash :: The flash notice to show after remember setting
-                         has been updated.
-remember_period :: The additional time to extend the remember deadline if
-                   extending remember deadlines.
+remember_id_column :: The id column in the +remember_table+, should be a foreign key referencing the accounts table.
+remember_key_column :: The remember key/token column in the +remember_table+.
+remember_notice_flash :: The flash notice to show after remember setting has been updated.
+remember_page_title :: The page title to use on the change remember settings form.
+remember_param :: The parameter name to use for the remember password settings choice.
+remember_period :: The additional time to extend the remember deadline if extending remember deadlines.
 remember_redirect :: Where to redirect after changing the remember settings.
-remember_remember_param_value :: The parameter value for switching on remembering.
 remember_remember_label :: The label for turning on remembering.
-remember_route :: The route to the change remember settings action. Defaults to
-                  +remember+.
+remember_remember_param_value :: The parameter value for switching on remembering.
+remember_route :: The route to the change remember settings action. Defaults to +remember+.
 remember_table :: The name of the remember keys table.
-remember_param :: The parameter name to use for the remember password settings
-                  choice.
-remembered_session_key :: The key in the session storing whether the current
-                          session has been autologged in via remember token.
 
 == Auth Methods
 
-add_remember_key :: Add a remember key for the current account to the remember
-                    keys table.
-after_load_memory :: Run arbitrary code after autologging in an account via
-                     a remember token.
+add_remember_key :: Add a remember key for the current account to the remember keys table.
+after_load_memory :: Run arbitrary code after autologging in an account via a remember token.
 after_remember :: Run arbitrary code after changing the remember settings.
-before_load_memory :: Run arbitrary code before autologging in an account via
-                      a remember token.
+before_load_memory :: Run arbitrary code before autologging in an account via a remember token.
 before_remember :: Run arbitrary code before changing the remember settings.
 before_remember_route :: Run arbitrary code before handling the remember route.
-clear_remembered_session_key :: Clear the flag for whether the current
-                                account was autologged in via token, called
-                                after successful password confirmation.
-disable_remember_login :: Disable the remember key token, clearing the token
-                          from the database so future connections with the
-                          token will not be recognized.
-forget_login :: Forget the current remember token, deleting the related cookie.
-                Other browsers that have the cookie cached can still use it
-                login.
+disable_remember_login :: Disable the remember key token, clearing the token from the database so future connections with the token will not be recognized.
+forget_login :: Forget the current remember token, deleting the related cookie.  Other browsers that have the cookie cached can still use it login.
 generate_remember_key_value :: A random string to use as the remember key.
 get_remember_key :: Retrieve the remember key from the database.
-load_memory :: If the remember key cookie is included in the request, and the
-               user is not currently logged in, check the remember keys table
-               and autologin the user if the remember key cookie matches the
-               current remember key for the account. This method needs to be
-               called manually inside the Roda route block to autologin users.
-logged_in_via_remember_key? :: Whether the current session was logged in via
-                               a remember key.
+load_memory :: If the remember key cookie is included in the request, and the user is not currently logged in, check the remember keys table and autologin the user if the remember key cookie matches the current remember key for the account. This method needs to be called manually inside the Roda route block to autologin users.
+logged_in_via_remember_key? :: Whether the current session was logged in via a remember key.
 remember_key_value :: The current value of the remember key/token.
-remember_login :: Set the cookie containing the remember token, so that future
-                  sessions will be autologged in.
+remember_login :: Set the cookie containing the remember token, so that future sessions will be autologged in.
 remember_view :: The HTML to use for the change remember settings form.
-remove_remember_key(id_value=account_id) :: Delete the related remember key from
-                                            the database.
+remove_remember_key(id_value=account_id) :: Delete the related remember key from the database.

data/doc/reset_password.rdoc

@@ -10,26 +10,29 @@ the login feature.
 
 no_matching_reset_password_key_error_flash :: The flash error message to show if attempting to access the reset password form with an invalid key.
 reset_password_additional_form_tags :: HTML fragment containing additional form tags to use on the reset password form.
-reset_password_autologin? :: Whether to autologin the user after successfully resetting a password.
+reset_password_autologin? :: Whether to autologin the user after successfully resetting a password, false by default.
 reset_password_button :: The text to use for the reset password button.
-reset_password_deadline_column :: The column name in the reset password keys table storing the deadline after which the token will be ignored.
-reset_password_deadline_interval :: The amount of time for which to allow users to reset their passwords, 1 day by default. Only used if set_deadline_values? is true.
+reset_password_deadline_column :: The column name in the +reset_password_table+ storing the deadline after which the token will be ignored.
+reset_password_deadline_interval :: The amount of time for which to allow users to reset their passwords, 1 day by default. Only used if +set_deadline_values?+ is true.
+reset_password_email_last_sent_column :: The email last sent column in the +reset_password_table+. Set to nil to always send a reset password email when requested.
 reset_password_email_recently_sent_error_flash :: The flash error to show if not sending reset password email because one has been sent recently.
 reset_password_email_recently_sent_redirect :: Where to redirect if not sending reset password email because one has been sent recently.
 reset_password_email_sent_notice_flash :: The flash notice to show after a reset password email has been sent.
 reset_password_email_sent_redirect :: Where to redirect after sending a reset password email.
 reset_password_email_subject :: The subject to use for reset password emails.
 reset_password_error_flash :: The flash error to show after resetting a password.
-reset_password_email_last_sent_column :: The email last sent column in the reset password keys table.  nil by default, so a reset password email is always sent when requested by default.
 reset_password_explanatory_text :: The text to display above the button to request a password reset.
-reset_password_id_column :: The id column in the reset password keys table, should be a foreign key referencing the accounts table.
-reset_password_key_column :: The reset password key/token column in the reset password keys table.
+reset_password_id_column :: The id column in the +reset_password_table+, should be a foreign key referencing the accounts table.
+reset_password_key_column :: The reset password key/token column in the +reset_password_table+.
 reset_password_key_param :: The parameter name to use for the reset password key.
+reset_password_notice_flash :: The flash notice to show after resetting a password.
+reset_password_page_title :: The page title to use on the reset password form.
 reset_password_redirect :: Where to redirect after resetting a password.
 reset_password_request_additional_form_tags :: HTML fragment containing additional form tags to use on the reset password request form.
 reset_password_request_button :: The text to use for the reset password request button.
 reset_password_request_error_flash :: The flash error to show if not able to send a reset password email.
-reset_password_request_link :: The HTML to use for a link to the page to request a password reset.
+reset_password_request_link_text :: The text to use for a link to the page to request a password reset.
+reset_password_request_page_title :: The page title to use on the reset password request form.
 reset_password_request_route :: The route to the reset password request action.  Defaults to +reset-password-request+.
 reset_password_route :: The route to the reset password action. Defaults to +reset-password+.
 reset_password_session_key :: The key in the session to hold the reset password key temporarily.
@@ -45,15 +48,15 @@ before_reset_password :: Run arbitrary code before resetting a password.
 before_reset_password_request :: Run arbitrary code before sending the reset password email.
 before_reset_password_request_route :: Run arbitrary code before handling a reset password request route.
 before_reset_password_route :: Run arbitrary code before handling a reset password route.
-create_reset_password_key :: Add the reset password key data to the database.
 create_reset_password_email :: A Mail::Message for the reset password email.
+create_reset_password_key :: Add the reset password key data to the database.
 get_reset_password_email_last_sent :: Get the last time a reset password email is sent, or nil if there is no last sent time.
 get_reset_password_key(id) :: Get the password reset key for the given account id from the database.
 login_failed_reset_password_request_form :: The HTML to use for a form to request a password reset, shown on the login page after the user tries to login with an invalid password.
 remove_reset_password_key :: Remove the reset password key for the current account, run after successful password reset.
 reset_password_email_body :: The body to use for the reset password email.
 reset_password_email_link :: The link to the reset password form in the reset password email.
-reset_password_key_insert_hash :: The hash to insert into the reset password keys table.
+reset_password_key_insert_hash :: The hash to insert into the +reset_password_table+.
 reset_password_key_value :: The reset password key for the current account.
 reset_password_request_view :: The HTML to use for the reset password request form.
 reset_password_view :: The HTML to use for the reset password form.

data/doc/session_expiration.rdoc

@@ -22,6 +22,7 @@ max_session_lifetime :: The maximum number of seconds since session creation tha
 session_created_session_key :: The session key storing the session creation timestamp.
 session_expiration_default :: Whether to expire sessions that don't have the created at or last activity at timestamps set, true by default.
 session_expiration_error_flash :: The flash error to show if a session expires.
+session_expiration_error_status :: The error status to use when a JSON request is made and the session has expired, 401 by default.
 session_expiration_redirect :: Where to redirect if a session expires.
 session_inactivity_timeout :: The maximum number of seconds allowed since the last activity before the session will be considered invalid.  1800 by default (30 minutes).
 session_last_activity_session_key :: The session key storing the last session activity timestamp.

data/doc/single_session.rdoc

@@ -7,40 +7,31 @@ the stored key by doing:
 
   rodauth.check_single_session
 
-Note that it is not recommended to use this feature unless you
+It is not recommended to use this feature unless you
 have a policy that requires it.  Many users find it useful to
 be able to have multiple concurrent sessions, and restricting
-this ability does not make things more secure.
+this ability does not make things more secure.  You can use the
+active_sessions feature for something with similar behavior but
+that allows for concurrent sessions.
 
-Note that one of the side benefits with this feature is that
+One of the side benefits with this feature is that
 logouts reset the single session key, so attempts to reuse
 the previous session after logout no longer work.
 
 == Auth Value Methods
 
-allow_raw_single_session_key? :: Whether to allow a raw single session key to
-                                 be accepted, should only be enabled for graceful
-                                 transition when +hmac_secret+ is first set.
-single_session_id_column :: The column in the +single_session_table+ containing
-                            the account id.
-single_session_key_column :: The column in the +single_session_table+ containing
-                             the single session key.
-single_session_error_flash :: The flash error to display if the current session
-                              is no longer the active session for the account.
-single_session_redirect :: Where to redirect if the current session is no longer
-                           the active session for the account.
-single_session_session_key :: The session key name to use for storing the single
-                              session key.
+allow_raw_single_session_key? :: Whether to allow a raw single session key to be accepted, should only be enabled for graceful transition when +hmac_secret+ is first set.
+inactive_session_error_status :: The error status to use when a JSON request is made and the session is no longer active, 401 by default.
+single_session_error_flash :: The flash error to display if the current session is no longer the active session for the account.
+single_session_id_column :: The column in the +single_session_table+ containing the account id.
+single_session_key_column :: The column in the +single_session_table+ containing the single session key.
+single_session_redirect :: Where to redirect if the current session is no longer the active session for the account.
+single_session_session_key :: The session key name to use for storing the single session key.
 single_session_table :: The database table storing single session keys.
 
 == Auth Methods
 
-currently_active_session? :: Whether the current session is the active session for
-                             the user.
-no_longer_active_session :: The action to take if the current session is no longer
-                            the active session for the user.
-reset_single_session_key :: Reset the single session key for the user, by default
-                            to a new random key.
-update_single_session_key :: Update the single session key in the current session
-                             and in the database, reflecting that the current
-                             session is the active session for the user.
+currently_active_session? :: Whether the current session is the active session for the user.
+no_longer_active_session :: The action to take if the current session is no longer the active session for the user.
+reset_single_session_key :: Reset the single session key for the user, by default to a new random key.
+update_single_session_key :: Update the single session key in the current session and in the database, reflecting that the current session is the active session for the user.

data/doc/sms_codes.rdoc

@@ -1,8 +1,8 @@
 = Documentation for SMS Codes Feature
 
-The sms codes feature allows 2nd factor authentication via codes provided via
-SMS messages.  It is usually used as a backup if OTP authentication is not available
-or has been locked out, but it can be used as the primary 2nd factor.
+The sms codes feature allows for multifactor authentication via codes provided via
+SMS messages.  It is usually used as a backup if other multifactor authentication is not available
+or has been locked out, but it can be used as the primary multifactor authentication method.
 
 This feature allows users to register their mobile phone number with the system, confirm that
 they can receive SMS messages on the mobile phone number they have registered, request
@@ -21,30 +21,36 @@ you prefer:
 == Auth Value Methods
 
 no_current_sms_code_error_flash :: The flash error to show when going to the SMS authentication page and no current SMS authentication code is available.
-sms_already_setup_error_status :: The response status to use when going to a page to setup SMS authentication if SMS authentication has already been setup, 403 by default.
+sms :: A hash of SMS information for the user, if SMS authentication has been setup.
 sms_already_setup_error_flash :: The flash error to show when going to a page to setup SMS authentication if SMS authentication has already been setup.
+sms_already_setup_error_status :: The response status to use when going to a page to setup SMS authentication if SMS authentication has already been setup, 403 by default.
 sms_already_setup_redirect :: Where to redirect when going to a page to setup SMS authentication if SMS authentication has already been setup.
 sms_auth_additional_form_tags :: HTML fragment containing additional form tags when authenticating via SMS.
-sms_auth_button :: Text to use for button on form to authenticate via SMS.
+sms_auth_button :: Text to use for button on the form to authenticate via SMS.
 sms_auth_code_length :: The length of SMS authentication codes, 6 by default.
+sms_auth_link_text :: The text to use for the link from the multifactor auth page.
+sms_auth_page_title :: The page title to use on the form to authenticate via SMS code.
 sms_auth_redirect :: Where to redirect if SMS authentication is needed.
 sms_auth_route :: The route to the SMS authentication action. Defaults to +sms-auth+.
 sms_code_allowed_seconds :: The number of seconds after an SMS authentication is sent until it is no longer valid, 300 seconds by default.
 sms_code_column :: The column in the +sms_codes_table+ containing the currently valid SMS authentication/confirmation code.
 sms_code_label :: The label for SMS codes.
 sms_code_param :: The parameter name for SMS codes.
+sms_codes_primary? :: Whether SMS codes are a primary multifactor authentication method.  If not, they cannot be setup unless multifactor authentication has already been setup.
 sms_codes_table :: The name of the table storing SMS code data.
-sms_codes_primary? :: Whether SMS codes are the primary 2nd factor authentication method, true by default if not using the otp feature.
 sms_confirm_additional_form_tags :: HTML fragment containing additional form tags when confirming SMS setup.
-sms_confirm_button :: Text to use for button on form to confirm SMS setup.
+sms_confirm_button :: Text to use for button on the form to confirm SMS setup.
 sms_confirm_code_length :: The length of SMS confirmation codes, 12 by default, as there is no lockout. 
 sms_confirm_notice_flash :: The flash notice to show when SMS authentication setup has been confirmed.
-sms_confirm_redirect ::Where to redirect after SMS authentication setup has been confirmed.
+sms_confirm_page_title :: The page title to use on the form to authenticate via SMS code.
+sms_confirm_redirect :: Where to redirect after SMS authentication setup has been confirmed.
 sms_confirm_route :: The route to the SMS setup confirmation action. Defaults to +sms-confirm+.
 sms_disable_additional_form_tags :: HTML fragment containing additional form tags when disabling SMS authentication.
-sms_disable_button :: Text to use for button on form to disable SMS authentication.
+sms_disable_button :: Text to use for button on the form to disable SMS authentication.
 sms_disable_error_flash :: The flash error to show when disabling SMS authentication fails.
+sms_disable_link_text :: The text to use for the remove link from the multifactor manage page.
 sms_disable_notice_flash :: The flash notice to show when SMS authentication has been successfully disabled.
+sms_disable_page_title :: The page title to use on the form to disable SMS authentication.
 sms_disable_redirect :: Where to redirect after SMS authentication has been disabled.
 sms_disable_route :: The route to the SMS authentication disable action. Defaults to +sms-disable+.
 sms_failure_limit :: The number of failures until SMS authentication is locked out.
@@ -57,23 +63,27 @@ sms_invalid_phone_message :: The error message to show when an invalid SMS phone
 sms_issued_at_column :: The column in the +sms_codes_table+ containing the time the SMS code was issued.
 sms_lockout_error_flash :: The flash error to show when SMS authentication has been locked out due to repeated failures.
 sms_lockout_redirect :: Where to redirect after SMS authentication has been locked out.
-sms_needs_confirmation_error_status :: The response status to use on SMS authentication pages when SMS authentication setup needs confirmation, 403 by default.
 sms_needs_confirmation_error_flash :: The flash error to show on SMS authentication pages when SMS authentication setup needs confirmation.
+sms_needs_confirmation_error_status :: The response status to use on SMS authentication pages when SMS authentication setup needs confirmation, 403 by default.
 sms_needs_confirmation_redirect :: Where to redirect after SMS setup, when confirmation is required.
 sms_needs_setup_redirect :: Where to redirect if going to an SMS authentication page when SMS authentication has not been setup.
 sms_not_setup_error_flash :: The flash error to show when on SMS authentication pages when SMS authentication has not yet been setup.
 sms_phone_column :: The column in the +sms_codes_table+ containing the phone number to which to send SMS messages.
+sms_phone_input_type :: The input type to use for SMS phone numbers, tel by default.
 sms_phone_label :: The label for SMS phone numbers.
 sms_phone_min_length :: The minimum length of phone numbers allowed for SMS authentication, 7 by default.
 sms_phone_param :: The parameter name for SMS phone numbers.
 sms_request_additional_form_tags :: HTML fragment containing additional form tags when requesting an SMS authentication code.
-sms_request_button :: Text to use for button on form to request an SMS authentication code.
+sms_request_button :: Text to use for button on the form to request an SMS authentication code.
 sms_request_notice_flash :: The flash notice to show when an SMS authentication code is requested.
+sms_request_page_title :: The page title to use on the form to request an SMS authentication code.
 sms_request_redirect :: Where to redirect after requesting an SMS authentication code.
 sms_request_route :: The route to the SMS authentication code request action. Defaults to +sms-request+.
 sms_setup_additional_form_tags :: HTML fragment containing additional form tags when setting up SMS authentication.
-sms_setup_button :: Text to use for button on form to setup SMS authentication.
+sms_setup_button :: Text to use for button on the form to setup SMS authentication.
 sms_setup_error_flash :: The flash error to show when setting up SMS authentication fails.
+sms_setup_link_text :: The text to use for the setup link from the multifactor manage page.
+sms_setup_page_title :: The page title to use on the form to setup SMS authentication.
 sms_setup_route :: The route to the SMS authentication setup action. Defaults to +sms-setup+.
 
 == Auth Methods
@@ -111,10 +121,10 @@ sms_new_auth_code :: A new SMS authentication code that can be used for the acco
 sms_new_confirm_code :: A new SMS confirmation code that can be used for the account.
 sms_normalize_phone(phone) :: A normalized version of the given phone number, by default removing everything except 0-9.
 sms_record_failure :: Record an SMS authentication failure for the current account.
-sms_remove_failures :: Reset the SMS authentication failure counter for the current account, used after a successful SMS authentication.
+sms_remove_failures :: Reset the SMS authentication failure counter for the current account, used after a successful multifactor authentication.
 sms_request_view :: The HTML to use for the form to request an SMS authentication code.
 sms_send(phone, message) :: Send the given message to the given phone number via SMS.  By default a NotImplementedError is raised, this is the only method that must be overridden. 
-sms_set_code(code) :: Set the SMS authentication code for the current account to the given code.  The code can be +nil+ to specify that no SMS authentication code is currently valid.
+sms_set_code(code) :: Set the SMS authentication code for the current account to the given code.  The code can be nil to specify that no SMS authentication code is currently valid.
 sms_setup :: Setup SMS authentication for the current account.
 sms_setup? :: Whether SMS authentication has been setup and confirmed for the current account.
 sms_setup_view :: The HTML to use for the form to setup SMS authentication.

data/doc/two_factor_base.rdoc

@@ -1,30 +1,68 @@
 = Documentation for Two Factor Base Feature
 
-The two factor base feature implements shared functionality for the other 2nd
-factor authentication features.
+The two_factor_base feature implements shared functionality for the other
+multifactor authentication features.
+
+To handle multiple and potentially different multifactor authentication setups
+per user, this feature implements disambiguation pages for multifactor
+authentication and manage.  If only a single multifactor authentication is
+available to setup, the manage page will redirect to the appropriate page.
+Likewise, if only a single multifactor authentication method is available,
+the authentication page will redirect to the appropriate page.  Otherwise,
+the authentication and manage pages will show links to the available pages.
+Additionally, there is a separate page for disabling all multifactor
+authentication methods and reverting to single factor authentication,
+so users do not have to disable each multifactor authentication method
+individually.
 
 == Auth Value Methods
 
-two_factor_already_authenticated_error_status :: The response status to use if going to a two factor authentication page when already authenticated via 2nd factor, 403 by default.
-two_factor_already_authenticated_error_flash :: The flash error to show if going to a two factor authentication page when already authenticated via 2nd factor.
-two_factor_already_authenticated_redirect :: Where to redirect if going to a two factor authentication page when already authenticated via 2nd factor.
-two_factor_auth_notice_flash :: The flash notice to show after a successful two factor authentication.
-two_factor_auth_redirect :: Whether to redirect after a successful two factor authentication.
-two_factor_auth_required_redirect :: Where to redirect if going to a page requiring two factor authentication when not authenticated via 2nd factor.
-two_factor_modifications_require_password? :: Whether modifications to two factor authentication require the use of passwords.
-two_factor_need_authentication_error_status :: The response status to use if going to a page that requires two factor authentication when not authenticated, 401 by default.
-two_factor_need_authentication_error_flash :: The flash error to show if going to a page that requires two factor authentication when not authenticated.
-two_factor_need_setup_redirect :: Where to redirect if going to a two factor authentication page when two factor authentication has not been setup.
-two_factor_not_setup_error_status :: The response status to use if going to a two factor authentication page when two factor authentication has not been setup, 403 by default.
-two_factor_not_setup_error_flash :: The flash error to show if going to a two factor authentication page when two factor authentication has not been setup.
-two_factor_session_key :: The session key used for storing a symbol indicating which type of 2nd factor was used to authenticate.
-two_factor_setup_session_key :: The session key used for storing whether two factor authentication has been setup for the current account.
+two_factor_already_authenticated_error_flash :: The flash error to show if going to a multifactor authentication page when already multifactor authenticated.
+two_factor_already_authenticated_error_status :: The response status to use if going to a multifactor authentication page when already multifactor authenticated, 403 by default.
+two_factor_already_authenticated_redirect :: Where to redirect if going to a multifactor authentication page when already multifactor authenticated.
+two_factor_auth_notice_flash :: The flash notice to show after a successful multifactor authentication.
+two_factor_auth_page_title :: The page title to use on the page linking to other multifactor authentication pages.
+two_factor_auth_redirect :: Where to redirect after a successful multifactor authentication.
+two_factor_auth_redirect_session_key :: The key in the session hash storing the location to redirect to after successful multifactor authentication.
+two_factor_auth_required_redirect :: Where to redirect if going to a page requiring multifactor authentication when not multifactor authenticated (the multifactor auth page by default).
+two_factor_auth_return_to_requested_location? :: Whether to redirect to the originally requested location after successful multifactor authentication when +require_two_factor_authenticated+ was used, false by default.
+two_factor_auth_route :: The route to the multifactor authentication page. Defaults to +multifactor-auth+.
+two_factor_disable_additional_form_tags :: HTML fragment containing additional form tags when disabling all multifactor authentication.
+two_factor_disable_button :: Text to use for button on the form to disable all multifactor authentication.
+two_factor_disable_error_flash :: The flash error to show if unable to disable all multifactor authentication.
+two_factor_disable_link_text :: The text to use for the link to disable all multifactor authentication from the multifactor manage page.
+two_factor_disable_notice_flash :: The flash notice to show after a successfully disabling all multifactor authentication.
+two_factor_disable_page_title :: The page title to use on the page for disabling all multifactor authentication.
+two_factor_disable_redirect :: Where to redirect after a successfully disabling all multifactor authentication.
+two_factor_disable_route :: The route to the page to disable all multifactor authentication. Defaults to +multifactor-disable+.
+two_factor_manage_page_title :: The page title to use on the page linking to other multifactor setup and remove pages.
+two_factor_manage_route :: The route to the page to manage multifactor authentication. Defaults to +multifactor-manage+.
+two_factor_modifications_require_password? :: Whether modifications to multifactor authentication require the inputing the user's password.
+two_factor_need_authentication_error_flash :: The flash error to show if going to a page that requires multifactor authentication when not authenticated.
+two_factor_need_authentication_error_status :: The response status to use if going to a page that requires multifactor authentication when not authenticated, 401 by default.
+two_factor_need_setup_redirect :: Where to redirect if going to a multifactor authentication page when multifactor authentication has not been setup (the multifactor manage page by default).
+two_factor_not_setup_error_flash :: The flash error to show if going to a multifactor authentication page when multifactor authentication has not been setup.
+two_factor_not_setup_error_status :: The response status to use if going to a multifactor authentication page when multifactor authentication has not been setup, 403 by default.
+two_factor_remove_heading :: The HTML to use above the remove links on the multifactor manage page.
+two_factor_setup_heading :: The HTML to use above the setup links on the multifactor manage page.
+two_factor_setup_session_key :: The session key used for storing whether multifactor authentication has been setup for the current account.
 
 == Auth Methods
 
-after_two_factor_authentication :: Any actions to take after successful two factor authentication.
-two_factor_authenticated? :: Whether the current session has already been authenticated via 2nd factor.
-two_factor_remove :: Any action to take to remove two factor authentication, called when closing accounts.
-two_factor_remove_auth_failures :: Any action to take to remove 2nd factor authentication failures, called after a successful 2nd factor authentication.
-two_factor_remove_session :: What actions to take to remove two factor authentication, called when disabling two factor authentication.
-two_factor_update_session(type) :: How to update the session to reflect a successful two factor authentication.
+after_two_factor_authentication :: Any actions to take after successful multifactor authentication.
+after_two_factor_disable :: Any actions to take after successful disabling of all multifactor authentication.
+before_two_factor_auth_route :: Run arbitrary code before handling the multifactor auth route.
+before_two_factor_disable :: Any actions to take before disabling of all multifactor authentication.
+before_two_factor_disable_route :: Run arbitrary code before handling the multifactor disable route.
+before_two_factor_manage_route :: Run arbitrary code before handling the multifactor manage route.
+two_factor_auth_links :: An array of entries for links to show on the multifactor auth page.  Each entry is an array of three elements, sort order (integer), link href, and link text.
+two_factor_auth_view :: The HTML to use for the page linking to other multifactor authentication pages.
+two_factor_authenticated? :: Whether the current session has already been multifactor authenticated.
+two_factor_disable_view :: The HTML to use for the page for disabling all multifactor authentication.
+two_factor_manage_view :: The HTML to use for the page linking to other multifactor setup and remove pages.
+two_factor_remove :: Any action to take to remove multifactor authentication, called when closing accounts.
+two_factor_remove_auth_failures :: Any action to take to remove multifactor authentication failures, called after a successful multifactor authentication.
+two_factor_remove_links :: An array of entries for remove links to show on the multifactor manage page.  Each entry is an array of three elements, sort order (integer), link href, and link text.
+two_factor_remove_session :: What actions to take to remove multifactor authentication status from the session, called when disabling multifactor authentication when authenticated using the factor being removed.
+two_factor_setup_links :: An array of entries for setup links to show on the multifactor manage page.  Each entry is an array of three elements, sort order (integer), link href, and link text.
+two_factor_update_session(type) :: How to update the session to reflect a successful multifactor authentication.