rodauth 0.10.0 → 1.0.0

data/Rakefile

@@ -1,7 +1,7 @@
 require "rake"
 require "rake/clean"
 
-CLEAN.include ["rodauth-*.gem", "rdoc", "coverage"]
+CLEAN.include ["rodauth-*.gem", "rdoc", "coverage", "www/public/rdoc", "www/public/*.html"]
 
 # Packaging
 
@@ -12,7 +12,7 @@ end
 
 ### RDoc
 
-RDOC_DEFAULT_OPTS = ["--line-numbers", "--inline-source", '--title', 'Rodauth: Authentication framework using Roda, Sequel, and PostgreSQL']
+RDOC_DEFAULT_OPTS = ["--line-numbers", "--inline-source", '--title', 'Rodauth: Authentication and Account Management Framework for Rack Applications']
 
 begin
   gem 'hanna-nouveau'
@@ -44,11 +44,11 @@ task :default=>:spec
 
 spec = proc do |env|
   env.each{|k,v| ENV[k] = v}
-  sh "#{FileUtils::RUBY} spec/rodauth_spec.rb"
+  sh "#{FileUtils::RUBY} spec/all.rb"
   env.each{|k,v| ENV.delete(k)}
 end
 
-desc "Run specs"
+desc "Run specs on PostgreSQL"
 task "spec" do
   spec.call({})
 end
@@ -66,12 +66,13 @@ task "spec_w" do
   sh %{#{rake} 2>&1 | egrep -v \": warning: instance variable @.* not initialized|: warning: method redefined; discarding old|: warning: previous definition of|: warning: statement not reached"}
 end
 
-desc "Setup database used for testing"
-task :db_setup do
-  sh 'echo "CREATE USER rodauth_test PASSWORD \'rodauth_test\'" | psql -U postgres'
-  sh 'echo "CREATE USER rodauth_test_password PASSWORD \'rodauth_test\'" | psql -U postgres'
+desc "Setup database used for testing on PostgreSQL"
+task :db_setup_postgres do
+  sh 'psql -U postgres -c "CREATE USER rodauth_test PASSWORD \'rodauth_test\'"'
+  sh 'psql -U postgres -c "CREATE USER rodauth_test_password PASSWORD \'rodauth_test\'"'
   sh 'createdb -U postgres -O rodauth_test rodauth_test'
-  sh 'echo "CREATE EXTENSION citext" | psql -U postgres rodauth_test'
+  sh 'psql -U postgres -c "CREATE EXTENSION citext" rodauth_test'
+  $: << 'lib'
   require 'sequel'
   Sequel.extension :migration
   Sequel.postgres(:user=>'rodauth_test', :password=>'rodauth_test') do |db|
@@ -82,9 +83,96 @@ task :db_setup do
   end
 end
 
-desc "Teardown database used for testing"
-task :db_teardown do
+desc "Teardown database used for testing on MySQL"
+task :db_teardown_postgres do
   sh 'dropdb -U postgres rodauth_test'
   sh 'dropuser -U postgres rodauth_test_password'
   sh 'dropuser -U postgres rodauth_test'
 end
+
+desc "Setup database used for testing on MySQL"
+task :db_setup_mysql do
+  sh 'mysql --user=root -p mysql < spec/sql/mysql_setup.sql'
+  $: << 'lib'
+  require 'sequel'
+  Sequel.extension :migration
+  Sequel.mysql2('rodauth_test', :user=>'rodauth_test_password', :password=>'rodauth_test') do |db|
+    Sequel::Migrator.run(db, 'spec/migrate')
+  end
+  Sequel.mysql2('rodauth_test', :user=>'rodauth_test_password', :password=>'rodauth_test') do |db|
+    Sequel::Migrator.run(db, 'spec/migrate_password', :table=>'schema_info_password')
+  end
+end
+
+desc "Teardown database used for testing on MySQL"
+task :db_teardown_mysql do
+  sh 'mysql --user=root -p mysql < spec/sql/mysql_teardown.sql'
+end
+
+desc "Setup database used for testing on Microsoft SQL Server"
+task :db_setup_mssql do
+  sh 'sqlcmd -E -e -b -r1 -i spec\\sql\\mssql_setup.sql'
+  $: << 'lib'
+  require 'sequel'
+  Sequel.extension :migration
+  Sequel.tinytds('rodauth_test', :user=>'rodauth_test_password', :password=>'rodauth_test') do |db|
+    Sequel::Migrator.run(db, 'spec/migrate')
+  end
+  Sequel.tinytds('rodauth_test', :user=>'rodauth_test_password', :password=>'rodauth_test') do |db|
+    Sequel::Migrator.run(db, 'spec/migrate_password', :table=>'schema_info_password')
+  end
+end
+
+desc "Teardown database used for testing on Microsoft SQL Server"
+task :db_teardown_mssql do
+  sh 'sqlcmd -E -e -b -r1 -i spec\\sql\\mssql_teardown.sql'
+end
+
+desc "Run specs on MySQL"
+task :spec_mysql do
+  spec.call('RODAUTH_SPEC_DB'=>'mysql2://rodauth_test:rodauth_test@localhost/rodauth_test')
+end
+
+task :spec_travis do
+  if defined?(RUBY_ENGINE) && RUBY_ENGINE == 'jruby'
+    pg_db = 'jdbc:postgresql://localhost/rodauth_test?user=postgres'
+    my_db = "jdbc:mysql://localhost/rodauth_test?user=root"
+  else
+    pg_db = 'postgres:///rodauth_test?user=postgres'
+    my_db = "mysql2://localhost/rodauth_test?user=root"
+  end
+  sh 'psql -U postgres -c "CREATE EXTENSION citext" rodauth_test'
+  spec.call('RODAUTH_SPEC_MIGRATE'=>'1', 'RODAUTH_SPEC_DB'=>pg_db)
+  spec.call('RODAUTH_SPEC_MIGRATE'=>'1', 'RODAUTH_SPEC_DB'=>my_db)
+end
+
+desc "Run specs on SQLite"
+task :spec_sqlite do
+  spec_db = if defined?(RUBY_ENGINE) && RUBY_ENGINE == 'jruby'
+    'jdbc:sqlite::memory:'
+  else
+    'sqlite:/'
+  end
+  spec.call('RODAUTH_SPEC_MIGRATE'=>'1', 'RODAUTH_SPEC_DB'=>spec_db)
+end
+
+### Website
+
+rdoc_task_class.new(:website_rdoc) do |rdoc|
+  rdoc.rdoc_dir = "www/public/rdoc"
+  rdoc.options += RDOC_OPTS
+  rdoc.rdoc_files.add RDOC_FILES
+end
+
+desc "Make local version of website"
+task :website_base do
+  sh %{#{FileUtils::RUBY} -I lib www/make_www.rb}
+end
+
+desc "Make local version of website, with rdoc"
+task :website => [:website_base, :website_rdoc]
+
+desc "Serve local version of website via rackup"
+task :serve => :website do
+  sh %{#{FileUtils::RUBY} -C www -S rackup}
+end

data/doc/account_expiration.rdoc

@@ -0,0 +1,55 @@
+= Documentation for Account Expiration Feature
+
+The account expiration feature disallows access to accounts after
+a configurable amount of time since the last login or activity
+(default: 180 days since last login).  By default, this feature
+does not track activity times as that can slow things down, but if
+you want to record activity times, you can do so by adding the
+following code to your routing block:
+
+  rodauth.update_last_activity
+
+Note that it only makes sense to do this if you are also expiring
+accounts based on last activity instead of last login, via the
++expire_account_on_last_activity?+ configuration setting.
+
+Note that this feature does not support the reenabling of expired
+accounts, that is something you would have to implement yourself,
+if you need such a feature.
+
+== Auth Value Methods
+
+account_activity_expired_column :: The column in the +account_activity_table+
+                                   storing the expiration timestamp.
+account_activity_id_column :: The column in the +account_activity_table+
+                              storing the account id.
+account_activity_last_activity_column :: The column in the +account_activity_table+
+                                         storing the last activity timestamp.
+account_activity_last_login_column :: The column in the +account_activity_table+
+                                      storing the last login timestamp.
+account_activity_table :: The database table use for storing account
+                          login/activity/expiration timestamps.
+account_expiration_error_flash :: The flash error to show when attempting to
+                                  login to an account that has expired.
+account_expiration_redirect :: Where to redirect after attempting to login to
+                               an account that has expired.
+expire_account_after :: How long in seconds from last login or activity until
+                        an account is considered expired.
+expire_account_on_last_activity? :: Whether to use the last activity timestamp
+                                    when checking an account for expiration.
+                                    By default, this is false and it uses the
+                                    last login timestamp.
+
+== Auth Methods
+
+account_expired? :: Whether the current account has expired.
+account_expired_at :: The expiration timestamp for the current account, nil if the
+                      account hasn't been expired.
+after_account_expiration :: Run arbitrary code after account expiration.
+last_account_activity_at :: The last activity timestamp for the current account, nil if
+                            the account hasn't had activity recorded yet.
+last_account_login_at :: The last login timestamp for the current account, nil if
+                         the account hasn't had a login recorded yet.
+set_expired :: Set the current account as having expired.
+update_last_activity :: Update the last activity timestamp for the account.
+update_last_login :: Update the last login timestamp for the account.

data/doc/base.rdoc

@@ -0,0 +1,104 @@
+= 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
+
+accounts_table :: The database table containing the accounts.
+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.
+db :: The Sequel::Database object used for database access.
+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.
+require_bcrypt? :: Set to false to not require bcrypt, useful if using custom
+                   authentication.
+session_key :: The key in the session hash storing the primary key of the
+               logged in account.
+skip_status_checks? :: Whether status checks should be skipped for accounts.
+                       Defaults to false 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.
+
+=== Other
+
+account_id_column :: The primary key column of the account model.
+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 account model.
+account_unverified_status_value :: The representating unverified accounts.
+default_redirect :: Where to redirect after most successful actions.
+invalid_password_message :: The error message to display when a given
+                            password doesn't match the stored password hash.
+login_column :: The login column in the account model.
+login_label :: The label to use for logins.
+login_param :: The parameter name to use for logins.
+modifications_require_password? :: Whether making changes to an account requires
+                                   the user reinputing their password.
+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.
+use_date_arithmetic? :: Whether the date_arithmetic extension should be loaded into
+                        the database.  Defaults to whether deadline values should
+                        be set.
+use_database_authentication_functions? :: Whether to use functions to do authentication.
+                                          True by default on PostgreSQL, false otherwise.
+
+== Auth Methods
+
+before_rodauth :: Run arbitrary code before handling any rodauth route.
+account_from_login(login) :: Retrieve the account model instance related to the
+                             given login or nil if no login matches.
+account_from_session :: Retrieve the account model instance 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 account currently stored in the
+                         session.
+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.
+authenticated? :: Whether the user has been authenticated. If 2 factor authentication
+                  has not been enabled for the account, this is true only if both
+                  factors have been authenticated.
+clear_session :: Clears the current session.
+csrf_tag :: 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 there is an account currently logged in.
+login_required :: Action to take when a login is required to access the page and
+                  the user is not logged in.
+open_account? :: Whether the current account is an open account (not closed or
+                 unverified).
+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 :: Alias for account_session_value.
+set_error_flash(message) :: Set the current error flash to the given message.
+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.
+unverified_account_message :: The message to use when attempting to login to an
+                              unverified account.
+update_session :: Set the session key to the primary key of the current account.

data/doc/change_login.rdoc

@@ -0,0 +1,29 @@
+= Documentation for Change Login Feature
+
+The change login feature implements a form that a user can use to
+change their login.
+
+== Auth Value Methods
+
+change_login_additional_form_tags :: HTML fragment containing additional
+                                     form tags to use on the change login
+                                     form.
+change_login_button :: The text to use for the change login button.
+change_login_error_flash :: The flash error to show for an unsuccessful
+                            login change.
+change_login_notice_flash :: The flash notice to show after a successful
+                             login change.
+change_login_redirect :: Where to redirect after a sucessful login change.
+change_login_requires_password? :: Whether a password is required when
+                                   changing logins.
+change_login_route :: The route to the change login action.
+
+== Auth Methods
+
+after_change_login :: Run arbitrary code after successful login change.
+before_change_login :: Run arbitrary code before changing a login.
+before_change_login_route :: Run arbitrary code before handling a change login route.
+change_login(login) :: Change the users login to the given login, or
+                       return nil/false if the login cannot be changed to
+                       the given login.
+change_login_view :: The HTML to use for the change login form.

data/doc/change_password.rdoc

@@ -0,0 +1,26 @@
+= Documentation for Change Password Feature
+
+The change password feature implements a form that a user can use to
+change their password.
+
+== Auth Value Methods
+
+change_password_additional_form_tags :: HTML fragment containing additional
+                                        form tags to use on the change password
+                                        form.
+change_password_button :: The text to use for the change password button.
+change_password_error_flash :: The flash error to show for an unsuccessful
+                               password change.
+change_password_notice_flash :: The flash notice to show after a successful
+                                password change.
+change_password_redirect :: Where to redirect after a sucessful password change.
+change_password_requires_password? :: Whether a password is required when
+                                      changing passwords.
+change_password_route :: The route to the change password action.
+
+== Auth Methods
+
+after_change_password :: Run arbitrary code after successful password change.
+before_change_password :: Run arbitrary code before changing the password for an account.
+before_change_password_route :: Run arbitrary code before handling a change password route.
+change_password_view :: The HTML to use for the change password form.

data/doc/close_account.rdoc

@@ -0,0 +1,31 @@
+= Documentation for Close Account Feature
+
+The close account feature allows users to close their accounts.
+
+== Auth Value Methods
+
+account_closed_status_value :: The integer representing closed accounts.
+close_account_additional_form_tags :: HTML fragment containing additional
+                                      form tags to use on the close account
+                                      form.
+close_account_button :: The text to use for the close account button.
+close_account_notice_flash :: The flash notice to show after closing the
+                              account.
+close_account_redirect :: Where to redirect after closing the account.
+close_account_requires_password? :: Whether a password is required when
+                                    closing accounts.
+close_account_route :: The route to the close account action.
+delete_account_on_close? :: Whether to delete the account when closing it,
+                            default value is to use +skip_status_checks?+.
+
+== Auth Methods
+
+after_close_account :: Run arbitrary code after closing the account.
+before_close_account :: Run arbitrary code before closing an account.
+before_close_account_route :: Run arbitrary code before handling a close account route.
+close_account :: Close the account, by default setting the account status
+                 to closed.
+close_account_view :: The HTML to use for the close account form.
+delete_account :: If +delete_account_on_close?+ is true, delete the account
+                  when closing it.
+                  

data/doc/confirm_password.rdoc

@@ -0,0 +1,22 @@
+= Documentation for Confirm Password Feature
+
+The confirm password feature allows you to redirect users to a page to
+confirm their password.  It's used by the remember feature, but can also
+by your application if you want to confirm passwords.
+
+== Auth Value Methods
+
+confirm_password_additional_form_tags :: HTML fragment containing additional form tags to use on the confirm password form.
+confirm_password_button :: The text to use for the confirm password button.
+confirm_password_error_flash :: The flash error to show if password confirmation is unsuccessful.
+confirm_password_notice_flash :: The flash notice to show after password confirmed successful.
+confirm_password_redirect :: Where to redirect after successful password confirmation. By default, uses <tt>session[:confirm_password_redirect]</tt> if set, allowing an easy way to redirect back to the page requesting password confirmation.
+confirm_password_route :: The route to the confirm password form.
+
+== Auth Methods
+
+after_confirm_password :: Run arbitrary code after successful confirmation of password.
+before_confirm_password :: Run arbitrary code before setting that the password has been confirmed.
+confirm_password :: Run arbitrary code on correct password confirmation.
+before_confirm_password_route :: Run arbitrary code before handling the password confirmation route.
+confirm_password_view :: The HTML to use for the confirm password form.

data/doc/create_account.rdoc

@@ -0,0 +1,34 @@
+= Documentation for Create Account Feature
+
+The create account feature allows users to create new accounts.
+
+== Auth Value Methods
+
+create_account_additional_form_tags :: HTML fragment containing additional
+                                       form tags to use on the create account
+                                       form.
+create_account_button :: The text to use for the create account button.
+create_account_error_flash :: The flash error to show for unsuccessful
+                              account creation.
+create_account_notice_flash :: The flash notice to show after successful
+create_account_redirect :: Where to redirect after creating the account.
+create_account_route :: The route to the create account action.
+                        account creation.
+
+== Auth Methods
+
+after_create_account :: Run arbitrary code after creating the account.
+before_create_account :: Run arbitrary code before creating the account.
+before_create_account_route :: Run arbitrary code before handling a create account route.
+create_account_autologin? :: Whether to autologin the user upon
+                             successful account creation, true by default unless verifying
+                             accounts.
+create_account_link :: HTML fragment to display with a link to the create
+                       account form.
+create_account_view :: The HTML to use for the create account form.
+new_account(login) :: Instantiate a new account model instance for the
+                      given login, without saving it.
+save_account :: Insert the account into the database, or return nil/false if that
+                was not successful.
+set_new_account_password :: Set the password for a new account if
+                            +account_password_hash_column+ is set, without saving.