rodauth 1.20.0 → 2.1.0

data/doc/close_account.rdoc

@@ -5,28 +5,21 @@ The close account feature allows users to close their accounts.
 == Auth Value Methods
 
 account_closed_status_value :: The integer representing closed accounts.
-close_account_additional_form_tags :: HTML fragment containing additional
-                                      form tags to use on the close account
-                                      form.
+close_account_additional_form_tags :: HTML fragment containing additional form tags to use on the close account form.
 close_account_button :: The text to use for the close account button.
-close_account_notice_flash :: The flash notice to show after closing the
-                              account.
+close_account_error_flash :: The flash error to show if there is an error closing the account.
+close_account_notice_flash :: The flash notice to show after closing the account.
+close_account_page_title :: The page title to use on the close account form.
 close_account_redirect :: Where to redirect after closing the account.
-close_account_requires_password? :: Whether a password is required when
-                                    closing accounts.
-close_account_route :: The route to the close account action. Defaults to
-                       +close-account+.
-delete_account_on_close? :: Whether to delete the account when closing it,
-                            default value is to use +skip_status_checks?+.
+close_account_requires_password? :: Whether a password is required when closing accounts.
+close_account_route :: The route to the close account action. Defaults to +close-account+.
+delete_account_on_close? :: Whether to delete the account when closing it, default value is to use +skip_status_checks?+.
 
 == Auth Methods
 
 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 :: Close the account, by default setting the account status to closed.
 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.
-                  
+delete_account :: If +delete_account_on_close?+ is true, delete the account when closing it.

data/doc/confirm_password.rdoc

@@ -1,24 +1,31 @@
 = Documentation for Confirm Password Feature
 
 The confirm password feature allows you to redirect users to a page to
-confirm their password.  It's used by the remember feature, but can also
-by your application if you want to confirm passwords.
+confirm their password.
+
+When confirming passwords, if authenticated via autologin, a remember token,
+or an email_auth token, switches the authentication type from that login
+method to password.
 
 == Auth Value Methods
 
 confirm_password_additional_form_tags :: HTML fragment containing additional form tags to use on the confirm password form.
 confirm_password_button :: The text to use for the confirm password button.
 confirm_password_error_flash :: The flash error to show if password confirmation is unsuccessful.
+confirm_password_link_text :: The text to use for the link from the two factor auth page.
 confirm_password_notice_flash :: The flash notice to show after password confirmed successful.
+confirm_password_page_title :: The page title to use on the confirm password form.
 confirm_password_redirect :: Where to redirect after successful password confirmation. By default, uses <tt>session[confirm_password_redirect_session_key]</tt> if set, allowing an easy way to redirect back to the page requesting password confirmation.
 confirm_password_redirect_session_key :: The session key used to check for the confirm_password_redirect.
-confirm_password_route :: The route to the confirm password form. Defaults to
-                          +confirm-password+.
+confirm_password_route :: The route to the confirm password form. Defaults to +confirm-password+.
+password_authentication_required_error_flash :: The flash error to show if going to a page requiring password confirmation.
+password_authentication_required_error_status :: The response status to use if going to a page requiring password confirmation, 401 by default.
+password_authentication_required_redirect :: Where to redirect when going to a page requiring password confirmation.
 
 == Auth Methods
 
 after_confirm_password :: Run arbitrary code after successful confirmation of password.
 before_confirm_password :: Run arbitrary code before setting that the password has been confirmed.
-confirm_password :: Run arbitrary code on correct password confirmation.
 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_view :: The HTML to use for the confirm password form.

data/doc/create_account.rdoc

@@ -4,34 +4,23 @@ The create account feature allows users to create new accounts.
 
 == Auth Value Methods
 
-create_account_additional_form_tags :: HTML fragment containing additional
-                                       form tags to use on the create account
-                                       form.
+create_account_additional_form_tags :: HTML fragment containing additional form tags to use on the create account form.
 create_account_button :: The text to use for the create account button.
-create_account_error_flash :: The flash error to show for unsuccessful
-                              account creation.
-create_account_notice_flash :: The flash notice to show after successful
+create_account_error_flash :: The flash error to show for unsuccessful account creation.
+create_account_notice_flash :: The flash notice to show after successful account creation.
+create_account_page_title :: The page title to use on the create account form.
 create_account_redirect :: Where to redirect after creating the account.
-create_account_route :: The route to the create account action. Defaults to
-                        +create-account+.
-create_account_set_password? :: Whether to ask for a password to be set on the create
-                                account form.  Defaults to true.  If set to false, an
-                                alternative method to set the password should be used.
+create_account_route :: The route to the create account action. Defaults to +create-account+.
+create_account_set_password? :: Whether to ask for a password to be set on the create account form.  Defaults to true if not verifying accounts.  If set to false, an alternative method to set the password should be used (assuming you want to allow password authentication).
 
 == Auth Methods
 
 after_create_account :: Run arbitrary code after creating the account.
 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 :: HTML fragment to display with a link to the create
-                       account form.
+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_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.
-set_new_account_password :: Set the password for a new account if
-                            +account_password_hash_column+ is set, without saving.
+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.
+set_new_account_password :: Set the password for a new account if +account_password_hash_column+ is set, without saving.

data/doc/disallow_password_reuse.rdoc

@@ -17,21 +17,14 @@ current password.
 
 == Auth Value Methods
 
-password_same_as_previous_password_message :: The error message fragment to display if the
-                                              given password is the same as a previous
-                                              password.
-previous_password_account_id_column :: The column in the +previous_password_hash_table+ that
-                                       stores the account id.
-previous_password_hash_column :: The column in the +previous_password_hash_table+ that
-                                 stores the password hash.
+password_same_as_previous_password_message :: The error message fragment to display if the given password is the same as a previous password.
+previous_password_account_id_column :: The column in the +previous_password_hash_table+ that stores the account id.
+previous_password_hash_column :: The column in the +previous_password_hash_table+ that stores the password hash.
 previous_password_hash_table :: The table storing previous password hashes.
-previous_password_id_column :: The column in the +previous_password_hash_table+ that
-                               stores the autoincrementing primary key.
+previous_password_id_column :: The column in the +previous_password_hash_table+ that stores the autoincrementing primary key.
 previous_passwords_to_check :: The number of previous password hashes to store and check.
 
 == Auth Methods
 
-add_previous_password_hash(hash) :: Add the given hash to the list of previous hashes for
-                                    the current account.
-password_doesnt_match_previous_password?(password) :: Whether the password given matches any
-                                                      of the previous passwords.
+add_previous_password_hash(hash) :: Add the given hash to the list of previous hashes for the current account.
+password_doesnt_match_previous_password?(password) :: Whether the password given matches any of the previous passwords.

data/doc/email_auth.rdoc

@@ -1,34 +1,35 @@
 = Documentation for Email Auth Feature
 
-The email auth feature implements login using links sent via email.  It is
-very similar to the email auth feature, except you don't need to update
-a password, or even have a password to login.  Depends on the login and
+The email auth feature implements passwordless login using links sent via email.  It is
+similar to the reset password feature, except you don't need to update
+a password, or even have a password to login.  It depends on the login and
 email_base features.
 
 == Auth Value Methods
 
 email_auth_additional_form_tags :: HTML fragment containing additional form tags to use on the email auth login form.
+email_auth_deadline_column :: The column name in the +email_auth_table+ storing the deadline after which the token will be ignored.
+email_auth_deadline_interval :: The amount of time for which to allow users to use email auth keys, 1 day by default. Only used if set_deadline_values? is true.
+email_auth_email_last_sent_column :: The email auth last sent column in the +email_auth_table+, storing the last time the email was sent. Set to nil to always send an email when requested.
 email_auth_email_recently_sent_error_flash :: The flash error to show if not sending an email auth email because another was sent recently.
 email_auth_email_recently_sent_redirect :: Where to redirect after not sending an email auth email because another was sent recently.
-email_auth_deadline_column :: The column name in the email auth keys table storing the deadline after which the token will be ignored.
-email_auth_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.
 email_auth_email_sent_notice_flash :: The flash notice to show after an email auth email has been sent.
 email_auth_email_sent_redirect :: Where to redirect after sending an email auth email.
 email_auth_email_subject :: The subject to use for email auth emails.
 email_auth_error_flash :: The flash error to show if unable to login using email authentication.
-email_auth_id_column :: The id column in the email auth keys table, should be a foreign key referencing the accounts table.
-email_auth_key_column :: The email auth key/token column in the email auth keys table.
+email_auth_id_column :: The id column in the +email_auth_table+, should be a foreign key referencing the accounts table.
+email_auth_key_column :: The email auth key/token column in the +email_auth_table+.
 email_auth_key_param :: The parameter name to use for the email auth key.
-email_auth_last_column :: The email auth last sent column in the email auth keys table, storing the last time the email was sent. Set to nil to always send an email when requested.
+email_auth_page_title :: The page title to use on the email auth form.
 email_auth_request_additional_form_tags :: HTML fragment containing additional form tags to use on the email auth request form.
 email_auth_request_button :: The text to use for the email auth request button.
 email_auth_request_error_flash :: The flash error to show if not able to send an email auth email.
 email_auth_request_route :: The route to the email auth request action.  Defaults to +email-auth-request+.
 email_auth_route :: The route to the email auth action. Defaults to +email-auth+.
 email_auth_session_key :: The key in the session to hold the email auth key temporarily.
-email_auth_skip_resend_within :: The number of seconds before sending another email auth email.
-email_auth_table :: The name of the email auth keys table.
-force_email_auth? :: Whether email auth should be forced for the account.  By default, email auth is forced if the account does not have a password.
+email_auth_skip_resend_email_within :: The number of seconds required before sending another email auth email, 5 minutes by default.
+email_auth_table :: The name of the table storing email auth keys.
+force_email_auth? :: Whether email auth should be forced for the account.  False by default, which results in email auth only be used automatically if the account does not have a password.
 no_matching_email_auth_key_error_flash :: The flash error message to show if attempting to access the email auth form with an invalid key.
 
 == Auth Methods
@@ -42,12 +43,12 @@ 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_key_insert_hash :: The hash to insert into the email auth keys table.
+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.
+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.
 email_auth_view :: The HTML to use for the email auth form.
-get_email_auth_key(id) :: Get the email auth key for the given account id from the database.
 get_email_auth_email_last_sent :: Get the last time an email auth email is sent, or nil if there is no last sent time.
+get_email_auth_key(id) :: Get the email auth key for the given account id from the database.
 remove_email_auth_key :: Remove the email auth key for the current account, run after successful email auth.
 send_email_auth_email :: Send the email auth email.
 set_email_auth_email_last_sent :: Set the last time an email auth email is sent.  This is only called if there is a previous email auth token still active.

data/doc/email_base.rdoc

@@ -5,23 +5,14 @@ that requires sending emails.
 
 == Auth Value Methods
 
-allow_raw_email_token? :: When +email_token_hmac_secret+ is used, this allows the use of the raw
-                          token.  This should only be set to true temporarily during a transition
-                          period from using raw tokens to using HMACed tokens.  After the transition
-                          period, this should not be set, as setting this to true removes the
-                          security that HMACed tokens add.
-default_post_email_redirect :: Where to redirect after sending an email. This is the default
-                               redirect location for all redirects after an email is sent when the
-                               account is not logged in.  Also includes cases where an email is not
-                               sent due to rate limiting.
+allow_raw_email_token? :: When +hmac_secret+ is used, this allows the use of the raw token.  This should only be set to true temporarily during a transition period from using raw tokens to using HMACed tokens.  After the transition period, this should not be set, as setting this to true removes the security that HMACed tokens add.
+default_post_email_redirect :: Where to redirect after sending an email. This is the default redirect location for all redirects after an email is sent when the account is not logged in.  Also includes cases where an email is not sent due to rate limiting.
 email_from :: The from address to use for emails sent by Rodauth.
 email_subject_prefix :: The prefix to use for email subjects 
-require_mail? :: Set to false to not require mail, useful if using a different
-                 library for sending email.
+require_mail? :: Set to false to not require mail, useful if using a different library for sending email.
 
 == Auth Methods
 
-email_to :: The email address to send emails to, by default the login of the
-            current account.
-create_email(subject, body) :: Return a Mail::Message instance with the given subject
-                               and body.
+create_email(subject, body) :: Return a Mail::Message instance with the given subject and body.
+email_to :: The email address to send emails to, by default the login of the current account.
+send_email(email) :: Deliver a given Mail::Message instance.

data/doc/http_basic_auth.rdoc

@@ -3,7 +3,16 @@
 The HTTP basic auth feature allows logins using HTTP basic authentication,
 described in RFC 1945.
 
+In your routing block, you can require HTTP basic authentication via:
+
+  rodauth.require_http_basic_auth
+
+If you want to allow HTTP basic authentication but not require it, you can
+call:
+
+  rodauth.http_basic_auth
+
 == Auth Value Methods
 
 http_basic_auth_realm :: The realm to return in the WWW-Authenticate header.
-require_http_basic_auth :: If true, when +rodauth.require_authentication+ is used, return a 401 status if basic auth has not been provided, instead of redirecting to the login page. False by default.
+require_http_basic_auth? :: If true, when +rodauth.require_login+ or +rodauth.require_authentication+ is used, return a 401 status page if basic auth has not been provided, instead of redirecting to the login page. If false, +rodauth.require_login+ or +rodauth.require_authentication+ will check for HTTP basic authentication if not already logged in.  False by default.

data/doc/internals.rdoc

@@ -183,7 +183,7 @@ Here's a heavily commented example showing what is going on inside a Rodauth fea
           foo_view
         end
 
-        # Just like in Roda, r.post is called for GET requests
+        # Just like in Roda, r.post is called for POST requests
         r.post do
           # This is called before performing the foo action
           before_foo

data/doc/jwt.rdoc

@@ -2,7 +2,7 @@
 
 The jwt feature adds support for JSON API access for all other features
 that ship with Rodauth, using JWT (JSON Web Tokens) to hold the
-authentication data.
+session information.
 
 When this feature is used, all other features become accessible via a
 JSON API.  The JSON API uses the POST method for all requests, using
@@ -10,10 +10,10 @@ the same parameter names as the features uses.  JSON API requests to
 Rodauth endpoints that use a method other than POST will result in a
 405 Method Not Allowed response.
 
-Responses are returned as JSON hashes.  In case of an error, the "error"
-entry is set to an error message, and the "field-error" entry is set to
+Responses are returned as JSON hashes.  In case of an error, the +error+
+entry is set to an error message, and the <tt>field-error</tt> entry is set to
 an array containing the field name and the error message for that field.
-Successful requests by default store a "success" entry with a success
+Successful requests by default store a +success+ entry with a success
 message, though that can be disabled.
 
 In order to use this feature, you have to set the +jwt_secret+ configuration
@@ -26,42 +26,42 @@ future requests, if the response Authorization header is set. If the
 response Authorization header is not set, then continue to use the
 previous Authorization header.
 
-When using this feature, consider using the :json=>:only option when
+When using this feature, consider using the <tt>json: :only</tt> option when
 loading the rodauth plugin, if you want Rodauth to only handle
-JSON requests.  If you don't use the :json=>:only option, the jwt feature
+JSON requests.  If you don't use the <tt>json: :only</tt> option, the jwt feature
 will probably result in an error if a request to a Rodauth endpoint comes
 in with a Content-Type that isn't application/json, unless you also set
 <tt>only_json? false</tt> in your rodauth configuration.
 
 If you would like to check if a valid JWT was submitted with the current
-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.
+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+.
 
 == 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.
-json_accept_regexp :: The regexp to use to check the Accept header for JSON if jwt_check_accept? is true.
+json_accept_regexp :: The regexp to use to check the Accept header for JSON if +jwt_check_accept?+ is true.
 json_non_post_error_message :: The error message to use when a JSON non-POST request is sent.
-json_not_accepted_error_message :: The error message to display if jwt_check_accept? is true and the Accept header is present but does not match json_request_content_type_regexp.
+json_not_accepted_error_message :: The error message to display if +jwt_check_accept?+ is true and the Accept header is present but does not match +json_request_content_type_regexp+.
 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, application/json by default.
-json_response_custom_error_status? :: Whether to use custom error statuses, instead of always using +json_response_error_status+, false by default for backwards compatibility.
-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, 400 by default.
-json_response_field_error_key :: The JSON result key containing an field error message, "field-error" by default.
-json_response_success_key :: The JSON result key containing a success message for successful request, if set.  nil by default to not set success messages.
-jwt_algorithm :: The JWT algorithm to use, "HS256" by default.
+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_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.
+json_response_success_key :: The JSON result key containing a success message for successful request, if set.  +success+ by default.
+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_check_accept? :: Whether to check the Accept header to see if the client supports JSON responses, false by default for backwards compatibility.
-jwt_decode_opts :: An optional hash to pass to JWT.decode. Can be used to set JWT verifiers.
+jwt_check_accept? :: Whether to check the Accept header to see if the client supports JSON responses, true by default, can be set to false for backwards compatibility with Rodauth 1.
+jwt_decode_opts :: An optional hash to pass to +JWT.decode+. Can be used to set JWT verifiers.
 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.
 non_json_request_error_message :: The error message to use when a non-JSON request is sent and +only_json?+ is set.
-only_json? :: Whether to have Rodauth only allow JSON requests.  True by default if :json=>:only option was given when loading the plugin.  If set, rodauth endpoints will issue an error for non-JSON requests.
-use_jwt? :: Whether to use the JWT in the Authorization header for authentication information.  If false, falls back to using the rack session. By default, the Authorization header is used if it is present, if only_json? is true, or if the request uses a json content type.
+only_json? :: Whether to have Rodauth only allow JSON requests.  True by default if <tt>json: :only</tt> option was given when loading the plugin.  If set, rodauth endpoints will issue an error for non-JSON requests.
+use_jwt? :: Whether to use the JWT in the Authorization header for authentication information.  If false, falls back to using the rack session. By default, the Authorization header is used if it is present, if +only_json?+ is true, or if the request uses a json content type.
 
 == Auth Methods
 

data/doc/jwt_cors.rdoc

@@ -0,0 +1,22 @@
+= Documentation for JWT CORS Feature
+
+The jwt_cors feature adds support for Cross-Origin Resource Sharing
+to Rodauth's JSON API.
+
+When this feature is used, CORS requests are handled.  This includes
+CORS preflight requests, which are required since Rodauth's JSON API
+uses the application/json request content type.
+
+This feature depends on the jwt feature.
+
+== Auth Value Methods
+
+jwt_cors_allow_headers :: For allowed CORS-preflight requests, the value returned in the Access-Control-Allow-Headers header (default: 'Content-Type, Authorization, Accept'). This specifies which headers can be included in CORS requests.
+jwt_cors_allow_methods :: For allowed CORS-preflight requests, the value returned in the Access-Control-Allow-Methods header (default: 'POST'). This specifies which methods are allowed in CORS requests.
+jwt_cors_allow_origin :: Which origins are allowed to perform CORS requests.  The default is +false+.  This can be a String, Array of Strings, Regexp, or +true+ to allow CORS requests from any domain.
+jwt_cors_expose_headers :: For allowed CORS requests, the value returned in the Access-Control-Expose-Headers header (default: 'Authorization'). This specifies which headers the browser is allowed to access from a response to a CORS request.
+jwt_cors_max_age :: For allowed CORS-preflight requests, the value returned in the Access-Control-Max-Age header (default: 86400). This specifies how long before the information returned should be considered stale and another CORS preflight request made.
+
+== Auth Methods
+
+jwt_cors_allow? :: Whether the request should be allowed.  This is called for all requests for a Rodauth route that include an Origin header.  It should return true or false for whether to specially handle the cross-origin request.  By default, uses the +jwt_cors_allow_origin+ setting to check the origin.

data/doc/jwt_refresh.rdoc

@@ -5,11 +5,13 @@ setting a short lifetime on JWT access tokens.
 
 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 /jwt-refresh.
+header), and for any subsequent POST to <tt>/jwt-refresh</tt>.
 
-Note that using the refresh token invalides the old refresh token and creates
+Note that using the refresh token invalides 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.
+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
+as soon as the refresh token is used.
 
 This feature depends on the jwt feature.
 
@@ -18,18 +20,20 @@ This feature depends on the jwt feature.
 jwt_access_token_key :: Name of the key in the response json holding the access token.  Default is +access_token+.
 jwt_access_token_not_before_period :: How many seconds before the current time will the jwt be considered valid (to account for inaccurate clocks). Default is 5.
 jwt_access_token_period :: Validity of an access token in seconds, default is 1800 (30 minutes).
+jwt_refresh_route :: The route to the login action. Defaults to <tt>jwt-refresh</tt>.
 jwt_refresh_invalid_token_message :: Error message when the provided refresh token is non existent, invalid or expired.
-jwt_refresh_token_account_id_column :: The column name in the refresh token table storing the account id, should be a foreign key referencing the accounts table.
-jwt_refresh_token_deadline_column :: The column name in the refresh token keys table storing the deadline after which the refresh token will no longer be valid.
-jwt_refresh_token_deadline_interval :: validity of a refresh token. Default is 14 days.
+jwt_refresh_token_account_id_column :: The column name in the +jwt_refresh_token_table+ storing the account id, should be a foreign key referencing the accounts table.
+jwt_refresh_token_deadline_column :: The column name in the +jwt_refresh_token_table+ storing the deadline after which the refresh token will no longer be valid.
+jwt_refresh_token_deadline_interval :: Validity of a refresh token. Default is 14 days.
 jwt_refresh_token_id_column :: The column name in the refresh token keys table storing the id of each token (the primary key of the table).
 jwt_refresh_token_key :: Name of the key in the response json holding the refresh token.  Default is +refresh_token+.
-jwt_refresh_token_key_column :: The column name in the refresh token keys table holding the refresh token key value.
+jwt_refresh_token_key_column :: The column name in the +jwt_refresh_token_table+ holding the refresh token key value.
 jwt_refresh_token_key_param :: Name of parameter in which the refresh token is provided when requesting a new token.  Default is +refresh_token+.
 jwt_refresh_token_table :: Name of the table holding refresh token keys.
 
 == Auth Methods
 
-after_refresh_token :: Hooks for specific processing once the refresh token has been set.
 account_from_refresh_token(token) :: Returns the account hash for the given refresh token.
+after_refresh_token :: Hooks for specific processing once the refresh token has been set.
+before_jwt_refresh_route :: Run arbitrary code before handling a jwt_refresh route.
 before_refresh_token :: Hooks for specific processing before the refresh token is computed.

data/doc/lockout.rdoc

@@ -8,37 +8,39 @@ unlock via an email sent to them.
 
 == Auth Value Methods
 
-account_lockouts_id_column :: The id column in the account lockouts table, should be a foreign key referencing the accounts table.
-account_lockouts_deadline_column :: The deadline column in the account lockouts table, containing how long the account is locked out until.
-account_lockouts_deadline_interval :: The amount of time for which to lock out accounts, 1 day by default. Only used if set_deadline_values?  is true.
-account_lockouts_email_last_sent_column :: The email last sent column in the account lockouts table.  nil by default, so an unlock account email is always sent when requested by default.
-account_lockouts_key_column :: The unlock key column in the account lockouts table.
+account_lockouts_deadline_column :: The deadline column in the +account_lockouts_table+, containing the timestamp until which the account is locked out.
+account_lockouts_deadline_interval :: The amount of time for which to lock out accounts, 1 day by default. Only used if +set_deadline_values?+ is true.
+account_lockouts_email_last_sent_column :: The email last sent column in the +account_lockouts_table+.  Set to nil to always send an unlock account email when requested.
+account_lockouts_id_column :: The id column in the +account_lockouts_table+, should be a foreign key referencing the accounts table.
+account_lockouts_key_column :: The unlock key column in the +account_lockouts_table+.
 account_lockouts_table :: The table containing account lockout information.
-account_login_failures_id_column :: The id column in the account login failures table, should be a foreign key referencing the accounts table.
-account_login_failures_number_column :: The column in the account login failures table containing the number of login failures for the account.
+account_login_failures_id_column :: The id column in the +account_login_failures_table+, should be a foreign key referencing the accounts table.
+account_login_failures_number_column :: The column in the +account_login_failures_table+ containing the number of login failures for the account.
 account_login_failures_table :: The table containing number of login failures per account.
 login_lockout_error_flash :: The flash error to show if there if the account is or becomes locked out after a login attempt.
-max_invalid_logins :: The maximum number of failed logins before account lockout. As this feature is just designed for bruteforce protection, this is set to 100.
+max_invalid_logins :: The maximum number of failed logins before account lockout. As this feature is just designed for bruteforce protection, this defaults to 100.
 no_matching_unlock_account_key_error_flash :: The flash error message to show if attempting to access the unlock account form with an invalid key.
 unlock_account_additional_form_tags :: HTML fragment with additional form tags to use on the unlock account form.
-unlock_account_autologin? :: Whether to autologin users after successful account unlock.
+unlock_account_autologin? :: Whether to autologin users after successful account unlock. This defaults to true, as otherwise an attacker can prevent an account from logging in by continually locking out their account.
 unlock_account_button :: The text to use on the unlock account button.
 unlock_account_email_recently_sent_error_flash :: The flash error to show if not sending an unlock account email because another was sent recently.
 unlock_account_email_recently_sent_redirect :: Where to redirect after not sending an unlock account email because another was sent recently.
 unlock_account_email_subject :: The subject to use for the unlock account email.
-unlock_account_explanatory_text :: The text to display above the button to unlock an account.
 unlock_account_error_flash :: The flash error to display upon unsuccessful account unlock.
+unlock_account_explanatory_text :: The text to display above the button to unlock an account.
 unlock_account_key_param :: The parameter name to use for the unlock account key.
 unlock_account_notice_flash :: The flash notice to display upon successful account unlock.
+unlock_account_page_title :: The page title to use on the unlock account form.
 unlock_account_redirect :: Where to redirect after successful account unlock.
 unlock_account_request_additional_form_tags :: HTML fragment with additional form tags to use on the form to request an account unlock.
 unlock_account_request_button :: The text to use on the unlock account request button.
 unlock_account_request_explanatory_text :: The text to display above the button to request an account unlock.
 unlock_account_request_notice_flash :: The flash notice to display upon successful sending of the unlock account email.
-unlock_account_request_redirect :: Where to redirect after account unlock email is sent.
+unlock_account_request_page_title :: The page title to use on the unlock account request form.
+unlock_account_request_redirect :: Where to redirect after the account unlock email is sent.
 unlock_account_request_route :: The route to the unlock account request action.  Defaults to +unlock-account-request+.
 unlock_account_requires_password? :: Whether a password is required when unlocking accounts, false by default.  May want to set to true if not allowing password resets.
-unlock_account_route :: Alias for lockout_route.
+unlock_account_route :: The route to the unlock account action.  Defaults to +unlock-account+.
 unlock_account_session_key :: The key in the session to hold the unlock account key temporarily.
 unlock_account_skip_resend_email_within :: The number of seconds before sending another unlock account email, if +account_lockouts_email_last_sent_column+ is set.
 
@@ -55,15 +57,15 @@ before_unlock_account_route :: Run arbitrary code before handling an unlock acco
 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.
-get_unlock_account_email_last_sent :: Get the last time an unlock_account email is sent, or nil if there is no last sent time.
+get_unlock_account_email_last_sent :: Get the last time an unlock account email is sent, or nil if there is no last sent time.
 get_unlock_account_key :: Retrieve the unlock account key for the current account.
-invalid_login_attempt :: Record an invalid login attempt, incrementing the number of login failures, and possibly locking out the account.
+invalid_login_attempted :: Record an invalid login attempt, incrementing the number of login failures, and possibly locking out the account.
 locked_out? :: Whether the current account is locked out.
 send_unlock_account_email :: Send the account unlock email.
 set_unlock_account_email_last_sent :: Set the last time an unlock_account email is sent.
+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 :: Unlock the account.
 unlock_account_key :: The unlock account key for the current account.
 unlock_account_request_view :: The HTML to use for the unlock account request form.
 unlock_account_view :: The HTML to use for the unlock account form.