rodauth 0.10.0 → 1.0.0

data/doc/disallow_password_reuse.rdoc

@@ -0,0 +1,37 @@
+= Documentation for Disallow Password Reuse Feature
+
+The disallow password reuse feature disallows setting of a password
+that matches a number of previous passwords (6 by default).
+
+On databases where Rodauth supports the use of database authentication
+functions, Rodauth also supports the use of database functions for checking
+previous passwords, so previous password hashes enjoy the same database
+security as current password hashes.
+
+It is not recommended to use this feature unless you have a policy that
+requires it.  This will significantly slow down setting a new password
+due to the need to check all of the previous stored passwords.  Additionally,
+storing previous passwords means that if attackers can get access to the
+the database, they can get the previous stored passwords in addition to the
+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.
+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_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.

data/doc/email_base.rdoc

@@ -0,0 +1,19 @@
+= Documentation for Email Base Feature
+
+The email base feature is automatically loaded when you use a Rodauth feature
+that requires sending emails.
+
+== Auth Value Methods
+
+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.
+token_separator :: The string used to separate account id from the random key in links.
+
+== 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.

data/doc/jwt.rdoc

@@ -0,0 +1,35 @@
+= Documentation for JWT Feature
+
+The jwt feature adds support for JSON API access for all other features
+that ship with Rodauth, using JWT as the token format.
+
+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
+the same parameter names as the features uses.
+
+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
+an array containing the field name and the error message for that field.
+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
+option the secret used to cryptographically protect the token.
+
+== Auth Value Methods
+
+json_non_post_error_message :: The error message to use when a JSON non-POST request is sent.
+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.
+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, which means that rodauth will issue an error for non-JSON requests.
+jwt_secret :: The JWT secret to use.  Access to this should be protected the same as a session secret.
+
+== Auth Methods
+
+json_request? :: Whether the current request is a JSON request, looks at the Content-Type request header by default.
+jwt_token :: Retrieve the JWT token from the request, by default taking it from the Authorization header.
+set_jwt_token(token) :: Set the JWT token in the response, by default storing it in the Authorization header.

data/doc/lockout.rdoc

@@ -0,0 +1,83 @@
+= Documentation for Lockout Feature
+
+The lockout feature implements bruteforce protection for accounts.
+It depends on the login feature.  If a user fails to login due to
+a password error more than a given number of times, their account
+gets locked out, and they are given an option to request an account
+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.
+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_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.
+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_button :: The text to use on the unlock account button.
+unlock_account_email_subject :: The subject to use for the unlock account email.
+unlock_account_error_flash :: The flash error to display upon unsuccessful account unlock.
+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_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_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_route :: The route to the unlock account request action.
+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.
+
+== Auth Methods
+
+account_from_unlock_key(key) :: Retrieve the account using the given verify
+                                account key, or return nil if no account
+                                matches. 
+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_lockout_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.
+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.
+locked_out? :: Whether the current account is locked out.
+send_unlock_account_email :: Send the account unlock email.
+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.

data/doc/login.rdoc

@@ -0,0 +1,27 @@
+= Documentation for Login Feature
+
+The login feature implements a login page.  It's the most commonly
+used feature.
+
+== Auth Value Methods
+
+login_additional_form_tags :: HTML fragment containing additional form
+                              tags to use on the login form.
+login_button :: The text to use for the login button.
+login_error_flash :: The flash error to show for an unsuccesful login.
+login_form_footer :: A message to display after the login form.
+login_notice_flash :: The flash notice to show after successful login.
+login_redirect :: Where to redirect after a sucessful login.
+login_route :: The route to the login action.
+
+== Auth Methods
+
+after_login :: Run arbitrary code after a successful login.
+after_login_failure :: Run arbitrary code after a login failure due to
+                       an invalid password.
+before_login :: Run arbitrary code after password has been checked, but
+                before updating the session.
+before_login_attempt :: Run arbitrary code after an account has been
+                        located, but before the password has been checked.
+before_login_route :: Run arbitrary code before handling a login route.
+login_view :: The HTML to use for the login form.

data/doc/login_password_requirements_base.rdoc

@@ -0,0 +1,50 @@
+= Documentation for Login Password Requirements Base Feature
+
+The login password requirements base feature is automatically loaded when you
+use a Rodauth feature that requires setting logins or passwords.
+
+== Auth Value Methods
+
+login_confirm_label :: The label to use for login confirmations.
+login_confirm_param :: The parameter name to use for login confirmations.
+login_does_not_meet_requirements_message :: The error message to display when
+                                            the login does not meet the
+                                            requirements you have set.
+login_minimum_length :: The minimum length for logins, 3 by default.
+login_too_short_message :: The error message fragment to show if the login is
+                           too short.
+logins_do_not_match_message :: The error message to display when login and
+                               login confirmation do not match.
+password_confirm_label :: The label to use for password confirmations.
+password_confirm_param :: The parameter name to use for password confirmations.
+password_does_not_meet_requirements_message :: The error message to display when
+                                               the password does not meet the
+                                               requirements you have set.
+password_hash_cost :: The bcrypt cost to use for the password hash.
+password_minimum_length :: The minimum length for passwords, 6 by default.
+password_too_short_message :: The error message fragment to show if the password
+                              is too short.
+passwords_do_not_match_message :: The error message to display when password
+                                  and password confirmation do not match.
+require_email_address_logins? :: Whether logins need to be valid email addresses,
+                                 true by default.
+require_login_confirmation? :: Whether login confirmations are required when
+                               changing logins or creating accounts.
+require_password_confirmation? :: Whether password confirmations are required
+                                  when changing/resetting passwords and creating
+                                  accounts.
+same_as_existing_password_message :: The error message to display when a new
+                                     password is the same as the existing password.
+
+== Auth Methods
+
+login_meets_requirements?(login) :: Whether the given login meets the requirements.
+                                    By default, just checks that the login is a
+                                    valid email address.
+password_meets_requirements?(password) :: Whether the given password meets the
+                                          requirements. Can be used to implement
+                                          complexity requirements for passwords.
+password_hash(password) :: A hash of the given password.
+set_password(password) :: Set the password for the current account to the given
+                          password.
+

data/doc/logout.rdoc

@@ -0,0 +1,21 @@
+= Documentation for Logout Feature
+
+The logout feature implements a logout button, which clears the session.
+It is the simplest feature.
+
+== Auth Value Methods
+
+logout_additional_form_tags :: HTML fragment containing additional form
+                               tags to use on the logout form.
+logout_button :: The text to use for the logout button.
+logout_notice_flash :: The flash notice to show after logout.
+logout_redirect :: Where to redirect after a logout.
+logout_route :: The route to the logout action.
+
+== Auth Methods
+
+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_view :: The HTML to use for the logout form.

data/doc/otp.rdoc

@@ -0,0 +1,100 @@
+= Documentation for OTP Feature
+
+The otp feature implements a 2 factor authentication via time-based one-time
+passwords (TOTP).  It supports signing up for 2 factor authentication, logging
+in with authentication codes, and disabling two factor authentication.
+
+The otp feature requires the rotp and rqrcode gems.
+
+== Auth Value Methods
+
+otp_already_setup_error_flash :: The flash error to show if going to the OTP setup
+                                 page when OTP is already setup.
+otp_already_setup_redirect :: Where to redirect if going to the OTP setup page when OTP
+                              has already been setup.
+otp_auth_additional_form_tags :: HTML fragment containing additional form tags to use on
+                                 the OTP authentication form.
+otp_auth_button :: Text to use for button on OTP authentication form.
+otp_auth_error_flash :: The flash error to show if unable to authenticate via OTP.
+otp_auth_failures_limit :: The number of allowed OTP authentication failures before locking
+                           out.
+otp_auth_form_footer :: A footer to display at the bottom of the OTP authentication form.
+otp_auth_label :: The label for the OTP authentication code.
+otp_auth_param :: The parameter name for the OTP authentication code.
+otp_auth_route :: The route to the OTP authentication action.
+otp_class :: The class to use for OTP authentication (default: ROTP::TOTP)
+otp_digits :: The number of digits to use in OTP authentication codes (rotp's default is 6).
+otp_disable_additional_form_tags :: HTML fragment containing additional form tags to use on
+                                    the from to disable OTP authentication.
+otp_disable_button :: The text to use for button on form to disable OTP authentication.
+otp_disable_error_flash :: The flash error to show if unable to disable OTP authentication.
+otp_disable_notice_flash :: The flash notice to show after disabling OTP authentication.
+otp_disable_redirect :: Where to redirect after disabling OTP authentication.
+otp_disable_route :: The route to the OTP disable action.
+otp_invalid_auth_code_message :: The error message to show when an invalid OTP authentication
+                                 code is used.
+otp_invalid_secret_message :: The error message to show when an invalid OTP secret is submitted
+                              during OTP setup.
+otp_interval :: The number of seconds in which to rotate TOTP auth codes (rotp's default is 300).
+otp_issuer :: The issuer to use in the OTP provisioning URL.  Defaults to the host name of the
+              request.
+otp_keys_id_column :: The column in the otp_keys_table containing the account id.
+otp_keys_column :: The column in the otp_keys_table containing the OTP secret.
+otp_keys_failures_column :: The column in the otp_keys_table containing the
+                            number of OTP authentication failures.
+otp_keys_last_use_column :: The column in otp_keys_table containing the last authentication
+                            timestamp.
+otp_keys_table :: The table name containing the OTP secrets.
+otp_lockout_redirect :: Where to redirect if going to OTP authentication page and OTP
+                        authentication has been locked out.
+otp_lockout_error_flash :: The flash error show show when OTP authentication has been locked
+                           out due to numerous authentication failures.
+otp_modifications_require_password? :: Whether modifying OTP settings requires reentering the
+                                       password for the account, true by default.
+otp_session_key :: The session key used to store whether the user has authenticated via OTP.
+otp_setup_additional_form_tags :: HTML fragment containing additional form tags when setting up
+                                  OTP authentication.
+otp_setup_button :: Text for the button when setting up OTP authentication.
+otp_setup_error_flash :: The flash error to show if OTP authentication setup was not successful.
+otp_setup_notice_flash :: The flash notice to show if OTP authentication setup was successful.
+otp_setup_param :: The parameter name used for the OTP secret when setting up OTP authentication.
+otp_setup_redirect :: Where to redirect after sucessful OTP authentication setup.
+otp_setup_route :: The route to the OTP setup action.
+
+== Auth Methods
+
+after_otp_authentication_failure :: Run arbitrary code after OTP authentication failure.
+after_otp_disable :: Run arbitrary code after OTP authentication has been disabled.
+after_otp_setup :: Run arbitrary code after OTP authentication has been setup.
+before_otp_authentication :: Run arbitrary code before OTP authentication.
+before_otp_authentication_route :: Run arbitrary code before handling an OTP authentication route.
+before_otp_setup :: Run arbitrary code before OTP authentication setup.
+before_otp_setup_route :: Run arbitrary code before handling an OTP authentication setup route.
+before_otp_disable :: Run arbitrary code before OTP authentication disabling.
+before_otp_disable_route :: Run arbitrary code before handling an OTP authentication disable route.
+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_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.
+otp_locked_out? :: Whether the current account has been locked out of OTP authentication.
+otp_new_secret :: A new secret to use when setting up OTP.
+otp_provisioning_name :: The provisioning name to use during OTP setup, defaults to the
+                         account's email.
+otp_provisioning_uri :: The provisioning URI displayed during OTP setup.
+otp_qr_code :: The QR code containing the otp_provisioning_uri, by default an SVG image.
+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 OTP authentication.
+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 OTP key.
+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?(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/password_complexity.rdoc

@@ -0,0 +1,50 @@
+= Documentation for Password Complexity Feature
+
+The password complexity feature implements more sophisticated password
+complexity checks.  It is not recommended to use this feature unless
+you have a policy that requires it, as users that would not choose a
+good password in the absense of password complexity requirements are
+unlikely to choose a good password if you have password complexity
+requirements.
+
+Checks:
+
+* Contains characters in multiple character groups, by default at
+  least 3 of uppercase letters, lowercase letters, numbers, and
+  everything else, unless the password is over 11 characters.
+* Does not contain any invalid patterns, by default patterns like
+  +qwerty+, +azerty+, +asdf+, +zxcv+, or number sequences such as +123+.
+* Does not contain a certain number of repeating characters, by default 3.
+* Is not a dictionary word, after stripping off numbers from the prefix
+  and suffix and replacing some common numbers/symbols often substituted
+  for letters, catching things like <tt>P@$$w0rd1</tt>.
+
+== Auth Value Methods
+
+password_character_groups :: An array of regular expressions representing
+                             different character groups.
+password_dictionary :: A Array/Hash/Set containing dictionary words, which cannot
+                       match the password.
+password_dictionary_file :: A file containing dictionary words, which will not be allowed.
+                            By default, <tt>/usr/share/dict/words</tt> if present.  Set to
+                            false to not use a password dictionary. Note that this is only
+                            used during initialization, and cannot refer to request-specific
+                            state, unlike most other settings.
+password_in_dictionary_message :: The error message fragment to show if the password
+                                  is derived from a word in a dictionary.
+password_invalid_pattern :: A regexp where any match is considered an invalid password.
+                            For multiple sequences, use +Regexp.union+.
+password_invalid_pattern_message :: The error message fragment to show if the password
+                                    matches the invalid pattern.
+password_max_length_for_groups_check :: The number of characters above which
+                                        to skip the checks for character groups.
+password_max_repeating_characters :: The maximum number of repeating characters allowed.
+password_min_groups :: The minimum number of character groups the password
+                       has to contain if it is less than
+                       +password_max_length_for_groups_check+ characters.
+password_not_enough_character_groups_message :: The error message fragment to show if the
+                                                password does not contain characters from
+                                                enough character groups.
+password_too_many_repeating_characters_message :: The error message fragment to show if the
+                                                  password contains too many repeating
+                                                  characters.

data/doc/password_expiration.rdoc

@@ -0,0 +1,52 @@
+= Documentation for Password Expiration Feature
+
+The password expiration feature requires that users change their
+password on login if it has expired (default: every 90 days). You can
+force password expiration checks for all logged in users by adding
+the following code to your route block:
+
+   rodauth.require_current_password
+
+Additionally, you can set a minimum amount of time after a password
+is changed until it can be changed again.  By default this is not
+enabled, but it can be enabled by setting +allow_password_change_after+
+to a positive number of seconds.
+
+It is not recommended to use this feature unless you have a policy that
+requires it, as password expiration in general results in users chosing
+weaker passwords.  When asked to change their password, many users choose
+a password that is based on their previous password, so forcing password
+expiration is in general a net loss from a security perspective.
+
+== Auth Value Methods
+
+allow_password_change_after :: How long in seconds after the last password change
+                               until another password change is allowed (0 by default).
+password_expiration_error_flash :: The flash error to display when the account's
+                                   password has expired and needs to be changed.
+password_not_changeable_yet_error_flash :: The flash error to display when not
+                                           enough time has elapsed since the last
+                                           password change and an attempt is made
+                                           to change the password.
+password_not_changeable_yet_redirect :: Where to redirect if the password cannot
+                                        be changed yet.
+password_change_needed_redirect :: Where to redirect if a password needs to be
+                                   changes.
+password_changed_at_session_key :: The key in the session storing the timestamp the password
+                                   was changed at.
+password_expiration_default :: If the last password change time for an account cannot
+                               be determined, whether to consider the account expired,
+                               false by default.
+password_expiration_table :: The table holding the password last changed timestamps.
+password_expiration_id_column :: The column in the +password_expiration_table+ containing
+                                 the account's id.
+password_expiration_changed_at_column :: The column in the +password_expiration_table+
+                                         containing the timestamp
+require_password_change_after :: How long in seconds until a password change is
+                                 required (90 days by default).
+
+== Auth Methods
+
+password_expired? :: Whether the password has expired for the related account.
+update_password_changed_at :: Update the password last changed timestamp for the
+                              current account.