rodauth 2.30.0 → 2.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8270d10e6c0fbe554fc322958893f2c8069363af6455c0d17b0a7d3aafab11bd
-  data.tar.gz: 6eae8a9487764a9b189b27b8f1588e1516d86a6953fdabe0cff6adfd84facb5a
+  metadata.gz: ee670a5f0a59467c2043ca7649284c04665663fa4859b52bea1200722cf69256
+  data.tar.gz: 0a270ebc549934096225c47c0ea37e218658133cd7a5a10036c60e5d6a2f3c5c
 SHA512:
-  metadata.gz: d4dca9a0819842a478fac05f138b07452a054c7e498821eee7e61ab49640eccc46974d38c3aea1f71bf226eb7f76b03888a6734d7ae2139bcc74aca9a24bad6c
-  data.tar.gz: 5075118b0c6a8b27df251a2e6bfcd45e3dacc7ba1402bf5bacfc38a50b93b424a0ccdb479b1f5541d589f5687a8424c7319a194c0b01a80c762b725065190013
+  metadata.gz: 8e36ee900735384b6179c44f9549c10719cd24055b04b2b4a46daf7e499aa5e9057abb205b37bb4be2ab0d43eddff88314f945d6b8e47dde4bb2b21da1160947
+  data.tar.gz: 90970c54c4f2492ff0956a8c8bdb91eb475487e5e45b71fad06a39403c658234656a644b871de4d18c74d14c3288fef5db5932ee0fc5c8434cc69788348c606c

data/CHANGELOG

@@ -1,3 +1,43 @@
+=== 2.32.0 (2023-10-23)
+
+* Remove use of Base64 in argon2 feature (jeremyevans)
+
+* Add sms_needs_confirmation_notice_flash configuration method, supporting different flash notice for successful submission (jeremyevans)
+
+* Support *_response configuration methods for overriding common notice flash/redirect handling in many features (HoneyryderChuck, jeremyevans) (#369)
+
+* Support hmac_secret rotation in the otp feature (jeremyevans) (#365)
+
+* Support hmac_secret rotation in the email_base feature (jeremyevans) (#365)
+
+* Support hmac_secret rotation in the webauthn feature (jeremyevans) (#365)
+
+* Support hmac_secret rotation in the jwt_refresh feature (jeremyevans) (#365)
+
+* Support hmac_secret rotation in the single_session feature (jeremyevans) (#365)
+
+* Support hmac_secret rotation in the remember feature (jeremyevans) (#365)
+
+* Support hmac_secret rotation via hmac_old_secret configuration method in the active_sessions feature (jeremyevans) (#365)
+
+* Support argon2 secret rotation via argon2_old_secret configuration method and the update_password_hash feature (jeremyevans) (#365)
+
+* Support jwt secret rotation via jwt_old_secret configuration method, if using jwt 2.4+ (jeremyevans) (#365)
+
+=== 2.31.0 (2023-08-22)
+
+* Make clear_session work correctly for internal requests (janko) (#359)
+
+* Support webauthn_invalid_webauthn_id_message configuration method in the webauthn_autofill feature (janko) (#356)
+
+* Support webauth features in the internal_request feature (janko) (#355)
+
+* Allow WebAuthn login to count for two factors if user verification is provided (janko) (#354)
+
+* Allow explicit use of p_cost in argon2 feature if using argon2 2.1+ (estebanz01) (#353)
+
+* Add json_response_error? configuration method to json feature, for whether response indicates an error (opya) (#340)
+
 === 2.30.0 (2023-05-22)
 
 * Make load_memory in the remember feature not raise NoMethodError if logged in when the account no longer exists (jeremyevans) (#331)

data/README.rdoc

@@ -98,6 +98,9 @@ rqrcode :: Used by the otp feature
 jwt :: Used by the jwt feature
 webauthn :: Used by the webauthn feature
 
+You can use <tt>gem install --development rodauth</tt> to install
+the development dependencies in order to run tests.
+
 == Security
 
 === Password Hash Access Via Database Functions
@@ -1320,7 +1323,7 @@ application to call Rodauth methods.
 
 If you're using the remember feature with +extend_remember_deadline?+ set to
 true, you'll want to load roda's middleware plugin with
-+forward_response_headers: true+ option, so that +Set-Cookie+ header changes
+<tt>forward_response_headers: true</tt> option, so that +Set-Cookie+ header changes
 from the +load_memory+ call in the route block are propagated when the request
 is forwarded to the main app.
 

data/doc/argon2.rdoc

@@ -2,10 +2,13 @@
 
 The argon2 feature adds the ability to replace the bcrypt password hash
 algorithm with argon2 (specifically, argon2id).  Argon2 is an alternative to
-bcrypt that offers the ability to be memory-hard.  However, if you are storing
-password hashes in a table that the database user does not have access to
-(the recommended way to use Rodauth), argon2 does not offer significant
-security advantages over bcrypt.
+bcrypt that offers the ability to be memory-hard.  However, argon2 is weaker
+than bcrypt for interactive login environments (e.g. password check times
+under a second), so for the vast majority of web applications, using the
+argon2 feature will weaken the application's security.  You should not use
+the argon2 feature unless the usage of argon2 is required or you are a
+cryptographer and understand why argon2 would be better than bcrypt for your
+application.
 
 If you are using this feature with Rodauth's database authentication functions,
 you need to make sure that the database authentication functions are configured
@@ -32,7 +35,7 @@ In this example, +DB+ should be your Sequel::Database object:
 
 The argon2 feature provides the ability to allow for a gradual migration
 from transitioning from bcrypt to argon2 and vice-versa, if you are using the
-update_password_hash.
+update_password_hash feature.
 
 Argon2 is more configurable than bcrypt in terms of password hash cost
 speficiation.  Instead of specifying the password_hash_cost value as
@@ -46,5 +49,6 @@ memory.
 
 == Auth Value Methods
 
+argon2_old_secret :: The previous secret key used as input at hashing time, used for argon2_secret rotation.  In order to rotate the argon2_secret, you must also use the update_password_hash feature, and rotation will not be finished until all users have logged in using the new secret.
 argon2_secret :: A secret key used as input at hashing time, folded into the value of the hash.
 use_argon2? :: Whether to use the argon2 password hash algorithm for new passwords (true by default). The only reason to set this to false is if you have existing passwords using argon2 that you want to support, but want to use bcrypt for new passwords.

data/doc/base.rdoc

@@ -43,6 +43,7 @@ field_error_attributes(field) :: The attributes to use for the input field tags
 flash_error_key :: The flash key to use for error messages (default: +:error+ or <tt>'error'</tt> depending on session support for symbols).
 flash_notice_key :: The flash key to use for notice messages (default: +:notice+ or <tt>'notice'</tt> depending on session support for symbols).
 formatted_field_error(field, error) :: HTML to use for error messages for the field (parameter name), if the field has an error.  By default, uses a span tag for the error message.
+hmac_old_secret :: This sets the previous secret used for Rodauth's HMACs, to allow for secret rotation.
 hook_action(hook_type, action) :: Arbitrary action to take on all hook processing, with hook type being +:before+ or +:after+, and action being symbol for related action.
 input_field_error_class :: The CSS class to use for input fields with errors. Can be a space separated string for multiple CSS classes.
 input_field_error_message_class :: The CSS class to use for error messages. Can be a space separated string for multiple CSS classes.

data/doc/change_login.rdoc

@@ -21,4 +21,5 @@ after_change_login :: Run arbitrary code after successful login change.
 before_change_login :: Run arbitrary code before changing a login.
 before_change_login_route :: Run arbitrary code before handling a change login route.
 change_login(login) :: Change the users login to the given login, or return nil/false if the login cannot be changed to the given login.
+change_login_response :: Return a response after a successful login change. By default, redirects to +change_login_redirect+.
 change_login_view :: The HTML to use for the change login form.

data/doc/change_password.rdoc

@@ -22,4 +22,5 @@ new_password_param :: The parameter name to use for new passwords.
 after_change_password :: Run arbitrary code after successful password change.
 before_change_password :: Run arbitrary code before changing the password for an account.
 before_change_password_route :: Run arbitrary code before handling a change password route.
+change_password_response :: Return a response after a successful password change. By default, redirects to +change_password_redirect+.
 change_password_view :: The HTML to use for the change password form.

data/doc/close_account.rdoc

@@ -21,5 +21,6 @@ after_close_account :: Run arbitrary code after closing the account.
 before_close_account :: Run arbitrary code before closing an account.
 before_close_account_route :: Run arbitrary code before handling a close account route.
 close_account :: Close the account, by default setting the account status to closed.
+close_account_response :: Return a response after successfully closing the account . By default, redirects to +close_account_redirect+.
 close_account_view :: The HTML to use for the close account form.
 delete_account :: If +delete_account_on_close?+ is true, delete the account when closing it.

data/doc/confirm_password.rdoc

@@ -28,4 +28,5 @@ after_confirm_password :: Run arbitrary code after successful confirmation of pa
 before_confirm_password :: Run arbitrary code before setting that the password has been confirmed.
 before_confirm_password_route :: Run arbitrary code before handling the password confirmation route.
 confirm_password :: Update the session to reflect the password has been confirmed.
+confirm_password_response :: Return a response after successful password confirmation. By default, redirects to +confirm_password_redirect+.
 confirm_password_view :: The HTML to use for the confirm password form.

data/doc/create_account.rdoc

@@ -20,6 +20,7 @@ before_create_account :: Run arbitrary code before creating the account.
 before_create_account_route :: Run arbitrary code before handling a create account route.
 create_account_autologin? :: Whether to autologin the user upon successful account creation, true by default unless verifying accounts.
 create_account_link_text :: The text to use for a link to the create account form.
+create_account_response :: Return a response after successful account creation. By default, redirects to +create_account_redirect+.
 create_account_view :: The HTML to use for the create account form.
 new_account(login) :: Instantiate a new account hash for the given login, without saving it.
 save_account :: Insert the account into the database, or return nil/false if that was not successful.

data/doc/email_auth.rdoc

@@ -43,6 +43,7 @@ create_email_auth_email :: A Mail::Message for the email auth email.
 create_email_auth_key :: Add the email auth key data to the database.
 email_auth_email_body :: The body to use for the email auth email.
 email_auth_email_link :: The link to the email auth form in the email auth email.
+email_auth_email_sent_response :: Return a response after successfully sending an email auth email. By default, redirects to +email_auth_email_sent_redirect+.
 email_auth_key_insert_hash :: The hash to insert into the +email_auth_table+.
 email_auth_key_value :: The email auth key for the current account.
 email_auth_request_form :: The HTML to use for a form to request an email auth email, shown on the login page after the user submits their login, if +force_email_auth?+ is false and email authentication is not the only possible for of authentication for the user.

data/doc/error_reasons.rdoc

@@ -38,6 +38,7 @@ Rodauth will call +set_error_reason+ with:
 * :invalid_verify_account_key
 * :invalid_verify_login_change_key
 * :invalid_webauthn_auth_param
+* :invalid_webauthn_id
 * :invalid_webauthn_remove_param
 * :invalid_webauthn_setup_param
 * :invalid_webauthn_sign_count

data/doc/guides/registration_field.rdoc

@@ -10,7 +10,7 @@ or their company's name.
 Let's assume you wanted to wanted to store the additional field(s) directly on
 the +accounts+ table:
 
-  atler_table :accounts do
+  alter_table :accounts do
     add_column :name, String
   end
 

data/doc/guides/render_confirmation.rdoc

@@ -0,0 +1,17 @@
+= Render confirmation view
+
+Most Rodauth actions redirect and display a flash notice after they're succesfully performed. However, in some cases you may wish to render a view confirming that the action was succesful, for nicer user experience.
+
+For example, when the user creates an account, you might render a page with a call to action to verify their account. Assuming you've created an +account_created+ view template alongside your other Rodauth templates, you can configure the following:
+
+  after_create_account do
+    # render "account_created" view template with page title of "Account created!"
+    return_response view("account_created", "Account created!")
+  end
+
+Similarly, when the user has requested a password reset, you can render a page telling them to check their email:
+
+  after_reset_password_request do
+    # render "password_reset_sent" view template with page title of "Password sent!"
+    return_response view("password_reset_sent", "Password sent!")
+  end

data/doc/internal_request.rdoc

@@ -461,3 +461,79 @@ account login, before the change.
 
 Options:
 +:verify_login_change_key+ :: The verify login change key for the account. This allows verifying login changes by key, without knowing the account id or login.
+
+=== WebAuthn
+
+==== webauthn_setup_params (requires account)
+
+The +webauthn_setup_params+ method returns a hash with +:webauthn_setup+,
++:webauthn_setup_challenge+ and +:webauthn_setup_challenge_hmac+ keys.
+
+The +:webauthn_setup+ options should be provided to the client for WebAuthn
+registration, while +:webauthn_setup_challenge+ and
++webauthn_setup_challenge_hmac+ should be passed to the +webauthn_setup+
+method.
+
+==== webauthn_setup (requires account)
+
+The +webauthn_setup+ method creates a WebAuthn credential for the account.
+
+Options:
++:webauthn_setup+ :: The WebAuthn credential provided by the client during registration.
++:webauthn_setup_challenge+ :: The WebAuthn challenge generated for registration.
++:webauthn_setup_challenge_hmac+ :: The HMAC of the WebAuthn challenge generated for registration.
+
+==== webauthn_auth_params (requires account)
+
+The +webauthn_auth_params+ method returns a hash with +:webauthn_auth+,
++:webauthn_auth_challenge+ and +:webauthn_auth_challenge_hmac+ keys.
+
+The +:webauthn_auth+ options should be provided to the client for WebAuthn
+authentication, while +:webauthn_auth_challenge+ and
++webauthn_auth_challenge_hmac+ should be passed to the +webauthn_auth+ method.
+
+==== webauthn_auth (requires account)
+
+The +webauthn_auth+ method determines if the given WebAuthn credential is valid
+for the account.
+
+Options:
++:webauthn_auth+ :: The WebAuthn credential provided by the client during authentication.
++:webauthn_auth_challenge+ :: The WebAuthn challenge generated for authentication.
++:webauthn_auth_challenge_hmac+ :: The HMAC of the WebAuthn challenge generated for authentication.
+
+==== webauthn_remove (requires account)
+
+The +webauthn_remove+ methods deletes the given WebAuthn credential for the
+account.
+
+Options:
++:webauthn_remove+ :: The ID of the WebAuthn credential to delete.
+
+=== WebAuthn Login
+
+==== webauthn_login_params (requires account or login)
+
+The +webauthn_login_params+ method returns a hash with +:webauthn_auth+,
++:webauthn_auth_challenge+ and +:webauthn_auth_challenge_hmac+ keys.
+
+The +:webauthn_auth+ options should be provided to the client for WebAuthn
+authentication, while +:webauthn_auth_challenge+ and
++webauthn_auth_challenge_hmac+ should be passed to the +webauthn_login+ method.
+
+==== webauthn_login (requires account or login)
+
+The +webauthn_login+ method determines if the given WebAuthn credential is
+valid for the given account.
+
+This method will return the account id if the WebAuthn credential is valid.
+
+Options:
++:webauthn_auth+ :: The WebAuthn credential provided by the client during authentication.
++:webauthn_auth_challenge+ :: The WebAuthn challenge generated for authentication.
++:webauthn_auth_challenge_hmac+ :: The HMAC of the WebAuthn challenge generated for authentication.
+
+=== WebAuthn Autofill
+
+Enabling this feature modifies +webauthn_login_params+ and +webauthn_login+
+methods not to require an account or login.

data/doc/json.rdoc

@@ -41,6 +41,7 @@ json_not_accepted_error_message :: The error message to display if +json_check_a
 json_request_content_type_regexp :: The regexp to use to recognize a request as a json request.
 json_response_content_type :: The content type to set for json responses, <tt>application/json</tt> by default.
 json_response_custom_error_status? :: Whether to use custom error statuses, instead of always using +json_response_error_status+, true by default, can be set to false for backwards compatibility with Rodauth 1.
+json_response_error? :: Whether the current JSON response indicates an error.  By default, returns whether +json_response_error_key+ is set.
 json_response_error_key :: The JSON result key containing an error message, +error+ by default.
 json_response_error_status :: The HTTP status code to use for JSON error responses if not using custom error statuses, 400 by default.
 json_response_field_error_key :: The JSON result key containing an field error message, <tt>field-error</tt> by default.

data/doc/jwt.rdoc

@@ -5,7 +5,7 @@ that ship with Rodauth, using JWT (JSON Web Tokens) to hold the
 session information. It depends on the json feature.
 
 In order to use this feature, you have to set the +jwt_secret+ configuration
-option the secret used to cryptographically protect the token.
+option with the secret used to cryptographically protect the token.
 
 To use this JSON API, when processing responses for requests to a Rodauth
 endpoint, check for the Authorization header, and use the value of the
@@ -26,6 +26,11 @@ request in your Roda app, you can call the +rodauth.valid_jwt?+ method.  If
 +rodauth.valid_jwt?+ returns true, the contents of the jwt can be retrieved
 from +rodauth.session+.
 
+Logging the session out does not invalidate the previous JWT token by default.
+If you would like this behavior, you can use the active_sessions feature, which
+stores session identifiers in the database and deletes them when the session
+expires. This provides a whitelist approach of revoking JWT tokens.
+
 == Auth Value Methods
 
 invalid_jwt_format_error_message :: The error message to use when a JWT with an invalid format is submitted in the Authorization header.
@@ -33,6 +38,7 @@ jwt_algorithm :: The JWT algorithm to use, +HS256+ by default.
 jwt_authorization_ignore :: A regexp matched against the Authorization header, which skips JWT processing if it matches.  By default, HTTP Basic and Digest authentication are ignored.
 jwt_authorization_remove :: A regexp to remove from the Authorization header before processing the JWT.  By default, a Bearer prefix is removed.
 jwt_decode_opts :: An optional hash to pass to +JWT.decode+. Can be used to set JWT verifiers.
+jwt_old_secret :: The previous JWT secret used, to support JWT secret rotation (only supported when using jwt 2.4+).  Access to this should be protected the same as a session secret.
 jwt_secret :: The JWT secret to use.  Access to this should be protected the same as a session secret.
 jwt_session_key :: A key to nest the session hash under in the JWT payload.  nil by default, for no nesting.
 jwt_symbolize_deeply? :: Whether to symbolize the session hash deeply.  false by default.

data/doc/jwt_refresh.rdoc

@@ -7,7 +7,7 @@ When this feature is used, the access and refresh token are provided
 at login in the response body (the access token is still provided in the Authorization
 header), and for any subsequent POST to <tt>/jwt-refresh</tt>.
 
-Note that using the refresh token invalides the token and creates
+Note that using the refresh token invalidates the token and creates
 a new access token with an updated lifetime.  However, it does not invalidate
 older access tokens.  Older access tokens remain valid until they expire.  You
 can use the active_sessions feature if you want previous access tokens to be invalid

data/doc/lockout.rdoc

@@ -46,14 +46,14 @@ unlock_account_skip_resend_email_within :: The number of seconds before sending
 
 == Auth Methods
 
-account_from_unlock_key(key) :: Retrieve the account using the given verify account key, or return nil if no account matches. 
+account_from_unlock_key(key) :: Retrieve the account using the given verify account key, or return nil if no account matches.
 after_account_lockout :: Run arbitrary code after an account has been locked out.
 after_unlock_account :: Run arbitrary code after a successful account unlock.
 after_unlock_account_request :: Run arbitrary code after a successful account unlock request.
 before_unlock_account :: Run arbitrary code before unlocking an account.
 before_unlock_account_request :: Run arbitrary code before sending an account unlock email.
 before_unlock_account_request_route :: Run arbitrary code before handling an account unlock request route.
-before_unlock_account_route :: Run arbitrary code before handling an unlock account route. 
+before_unlock_account_route :: Run arbitrary code before handling an unlock account route.
 clear_invalid_login_attempts :: Clear any stored login failures or lockouts for the current account.
 create_unlock_account_email :: A Mail::Message for the account unlock email to send.
 generate_unlock_account_key :: A random string to use for a new unlock account key.
@@ -67,5 +67,7 @@ unlock_account :: Unlock the account.
 unlock_account_email_body :: The body to use for the unlock account email.
 unlock_account_email_link :: The link to the unlock account form to include in the unlock account email.
 unlock_account_key :: The unlock account key for the current account.
+unlock_account_request_response :: Return a response after successfully requesting an account unlock. By default, redirects to +unlock_account_request_redirect+.
 unlock_account_request_view :: The HTML to use for the unlock account request form.
+unlock_account_response :: Return a response after successfully unlocking an account. By default, redirects to +unlock_account_redirect+.
 unlock_account_view :: The HTML to use for the unlock account form.

data/doc/login.rdoc

@@ -33,6 +33,7 @@ use_multi_phase_login? :: Whether to ask for login first, and only ask for passw
 == Auth Methods
 
 before_login_route :: Run arbitrary code before handling a login route.
-login_view :: The HTML to use for the login form.
+login_response :: Return a response after a successful login. By default, redirects to +login_redirect+ (or the requested location if +login_return_to_requested_location?+ is true).
 login_return_to_requested_location_path :: If +login_return_to_requested_location?+ is true, the path to use as the requested location.  By default, uses the full path of the request for GET requests, and is nil for non-GET requests (in which case the default +login_redirect+ will be used).
+login_view :: The HTML to use for the login form.
 multi_phase_login_view :: The HTML to use for the login form after login has been entered when using multi phase login.

data/doc/logout.rdoc

@@ -18,4 +18,5 @@ after_logout :: Run arbitrary code after logout.
 before_logout :: Run arbitrary code before logout.
 before_logout_route :: Run arbitrary code before handling a logout route.
 logout :: Log the user out, by default clearing the session.
+logout_response :: Return a response after a successful logout. By default, redirects to +logout_redirect+.
 logout_view :: The HTML to use for the logout form.

data/doc/otp.rdoc

@@ -71,6 +71,7 @@ otp :: The object used for verifying OTP authentication attempts.
 otp_add_key(secret) :: Add an OTP key for the current account with the given secret.
 otp_auth_view :: The HTML to use for the OTP authentication form.
 otp_available? :: Whether OTP authentication is ready for use.
+otp_disable_response :: Return a response after successfully disabling OTP . By default, redirects to +otp_disable_redirect+.
 otp_disable_view :: The HTML to use for the OTP disable form.
 otp_exists? :: Whether the current account has setup OTP.
 otp_key :: The stored OTP secret for the account.
@@ -83,8 +84,10 @@ otp_qr_code :: The QR code containing the otp_provisioning_uri, by default an SV
 otp_record_authentication_failure :: Record an OTP authentication failure.
 otp_remove :: Removes all stored OTP data for the current account.
 otp_remove_auth_failures :: Removes OTP authentication failures for the current account, used after successful multifactor authentication.
+otp_setup_response :: Return a response after successful OTP setup. By default, redirects to +otp_setup_redirect+.
 otp_setup_view :: The HTML to use for the form to setup OTP authentication.
 otp_tmp_key(secret) :: Set the secret to use for the temporary OTP key, during OTP setup.
 otp_update_last_use :: Update the last time OTP authentication was successful for the account.  Return true if the authentication should be allowed, or false if it should not be allowed because the last authentication was too recent and indicates the possible reuse of a TOTP authentication code.
+otp_valid_code_for_old_secret :: Called when valid OTP authentication is performed using hmac_old_secret.  This indicates the OTP needs to be rotated before support for the previous hmac secret value is removed.  You can use this to track users who need their OTP rotated, and take appropriate action.
 otp_valid_code?(auth_code) :: Whether the given code is the currently valid OTP auth code for the account.
 otp_valid_key?(secret) :: Whether the given secret is a valid OTP secret.

data/doc/release_notes/2.31.0.txt

@@ -0,0 +1,47 @@
+= New Features
+
+* The internal_request feature now supports WebAuthn, using 
+  the following methods:
+
+  * With the webauthn feature:
+    * webauthn_setup_params
+    * webauthn_setup
+    * webauthn_auth_params
+    * webauthn_auth
+    * webauthn_remove
+
+  * With the webauthn_login feature:
+    * webauthn_login_params
+    * webauthn_login
+
+* A webauthn_login_user_verification_additional_factor? configuration
+  method has been added to the webauthn_login feature. By default,
+  this method returns false.  If you configure the method to return
+  true, and the WebAuthn credential provided specifies that it
+  verified the user, then this will treat the user verification as
+  a second factor, so the user will be considered multifactor
+  authenticated after successful login.  You should only set this
+  method to true if you consider the WebAuthn user verification
+  strong enough to be a independent factor.
+
+* A json_response_error? configuration method has been added to the
+  json feature.  This should return whether the current response
+  should be treated as an error by the json feature.  By default,
+  it is true if json_response_error_key is set in the response,
+  since that is the default place that Rodauth stores errors when
+  using the json feature.
+
+* A webauthn_invalid_webauthn_id_message configuration method has
+  been added for customizing the error message used for invalid
+  WebAuthn IDs.
+
+= Other Improvements
+
+* The argon2 feature now supports setting the Argon2 p_cost if
+  argon2 2.1+ is installed.
+
+* An :invalid_webauthn_id error reason is now used for invalid
+  WebAuthn IDs.
+
+* The clear_session method now works as expected for internal
+  requests.

data/doc/release_notes/2.32.0.txt

@@ -0,0 +1,65 @@
+= New Features
+
+* Rodauth now supports secret rotation using the following
+  configuration methods:
+
+  * hmac_old_secret
+  * argon2_old_secret (argon2 feature)
+  * jwt_old_secret (jwt feature)
+
+  You can use these methods to specify the previous secret when
+  rotating secrets.  Note that full secret rotation (where you can
+  remove use of the old secret) may not be simple.  Here are some
+  cases that require additional work:
+
+  * Rotating the argon2 secret requires the use of the
+    update_password_hash feature.  You cannot remove the use of
+    argon2_old_secret unless every user who created a password under
+    the old secret has logged in after the new secret was added.
+    Removing the old secret before a user has logged in after the new
+    secret was added will invalidate the password for the user. Thus,
+    full rotation of the argon2 secret requires invalidating passwords
+    for inactive accounts.
+
+  * Full rotating of the hmac secret when using the remember feature
+    requires that all remember cookies created under the previous
+    secret has been removed.  By default, remember cookies expire in
+    2 weeks, but it is possible to set them much longer.
+
+  * Full rotation of the hmac secret when using the verify_account
+    feature requires invalidating old verify account links, since
+    verify account links do not have a deadline.  However, after old
+    verify account links have been invalidated, a user can request a
+    new verify account link, which will work.
+
+  * Full rotation of the hmac secret when using the otp feature
+    requires disabling otp and reenabling otp.  The
+    otp_valid_code_for_old_secret configuration method has been added,
+    which can be used to handle cases where a user successfully
+    authenticated via TOTP using the old secret.  This can be used
+    to direct them to a page to remove the TOTP authenticator and
+    then setup a new TOTP authenicator.
+
+* Many *_response configuration methods have been added, which allow
+  users to override Rodauth's default behavior in successful cases of
+  setting a flash notice and then redirecting.  Note that using these
+  configuration methods correctly requires that they halt request
+  processing.  You cannot just have them return a response body.  You
+  can use the return_response method to set the response body and
+  halt processing.
+
+* An sms_needs_confirmation_notice_flash configuration method has been
+  added, for setting the flash notice when setting up SMS
+  authentication.  By default, it uses the
+  sms_needs_confirmation_error_flash value.
+
+= Other Improvements
+
+* The argon2 feature no longer uses the Base64 constant.  Previously,
+  it uses the library without attempting to require the base64 library,
+  which would break if the base64 library was not already required.
+
+* Rodauth's documentation now recommends against the use of the argon2
+  feature, because for typical interactive login uses (targetting
+  sub-200ms response times), argon2 provides significantly worse
+  security than bcrypt.

data/doc/remember.rdoc

@@ -74,5 +74,6 @@ logged_in_via_remember_key? :: Whether the current session was logged in via a r
 remembered_session_id :: The session_id which is validly remembered, if any.
 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_response :: Return a response after successfully changing remember settings. By default, redirects to +remember_redirect+.
 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.

data/doc/reset_password.rdoc

@@ -56,9 +56,11 @@ login_failed_reset_password_request_form :: The HTML to use for a form to reques
 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 request email.
 reset_password_email_link :: The link to the reset password form in the reset password request email.
+reset_password_email_sent_response :: Return a response after successfully sending a password reset email. By default, redirects to +reset_password_email_sent_redirect+.
 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_response :: Return a response after successfully resetting a password. By default, redirects to +reset_password_redirect+.
 reset_password_view :: The HTML to use for the reset password form.
 send_reset_password_email :: Send the reset password request email.
 set_reset_password_email_last_sent :: Set the last time a reset password request email is sent.

data/doc/sms_codes.rdoc

@@ -63,6 +63,7 @@ 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_notice_flash :: The flash notice to show on SMS authentication pages when SMS authentication setup needs confirmation (uses +sms_needs_confirmation_error_flash+ 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.
@@ -109,19 +110,23 @@ sms_available? :: Whether SMS authentication is ready for use.
 sms_code_issued_at :: The timestamp the current SMS code was issued at.
 sms_code_match?(code) :: Whether there is an active SMS authentication code for the current account and the given code matches it.
 sms_confirm_message(code) :: The SMS message to use for the given confirmation code.
+sms_confirm_response :: Return a response after successfully confirming SMS code during SMS setup. By default, redirects to +sms_confirm_redirect+.
 sms_confirm_view :: The HTML to use for the form to authenticate via SMS code.
 sms_confirmation_match?(code) :: Whether there is an active SMS confirmation code for the current account and the given code matches it.
 sms_current_auth? :: Whether there is a active SMS authentication code for the current account.
 sms_disable :: Action to take to disable SMS authentication for the account.
+sms_disable_response :: Return a response after successfully disabling SMS. By default, redirects to +sms_disable_redirect+.
 sms_disable_view :: The HTML to use for the form to disable SMS authentication.
 sms_failures :: The number of SMS authentication failures since the last successfully SMS authentication for this account.
 sms_locked_out? :: Whether SMS authentication has been locked out for the current account.
 sms_needs_confirmation? :: Whether SMS authentication has been setup but not confirmed for the current account.
+sms_needs_confirmation_response :: Return a response after successfully providing SMS number during SMS setup. By default, redirects to +sms_needs_confirmation_redirect+.
 sms_new_auth_code :: A new SMS authentication code that can be used for the account.
 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 multifactor authentication.
+sms_request_response :: Return a response after a successful SMS request during SMS authentication. By default, redirects to +sms_auth_redirect+.
 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.

data/doc/two_factor_base.rdoc

@@ -56,8 +56,10 @@ before_two_factor_disable :: Any actions to take before disabling of all multifa
 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_response :: Return a response after successful multifactor authentication. By default, redirects to +two_factor_auth_redirect+  (or the requested location if +two_factor_auth_return_to_requested_location?+ is true).
 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_response :: Return a response after successfully disabling multifactor authentication. By default, redirects to +two_factor_disable_redirect+.
 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.

data/doc/verify_account.rdoc

@@ -60,6 +60,8 @@ set_verify_account_email_last_sent :: Set the last time a verify account email i
 verify_account :: Verify the account by changing the status from unverified to open.
 verify_account_email_body :: The body to use for the verify account email.
 verify_account_email_link :: The link to the verify account form in the verify account email.
+verify_account_email_sent_response :: Return a response after successfully sending an verify account email. By default, redirects to +verify_account_email_sent_redirect+.
 verify_account_key_insert_hash :: The hash to insert into the +verify_account_table+.
 verify_account_key_value :: The value of the verify account key.
+verify_account_response :: Return a response after successfully verifying an account. By default, redirects to +verify_account_redirect+.
 verify_account_view :: The HTML to use for the verify account form.

data/doc/verify_login_change.rdoc

@@ -55,4 +55,5 @@ verify_login_change_key_insert_hash(login) :: The hash to insert into the +verif
 verify_login_change_key_value :: The value of the verify login change key.
 verify_login_change_new_login :: The new login to use when the login change is verified.
 verify_login_change_old_login :: The old login to display in the verify login change email.
+verify_login_change_response :: Return a response after successfully verifying a login change. By default, redirects to +verify_login_change_redirect+.
 verify_login_change_view :: The HTML to use for the verify login change form.

data/doc/webauthn.rdoc

@@ -109,8 +109,10 @@ webauthn_auth_view :: The HTML to use for the page for authenticating via WebAut
 webauthn_credential_options_for_get :: WebAuthn credential options to provide to the client during WebAuthn authentication.
 webauthn_key_insert_hash(webauthn_credential) :: The hash to insert into the +webauthn_keys_table+.
 webauthn_remove_authenticated_session :: Remove the authenticated WebAuthn ID, used when removing the WebAuthn credential with the ID after authenticating with it.
+webauthn_remove_response :: Return a response after successfully removing a WebAuthn authenticator. By default, redirects to +webauthn_remove_redirect+.
 webauthn_remove_view :: The HTML to use for the page for removing an existing WebAuthn authenticator.
 webauthn_setup_js_path :: The path to the WebAuthn registration javascript.
+webauthn_setup_response :: Return a response after successfully setting up a WebAuthn authenticator. By default, redirects to +webauthn_setup_redirect+.
 webauthn_setup_view :: The HTML to use for the page for registering a new WebAuthn authenticator.
 webauthn_update_session(webauthn_id) :: Set the authenticated WebAuthn ID after authenticating via WebAuthn.
 webauthn_user_name :: The user name to use when registering a new WebAuthn credential, the user's email by default.