= Documentation for Base Feature

The base feature is automatically loaded when you use Rodauth.  It contains
shared functionality that is used by multiple features.

== Auth Value Methods

=== Most Commonly Used

account_password_hash_column :: Set if the password hash column is in the same table as the login.  If this is set, Rodauth will check the password hash in ruby. This is often used if you are replacing a legacy authentication system with Rodauth.
accounts_table :: The database table containing the accounts.
base_url :: The base URL to use, used when construct absolute links. It is recommended to set this if the application can be reached using arbitrary Host headers, as otherwise it is possible for an attacker to control the value.
db :: The Sequel::Database object used for database access.
domain :: The domain to use, required by some other features. It is recommended to set this if the application can be reached using arbitrary Host headers, as otherwise it is possible for an attacker to control the value.
hmac_secret :: This sets the secret to use for all of Rodauth's HMACs.  This is not set by default, in which case Rodauth does not use HMACs for additional security.  However, it is highly recommended that you set this, and some features require it.
mark_input_fields_as_required? :: Whether input fields should be marked as required, so browsers will not allow submission without filling out the field (default: true).
prefix :: The routing prefix used for Rodauth routes.  If you are calling in a routing subtree, this should be set to the root path of the subtree.  This should include a leading slash if set, but not a trailing slash.
require_bcrypt? :: Set to false to not require bcrypt, useful if using custom authentication or when using the argon2 feature without existing bcrypt password hashes.
session_key :: The key in the session hash storing the primary key of the logged in account.
session_key_prefix :: The string that will be prepended to the default value for all session keys.
skip_status_checks? :: Whether status checks should be skipped for accounts.  Defaults to true unless enabling the verify_account or close_account features.
title_instance_variable :: The instance variable to set in the Roda scope with the page title.  The layout should use this instance variable if available to set the title of the page.  You can use +set_title+ if setting the page title is not done through an instance variable.

=== Other

account_id_column :: The primary key column of the +accounts_table+.
account_open_status_value :: The integer representing open accounts.
account_select :: An array of columns to select from +accounts_table+. By default, selects all columns in the table.
account_status_column :: The status id column in the +accounts_table+.
account_unverified_status_value :: The integer representing unverified accounts.
authenticated_by_session_key :: The key in the session hash storing an array of methods used to authenticate.
autocomplete_for_field?(param) :: Whether to use an autocomplete attribute for the given parameter, defaults to +mark_input_fields_with_autocomplete?+.
autologin_type_session_key :: The key in the session hash storing the type of autologin method used, if autologin was used to authenticate.
cache_templates :: Whether to cache templates. True by default. It may be worth switching this to false in development if you are using your own templates instead of the templates provided by Rodauth.
check_csrf? :: Whether Rodauth should use Roda's +check_csrf!+ method for checking CSRF tokens before dispatching to Rodauth routes, true by default.
check_csrf_opts :: Options to pass to Roda's +check_csrf!+ if Rodauth calls it before dispatching.
check_csrf_block :: Proc for block to pass to Roda's +check_csrf!+ if Rodauth calls it before dispatching.
clear_tokens(reason) :: Called when there is an account change, clears tokens for the account. By examining the reason symbol you can get different behavior per action, but the default behavior is clear all tokens whenever there is an account. Clearing actions/reasons are +:reset_password+, +:verify_account+, +:change_login+, +:unlock_account+, and +close_account+. Tokens are cleared for the following features +reset_password+, +verify_account+, +verify_login_change+, +jwt_refresh+, +remember+, +email_auth+, +single_session+, and +active_sessions+.
convert_token_id_to_integer? :: Whether token ids should be converted to a valid 64-bit integer value.  If not set, defaults to true if +account_id_column+ uses an integer type, and false otherwise.
default_field_attributes :: The default attributes to use for input field tags, if field_attributes returns nil for the field.
default_redirect :: Where to redirect after most successful actions.
field_attributes(field) :: The attributes to use for the input field tags for the given field (parameter name).
field_error_attributes(field) :: The attributes to use for the input field tags for the given field (parameter name), if the input has an error.
flash_error_key :: The flash key to use for error messages (default: +:error+ or <tt>'error'</tt> depending on session support for symbols).
flash_notice_key :: The flash key to use for notice messages (default: +:notice+ or <tt>'notice'</tt> depending on session support for symbols).
formatted_field_error(field, error) :: HTML to use for error messages for the field (parameter name), if the field has an error.  By default, uses a span tag for the error message.
hmac_old_secret :: This sets the previous secret used for Rodauth's HMACs, to allow for secret rotation.
hook_action(hook_type, action) :: Arbitrary action to take on all hook processing, with hook type being +:before+ or +:after+, and action being symbol for related action.
input_field_error_class :: The CSS class to use for input fields with errors. Can be a space separated string for multiple CSS classes.
input_field_error_message_class :: The CSS class to use for error messages. Can be a space separated string for multiple CSS classes.
input_field_label_suffix :: The suffix to use for all labels.  Useful for noting that the fields are required.
inputmode_for_field?(param) :: Whether to use an inputmode attribute for the given parameter, defaults to mark_input_fields_with_inputmode?.
invalid_field_error_status :: The response status to use for invalid field value errors, 422 by default.
invalid_key_error_status :: The response status to use for invalid key codes, 401 by default.
invalid_password_error_status :: The response status to use for invalid passwords, 401 by default.
invalid_password_message :: The error message to display when a given password doesn't match the stored password hash.
lockout_error_status :: The response status to use a login is attempted to an account that is locked out, 403 by default.
login_column :: The login column in the +accounts_table+.
login_input_type :: The input type to use for logins. Defaults to email if login column is email and text otherwise.
login_label :: The label to use for logins.
login_param :: The parameter name to use for logins.
login_required_error_status :: The response status to return when a login is required and you are not logged in, if not redirecting, 401 by default
login_uses_email? :: Whether the login field uses email, used to set the type of the login field as well as the autocomplete setting.
mark_input_fields_with_autocomplete? :: Whether input fields should be marked with autocomplete attribute appropriate for the field, true by default.
mark_input_fields_with_inputmode? :: Whether input fields should be marked with inputmode attribute appropriate for the field, true by default.
max_param_bytesize :: The maximum bytesize allowed for submitted parameters, 1024 by default. Use nil for no limit.
modifications_require_password? :: Whether making changes to an account requires the user reinputing their password.  True by default if the account has a password.
no_matching_login_error_status :: The response status to use when the login is not in the database, 401 by default.
no_matching_login_message :: The error message to display when the login used is not in the database.
password_hash_column :: The password hash column in the +password_hash_table+.
password_hash_id_column :: The account id column in the +password_hash_table+.
password_hash_table :: The table storing the password hashes.
password_label :: The label to use for passwords.
password_param :: The parameter name to use for passwords.
require_login_error_flash :: The flash error to display when accessing a page that requires a login, when you are not logged in.
require_login_redirect :: A redirect to the login page.
set_deadline_values? :: Whether deadline values should be set.  True by default on MySQL, as that doesn't support default values that are not constant.  Can be set to true on other databases if you want to vary the value based on a request parameter.
strftime_format :: The format to pass to Time#strftime when formatting timestamps to display to the user, '%F %T' by default.
template_opts :: Any template options to pass to view/render.  This can be used to set a custom layout, for example.
token_separator :: The string used to separate account id from the random key in links.
unmatched_field_error_status :: The response status to use when two field values should match but do not, 422 by default.
unopen_account_error_status :: The response status to use when trying to login to an account that isn't open, 403 by default.
use_database_authentication_functions? :: Whether to use functions to do authentication.  True by default on PostgreSQL, MySQL, and Microsoft SQL Server, false otherwise.
use_date_arithmetic? :: Whether the date_arithmetic extension should be loaded into the database.  Defaults to whether deadline values should be set.
use_request_specific_csrf_tokens? :: Whether to use request-specific CSRF tokens.  True if the default CSRF setting are used.
use_template_fixed_locals? :: Whether to specify fixed locals for rodauth templates.  True by default, should only be set to false if overriding the templates and having them accept different local variables.

== Auth Methods

account_from_id(id, status_id=nil) :: Retrieve the account hash for the given account id and status.
account_from_login(login) :: Retrieve the account hash related to the given login or nil if no login matches.
account_from_session :: Retrieve the account hash related to the currently logged in session.
account_id :: The primary key value of the current account.
account_session_value :: The primary value of the current account to store in the session when logging in.
after_login :: Run arbitrary code after a successful login.
after_no_matching_login :: Run arbitrary code after a login failure due to an invalid login.
after_login_failure :: Run arbitrary code after a login failure due to an invalid password.
already_logged_in :: What action to take if you are already logged in and attempt to access a page that only makes sense if you are not logged in.
around_rodauth(&block) :: Run arbitrary code around handling any rodauth route.  Call <tt>super(&block)</tt> for Rodauth to handle the action.
authenticated? :: Whether the user has been authenticated. If multifactor authentication has been enabled for the account, this is true only if the session is multifactor authenticated.
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_rodauth :: Run arbitrary code before handling any rodauth route, but after CSRF checks if Rodauth is doing CSRF checks.
check_csrf :: Checks CSRF token using Roda's +check_csrf!+ method.
clear_session :: Clears the current session.
convert_token_id(id) :: Convert the token id string to an appropriate object to use for the token id (or return +nil+ to signal an invalid token id).  By default, converts to a 64-bit signed integer if +convert_token_id_to_integer?+ is true.
csrf_tag(path=request.path) :: The HTML fragment containing the CSRF tag to use, if any.
function_name(name) :: The name of the database function to call.  It's passed either :rodauth_get_salt or :rodauth_valid_password_hash.
logged_in? :: Whether the current session is logged in.
login_required :: Action to take when a login is required to access the page and the user is not logged in.
normalize_login(login) :: How to normalize the submitted login parameter value, returns the argument by default.
null_byte_parameter_value(key, value) :: The value to use for the parameter if the parameter includes an ASCII NUL byte ("\0"), nil by default to ignore the parameter.
open_account? :: Whether the current account is an open account (not closed or unverified).
over_max_bytesize_param_value(key, value) :: The value to use for the parameter if the parameter is over the maximum allowed bytesize, nil by default to ignore the parameter.
password_match?(password) :: Check whether the given password matches the stored password hash.
random_key :: A randomly generated string, used for creating tokens.
redirect(path) :: Redirect the request to the given path.
session_value :: The value for session_key in the current session.
set_error_flash(message) :: Set the current error flash to the given message.
set_error_reason(reason) :: You can override this method to customize handling of specific error types (does nothing by default).  Each separate error type has a separate reason symbol, you can see the {list of error reason symbols}[rdoc-ref:doc/error_reasons.rdoc].
set_notice_flash(message) :: Set the next notice flash to the given message.
set_notice_now_flash(message) :: Set the current notice flash to the given message.
set_redirect_error_flash(message) :: Set the next error flash to the given message.
set_title(title) :: Set the title of the page to the given title.
translate(key, default_value) :: Return a translated version for the key (uses the default value by default).
unverified_account_message :: The message to use when attempting to login to an unverified account.
update_session :: Clear the session, then set the session key to the primary key of the current account.
