= Documentation for SMS Codes Feature

The sms codes feature allows for multifactor authentication via codes provided via
SMS messages.  It is usually used as a backup if other multifactor authentication is not available
or has been locked out, but it can be used as the primary multifactor authentication method.

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 :: A hash of SMS information for the user, if SMS authentication has been setup.
sms_already_setup_error_flash :: The flash error to show when going to a page to setup SMS authentication if SMS authentication has already been setup.
sms_already_setup_error_status :: The response status to use when going to a page to setup SMS authentication if SMS authentication has already been setup, 403 by default.
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 the form to authenticate via SMS.
sms_auth_code_length :: The length of SMS authentication codes, 6 by default.
sms_auth_link_text :: The text to use for the link from the multifactor auth page.
sms_auth_page_title :: The page title to use on the form to authenticate via SMS code.
sms_auth_redirect :: Where to redirect if SMS authentication is needed.
sms_auth_route :: The route to the SMS authentication action. Defaults to +sms-auth+.
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_primary? :: Whether SMS codes are a primary multifactor authentication method.  If not, they cannot be setup unless multifactor authentication has already been setup.
sms_codes_table :: The name of the table storing SMS code data.
sms_confirm_additional_form_tags :: HTML fragment containing additional form tags when confirming SMS setup.
sms_confirm_button :: Text to use for button on the 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_deadline :: The number of seconds before an SMS confirmation code expires (86400 seconds by default).
sms_confirm_notice_flash :: The flash notice to show when SMS authentication setup has been confirmed.
sms_confirm_page_title :: The page title to use on the form to authenticate via SMS code.
sms_confirm_redirect :: Where to redirect after SMS authentication setup has been confirmed.
sms_confirm_route :: The route to the SMS setup confirmation action. Defaults to +sms-confirm+.
sms_disable_additional_form_tags :: HTML fragment containing additional form tags when disabling SMS authentication.
sms_disable_button :: Text to use for button on the form to disable SMS authentication.
sms_disable_error_flash :: The flash error to show when disabling SMS authentication fails.
sms_disable_link_text :: The text to use for the remove link from the multifactor manage page.
sms_disable_notice_flash :: The flash notice to show when SMS authentication has been successfully disabled.
sms_disable_page_title :: The page title to use on the form to disable SMS authentication.
sms_disable_redirect :: Where to redirect after SMS authentication has been disabled.
sms_disable_route :: The route to the SMS authentication disable action. Defaults to +sms-disable+.
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_notice_flash :: The flash notice to show on SMS authentication pages when SMS authentication setup needs confirmation (uses +sms_needs_confirmation_error_flash+ by default).
sms_needs_confirmation_error_flash :: The flash error to show on SMS authentication pages when SMS authentication setup needs confirmation.
sms_needs_confirmation_error_status :: The response status to use on SMS authentication pages when SMS authentication setup needs confirmation, 403 by default.
sms_needs_confirmation_redirect :: Where to redirect after SMS setup, when confirmation is required.
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_input_type :: The input type to use for SMS phone numbers, tel by default.
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 the 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_page_title :: The page title to use on the form to request an SMS authentication code.
sms_request_redirect :: Where to redirect after requesting an SMS authentication code.
sms_request_route :: The route to the SMS authentication code request action. Defaults to +sms-request+.
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 the form to setup SMS authentication.
sms_setup_error_flash :: The flash error to show when setting up SMS authentication fails.
sms_setup_link_text :: The text to use for the setup link from the multifactor manage page.
sms_setup_page_title :: The page title to use on the form to setup SMS authentication.
sms_setup_route :: The route to the SMS authentication setup action. Defaults to +sms-setup+.

== 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_response :: Return a response after successfully confirming SMS code during SMS setup. By default, redirects to +sms_confirm_redirect+.
sms_confirm_view :: The HTML to use for the form to authenticate via SMS code.
sms_confirmation_match?(code) :: Whether there is an active SMS confirmation code for the current account and the given code matches it.
sms_current_auth? :: Whether there is a active SMS authentication code for the current account.
sms_disable :: Action to take to disable SMS authentication for the account.
sms_disable_response :: Return a response after successfully disabling SMS. By default, redirects to +sms_disable_redirect+.
sms_disable_view :: The HTML to use for the form to disable SMS authentication.
sms_failures :: The number of SMS authentication failures since the last successfully SMS authentication for this account.
sms_locked_out? :: Whether SMS authentication has been locked out for the current account.
sms_needs_confirmation? :: Whether SMS authentication has been setup but not confirmed for the current account.
sms_needs_confirmation_response :: Return a response after successfully providing SMS number during SMS setup. By default, redirects to +sms_needs_confirmation_redirect+.
sms_new_auth_code :: A new SMS authentication code that can be used for the account.
sms_new_confirm_code :: A new SMS confirmation code that can be used for the account.
sms_normalize_phone(phone) :: A normalized version of the given phone number, by default removing everything except 0-9.
sms_record_failure :: Record an SMS authentication failure for the current account.
sms_remove_expired_confirm_code :: Remove an expired SMS confirm code, allowing setup of a new sms confirm code.
sms_remove_failures :: Reset the SMS authentication failure counter for the current account, used after a successful multifactor authentication.
sms_request_response :: Return a response after a successful SMS request during SMS authentication. By default, redirects to +sms_auth_redirect+.
sms_request_view :: The HTML to use for the form to request an SMS authentication code.
sms_send(phone, message) :: Send the given message to the given phone number via SMS.  By default a NotImplementedError is raised, this is the only method that must be overridden. 
sms_set_code(code) :: Set the SMS authentication code for the current account to the given code.  The code can be nil to specify that no SMS authentication code is currently valid.
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.
