rodauth 2.36.0 → 2.37.0

data/doc/error_reasons.rdoc

@@ -1,77 +0,0 @@
-= Error Reasons
-
-Rodauth allows for customizing response status codes and error
-messages for each type of error.  However, in some cases, the
-response status code is too coarse for desired error handling
-by the application (since many error types use the same status
-code), and using the error message is too fragile since it may
-be translated.
-
-For this reason, Rodauth associates a fine grained reason for
-each type of error.  If an error occurs in Rodauth, it will
-call the +set_error_reason+ method with a symbol for the
-specific type of error.  By default, this method does not do
-anything, but you can use the +set_error_reason+ configuration
-method to customize the error handling.
-
-These are the currently supported error type symbols that
-Rodauth will call +set_error_reason+ with:
-
-* :account_locked_out
-* :already_an_account_with_this_login
-* :already_an_unverified_account_with_this_login
-* :duplicate_webauthn_id
-* :inactive_session
-* :invalid_email_auth_key
-* :invalid_otp_auth_code
-* :invalid_otp_secret
-* :invalid_password
-* :invalid_password_pattern
-* :invalid_phone_number
-* :invalid_previous_password
-* :invalid_recovery_code
-* :invalid_remember_param
-* :invalid_reset_password_key
-* :invalid_sms_code
-* :invalid_sms_confirmation_code
-* :invalid_unlock_account_key
-* :invalid_verify_account_key
-* :invalid_verify_login_change_key
-* :invalid_webauthn_auth_param
-* :invalid_webauthn_id
-* :invalid_webauthn_remove_param
-* :invalid_webauthn_setup_param
-* :invalid_webauthn_sign_count
-* :login_not_valid_email
-* :login_required
-* :login_too_long
-* :login_too_many_bytes
-* :login_too_short
-* :logins_do_not_match
-* :no_current_sms_code
-* :no_matching_login
-* :not_enough_character_groups_in_password
-* :otp_locked_out
-* :password_authentication_required
-* :password_contains_null_byte
-* :password_does_not_meet_requirements
-* :password_in_dictionary
-* :password_is_one_of_the_most_common
-* :password_same_as_previous_password
-* :password_too_long
-* :password_too_many_bytes
-* :password_too_short
-* :passwords_do_not_match
-* :same_as_current_login
-* :same_as_existing_password
-* :session_expired
-* :sms_already_setup
-* :sms_locked_out
-* :sms_needs_confirmation
-* :sms_not_setup
-* :too_many_repeating_characters_in_password
-* :two_factor_already_authenticated
-* :two_factor_need_authentication
-* :two_factor_not_setup
-* :unverified_account
-* :webauthn_not_setup

data/doc/guides/admin_activation.rdoc

@@ -1,46 +0,0 @@
-= Require account verification by admin
-
-There are scenarios in which, instead of allowing the user to verify they have
-access to the email for the account, you may want to have an admin or moderator
-approve new accounts manually. One way this can be achieved by sending the
-account verification email to the admin:
-
-  plugin :rodauth do
-    enable :login, :logout, :verify_account, :reset_password
-
-    # Send account verification email to the admin
-    email_to do
-      if account[account_status_column] == account_unverified_status_value
-        "admin@myapp.com"
-      else
-        super()
-      end
-    end
-
-    # Do not ask for password when creating or verifying account
-    verify_account_set_password? false
-    create_account_set_password? false
-
-    # Adjust the account verification email subject and body
-    verify_account_email_subject "New User Awaiting Admin Approval"
-    verify_account_email_body do
-      "The user #{account[login_column]} has created an account. Click here to approve it: #{verify_account_email_link}."
-    end
-
-    # Display this message to the user after they've created their account
-    verify_account_email_sent_notice_flash "Your account has been created and is awaiting approval"
-
-    # Prevent the admin from being logged in after confirming the account
-    verify_account_autologin? false
-    verify_account_notice_flash "The account has been approved"
-
-    # Send a reset password email after verifying the account.
-    # This allows the user to choose the password for the account,
-    # and also makes sure the user can only log in if they have
-    # access to the email address for the account.
-    after_verify_account do
-      generate_reset_password_key_value
-      create_reset_password_key
-      send_reset_password_email
-    end
-  end

data/doc/guides/already_authenticated.rdoc

@@ -1,10 +0,0 @@
-= Skip login page if already authenticated
-
-In some cases it may be useful to skip login/registration pages when the user
-is already logged in. This can be achieved as follows.  Note that this only
-matters if the user manually navigates to the login or create account pages.
-
-  plugin :rodauth do
-    # Redirect logged in users to the wherever login redirects to
-    already_logged_in { redirect login_redirect }
-  end

data/doc/guides/alternative_login.rdoc

@@ -1,46 +0,0 @@
-= Use a non-email login
-
-Rodauth's by default uses email addresses for identifying users, since that is
-the most common form of identifier currently. In some cases, you might want
-to allow logging in via alternative identifiers, such as a username.  In this
-case, it is best to choose a different column name for the login, such as
-+:username+.  Among other things, this also makes it so that the login field
-does not expect an email address to be provided.
-
-  plugin :rodauth do
-    enable :login, :logout
-    login_column :username
-  end
-
-Note that Rodauth features that require sending email need an email address, and
-that defaults to the value of the login column.  If you have both a username and
-an email for an account, you can have the login column be the user, and use the
-value of the email colummn for the email address.
-
-  plugin :rodauth do
-    enable :login, :logout, :reset_password
-
-    login_column :username
-    email_to do
-      account[:email]
-    end
-  end
-
-An alternative approach would be to accept a login and automatically change it
-to an email address. If you have a +username+ field on the +accounts+ table,
-then you can configure Rodauth to allow entering a username instead of email
-during login.  See the {Adding new registration field}[rdoc-ref:doc/guides/registration_field.rdoc]
-guide for instructions on requiring add an additional field during registration.
-
-  plugin :rodauth do
-    enable :login, :logout
-
-    account_from_login do |login|
-      # handle the case when login parameter is a username
-      unless login.include?("@")
-        login = db[:accounts].where(username: login).get(:email)
-      end
-
-      super(login)
-    end
-  end

data/doc/guides/change_table_and_column_names.rdoc

@@ -1,19 +0,0 @@
-= Change table and column names
-
-All tables that Rodauth uses will have a configuration method that ends with
-+_table+ for configuring the table name.  For example, if you store user accounts
-in the +users+ table instead of +accounts+ table, you can use the following
-in your configuration:
-
-  accounts_table :users
-
-All columns that Rodauth uses will have a configuration method that ends with
-+_column+ for configuring the column name.  For example, if you are storing the
-login for accounts in the +login+ column instead of the +email+ column, you
-can use the following in your configuration:
-
-  login_column :login
-
-Please see the documentation for Rodauth features for the names of the
-configuration methods that you can use.  You can see the default values for
-the tables and columns in the {"Creating tables" section of the README}[rdoc-ref:README.rdoc].

data/doc/guides/create_account_programmatically.rdoc

@@ -1,38 +0,0 @@
-= Create an account record programmatically
-
-In some scenarios you might want to create an account records programmatically,
-for example in your tests.
-
-If you're storing passwords in a separate table, you can create an account
-records as follows:
-
-  account_id = DB[:accounts].insert(
-    email:     "name@example.com",
-    status_id: 2, # verified
-  )
-
-  DB[:account_password_hashes].insert(
-    id:            account_id,
-    password_hash: BCrypt::Password.create("secret").to_s,
-  )
-
-If the password is stored in a column in the accounts table:
-
-  account_id = DB[:accounts].insert(
-    email:         "name@example.com",
-    password_hash: BCrypt::Password.create("secret").to_s,
-    status_id:     2, # verified
-  )
-
-If you are creating accounts in your tests, you probably want to use
-the +:cost+ option, otherwise you will have very slow tests:
-
-  account_id = DB[:accounts].insert(
-    email:     "name@example.com",
-    status_id: 2, # verified
-  )
-
-  DB[:account_password_hashes].insert(
-    id:            account_id,
-    password_hash: BCrypt::Password.create("secret", cost: BCrypt::Engine::MIN_COST).to_s,
-  )

data/doc/guides/delay_password.rdoc

@@ -1,25 +0,0 @@
-= Set password when verifying account
-
-If you want to request less information from the user on registration, you can
-ask the user to set their password only when they verify their account:
-
-  plugin :rodauth do
-    enable :login, :logout, :verify_account
-    verify_account_set_password? true
-  end
-
-Note that this is already the default behaviour when verify account feature is
-loaded, but it's not when verify account grace period is used, because it would
-prevent the account from logging in during the grace period. You can work around
-this by automatically remebering their login during account creation using the
-remember feature.  Be aware that remembering accounts has effects beyond the
-verification period, and this would only allow automatic logins from the browser
-that created the account.
-
-  plugin :rodauth do
-    enable :login, :logout, :verify_account_grace_period, :remember
-    verify_account_set_password? true
-    after_create_account do
-      remember_login
-    end
-  end

data/doc/guides/email_only.rdoc

@@ -1,16 +0,0 @@
-= Allow only email authentication
-
-When using the email authentication feature, you can avoid other authentication
-mechanisms entirely as follows:
-
-  plugin :rodauth do
-    enable :login, :email_auth, :create_account, :verify_account
-
-    create_account_set_password? false
-    verify_account_set_password? false
-    force_email_auth? true
-  end
-
-With this configuration, users won't be required to enter a password on
-registration, and on login the email authentication link will automatically be
-sent after the email address is entered.

data/doc/guides/i18n.rdoc

@@ -1,29 +0,0 @@
-= Translate with i18n gem
-
-Rodauth allows transforming user-facing text configuration such as flash
-messages, validation errors, labels etc. via the +translate+ configuration
-method. This method receives a name of a configuration along with its default
-value, and is expected to return the result text.
-
-You can use this to perform translations using the
-{i18n gem}[https://github.com/ruby-i18n/i18n]:
-
-  plugin :rodauth do
-    enable :login, :logout, :reset_password
-
-    translate do |key, default|
-      I18n.translate("rodauth.#{key}") || default
-    end
-  end
-
-Your translation file may then look something like this:
-
-  en:
-    rodauth:
-      login_notice_flash: "You have been signed in"
-      require_login_error_flash: "Login is required for accessing this page"
-      no_matching_login_message: "user with this email address doesn't exist"
-      reset_password_email_subject: "Password Reset Instructions"
-
-Alternatively, you can use the
-{rodauth-i18n}[https://github.com/janko/rodauth-i18n] gem.

data/doc/guides/internals.rdoc

@@ -1,233 +0,0 @@
-= Rodauth Internals
-
-Rodauth's implementation heavily uses metaprogramming in order to DRY up the codebase, which can be a little intimidating to developers who are not familiar with the codebase.  This guide explains how Rodauth is built, which should make the internals easier to understand.
-
-== Object Model
-
-First, let's talk about the basic parts of Rodauth.
-
-=== Rodauth::Auth
-
-Rodauth::Auth is the core of rodauth.  If a user calls +rodauth+ inside their Roda application, they get a Rodauth::Auth subclass instance.  Rodauth's configuration DSL is designed to build a Rodauth::Auth subclass appropriate to the application, by loading only the features that are needed, and overriding defaults as appropriate.
-
-=== Rodauth::Configuration
-
-Inside the block you pass to <tt>plugin :rodauth</tt>, +self+ is an instance of this class.  This class is mostly empty, as most of Rodauth is implemented as separate features, and the configuration for each feature is loaded as a separate module into this instance.
-
-=== Rodauth::Feature
-
-Each of the parts of rodauth that you can use is going to be a separate feature.  Rodauth::Feature is a Module subclass, and every rodauth feature you load is an instance of this class, which is included in the Rodauth::Auth subclass used by the Roda application.  Rodauth::Feature has many methods designed to make building Rodauth features easier by defining methods in the Rodauth::Feature instance.
-
-=== Rodauth::FeatureConfiguration
-
-Just as each feature is a module included in the Rodauth::Auth subclass for the application, each feature also contains a configuration module that is an instance of Rodauth::FeatureConfiguration (also a module subclass).  For each feature you load into the Rodauth configuration, the Rodauth::Configuration instance is extended with the feature's Rodauth::FeatureConfiguration instance, which is what makes the feature's configuration methods available inside the <tt>plugin :rodauth</tt> block.  This is why you need to enable the features in Rodauth before configuring them.
-
-
-== Object Model Example
-
-Here's some commented output hopefully showing the relation between the different parts
-
-   Roda.plugin :rodauth do
-     self                       # => #<Rodauth::Configuration> (instance)
-     auth                       # => Rodauth::Auth subclass
-
-     singleton_class.ancestors  # => [#<Class:#<Rodauth::Configuration>> (singleton class of self),
-                                #     Rodauth::FeatureConfiguration::Base (instance of Rodauth::FeatureConfiguration),
-                                #     Rodauth::Configuration,
-                                #     ...]
-     auth.ancestors             # => [Rodauth::Auth subclass,
-                                #     Rodauth::Base (instance of Rodauth::Feature),
-                                #     Rodauth::Auth,
-                                #     ...]
-
-     enable :login
-
-     singleton_class.ancestors  # => [#<Class:#<Rodauth::Configuration>> (singleton class of self),
-                                #     Rodauth::FeatureConfiguration::Login (instance of Rodauth::FeatureConfiguration),
-                                #     Rodauth::FeatureConfiguration::Base (instance of Rodauth::FeatureConfiguration),
-                                #     Rodauth::Configuration,
-                                #     ...]
-     auth.ancestors             # => [Rodauth::Auth subclass,
-                                #     Rodauth::Login (instance of Rodauth::Feature),
-                                #     Rodauth::Base (instance of Rodauth::Feature),
-                                #     Rodauth::Auth,
-                                #     ...]
-   end
-
-   Roda.rodauth                 # => Rodauth::Auth subclass
-   Roda.rodauth.ancestors       # => [Rodauth::Auth subclass,
-                                #     Rodauth::Login (instance of Rodauth::Feature),
-                                #     Rodauth::Base (instance of Rodauth::Feature),
-                                #     Rodauth::Auth,
-                                #     ...]
-
-   Roda.route do |r|
-     rodauth                    # => Rodauth::Auth subclass instance
-   end
-
-== Feature Creation Example
-
-Here's a heavily commented example showing what is going on inside a Rodauth feature.
-
-  module Rodauth
-    # Feature.define takes a symbol, specifying the name of the feature. This
-    # is the same symbol you would pass to enable when loading the feature into
-    # the Rodauth configuration.  Feature is a module subclass, and Feature.define
-    # is a class method that creates an instance of Feature (a module) and executes
-    # the block in the context of the Feature instance.
-    #
-    # The second argument is optional, and sets the Feature instance and related
-    # FeatureConfiguration instance to a constant in the Rodauth namespace, which
-    # makes it easier to locate via inspect.
-    Feature.define(:foo, :Foo) do
-      # Inside this block, self is an instance of Feature.  As this instance of
-      # Feature will be included in the Rodauth::Auth subclass instance if
-      # the feature is loaded into the rodauth configuration, methods you define
-      # in this block (via def or define_method) will be callable on any
-      # rodauth object if this feature is loaded into the rodauth configuration.
-
-      # Feature has many instance methods that define methods in the Feature
-      # instance.  This is one of those methods, which sets the text of the notice
-      # flash, shown after successful submission of the form. It's basically
-      # equivalent to executing this code in the feature:
-      #
-      #   def foo_notice_flash
-      #     "It worked!"
-      #   end
-      #
-      # while also adding a method to the configuration which does:
-      #
-      #   def foo_notice_flash(v=nil, &block)
-      #     block ||= proc{v}
-      #     @auth.class_eval do
-      #       define_method(:foo_notice_flash, &block)
-      #     end
-      #   end
-      #
-      # This is what easily allows you to modify any part of Rodauth during
-      # configuration.  The Rodauth::Auth subclass has the default behavior
-      # added via a method in an included module (the Feature instance), and the
-      # Rodauth::Configuration instance has a method that when called defines
-      # a method in the Rodauth::Auth subclass itself, which will take precedence
-      # over the default method, which defined in the included Feature instance.
-      notice_flash "It worked!"
-
-      # The rest of these method calls are fairly similar to notice_flash.
-      # This defines the foo_error_flash method, for the error flash message to
-      # show if the form submission wasn't successful.
-      error_flash "There was an error"
-
-      # This defines the foo_view method to use template 'foo.str' in the templates
-      # folder, and set the title of the page to 'Foo'.
-      view 'foo', 'Foo'
-
-      # This defines the foo_additional_form_tags method, which would generally be called
-      # inside the foo.str template.
-      additional_form_tags
-
-      # This defines the foo_button method, for the text to use on the submit button
-      # for the form in foo.str.
-      button 'Submit'
-
-      # This defines the foo_redirect method, for where to redirect after successful submission
-      # of the form.
-      redirect
-
-      # This defines the before_foo method, called before performing the foo action.
-      before
-
-      # This defines the after_foo method, called after successfully performing the foo action.
-      after
-
-      # This defines a loaded_templates method that calls super and adds 'foo' as one of the
-      # templates.  This is necessary for precompilation of templates to work.
-      loaded_templates ['foo']
-
-      # This defines the following methods related to sending email:
-      #
-      # * foo_email_subject: uses given subject
-      # * foo_email_body: renders foo-email template
-      # * create_foo_email: creates Mail::Message using subject and body
-      # * send_foo_email: sends created email
-      #
-      # The foo-email template should be included in the loaded_templates call to make sure
-      # template precompilation works.
-      email :foo, 'Foo Subject'
-
-      # auth_value_method is a generic method that takes two arguments, a method to define
-      # and a default value.  It is similar to the methods above, except that it allows
-      # arbitrary method names.  The notice_flash, error_flash, button, and additional_form_tags
-      # methods are actually defined in terms of this method.
-      #
-      # So this particular method defines a foo_error_status method that will return 401 by
-      # default, but also adds a configuration method that allows you to override the default.
-      auth_value_method :foo_error_status, 401
-
-      # This is similar to auth_value_method, but it only adds the configuration method.
-      # Using this should only be done if you have defining the method in the feature
-      # separately (see below).
-      auth_value_methods :foo_bar
-
-      # This is similar to auth_value_methods, but it changes the configuration method so that
-      # a block is required and you cannot provide an argument.  This is used for the cases
-      # where a statically defined value would never make sense, such as when any correct
-      # behavior would depend on accessing request-specific information.
-      auth_methods :foo
-
-      # route defines a route used for the feature.  This is the code that will be executed
-      # if a user goes to /foo in the Roda app.
-      route do |r|
-        # Inside the block, you are in the context of the Rodauth::Auth subclass instance.
-        # r is the Roda::RodaRequest subclass instance, just as it would be for a Roda
-        # route block.
-
-        # route adds a before_foo_route method that by default does nothing. It also
-        # adds a configuration method that you can call to set behavior that will be
-        # executed before routing.
-        before_foo_route
-
-        # Just like in Roda, r.get is called for GET requests
-        r.get do
-          # This will render a view to the user, using the foo.erb template from the
-          # templates directory (unless the user has overridden it), inside the Roda
-          # application's layout.
-          foo_view
-        end
-
-        # Just like in Roda, r.post is called for POST requests
-        r.post do
-          # This is called before performing the foo action
-          before_foo
-
-          # This assumes foo returns false or nil on failure, or otherwise on
-          # success.
-          if foo 
-            # In general, Rodauth only calls after_foo if foo is successful.
-            after_foo
-
-            # Successful form submission will usually set the notice flash,
-            # the redirect to the appropriate page.
-            set_notice_flash foo_notice_flash
-            redirect foo_redirect
-          else
-            # Unsucessful form subsmission will usually set the error flash,
-            # the redisplay the page so that the submission can be fixed.
-            set_error_flash foo_error_flash
-            foo_view
-          end
-        end
-      end
-
-      # This is the default behavior for the foo method, if a user doesn't
-      # call the foo method inside the configuration block.
-      def foo
-        # Do Something
-      end
-
-      # This is the default behavior for the foo_bar method, if a user doesn't
-      # call the foo_bar method inside the configuration block.
-      def foo_bar
-        42
-      end
-    end
-  end

data/doc/guides/links.rdoc

@@ -1,12 +0,0 @@
-= Display authentication links
-
-You can retrieve a relative URL to any Rodauth action by calling the
-corresponding <tt>*_path</tt> method on the Rodauth instance:
-
-  <a href="<%= rodauth.login_path %>">Sign in</a>
-  <a href="<%= rodauth.create_account_path %>">Sign up</a>
-
-For absolute URLs instead of paths, you can use the <tt>*_url</tt> methods:
-
-  <a href="<%= rodauth.login_url %>">Sign in</a>
-  <a href="<%= rodauth.create_account_url %>">Sign up</a>

data/doc/guides/login_return.rdoc

@@ -1,37 +0,0 @@
-= Redirect to original page after login
-
-When the user attempts to open a page that requires authentication, Rodauth
-redirects them to the login page. It can be useful to redirect them back to
-the page they originally requested after successful login.  Similarly, you
-can do this for pages requiring multifactor authentication.
-
-  plugin :rodauth do
-    enable :login, :logout, :otp
-
-    # Have successful login redirect back to originally requested page
-    login_return_to_requested_location? true
-
-    # Have successful multifactor authentication redirect back to
-    # originally requested page
-    two_factor_auth_return_to_requested_location? true
-  end
-
-You can manually set which page to redirect after login or multifactor
-authentication, though it is questionable whether the user will desire
-this behavior compared to the default.
-
-  route do |r|
-    r.rodauth
-
-    # Return the last visited path after login
-    if rodauth.logged_in?
-      # Return to the last visited page after multifactor authentication
-      unless rodauth.two_factor_authenticated?
-        session[rodauth.two_factor_auth_redirect_session_key] = request.fullpath
-      end
-    else
-      session[rodauth.login_redirect_session_key] = request.fullpath
-    end
-
-    # rest of routes
-  end

data/doc/guides/migrate_password_hash_algorithm.rdoc

@@ -1,15 +0,0 @@
-= Migrate users passwords from bcrypt to argon2 or back
-
-If you are currently using the default bcrypt password hash algorithm, and want to
-gradually migrate to the argon2 password hash algorithm, you can use both the argon2
-and update_password_hash features:
-
-  plugin :rodauth do
-    enable :login, :update_password_hash, :argon2
-  end
-
-When a user with a current bcrypt password hash next successfully uses their
-password, their password hash will be migrated to argon2.
-
-If for some reason you want to migrate back from argon2 to bcrypt, you can set
-<tt>use_argon2? false</tt> in your Rodauth configuration.

data/doc/guides/password_column.rdoc

@@ -1,25 +0,0 @@
-= Store password hash in accounts table
-
-By default, Rodauth stores the password hash in a separate
-+account_password_hashes+ table.  This makes it a lot less likely that the
-password hashes will be leaked, especially if you use Rodauth's default
-approach of using database functions for checking the hashes.
-
-However, if you have reasons for storing the password hashes in +accounts+
-table that outweigh the security benefits of Rodauth's default approach,
-Rodauth supports that.
-
-To do this, add the password hash column to the +accounts+ table:
-
-  alter_table :accounts do
-    add_column :password_hash, String
-  end
-
-And then tell Rodauth to use it:
-
-  plugin :rodauth do
-    enable :login, :logout
-
-    # Use the password_hash column in the accounts table
-    account_password_hash_column :password_hash
-  end