rodauth 2.13.0 → 2.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f01d42c90dd22a88566f17b3e77b9495dc1431f004f2f54865cff45a3874ce43
-  data.tar.gz: b09c0a44b2b4f6ab1eb795b11a69ec7acd1d4ed5ac4abbe45d8bb4072cb61e0f
+  metadata.gz: 59e6db4541ac9a7ad8c00cf690d757d6e25b3cbf787b273d4415cc5236add6aa
+  data.tar.gz: dacd42d02a586b2ab34e9dbaa916fb77e365fd436d7be60dbe2a2f32074d25e8
 SHA512:
-  metadata.gz: 2934f2824b7c805f6400fab52aad9c4aaca2f3bbfb4584688619b0b24b9e052a3cecc4b36b6eb7379e13f2a9bf2bc64e0efac077d932e390270401966223e2ae
-  data.tar.gz: c1dcf6d140117743baa62ba0715c99584bb80b8aa933f596424f242c2ffb6a31c7d25f0fdba65fed4b1bd93d63692502c7c63b36a1f2b793083b1972c5313304
+  metadata.gz: ed735a0beee837826544608e9f79fefc4421b311b0a75724a390d1368fe4ae8e68f5b6960085c45f3ba546e7c0faec034dc19023e1c5da70c0abfab5c75a4116
+  data.tar.gz: 8acc037e30b6c7528d7ac6d5c153cdb9f243473ed8a870cf75deff01ae185c0b5bb269f54f2a369e4246c17abe0deff27b576ea207b595cf8eef0cf1d07b8ca5

data/CHANGELOG

@@ -1,3 +1,31 @@
+=== 2.17.0 (2021-09-24)
+
+* Make jwt_refresh work correctly with verify_account_grace_period (jeremyevans)
+
+* Use 4xx status code when attempting to login to or create an unverified account (janko) (#177, #178)
+
+=== 2.16.0 (2021-08-23)
+
+* Add Rodauth.lib for using Rodauth as a library (jeremyevans)
+
+* Make internal_request feature work if the configuration uses only_json? true (janko) (#176)
+
+=== 2.15.0 (2021-07-27)
+
+* Add path_class_methods feature, for getting paths/URLs using class methods (jeremyevans)
+
+* Make default base_url method use configured domain (janko) (#171)
+
+* Add internal_request feature, for interacting with Rodauth by calling methods (jeremyevans, janko)
+
+=== 2.14.0 (2021-06-22)
+
+* Make jwt_refresh feature allow refresh with expired access tokens even if prefix is not set correctly (jeremyevans) (#168)
+
+* Make internal account_in_unverified_grace_period? method handle accounts missing or unverified accounts (janko, jeremyevans) (#167)
+
+* Add remembered_session_id configuration method for getting session id from valid remember token if present (bjeanes) (#166)
+
 === 2.13.0 (2021-05-22)
 
 * Make jwt_refresh expired access token support work when using rodauth.check_active_sessions before calling r.rodauth (renchap) (#165)

data/README.rdoc

@@ -60,6 +60,8 @@ HTML and JSON API for all supported features.
 * Argon2
 * HTTP Basic Auth
 * Change Password Notify
+* Internal Request
+* Path Class Methods
 
 == Resources
 
@@ -68,7 +70,6 @@ Demo Site :: http://rodauth-demo.jeremyevans.net
 Source :: http://github.com/jeremyevans/rodauth
 Bugs :: http://github.com/jeremyevans/rodauth/issues
 Google Group :: https://groups.google.com/forum/#!forum/rodauth
-IRC :: irc://chat.freenode.net/#rodauth
 
 == Dependencies
 
@@ -85,9 +86,9 @@ bcrypt :: Used by default for password hashing, can be skipped
           if password_match? is overridden for custom authentication.
 argon2 :: Used by the argon2 feature as alternative to bcrypt for
           password hashing.
-mail :: Used by default for mailing in the reset password, verify
-        account, verify_login_change, change_password_notify,
-        lockout, and email_auth features.
+mail :: Used by default for mailing in the reset_password, verify_account,
+        verify_login_change, change_password_notify, lockout, and
+        email_auth features.
 rotp :: Used by the otp feature
 rqrcode :: Used by the otp feature
 jwt :: Used by the jwt feature
@@ -831,7 +832,7 @@ overriding for all behavior, using any information from the request:
   plugin :rodauth do
     enable :login, :logout
     accounts_table do
-      request.ip.start_with?("192.168.1") ? :admins : :users
+      request.ip.start_with?("192.168.1.") ? :admins : :users
     end
   end
 
@@ -880,6 +881,7 @@ view the appropriate file in the doc directory.
 * {Disallow Password Reuse}[rdoc-ref:doc/disallow_password_reuse.rdoc]
 * {Email Authentication}[rdoc-ref:doc/email_auth.rdoc]
 * {HTTP Basic Auth}[rdoc-ref:doc/http_basic_auth.rdoc]
+* {Internal Request}[rdoc-ref:doc/internal_request.rdoc]
 * {JSON}[rdoc-ref:doc/json.rdoc]
 * {JWT CORS}[rdoc-ref:doc/jwt_cors.rdoc]
 * {JWT Refresh}[rdoc-ref:doc/jwt_refresh.rdoc]
@@ -892,6 +894,7 @@ view the appropriate file in the doc directory.
 * {Password Expiration}[rdoc-ref:doc/password_expiration.rdoc]
 * {Password Grace Period}[rdoc-ref:doc/password_grace_period.rdoc]
 * {Password Pepper}[rdoc-ref:doc/password_pepper.rdoc]
+* {Path Class Methods}[rdoc-ref:doc/path_class_methods.rdoc]
 * {Recovery Codes}[rdoc-ref:doc/recovery_codes.rdoc]
 * {Remember}[rdoc-ref:doc/remember.rdoc]
 * {Reset Password}[rdoc-ref:doc/reset_password.rdoc]
@@ -1051,6 +1054,46 @@ authenticated_webauthn_id :: (webauthn feature) If the current session was
          URL to the route. Any options passed to this method will be converted
          into query parameters.
 
+=== Calling Rodauth Methods for Other Accounts
+
+In some cases, you may want to interact with Rodauth directly on behalf
+of a user.  For example, let's say you want to create accounts or change passwords
+for existing accounts.  Using Rodauth's internal_request feature, you can do this
+by:
+
+  plugin :rodauth do
+    enable :create_account, :change_password, :internal_request
+  end
+  rodauth.create_account(login: 'foo@example.com', password: '...')
+  rodauth.change_password(account_id: 24601, password: '...')
+
+Here the +rodauth+ method is called as the Roda class level, which returns
+the appropriate <tt>Rodauth::Auth</tt> subclass.  You call internal request
+methods on that class to perform actions on behalf of a user. See the
+{internal request feature documentation}[rdoc-ref:doc/internal_request.rdoc]
+for details.
+
+== Using Rodauth as a Library
+
+Rodauth was designed to serve as an authentication framework for Rack applications.
+However, Rodauth can be used purely as a library outside of a web application. You
+can do this by requiring +rodauth+, and using the +Rodauth.lib+ method to return
+a <tt>Rodauth::Auth</tt> subclass, which you can call methods on.  You pass the
++Rodauth.lib+ method an optional hash of Rodauth plugin options and a Rodauth
+configuration block:
+
+  require 'rodauth'
+  rodauth = Rodauth.lib do
+    enable :create_account, :change_password
+  end
+  rodauth.create_account(login: 'foo@example.com', password: '...')
+  rodauth.change_password(account_id: 24601, password: '...')
+
+This supports builds on top of the internal_request support (it implicitly loads
+the internal_request feature before processing the configuration block), and
+allows the use of Rodauth in non-web applications. Note that you still have to
+setup a Sequel::Database connection for Rodauth to use for data storage.
+
 === With Multiple Configurations
 
 Rodauth supports using multiple rodauth configurations in the same
@@ -1362,7 +1405,7 @@ custom methods that will be callable on the +rodauth+ object.
 
 === Using External Features
 
-The enable configuration method is able to load features external to
+The +enable+ configuration method is able to load features external to
 Rodauth.  You need to place the external feature file where it can be
 required via rodauth/features/feature_name. That file should
 use the following basic structure
@@ -1401,7 +1444,7 @@ use the following basic structure
     end
   end
 
-See the {internals guide}[rdoc-ref:doc/internals.rdoc] for a more complete
+See the {internals guide}[rdoc-ref:doc/guides/internals.rdoc] for a more complete
 example of how to construct features.
 
 === Overriding Route-Level Behavior

data/doc/internal_request.rdoc

@@ -0,0 +1,463 @@
+= Documentation for Internal Request Feature
+
+The internal request feature allows interacting with Rodauth by
+calling methods, and is expected to be used mostly for administrative
+purposes.  It allows for things like an changing a login or password
+for an existing user, without requiring that the user login to the
+system. The reason the feature is named +internal_request+ is that
+it internally submits requests to Rodauth, which are handled almost
+identically to how actual web requests will be handled by Rodauth.
+
+The general form of calling these methods is:
+
+  App.rodauth.internal_request_method(hash)
+
+Where +App+ is the Roda class, and +internal_request_method+ is the
+method you are calling.  For example:
+
+  App.rodauth.change_password(account_id: 1, password: 'foobar')
+
+Will change the password for the account with id 1 to +foobar+.
+
+All internal request methods support the following options.  For
+internal requests that require an existing account, you should
+generally use one of the two following options:
+
+:account_id :: The id of the account to be considered as logged in when the internal request is submitted (most internal requests require a logged in account). This value is assumed to represent an existing account, the database is not checked to confirm that.
+:account_login :: The login of the account to be considered as logged in when the internal request is submitted (most internal requests require a login). This will query the database to determine the account's id before submitting the request. If there is no non-closed account for the login, this will raise an exception.
+
+There are additional options available, that you should only use
+if you have special requirements:
+
+:authenticated_by :: The array of strings to use for how the internal request's session was authenticated.
+:env :: A hash to merge into the internal request environment hash. Keys given will override default values, so you will probably have problems if you directly use an existing request environment.
+:session :: A hash for the session to use.
+:params :: A hash of custom parameters.
+
+All remaining options are considered parameters. Using the
+previous example:
+
+  App.rodauth.change_password(account_id: 1, password: 'foobar')
+
+The <tt>password: 'foobar'</tt> part means that the parameters
+for the request will be <tt>{rodauth.password_param => 'foobar'}</tt>,
+where +rodauth.password_param+ is the value of +password_param+ in
+your Rodauth configuration (this defaults to <tt>"password"</tt>).
+
+Passing any options not mentioned above that are not valid Rodauth
+parameters will result in a warning.
+
+== Configuration
+
+In general, the configuration for internal requests is almost
+the same as for regular requests.  There are some minor changes
+for easier usability.  +modifications_require_password?+ (and
+similar methods for requiring password),
++require_login_confirmation?+, and +require_password_confirmation?+
+are set to false. In general, the caller of the method should not
+be able to determine the user's password, and there is no point
+in requiring parameter confirmation when calling the method
+directly.
+
+You can override the configuration for internal requests by using
+the +internal_request_configuration+ configuration method. For
+example, you can set the minimum length for logins to be 15
+for normal requests, but only 3 for internal requests:
+
+  plugin :rodauth do
+    enable :create_account, :internal_request
+    login_minimum_length 15
+
+    internal_request_configuration do
+      login_minimum_length 3
+    end
+  end
+
+Another approach for doing this is to call the +internal_request?+
+method inside configuration method blocks:
+
+  plugin :rodauth do
+    enable :create_account, :internal_request
+    login_minimum_length{internal_request? ? 3 : 15}
+  end
+
+== Return Values and Exceptions
+
+Internal request methods ending in a question mark return true or false.
+Most other internal request methods return nil on success, and or raise a
+Rodauth::InternalRequestError exception on failure.  The exception
+message will include the flash message, {the reason for the
+failure}[rdoc-ref:doc/error_reasons.rdoc] if available, and any field errors.
+This data can also be retrieved via +flash+, +reason+, and +field_errors+
+attributes on the exception object.
+
+If an internal request method returns a non-nil value on success,
+it will be documented in the Features section below. In such
+cases, unless documented below, the methods will still raise a
+Rodauth::InternalRequestError exception on failure.
+
+== Domain
+
+While it is a good idea to use the +domain+ configuration method
+to force a domain to use, as it can avoid DNS rebinding attacks,
+Rodauth can function without it, as it can use the domain of the
+request.  However, for internal requests, there is no submitted
+domain, and Rodauth does not know what to use as the domain. To
+avoid potentially using a wrong domain, Rodauth will raise an
+Rodauth::InternalRequestError in internal requests if a domain
+is needed and has not been configured.
+
+== Features
+
+This section documents the methods that are available for each
+feature. You must load that feature and the internal request feature
+in order to call the internal request methods for that feature.
+Some features support multiple internal request methods, and
+each internal request method supported will be documented under
+the appropriate subheading.
+
+If the method subheading states it it requires an account, you
+must pass the +:account_id+ or +account_login+ option when calling
+the method.
+
+If the method subheading states it it requires an account or
+a login, you must pass either +:login+, +:account_id+, or
++account_login+ when calling the method.
+
+=== Base
+
+=== account_exists?
+
+The +account_exists?+ method returns whether the account exists
+for the given login.
+
+Options:
++:login+ :: (required) The login for the account.
+
+=== account_id_for_login
+
+The +account_id_for_login+ method returns the account id for
+the given login. A Rodauth::InternalRequestError is raised
+if the login given is not valid.
+
+Options:
++:login+ :: (required) The login for the account.
+
+=== internal_request_eval
+
+The +internal_request_eval+ requires a block and will +instance_eval+
+the block the context of an internal request instance.  This allows
+you full usage of the +Rodauth::Auth+ API inside the request.
+Before using this method, you should have a good understanding
+of Rodauth's internals and the effects of calling any methods you
+are calling inside the block.
+
+The return value of the method will be the return value of the
+block, unless one of the methods in the block has set a
+different return value.
+
+=== Change Login
+
+==== change_login (requires account)
+
+The +change_login+ method changes the login for the account.
+
+Options:
++:login+ :: (required) The new login for the account. Note that if the +:account_login+ option is provided, that is the current login for the account, not the new login.
+
+=== Change Password
+
+==== change_password (requires account)
+
+The +change_password+ method changes the password for the account.
+
+Options:
++:password+ or +new_password+ :: (required) The new password for the account.
+
+=== Close Account
+
+==== close_account (requires account)
+
+The +close_account+ method closes the account.  There is no method
+in Rodauth to reopen closed accounts.
+
+=== Create Account
+
+==== create_account
+
+The +create_account+ method creates an account.
+
+Options:
++:login+ :: (required) The login for the created account.
++:password+ :: The password for the created account.
+
+=== Email Auth
+
+==== email_auth_request (requires account or login)
+
+The +email_auth_request+ method requests an email with an
+authentication link be sent to the account's email address.
+
+==== email_auth
+
+The +email_auth+ method determines if the given email authentication
+key is valid.
+
+This method will return the account id if the authentication key is
+valid.
+
+Options:
++:email_auth_key+ :: (required) The email authentication key for the account.
+
+==== valid_email_auth?
+
+The +valid_email_auth?+ method returns whether the given email
+authentication key is valid.
+
+Options:
++:email_auth_key+ :: (required) The email authentication key for the account.
+
+=== Lockout
+
+==== lock_account (requires account)
+
+The +lock_account+ method locks an account, even if the account has
+not experienced any login failures.  This is one method only available
+as an internal request.
+
+==== unlock_account_request (requires account or login)
+
+The +unlock_account_request+ method requests an email with an
+link to unlock the account be sent to the account's email address.
+
+==== unlock_account
+
+The +unlock_account+ method unlocks the account.
+
+If an +:account_id+ or +:account_login+ option is provided, this
+will unlock the account without requiring the unlock account key
+value.
+
+Options:
++:unlock_account_key+ :: The unlock account key for the account. This allows unlocking accounts by key, without knowing the account id or login.
+
+=== Login
+
+==== login (requires account or login)
+
+The +login+ method determines if the given password is valid for
+the given account.
+
+This method will return the account id if the password is valid.
+
+Options:
++:password+ :: (required) The password for the account.
+
+==== valid_login_and_password? (requires account or login)
+
+The +valid_login_and_password?+ method returns whether the given
+password is valid for the given account.
+
+Options:
++:password+ :: (required) The password for the account.
+
+=== OTP
+
+==== otp_setup_params (requires account)
+
+The +otp_setup_params+ method returns a hash with an +:otp_setup+ 
+key, and an +:otp_setup_raw+ key if the Rodauth configuration uses
++hmac_secret+.
+
+The +:otp_setup+ key in the returned hash specifies the OTP secret.
+
+This hash should be merged into the options submitted to the
++otp_setup+ method in order to complete OTP setup.
+
+==== otp_setup (requires account)
+
+The +otp_setup+ method enables OTP multifactor authentication for
+the account.
+
+The values in the hash returned by the +otp_setup_params+ hash
+must be passed as options to this method.
+
+Additional Options:
++:otp_auth+ :: (required) The current OTP authentication code for the OTP secret.
+
+==== otp_auth (requires account)
+
+The +otp_auth+ method determines if the OTP authentication code is
+valid for the account.
+
+Options:
++:otp_auth+ :: (required) The current OTP authentication code for account.
+
+==== valid_otp_auth? (requires account)
+
+The +valid_otp_auth?+ method returns whether the OTP authentication
+code is valid for the account.
+
+Options:
++:otp_auth+ :: (required) The current OTP authentication code for account.
+
+==== otp_disable (requires account)
+
+The +otp_disable+ method disables OTP authentication for the account.
+
+=== Recovery Codes
+
+==== recovery_codes (requires account)
+
+The +recovery_codes+ method returns an array of recovery codes for
+the account.  This array can be empty if no recovery codes are setup.
+
+Options:
++:add_recovery_codes+ :: Generate new recovery codes for the account, up to the configured +recovery_codes_limit+, before returning the codes.
+
+==== recovery_auth (requires account)
+
+The +recovery_auth+ method determines if the recovery authentication
+code is valid for the account.
+
+Options:
++:recovery_codes+ :: (required) A valid recovery code for the account. This option sounds like it would take an array of recover codes, but it only takes a single recovery code.
+
+==== valid_recovery_auth? (requires account)
+
+The +valid_recovery_auth?+ method returns whether the recovery
+authentication code is valid for the account.
+
+Options:
++:recovery_codes+ :: (required) A valid recovery code for the account. This option sounds like it would take an array of recover codes, but it only takes a single recovery code.
+
+=== Remember
+
+==== remember_setup (requires_account)
+
+The +remember_setup+ method setups up the remember feature for
+the account, and returns the cookie value that can be used for
+the remember cookie.
+
+==== remember_disable (requires_account)
+
+The +remember_disable+ method disables the remember feature for
+the account.
+
+==== account_id_for_remember_key
+
+The +account_id_for_remember_key+ method returns the account id
+for the given remember key.
+
+Options:
++:remember+ :: (required) The remember key for the account. This is the same value returned by +remember_setup+.
+
+=== Reset Password
+
+==== reset_password_request (requires account or login)
+
+The +reset_password_request+ method requests an email with an
+link to reset the password for the account be sent to the account's
+email address.
+
+==== reset_password
+
+The +reset_password+ method resets the password for an account.
+This is similar to the +change_password+ method, but requires
+that a reset password key has been created for the account, and
+removes the key after the password has been reset.
+
+If an +:account_id+ or +:account_login+ option is provided, this
+will reset the password for the account without requiring the
+reset password key value.
+
+Options:
++:password+ :: (required) The new password for the account.
++:reset_password_key+ :: The reset password key for the account. This allows resetting passwords by key, without knowing the account id or login.
+
+=== SMS Codes
+
+==== sms_setup (requires account)
+
+The +sms_setup+ method sends an SMS message to the given
+phone number with a code to setup SMS authentication for
+the account.
+
+Options:
++:sms_phone+ :: (required) The phone number to use to setup SMS authentication.
+
+==== sms_confirm (requires account)
+
+The +sms_confirm+ method sets up SMS authentication for
+an account, confirming that the SMS authentication code
+sent previously was received.
+
+Options:
++:sms_code+ :: (required) The authentication code sent to the user for setting up SMS authentication.
+
+==== sms_request (requires account)
+
+The +sms_setup+ method sends an SMS message to the account's
+SMS phone number with an authentication code for two factor
+authentication.
+
+==== sms_auth (requires account)
+
+The +sms_auth+ method determines if the SMS authentication code is
+valid for the account.
+
+Options:
++:sms_code+ :: (required) The authentication code sent to the user via SMS.
+
+==== valid_sms_auth? (requires account)
+
+The +valid_sms_auth?+ method returns whether the SMS authentication
+code is valid for the account.
+
+Options:
++:sms_code+ :: (required) The authentication code sent to the user via SMS.
+
+==== sms_disable (requires account)
+
+The +sms_disable+ method disables SMS authentication for the account.
+
+=== Two Factor Base
+
+==== two_factor_disable (requires_account)
+
+The +two_factor_disable+ method disables all multifactor authentication
+for the account.
+
+=== Verify Account
+
+==== verify_account_resend (requires account or login)
+
+The +verify_account_resend+ method resends the account verification email
+to the account's email address.
+
+==== verify_account
+
+The +verify_account+ method verifies the account.
+to the account's email address.
+
+If an +:account_id+ or +:account_login+ option is provided, this
+will verify the account without requiring the verify account key value.
+
+Options:
++:password+ :: The password for the account, if setting up passwords during verification.
++:verify_account_key+ :: The verify account key for the account. This allows verifying accounts by key, without knowing the account id or login.
+
+=== Verify Login Change
+
+==== verify_login_change
+
+The +verify_login_change+ method verifies the login change for the
+account.
+
+If an +:account_id+ or +:account_login+ option is provided, this
+will verify the account without requiring the verify account key value.
+If the +:account_login+ option is provided, it specifies the current
+account login, before the change.
+
+Options:
++:verify_login_change_key+ :: The verify login change key for the account. This allows verifying login changes by key, without knowing the account id or login.

data/doc/path_class_methods.rdoc

@@ -0,0 +1,10 @@
+= Documentation for Path Class Methods Feature
+
+The path class methods feature allows for calling the *_path and *_url
+methods directly on the class, as opposed to an instance of the class.
+
+In order for the *_url methods to be used, you must use the base_url
+configuration so that determining the base URL doesn't depend on the
+submitted request, as the request will not be set when using the
+class method. Failure to do this will probably result in a NoMethodError
+being raised.

data/doc/release_notes/2.14.0.txt

@@ -0,0 +1,17 @@
+= New Features
+
+* A remembered_session_id method has been added for getting the
+  account id from a valid remember token, without modifying the
+  session to log the account in.
+
+= Other Improvements
+
+* The jwt_refresh feature's support for allowing refresh with
+  an expired access token now works even if the Rodauth
+  configuration uses an incorrect prefix.
+
+* The internal account_in_unverified_grace_period? method now
+  returns false if an account has not been loaded and the
+  session has not been logged in. Previously, calling this
+  method in such cases would result in an exception being
+  raised.