rodauth 1.19.1 → 1.20.0

data/doc/recovery_codes.rdoc

@@ -13,38 +13,27 @@ of them being required due to a missing / lost device.
 
 add_recovery_codes_button :: Text to use for button on form to add recovery codes.
 add_recovery_codes_error_flash :: The flash error to show when adding recovery codes.
+add_recovery_codes_heading :: Text to use for heading above form to add recovery codes.
 add_recovery_codes_param :: The parameter name to use for adding recovery codes.
-add_recovery_auth_redirect :: Where to redirect to add recovery codes if recovery codes
-                              are the primary 2nd factor and have not been setup yet.
-invalid_recovery_code_error_flash :: The flash error to show when an invalid recovery
-                                     code is used.
-invalid_recovery_code_message :: The error message to show when an invalid recovery code
-                                 is used.
-recovery_auth_additional_form_tags :: HTML fragment containing additional form tags when
-                                      authenticating via a recovery code.
+add_recovery_auth_redirect :: Where to redirect to add recovery codes if recovery codes are the primary 2nd factor and have not been setup yet.
+invalid_recovery_code_error_flash :: The flash error to show when an invalid recovery code is used.
+invalid_recovery_code_message :: The error message to show when an invalid recovery code is used.
+recovery_auth_additional_form_tags :: HTML fragment containing additional form tags when authenticating via a recovery code.
 recovery_auth_button :: The text to use for the button when authenticating via a recovery code.
 recovery_auth_redirect :: Where to redirect after authenticating via an recovery code.
-recovery_auth_route :: The route to the recovery code authentication action.
-                       Defaults to +recovery-auth+.
-recovery_codes_added_notice_flash :: The flash notice to show when recovery codes
-                                     were added.
-recovery_codes_additional_form_tags :: HTML fragment containing additional form tags when
-                                       adding recovery codes.
-recovery_codes_column :: The column in the recovery_codes_table containing the recovery
-                         code.
-recovery_codes_id_column :: The column in the recovery_codes_table containing the
-                            account id.
+recovery_auth_route :: The route to the recovery code authentication action.  Defaults to +recovery-auth+.
+recovery_codes_added_notice_flash :: The flash notice to show when recovery codes were added.
+recovery_codes_additional_form_tags :: HTML fragment containing additional form tags when adding recovery codes.
+recovery_codes_column :: The column in the recovery_codes_table containing the recovery code.
+recovery_codes_id_column :: The column in the recovery_codes_table containing the account id.
 recovery_codes_label :: The label for recovery codes.
 recovery_codes_limit :: The number of recovery codes to allow.
 recovery_codes_param :: The parameter name for the recovery code.
-recovery_codes_primary? :: Whether recovery codes are the primary second factor, true by
-                           default if neither the otp or sms_codes features are enabled.
-recovery_codes_route :: The route to the view recovery codes action. Defaults to
-                        +recovery-codes+.
+recovery_codes_primary? :: Whether recovery codes are the primary second factor, true by default if neither the otp or sms_codes features are enabled.
+recovery_codes_route :: The route to the view recovery codes action. Defaults to +recovery-codes+.
 recovery_codes_table :: The table storing the recovery codes.
 view_recovery_codes_button :: Text for the button to view recovery codes.
-view_recovery_codes_error_flash :: The flash error to show when viewing recovery codes
-                                       was not successful.
+view_recovery_codes_error_flash :: The flash error to show when viewing recovery codes was not successful.
 
 == Auth Methods
 
@@ -59,8 +48,6 @@ before_view_recovery_codes :: Run arbitrary code before viewing recovery codes.
 can_add_recovery_codes? :: Whether the current account can add more recovery codes.
 new_recovery_code :: A new recovery code to insert into the recovery codes table.
 recovery_auth_view :: The HTML to use for the form to authenticate via a recovery code.
-recovery_code_match?(code) :: Whether the given code matches any of the existing
-                              recovery_codes.
-recovery_codes :: An array containing all valid recovery codes for the current
-                  account.
+recovery_code_match?(code) :: Whether the given code matches any of the existing recovery_codes.
+recovery_codes :: An array containing all valid recovery codes for the current account.
 recovery_codes_view :: The HTML to use for the form to view recovery codes.

data/doc/release_notes/1.20.0.txt

@@ -0,0 +1,175 @@
+= New Features
+
+* An hmac_secret configuration method has been added.  If set,
+  Rodauth will use HMACs for all of the tokens that Rodauth creates.
+  By using HMACs for the tokens, even if the database storing the
+  tokens is compromised (e.g. via an SQL injection vulnerability), the
+  tokens stored in the database will not be usable without knowledge
+  of the HMAC secret.
+
+  The following features are affected by setting the hmac_secret
+  configuration method:
+
+  * email_auth
+  * lockout
+  * otp
+  * remember
+  * reset_password
+  * single_session
+  * verify_account
+  * verify_login_change
+
+  To allow for graceful transition when adding hmac_secret to an
+  existing Rodauth installation, you can use the
+  allow_raw_email_token? configuration method to keep allowing
+  raw tokens.  However, you should remove the allow_raw_email_token?
+  setting after the existing tokens have expired (most tokens expire
+  after 1 day by default).  Verify account tokens do not expire,
+  but users can request a new verify account token if their token has
+  expired.
+
+  For remember tokens, the raw_remember_token_deadline configuration
+  method can be used, which will only allow the use of raw remember
+  tokens before the given deadline, which should be the time in the
+  future when you want to no longer accept raw remember tokens.  You
+  can remove this configuration method after the deadline has passed.
+  By default, the deadline should be set to 14 days after the time
+  you enable hmac_secret, since remember tokens expire in 14 days by
+  default.
+
+  Similarly, in the single_session feature, you can use the
+  allow_raw_single_session_key? configuration method to allow raw
+  single session keys.
+
+  In the otp feature, you cannot mix HMAC and non-HMAC tokens. If
+  the hmac_secret setting is enabled and there are any existing
+  otp tokens already setup, they will stop working.  If you are
+  already using the otp feature and would like to use the hmac_secret
+  configuration method, you need to set the otp_keys_use_hmac?
+  configuration method to false unless you want to invalidate all
+  existing otp tokens.
+
+  The hmac_secret configuration is also used during OTP setup 
+  in the otp feature, to ensure that the OTP secrets for two factor
+  authentication came from the server and were not modified by the
+  user.  If hmac_secret is used, setting up OTP via JSON requires
+  sending a POST request to the otp-setup route.  This request will
+  fail, but included in the response will be the OTP secret and raw
+  OTP secret to use.  Submitting a POST request including the OTP
+  secret and raw OTP secret will allow OTP setup to complete.
+
+* A jwt_refresh feature has been added.  This uses the jwt feature,
+  and issuing short-lived JWTs with exp, iat, and nbf claims, with a
+  database-backed refresh token for issuing another short-lived JWT.
+  The refresh tokens will automatically use HMACs if the hmac_secret
+  configuration method is set.
+
+* Rodauth's handling of form errors is now accessible by default.
+  aria-invalid attributes are now used on all input fields with
+  errors, and aria-describedby attributes are used to tie the input
+  fields to the error messages.
+
+* All hard coded strings are now overridable via configuration
+  methods, with the following configuration methods added:
+
+  * lockout feature
+    * unlock_account_explanatory_text
+    * unlock_account_request_explanatory_text
+  * login_password_requirements_base feature
+    * already_an_account_with_this_login_message
+  * otp feature
+    * otp_provisioning_uri_label
+    * otp_secret_label
+  * recovery_codes feature
+    * add_recovery_codes_heading
+  * reset_password feature
+    * reset_password_explanatory_text
+  * verify_account feature
+    * verify_account_resend_explanatory_text
+
+* The following configuration methods have been added to the base
+  feature, related to customization of input fields in Rodauth forms:
+
+  default_field_attributes :: The default attributes to use for input
+                              field tags, if field_attributes does not
+                              handle the field.
+  field_attributes(field) :: The attributes to use for input fields
+                             with the given parameter name.
+  field_error_attributes(field) :: The attributes to use for input
+                                   fields with the given parameter
+                                   name if the field has an error.
+  formatted_field_error(field, error) :: HTML to use for the given
+                                         parameter name and error
+                                         text.  Uses a span by
+                                         default.
+  input_field_error_class :: The CSS class to add for input fields
+                             with errors.
+  input_field_error_message_class :: The CSS class to add for error
+                                     message spans.
+  input_field_label_suffix :: Adds suffix to all input field labels
+  login_input_type :: The input type to use for login fields.
+                      Defaults to text, but can be set to email,
+                      though that is currently a bad idea if you
+                      want the login fields to have accessible error
+                      handling.
+  mark_input_fields_as_required? :: Whether to mark all input fields
+                                    as required by default. Note that
+                                    this is currently a bad idea if
+                                    you want the fields to have
+                                    accessible error handling.
+
+= Other Improvements
+
+* rotp 5 is now supported in the otp feature.  Previous rotp versions
+  down to rotp 2.1.1 remain supported.
+
+* Performance of Rodauth routes has been improved by using defined
+  methods instead of instance_exec for route dispatching.  Internal
+  unnecessary uses of instance_exec have also been removed for
+  performance reasons.
+
+* When the disallow_password_reuse feature is used without the
+  verify_account feature, and account_password_hash_column
+  configuration is not used, Rodauth no longer tries to call a method
+  that does not exist.
+
+* When using the disallow_password_reuse and verify_account features,
+  with verify_account_set_password? set to true, Rodauth skips adding
+  an empty password to the list of previous passwords.
+
+* Rodauth now avoids an unnecessary DELETE query in the
+  disallow_password_reuse feature if there are no previous passwords.
+  
+* The otp-auth-code field now has an autocomplete=off attribute.
+
+* On Ruby 1.8, new tokens now use URL safe base64 encoding, instead
+  of hex encoding.  Rodauth has always used URL safe base64 encoding
+  for new tokens on Ruby 1.9+.
+
+= Backwards Compatibility
+
+* The following configuration methods have been renamed:
+
+  * email_auth feature
+    * no_matching_email_auth_key_message =>
+      no_matching_email_auth_key_error_flash
+  * lockout feature
+    * no_matching_unlock_account_key_message =>
+      no_matching_unlock_account_key_error_flash
+  * reset_password feature
+    * no_matching_reset_password_key_message =>
+      no_matching_reset_password_key_error_flash
+  * verify_account feature
+    * attempt_to_create_unverified_account_notice_message =>
+      attempt_to_create_unverified_account_error_flash
+    * attempt_to_login_to_unverified_account_notice_message =>
+      attempt_to_login_to_unverified_account_error_flash
+    * no_matching_verify_account_key_message =>
+      no_matching_verify_account_key_error_flash
+  * verify_login_change feature
+    * no_matching_verify_login_change_key_message =>
+      no_matching_verify_login_change_key_error_flash
+      
+  Attempts to use the old method at configuration time, or calling
+  the method on the rodauth object at runtime, will result in a
+  deprecation warning.

data/doc/remember.rdoc

@@ -23,6 +23,9 @@ remembering on login, you can do that via:
 
 extend_remember_deadline? :: Whether to extend the remember token deadline
                              when the user is autologged in via token.
+raw_remember_token_deadline :: A deadline before which to allow a raw remember
+                               token to be used. Allows for graceful transition
+                               for when +hmac_secret+ is first set.
 remember_additional_form_tags :: HTML fragment containing additional
                                  form tags to use on the change remember 
                                  setting form.

data/doc/reset_password.rdoc

@@ -8,7 +8,7 @@ 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.
+no_matching_reset_password_key_error_flash :: 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.
@@ -21,6 +21,7 @@ reset_password_email_sent_redirect :: Where to redirect after sending a reset pa
 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_email_last_sent_column :: The email last sent column in the reset password keys table.  nil by default, so a reset password email is always sent when requested by default.
+reset_password_explanatory_text :: The text to display above the button to request a password reset.
 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.

data/doc/single_session.rdoc

@@ -18,6 +18,9 @@ the previous session after logout no longer work.
 
 == Auth Value Methods
 
+allow_raw_single_session_key? :: Whether to allow a raw single session key to
+                                 be accepted, should only be enabled for graceful
+                                 transition when +hmac_secret+ is first set.
 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

data/doc/verify_account.rdoc

@@ -7,9 +7,9 @@ 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.
+attempt_to_create_unverified_account_error_flash :: The flash error message to show when attempting to create an account awaiting verification.
+attempt_to_login_to_unverified_account_error_flash :: The flash error message to show when attempting to login to an account awaiting verification.
+no_matching_verify_account_key_error_flash :: 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.
@@ -28,6 +28,7 @@ verify_account_resend_additional_form_tags :: HTML fragment containing additiona
 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_explanatory_text :: The text to display above the button to resend the verify account email.
 verify_account_resend_link :: The HTML to use for a link to the page to request the account verification email be resent.
 verify_account_resend_route :: The route to the verify account resend action.  Defaults to +verify-account-resend+.
 verify_account_route :: The route to the verify account action. Defaults to +verify-account+.

data/doc/verify_login_change.rdoc

@@ -13,7 +13,7 @@ control.  Depends on the change login and email base features.
 
 == Auth Value Methods
 
-no_matching_verify_login_change_key_message :: The flash error message to show when an invalid verify login change key is used.
+no_matching_verify_login_change_key_error_flash :: The flash error message to show when an invalid verify login change key is used.
 verify_login_change_additional_form_tags :: HTML fragment containing additional form tags to use on the verify login change form.
 verify_login_change_autologin? :: Whether to autologin the user after successful login change verification, false by default.
 verify_login_change_button :: The text to use for the verify login change button.

data/lib/rodauth.rb

@@ -18,11 +18,11 @@ module Rodauth
       when false
         # nothing
       when :route_csrf
-        # :nocov:
         app.plugin :route_csrf
-        # :nocov:
       else
+        # :nocov:
         app.plugin :csrf
+        # :nocov:
       end
 
       app.plugin :flash unless opts[:flash] == false
@@ -103,14 +103,23 @@ module Rodauth
     def route(name=feature_name, default=name.to_s.tr('_', '-'), &block)
       auth_value_method "#{name}_route", default
 
-      handle_meth = "handle_#{name}"
+      handle_meth = :"handle_#{name}"
+      internal_handle_meth = :"_#{handle_meth}"
       route_meth = :"#{name}_route"
       before route_meth
 
+      unless block.arity == 1
+        # :nocov:
+        b = block
+        block = lambda{|r| instance_exec(r, &b)}
+        # :nocov:
+      end
+      define_method(internal_handle_meth, &block)
+
       define_method(handle_meth) do
         request.is send(route_meth) do
           before_rodauth
-          instance_exec(request, &block)
+          send(internal_handle_meth, request)
         end
       end
 
@@ -138,6 +147,26 @@ module Rodauth
       configuration.module_eval(&block)
     end
 
+    if RUBY_VERSION >= '2.5'
+      DEPRECATED_ARGS = [{:uplevel=>1}]
+    else
+      # :nocov:
+      DEPRECATED_ARGS = []
+      # :nocov:
+    end
+    def def_deprecated_alias(new, old)
+      configuration_module_eval do
+        define_method(old) do |*a, &block|
+          warn("Deprecated #{old} method used during configuration, switch to using #{new}", *DEPRECATED_ARGS)
+          send(new, *a, &block)
+        end
+      end
+      define_method(old) do
+        warn("Deprecated #{old} method called at runtime, switch to using #{new}", *DEPRECATED_ARGS)
+        send(new)
+      end
+    end
+
     DEFAULT_REDIRECT_BLOCK = proc{default_redirect}
     def redirect(name=feature_name, &block)
       meth = :"#{name}_redirect"

data/lib/rodauth/features/base.rb

@@ -21,6 +21,10 @@ module Rodauth
     auth_value_method :default_redirect, '/'
     session_key :flash_error_key, :error
     session_key :flash_notice_key, :notice
+    auth_value_method :hmac_secret, nil
+    auth_value_method :input_field_label_suffix, ''
+    auth_value_method :input_field_error_class, 'error'
+    auth_value_method :input_field_error_message_class, 'error_message'
     auth_value_method :invalid_field_error_status, 422
     auth_value_method :invalid_key_error_status, 401
     auth_value_method :invalid_password_error_status, 401
@@ -35,15 +39,18 @@ module Rodauth
     auth_value_method :no_matching_login_message, "no matching login"
     auth_value_method :login_param, 'login'
     auth_value_method :login_label, 'Login'
+    auth_value_method :login_input_type, 'text'
     auth_value_method :password_label, 'Password'
     auth_value_method :password_param, 'password'
     auth_value_method :modifications_require_password?, true
     session_key :session_key, :account_id
     auth_value_method :prefix, ''
     auth_value_method :require_bcrypt?, true
+    auth_value_method :mark_input_fields_as_required?, false
     auth_value_method :skip_status_checks?, true
     auth_value_method :template_opts, {}
     auth_value_method :title_instance_variable, nil 
+    auth_value_method :token_separator, "_"
     auth_value_method :unmatched_field_error_status, 422
     auth_value_method :unopen_account_error_status, 403
     auth_value_method :unverified_account_message, "unverified account, please verify account before logging in"
@@ -52,6 +59,7 @@ module Rodauth
 
     auth_value_methods(
       :db,
+      :default_field_attributes,
       :set_deadline_values?,
       :use_date_arithmetic?,
       :use_database_authentication_functions?,
@@ -84,7 +92,10 @@ module Rodauth
 
     auth_private_methods(
       :account_from_login,
-      :account_from_session
+      :account_from_session,
+      :field_attributes,
+      :field_error_attributes,
+      :formatted_field_error
     )
 
     configuration_module_eval do
@@ -144,6 +155,51 @@ module Rodauth
       @field_errors[field]
     end
 
+    def add_field_error_class(field)
+      if field_error(field)
+        " #{input_field_error_class}"
+      end
+    end
+
+    def input_field_string(param, id, opts={})
+      type = opts.fetch(:type, "text")
+
+      unless type == "password"
+        value = opts.fetch(:value){scope.h param(param)}
+      end
+
+      "<input #{opts[:attr]} #{field_attributes(param)} #{field_error_attributes(param)} type=\"#{type}\" class=\"form-control#{add_field_error_class(param)}\" name=\"#{param}\" id=\"#{id}\" value=\"#{value}\"/> #{formatted_field_error(param)}"
+    end
+
+    def default_field_attributes
+      if mark_input_fields_as_required?
+        "required=\"required\""
+      end
+    end
+
+    def field_attributes(field)
+      _field_attributes(field) || default_field_attributes
+    end
+
+    def field_error_attributes(field)
+      if field_error(field)
+        _field_error_attributes(field)
+      end
+    end
+
+    def formatted_field_error(field)
+      if error = field_error(field)
+        _formatted_field_error(field, error)
+      end
+    end
+
+    # Return urlsafe base64 HMAC for data, assumes hmac_secret is set.
+    def compute_hmac(data)
+      s = [compute_raw_hmac(data)].pack('m').chomp!("=\n")
+      s.tr!('+/', '-_')
+      s
+    end
+
     def account_id
       account[account_id_column]
     end
@@ -241,11 +297,11 @@ module Rodauth
       return unless scope.respond_to?(:csrf_tag)
 
       if use_request_specific_csrf_tokens?
-        # :nocov:
         scope.csrf_tag(path)
-        # :nocov:
       else
+        # :nocov:
         scope.csrf_tag
+        # :nocov:
       end
     end
 
@@ -315,6 +371,18 @@ module Rodauth
 
     private
 
+    def convert_token_key(key)
+      if key && hmac_secret
+        compute_hmac(key)
+      else
+        key
+      end
+    end
+
+    def split_token(token)
+      token.split(token_separator, 2)
+    end
+
     def redirect(path)
       request.redirect(path)
     end
@@ -330,7 +398,9 @@ module Rodauth
     else
       # :nocov:
       def random_key
-        SecureRandom.hex(32)
+        s = [SecureRandom.random_bytes(32)].pack('m').chomp!("=\n")
+        s.tr!('+/', '-_')
+        s
       end
       # :nocov:
     end
@@ -438,6 +508,22 @@ module Rodauth
       ds.first
     end
 
+    def compute_raw_hmac(data)
+      OpenSSL::HMAC.digest(OpenSSL::Digest::SHA256.new, hmac_secret, data)
+    end
+
+    def _field_attributes(field)
+      nil
+    end
+
+    def _field_error_attributes(field)
+      " aria-invalid=\"true\" aria-describedby=\"#{field}_error_message\" "
+    end
+
+    def _formatted_field_error(field, error)
+      "<span class=\"#{input_field_error_message_class}\" id=\"#{field}_error_message\">#{error}</span>"
+    end
+
     def account_session_status_filter
       {account_status_column=>account_open_status_value}
     end
@@ -536,18 +622,15 @@ module Rodauth
     end
 
     def _view_opts(page)
-      auth_template_path = template_path(page)
       opts = template_opts.dup
       opts[:locals] = opts[:locals] ? opts[:locals].dup : {}
       opts[:locals][:rodauth] = self
       opts[:cache] = cache_templates
       opts[:cache_key] = :"rodauth_#{page}"
 
-      scope.instance_exec do
-        opts = find_template(parse_template_opts(page, opts))
-        unless File.file?(template_path(opts))
-          opts[:path] = auth_template_path
-        end
+      opts = scope.send(:find_template, scope.send(:parse_template_opts, page, opts))
+      unless File.file?(scope.send(:template_path, opts))
+        opts[:path] = template_path(page)
       end
 
       opts