rodauth 0.10.0 → 1.0.0

data/doc/remember.rdoc

@@ -0,0 +1,82 @@
+= Documentation for Remember Feature
+
+The remember feature allows for token-based autologin for users. It records
+which sessions were autologged in via a token, and allows you to request
+password confirmation later for such sessions if they are accessing a
+section requiring more security.  The remember feature depends on the
+logout feature.
+
+== Auth Value Methods
+
+extend_remember_deadline? :: Whether to extend the remember token deadline
+                             when the user is autologged in via token.
+remember_additional_form_tags :: HTML fragment containing additional
+                                 form tags to use on the change remember 
+                                 setting form.
+remember_button :: The text to use for the change remember settings button.
+remember_cookie_key :: The cookie name to use for the remember token.
+remember_cookie_options :: Any options to set for the remember cookie.
+remember_deadline_column :: The column name in the remember keys table storing
+                            the deadline after which the token will be
+                            ignored.
+remember_deadline_interval :: The amount of time for which to remember accounts,
+                              14 days by default.
+remember_disable_label :: The label for disabling remembering.
+remember_disable_param_value :: The parameter value for disabling remembering.
+remember_error_flash :: The flash error to show if there is an error changing a
+                        remember setting.
+remember_forget_label :: The label for turning off remembering.
+remember_forget_param_value :: The parameter value for turning off remembering.
+remember_id_column :: The id column in the remember keys table, should be a
+                      foreign key referencing the accounts table.
+remember_key_column :: The remember key/token column in the remember keys table.
+remember_notice_flash :: The flash notice to show after remember setting
+                         has been updated.
+remember_period :: The additional time to extend the remember deadline if
+                   extending remember deadlines.
+remember_redirect :: Where to redirect after changing the remember settings.
+remember_remember_param_value :: The parameter value for switching on remembering.
+remember_remember_label :: The label for turning on remembering.
+remember_route :: The route to the change remember settings action.
+remember_table :: The name of the remember keys table.
+remember_param :: The parameter name to use for the remember password settings
+                  choice.
+remembered_session_key :: The key in the session storing whether the current
+                          session has been autologged in via remember token.
+
+
+== Auth Methods
+
+add_remember_key :: Add a remember key for the current account to the remember
+                    keys table.
+after_load_memory :: Run arbitrary code after autologging in an account via
+                     a remember token.
+after_remember :: Run arbitrary code after changing the remember settings.
+before_load_memory :: Run arbitrary code before autologging in an account via
+                      a remember token.
+before_remember :: Run arbitrary code before changing the remember settings.
+before_remember_route :: Run arbitrary code before handling the remember route.
+clear_remembered_session_key :: Clear the flag for whether the current
+                                account was autologged in via token, called
+                                after successful password confirmation.
+disable_remember_login :: Disable the remember key token, clearing the token
+                          from the database so future connections with the
+                          token will not be recognized.
+forget_login :: Forget the current remember token, deleting the related cookie.
+                Other browsers that have the cookie cached can still use it
+                login.
+generate_remember_key_value :: A random string to use as the remember key.
+get_remember_key :: Retrieve the remember key from the database.
+load_memory :: If the remember key cookie is included in the request, and the
+               user is not currently logged in, check the remember keys table
+               and autologin the user if the remember key cookie matches the
+               current remember key for the account. This method needs to be
+               called manually inside the Roda route block to autologin users.
+logged_in_via_remember_key? :: Whether the current session was logged in via
+                               a remember key.
+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_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

@@ -0,0 +1,70 @@
+= Documentation for Reset Password Feature
+
+The reset password feature implements password resets.  If the user enters
+an invalid password, they will be displayed a form where they can request
+a password reset.  Submitting that form will send an email containing a
+link, and that link will taken them to a password reset form. Depends on
+the login feature.
+
+== Auth Value Methods
+
+no_matching_reset_password_key_message :: The flash error message to show if attempting
+                                          to access the reset password form with an
+                                          invalid key.
+reset_password_additional_form_tags :: HTML fragment containing additional form
+                                       tags to use on the reset password form.
+reset_password_autologin? :: Whether to autologin the user after successfully
+                             resetting a password.
+reset_password_button :: The text to use for the reset password button.
+reset_password_deadline_column :: The column name in the reset password keys table storing
+                                  the deadline after which the token will be ignored.
+reset_password_deadline_interval :: The amount of time for which to allow users to
+                                    reset their passwords, 1 day by default.
+reset_password_email_sent_notice_flash :: The flash notice to show after a reset
+                                          password email has been sent.
+reset_password_email_sent_redirect :: Where to redirect after sending a reset
+                                      password email.
+reset_password_email_subject :: The subject to use for reset password emails.
+reset_password_error_flash :: The flash error to show after resetting a password.
+reset_password_id_column :: The id column in the reset password keys table, should
+                            be a foreign key referencing the accounts table.
+reset_password_key_column :: The reset password key/token column in the reset
+                             password keys table.
+reset_password_key_param :: The parameter name to use for the reset password key.
+reset_password_redirect :: Where to redirect after resetting a password.
+reset_password_request_additional_form_tags :: HTML fragment containing additional form
+                                               tags to use on the reset password request
+                                               form.
+reset_password_request_button :: The text to use for the reset password request button.
+reset_password_request_error_flash :: The flash error to show if not able to send a reset
+                                      password email.
+reset_password_request_route :: The route to the reset password request action.
+reset_password_route :: The route to the reset password action.
+reset_password_table :: The name of the reset password keys table.
+
+== Auth Methods
+
+account_from_reset_password_key(key) :: Retrieve the account using the given reset
+                                        password key, or return nil if no account
+                                        matches.
+after_reset_password :: Run arbitrary code after successfully resetting a password.
+after_reset_password_request :: Run arbitrary code after sending the reset password
+                                email.
+before_reset_password :: Run arbitrary code before resetting a password.
+before_reset_password_request :: Run arbitrary code before sending the reset password
+                                 email.
+before_reset_password_route :: Run arbitrary code before handling a reset password route.
+create_reset_password_key :: A random string to use as a reset password key.
+get_reset_password_key(id) :: Get the password reset key for the given account id
+                              from the database.
+create_reset_password_email :: A Mail::Message for the reset password email.
+remove_reset_password_key :: Remove the reset password key for the current account,
+                             run after successful password reset.
+reset_password_email_body :: The body to use for the reset password email.
+reset_password_email_link :: The link to the reset password form in the reset
+                             password email.
+reset_password_key_insert_hash :: The hash to insert into the reset password keys
+                                  table.
+reset_password_key_value :: The reset password key for the current account.
+reset_password_view :: The HTML to use for the reset password form.
+send_reset_password_email :: Send the reset password email.

data/doc/session_expiration.rdoc

@@ -0,0 +1,27 @@
+= Documentation for Session Expiration Feature
+
+The session expiration feature allows setting an inactivity timeout and a max
+lifetime for sessions.  When this feature is used, you should use
++rodauth.check_session_expiration+ at the top (or other appropriate place)
+in your routing tree.
+
+  route do |r|
+    rodauth.check_session_expiration
+    r.rodauth
+
+    # ...
+  end
+
+When checking session expiration, if the last activity was more than the
+inactivity timeout, or the session was created more the maximum lifetime
+ago, the session is cleared, and the user is redirected to the login page.
+
+== Auth Value Methods
+
+max_session_lifetime :: The maximum number of seconds since session creation that sessions will be valid for, regardless of session activity. 86400 by default (1 day).
+session_created_session_key :: The session key storing the session creation timestamp.
+session_expiration_default :: Whether to expire sessions that don't have the created at or last activity at timestamps set, true by default.
+session_expiration_error_flash :: The flash error to show if a session expires.
+session_expiration_redirect :: Where to redirect if a session expires.
+session_inactivity_timeout :: The maximum number of seconds allowed since the last activity before the session will be considered invalid.  1800 by default (30 minutes).
+session_last_activity_session_key :: The session key storing the last session activity timestamp.

data/doc/single_session.rdoc

@@ -0,0 +1,43 @@
+= Documentation for Single Session Feature
+
+The single session feature stores the key for the session in a
+database table whenever a user logs in to the system.  In your
+routing block, you can check that the session key given matches
+the stored key by doing:
+
+  rodauth.check_single_session
+
+Note that it is not recommended to use this feature unless you
+have a policy that requires it.  Many users find it useful to
+be able to have multiple concurrent sessions, and restricting
+this ability does not make things more secure.
+
+Note that one of the side benefits with this feature is that
+logouts reset the single session key, so attempts to reuse
+the previous session after logout no longer work.
+
+== Auth Value Methods
+
+single_session_id_column :: The column in the +single_session_table+ containing
+                            the account id.
+single_session_key_column :: The column in the +single_session_table+ containing
+                             the single session key.
+single_session_error_flash :: The flash error to display if the current session
+                              is no longer the active session for the account.
+single_session_redirect :: Where to redirect if the current session is no longer
+                           the active session for the account.
+single_session_session_key :: The session key name to use for storing the single
+                              session key.
+single_session_table :: The database table storing single session keys.
+
+== Auth Methods
+
+currently_active_session? :: Whether the current session is the active session for
+                             the user.
+no_longer_active_session :: The action to take if the current session is no longer
+                            the active session for the user.
+reset_single_session_key :: Reset the single session key for the user, by default
+                            to a new random key.
+update_single_session_key :: Update the single session key in the current session
+                             and in the database, reflecting that the current
+                             session is the active session for the user.

data/doc/sms_codes.rdoc

@@ -0,0 +1,119 @@
+= Documentation for SMS Codes Feature
+
+The sms codes feature allows 2nd factor authentication via codes provided via
+SMS messages.  It is usually used as a backup if OTP authentication is not available
+or has been locked out, but it can be used as the primary 2nd factor.
+
+This feature allows users to register their mobile phone number with the system, confirm that
+they can receive SMS messages on the mobile phone number they have registered, request
+SMS authentication codes, authenticate via SMS codes, and disable SMS authentication.
+
+While this feature sets up all of the infrastructure needed to support SMS authentication,
+it doesn't handle sending SMS messages itself.  There are many ruby libraries that send
+SMS messages, and you can choose which one to use.  When using this feature, you must
+use the +sms_send+ configuration method and send the SMS using whatever SMS library
+you prefer:
+
+    sms_send do |phone_number, message|
+      # ...
+    end
+
+== Auth Value Methods
+
+no_current_sms_code_error_flash :: The flash error to show when going to the SMS authentication page and no current SMS authentication code is available.
+sms_already_setup_error_flash :: The flash error to show when goign to a page to setup SMS authentication if SMS authentication has already been setup.
+sms_already_setup_redirect :: Where to redirect when going to a page to setup SMS authentication if SMS authentication has already been setup.
+sms_auth_additional_form_tags :: HTML fragment containing additional form tags when authenticating via SMS.
+sms_auth_button :: Text to use for button on form to authenticate via SMS.
+sms_auth_code_length :: The length of SMS authentication codes, 6 by default.
+sms_auth_redirect :: Where to redirect if SMS authentication is needed.
+sms_auth_route :: The route to the SMS authentication action.
+sms_code_allowed_seconds :: The number of seconds after an SMS authentication is sent until it is no longer valid, 300 seconds by default.
+sms_code_column :: The column in the +sms_codes_table+ containing the currently valid SMS authentication/confirmation code.
+sms_code_label :: The label for SMS codes.
+sms_code_param :: The parameter name for SMS codes.
+sms_codes_table :: The name of the table storing SMS code data.
+sms_codes_primary? :: Whether SMS codes are the primary 2nd factor authentication method, true by default if not using the otp feature.
+sms_confirm_additional_form_tags :: HTML fragment containing additional form tags when confirming SMS setup.
+sms_confirm_button :: Text to use for button on form to confirm SMS setup.
+sms_confirm_code_length :: The length of SMS confirmation codes, 12 by default, as there is no lockout. 
+sms_confirm_notice_flash :: The flash notice to show when SMS authentication setup has been confirmed.
+sms_confirm_redirect ::Where to redirect after SMS authentication setup has been confirmed.
+sms_confirm_route :: The route to the SMS setup confirmation action.
+sms_disable_additional_form_tags :: HTML fragment containing additional form tags when disabling SMS authentication.
+sms_disable_button :: Text to use for button on form to disable SMS authentication.
+sms_disable_error_flash :: The flash error to show when disabling SMS authentication fails.
+sms_disable_notice_flash :: The flash notice to show when SMS authentication has been successfully disabled.
+sms_disable_redirect :: Where to redirect after SMS authentication has been disabled.
+sms_disable_route :: The route to the SMS authentication disable action.
+sms_failure_limit :: The number of failures until SMS authentication is locked out.
+sms_failures_column :: The column in the +sms_codes_table+ containing the number of SMS authentication failures since the last successful authentication.
+sms_id_column :: The column in the +sms_codes_table+ containing the account id.
+sms_invalid_code_error_flash :: The flash error to show when an invalid SMS authentication code is used.
+sms_invalid_code_message :: The error message to show when an invalid SMS code is used.
+sms_invalid_confirmation_code_error_flash :: The flash error to show when an invalid SMS confirmation code is used.
+sms_invalid_phone_message :: The error message to show when an invalid SMS phone number is used.
+sms_issued_at_column :: The column in the +sms_codes_table+ containing the time the SMS code was issued.
+sms_lockout_error_flash :: The flash error to show when SMS authentication has been locked out due to repeated failures.
+sms_lockout_redirect :: Where to redirect after SMS authentication has been locked out.
+sms_needs_confirmation_error_flash :: The flash error to show on SMS authentication pages when SMS authentication setup needs confirmation.
+sms_needs_confirmation_redirect :: Where to redirect after SMS setup, when confirmation is required.
+sms_needs_setup_redirect :: Where to redirect if going to an SMS authentication page when SMS authentication has not been setup.
+sms_not_setup_error_flash :: The flash error to show when on SMS authentication pages when SMS authentication has not yet been setup.
+sms_phone_column :: The column in the +sms_codes_table+ containing the phone number to which to send SMS messages.
+sms_phone_label :: The label for SMS phone numbers.
+sms_phone_min_length :: The minimum length of phone numbers allowed for SMS authentication, 7 by default.
+sms_phone_param :: The parameter name for SMS phone numbers.
+sms_request_additional_form_tags :: HTML fragment containing additional form tags when requesting an SMS authentication code.
+sms_request_button :: Text to use for button on form to request an SMS authentication code.
+sms_request_notice_flash :: The flash notice to show when an SMS authentication code is requested.
+sms_request_redirect :: Where to redirect after requesting an SMS authentication code.
+sms_request_route :: The route to the SMS authentication code request action.
+sms_setup_additional_form_tags :: HTML fragment containing additional form tags when setting up SMS authentication.
+sms_setup_button :: Text to use for button on form to setup SMS authentication.
+sms_setup_error_flash :: The flash error to show when setting up SMS authentication fails.
+sms_setup_route :: The route to the SMS authentication setup action.
+
+== Auth Methods
+
+after_sms_confirm :: Run arbitrary code after successful SMS authentication confirmation.
+after_sms_disable :: Run arbitrary code after disabling SMS authentication.
+after_sms_failure :: Run arbitrary code after SMS authentication failure.
+after_sms_request :: Run arbitrary code after SMS authentication code request.
+after_sms_setup :: Run arbitrary code after SMS authentication setup.
+before_sms_auth :: Run arbitrary code before SMS authentication.
+before_sms_auth_route :: Run arbitrary code before handling SMS authentication route.
+before_sms_confirm :: Run arbitrary code before SMS confirmation.
+before_sms_confirm_route :: Run arbitrary code before handling SMS confirmation route.
+before_sms_disable :: Run arbitrary code before disabling SMS authentication.
+before_sms_disable_route :: Run arbitrary code before handling SMS disable route.
+before_sms_request :: Run arbitrary code before sending SMS code.
+before_sms_request_route :: Run arbitrary code before handling SMS request route.
+before_sms_setup :: Run arbitrary code before setting up SMS authentication.
+before_sms_setup_route :: Run arbitrary code before handling SMS setup route.
+sms_auth_message(code) :: The SMS message to use for the given authentication code.
+sms_auth_view :: The HTML to use for the form to authenticate via SMS code.
+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_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_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_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 SMS authentication.
+sms_request_view :: The HTML to use for the form to request an SMS authentication code.
+sms_send(phone, message) :: Send the given message to the given phone number via SMS.  By default a NotImplementedError is raised, this is the only method that must be overridden. 
+sms_set_code(code) :: Set the SMS authentication code for the current account to the given code.  The code can be +nil+ to specify that no SMS authentication code is currently valid.
+sms_setup :: Setup SMS authentication for the current account.
+sms_setup? :: Whether SMS authentication has been setup and confirmed for the current account.
+sms_setup_view :: The HTML to use for the form to setup SMS authentication.
+sms_valid_phone?(phone) :: Whether the given phone number is a valid phone number.

data/doc/two_factor_base.rdoc

@@ -0,0 +1,27 @@
+= Documentation for Two Factor Base Feature
+
+The two factor base feature implements shared functionality for the other 2nd
+factor authentication features.
+
+== Auth Value Methods
+
+two_factor_already_authenticated_error_flash :: The flash error to show if going to a two factor authentication page when already authenticated via 2nd factor
+two_factor_already_authenticated_redirect :: Where to redirect if going to a two factor authentication page when already authenticated via 2nd factor.
+two_factor_auth_notice_flash :: The flash notice to show after a successful two factor authentication.
+two_factor_auth_redirect :: Whether to redirect after a successful two factor authentication.
+two_factor_auth_required_redirect :: Where to redirect if going to a page requiring two factor authentication when not authenticated via 2nd factor.
+two_factor_modifications_require_password? :: Whether modifications to two factor authentication require the use of passwords.
+two_factor_need_authentication_error_flash :: The flash error to show if going to a page that requires two factor authentication when not authenticated.
+two_factor_need_setup_redirect :: Where to redirect if going to a two factor authentication page when two factor authentication has not been setup.
+two_factor_not_setup_error_flash :: The flash error to show if going to a two factor authentication page when two factor authentication has not been setup.
+two_factor_session_key :: The session key used for storing a symbol indicating which type of 2nd factor was used to authenticate.
+two_factor_setup_session_key :: The session key used for storing whether two factor authentication has been setup for the current account.
+
+== Auth Methods
+
+after_two_factor_authentication :: Any actions to take after successful two factor authentication.
+two_factor_authenticated? :: Whether the current session has already been authenticated via 2nd factor.
+two_factor_remove :: Any action to take to remove two factor authentication, called when closing accounts.
+two_factor_remove_auth_failures :: Any action to take to remove 2nd factor authentication failures, called after a successful 2nd factor authentication.
+two_factor_remove_session :: What actions to take to remove two factor authentication, called when disabling two factor authentication.
+two_factor_update_session(type) :: How to update the session to reflect a successful two factor authentication.

data/doc/verify_account.rdoc

@@ -0,0 +1,70 @@
+= Documentation for Verify Account Feature
+
+The verify account feature implements account verification after account
+creation.  After account creation, users are sent an email containing
+a link to verify the account. Users cannot login to the account until
+after verifying the account. Depends on the login and create account features.
+
+== Auth Value Methods
+
+attempt_to_create_unverified_account_notice_message :: Message displayed when attempting to
+                                                       create an account awaiting verification.
+attempt_to_login_to_unverified_account_notice_message :: Message displayed when attempting to
+                                                         login to an account awaiting verification.
+no_matching_verify_account_key_message :: The flash error message to show when
+                                          an invalid verify account key is used.
+verify_account_additional_form_tags :: HTML fragment containing additional form
+                                       tags to use on the verify account form.
+verify_account_autologin? :: Whether to autologin the user after successful
+                             account verification, true by default.
+verify_account_button :: The text to use for the verify account button.
+verify_account_email_subject :: The subject to use for the verify account email.
+verify_account_email_sent_redirect :: Where to redirect after sending the verify
+                                      account email.
+verify_account_email_sent_notice_flash :: The flash notice to set after sending
+                                          the verify account email.
+verify_account_error_flash :: The flash error to show if no matching key is submitted
+                              when verifying an account.
+verify_account_id_column :: The id column in the verify account keys table, should
+                            be a foreign key referencing the accounts table.
+verify_account_key_column :: The verify account key/token column in the verify
+                             account keys table.
+verify_account_key_param :: The parameter name to use for the verify account key.
+verify_account_notice_flash :: The flash notice to show after verifying the account.
+verify_account_resend_additional_form_tags :: HTML fragment containing additional form
+                                              tags to use on the page requesting
+                                              resending the verify account email.
+verify_account_resend_button :: The text to use for the verify account resend button.
+verify_account_redirect :: Where to redirect after verifying the account.
+verify_account_resend_error_flash :: The flash error to show if unable to resend a
+                                     verify account email.
+verify_account_resend_route :: The route to the verify account resend action.
+verify_account_route :: The route to the verify account action.
+verify_account_table :: The name of the verify account keys table.
+
+== Auth Methods
+
+account_from_verify_account_key(key) :: Retrieve the account using the given verify
+                                        account key, or return nil if no account
+                                        matches.
+after_verify_account :: Run arbitrary code after verifying the account.
+after_verify_account_resend :: Run arbitrary code after resending a verify account email.
+before_verify_account :: Run arbitrary code before verifying the account.
+before_verify_account_resend :: Run arbitrary code before resending a verify account email.
+before_verify_account_route :: Run arbitrary code before handling a verify account route.
+create_verify_account_key :: A random string to use as a verify account key.
+create_verify_account_email :: A Mail::Message for the verify account email.
+get_verify_account_key(id) :: Get the verify account key for the given account id
+                              from the database.
+remove_verify_account_key :: Remove the verify account key for the current account,
+                             run after successful account verification.
+resend_verify_account_view :: The HTML to use for page requesting resending the
+                              verify account email.
+send_verify_account_email :: Send the verify account email.
+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_key_insert_hash :: The hash to insert into the verify account keys
+                                  table.
+verify_account_view :: The HTML to use for the verify account form.

data/doc/verify_account_grace_period.rdoc

@@ -0,0 +1,15 @@
+= Documentation for Verify Account Grace Period Feature
+
+The verify account grace period feature allows users to login for
+a given period of time (1 day by default) before their account is
+verified.  Depends on the verify account feature.
+
+== Auth Value Methods
+
+verification_requested_at_column :: The column in the +verify_account_table+ table that holds the verification requested timestamp.
+unverified_account_session_key :: The session key set if the logged in account has not been unverified.
+verify_account_grace_period :: The amount of seconds after an account creation that a user will be able to login without verifying (86400 by default).
+
+== Auth Methods
+
+account_in_unverified_grace_period? :: Whether the current account is in an unverified grace period.