booth 0.0.1

data/lib/booth.rb

@@ -0,0 +1,267 @@
+# ------------
+# Dependencies
+# ------------
+
+# Rails
+require 'active_model'
+require 'active_record'
+require 'active_support'
+
+# Gems
+require 'active_model_otp'
+require 'browser'
+require 'dry-initializer'
+require 'i18n'
+require 'pwned'
+require 'rqrcode'
+require 'tron'
+require 'warden'
+require 'webauthn'
+
+require_relative 'booth/method_object' # Extracted from a gem
+
+# -----
+# BOOTH
+# -----
+
+# Generators
+require 'generators/booth/migration/migration_generator'
+
+# Global
+require_relative 'booth/logging'
+require_relative 'booth/logger'
+require_relative 'booth/errors'
+require_relative 'booth/configuration'
+require_relative 'booth/configure'
+require_relative 'booth/engine'
+
+# Syntax Checkers
+require_relative 'booth/syntaxes/contest_code'
+require_relative 'booth/syntaxes/email'
+require_relative 'booth/syntaxes/ip'
+require_relative 'booth/syntaxes/otp'
+require_relative 'booth/syntaxes/scope'
+require_relative 'booth/syntaxes/scope_comparison'
+require_relative 'booth/syntaxes/secret_key'
+require_relative 'booth/syntaxes/username'
+require_relative 'booth/syntaxes/uuid'
+
+# Helpers
+require_relative 'booth/concerns/action'
+require_relative 'booth/concerns/transition'
+require_relative 'booth/geolocation'
+require_relative 'booth/request'
+require_relative 'booth/routes/userland'
+require_relative 'booth/to_struct'
+require_relative 'booth/mode'
+require_relative 'booth/modes/base'
+require_relative 'booth/modes/username_and_password'
+require_relative 'booth/modes/username_and_webauth'
+require_relative 'booth/modes/username_password_and_otp'
+require_relative 'booth/modes/username_password_and_webauth'
+
+# Model dependencies
+require_relative 'booth/models/contests/scopes/recently_created'
+require_relative 'booth/models/contests/scopes/recently_responded'
+
+# Models
+require_relative 'booth/models/application_record'
+require_relative 'booth/models/audit'
+require_relative 'booth/models/authenticator'
+require_relative 'booth/models/concerns/modeable'
+require_relative 'booth/models/concerns/otpable'
+require_relative 'booth/models/concerns/passwordable'
+require_relative 'booth/models/contest'
+require_relative 'booth/models/credential'
+require_relative 'booth/models/onboarding'
+require_relative 'booth/models/password_reset'
+require_relative 'booth/models/recovery'
+require_relative 'booth/models/session'
+require_relative 'booth/models/user_agent'
+
+# Services
+require_relative 'booth/audits/register/added_otp'
+require_relative 'booth/audits/register/changed_otp'
+require_relative 'booth/audits/register/completed_onboarding'
+require_relative 'booth/audits/register/correct_otp'
+require_relative 'booth/audits/register/correct_password'
+require_relative 'booth/audits/register/requested_password_reset'
+require_relative 'booth/audits/register/logout'
+require_relative 'booth/audits/register/wrong_otp'
+require_relative 'booth/audits/register/wrong_password'
+require_relative 'booth/authenticators/confirm'
+require_relative 'booth/authenticators/credential_mode_after_confirmation'
+require_relative 'booth/authenticators/step'
+require_relative 'booth/contests/get'
+require_relative 'booth/contests/respond'
+require_relative 'booth/contests/set_for_login'
+require_relative 'booth/cooldowns/distance_of_time'
+require_relative 'booth/cooldowns/otp'
+require_relative 'booth/cooldowns/password'
+require_relative 'booth/cooldowns/password_reset'
+require_relative 'booth/cooldowns/strategies/exponential'
+require_relative 'booth/cooldowns/strategies/global'
+require_relative 'booth/cooldowns/strategies/result'
+require_relative 'booth/credentials/create_with_onboarding'
+require_relative 'booth/credentials/create'
+require_relative 'booth/credentials/find_by_username'
+require_relative 'booth/credentials/mode'
+require_relative 'booth/credentials/modes/otp_addable'
+require_relative 'booth/credentials/modes/otp_changeable'
+require_relative 'booth/credentials/modes/otp_manageable'
+require_relative 'booth/credentials/modes/otp_removable'
+require_relative 'booth/credentials/modes/password_addable'
+require_relative 'booth/credentials/modes/password_changeable'
+require_relative 'booth/credentials/modes/password_manageable'
+require_relative 'booth/credentials/modes/password_removable'
+require_relative 'booth/credentials/modes/webauth_addable'
+require_relative 'booth/credentials/modes/webauth_removable'
+require_relative 'booth/credentials/modes/webauth_manageable'
+require_relative 'booth/credentials/otp_authentication'
+require_relative 'booth/credentials/password_authentication'
+require_relative 'booth/credentials/webauth_challenge'
+require_relative 'booth/hooks/after_fetch'
+require_relative 'booth/hooks/before_logout'
+require_relative 'booth/hooks/serialize_from_session'
+require_relative 'booth/hooks/serialize_into_session'
+require_relative 'booth/onboardings/find'
+require_relative 'booth/onboardings/propagate_to_credential'
+require_relative 'booth/onboardings/step'
+require_relative 'booth/password_resets/create'
+require_relative 'booth/password_resets/find'
+require_relative 'booth/password_resets/propagate_to_credential'
+require_relative 'booth/password_resets/step'
+require_relative 'booth/recoveries/create'
+require_relative 'booth/requests/agent'
+require_relative 'booth/requests/authentication'
+require_relative 'booth/requests/ip'
+require_relative 'booth/requests/return_path'
+require_relative 'booth/requests/session'
+require_relative 'booth/requests/storage'
+require_relative 'booth/requests/storages/login'
+require_relative 'booth/requests/storages/otp'
+require_relative 'booth/requests/storages/password_reset'
+require_relative 'booth/requests/storages/password'
+require_relative 'booth/requests/storages/recovery'
+require_relative 'booth/requests/storages/registration'
+require_relative 'booth/requests/storages/webauth'
+require_relative 'booth/requests/sudo'
+require_relative 'booth/sessions/create_and_login'
+require_relative 'booth/sessions/historical_locations'
+require_relative 'booth/sessions/index'
+require_relative 'booth/sessions/revoke_all_others'
+require_relative 'booth/sessions/revoke'
+require_relative 'booth/sessions/to_passport'
+require_relative 'booth/webauth/authentication_verification'
+require_relative 'booth/webauth/demand_user_verification'
+require_relative 'booth/webauth/options_for_create'
+require_relative 'booth/webauth/options_for_get'
+
+# Userland Transitions
+require_relative 'booth/userland/logins/transitions/create/choose_username'
+require_relative 'booth/userland/logins/transitions/create/enter_otp'
+require_relative 'booth/userland/logins/transitions/create/skip_remotes'
+require_relative 'booth/userland/logins/transitions/create/verify_password'
+require_relative 'booth/userland/logins/transitions/create/webauth_authentication_initiation'
+require_relative 'booth/userland/logins/transitions/create/webauth_authentication_verification'
+require_relative 'booth/userland/logins/transitions/new/fallible' # Concern, needs to come first
+require_relative 'booth/userland/logins/transitions/new/already_logged_in'
+require_relative 'booth/userland/logins/transitions/new/mode_first_time'
+require_relative 'booth/userland/logins/transitions/new/mode_username_and_password'
+require_relative 'booth/userland/logins/transitions/new/mode_username_and_webauth'
+require_relative 'booth/userland/logins/transitions/new/mode_username_password_and_otp'
+require_relative 'booth/userland/logins/transitions/new/mode_username_password_and_webauth'
+require_relative 'booth/userland/logins/transitions/new/no_username_chosen'
+require_relative 'booth/userland/logins/transitions/new/remote_session_available'
+require_relative 'booth/userland/logins/transitions/new/timed_out'
+require_relative 'booth/userland/onboardings/transitions/update/choose_mode'
+require_relative 'booth/userland/onboardings/transitions/update/choose_password'
+require_relative 'booth/userland/onboardings/transitions/update/choose_webauth_nickname'
+require_relative 'booth/userland/onboardings/transitions/update/confirm_otp'
+require_relative 'booth/userland/onboardings/transitions/update/confirm_password'
+require_relative 'booth/userland/onboardings/transitions/update/register_otp'
+require_relative 'booth/userland/onboardings/transitions/update/reset_otp'
+require_relative 'booth/userland/onboardings/transitions/update/reset_password'
+require_relative 'booth/userland/onboardings/transitions/update/reset_webauth'
+require_relative 'booth/userland/onboardings/transitions/update/webauth_authentication_initiation'
+require_relative 'booth/userland/onboardings/transitions/update/webauth_authentication_verification'
+require_relative 'booth/userland/onboardings/transitions/update/webauth_registration_initiation'
+require_relative 'booth/userland/onboardings/transitions/update/webauth_registration_verification'
+require_relative 'booth/userland/otps/guards/manageable'
+require_relative 'booth/userland/otps/guards/sudo'
+require_relative 'booth/userland/otps/transitions/update/confirm'
+require_relative 'booth/userland/otps/transitions/update/register'
+require_relative 'booth/userland/otps/transitions/update/reset'
+require_relative 'booth/userland/password_resets/guards/logged_out'
+require_relative 'booth/userland/password_resets/transitions/update/choose_password'
+require_relative 'booth/userland/password_resets/transitions/update/confirm_password'
+require_relative 'booth/userland/password_resets/transitions/update/reset_password'
+require_relative 'booth/userland/passwords/guards/manageable'
+require_relative 'booth/userland/passwords/guards/removable'
+require_relative 'booth/userland/passwords/guards/sudo'
+require_relative 'booth/userland/passwords/transitions/remove/step'
+require_relative 'booth/userland/passwords/transitions/update/choose_password'
+require_relative 'booth/userland/passwords/transitions/update/confirm_password'
+require_relative 'booth/userland/sessions/transitions/destroy/enter_password'
+require_relative 'booth/userland/sessions/transitions/destroy/enter_webauth'
+require_relative 'booth/userland/sessions/transitions/destroy/verify_password'
+require_relative 'booth/userland/sessions/transitions/destroy/webauth_authentication_initiation'
+require_relative 'booth/userland/sessions/transitions/destroy/webauth_authentication_verification'
+require_relative 'booth/userland/sessions/transitions/show/enter_webauth'
+require_relative 'booth/userland/webauths/transitions/create/authentication_initiation'
+require_relative 'booth/userland/webauths/transitions/create/authentication_verification'
+require_relative 'booth/userland/webauths/transitions/create/choose_nickname'
+require_relative 'booth/userland/webauths/transitions/create/registration_initiation'
+require_relative 'booth/userland/webauths/transitions/create/registration_verification'
+require_relative 'booth/userland/webauths/transitions/create/reset'
+require_relative 'booth/userland/webauths/transitions/sudo/authentication_initiation'
+require_relative 'booth/userland/webauths/transitions/sudo/authentication_verification'
+
+# Userland Actions
+require_relative 'booth/userland'
+require_relative 'booth/userland/extract_flash_messages'
+require_relative 'booth/userland/logins/create'
+require_relative 'booth/userland/logins/destroy'
+require_relative 'booth/userland/logins/new'
+require_relative 'booth/userland/onboardings/show'
+require_relative 'booth/userland/onboardings/update'
+require_relative 'booth/userland/otps/destroy'
+require_relative 'booth/userland/otps/edit'
+require_relative 'booth/userland/otps/show'
+require_relative 'booth/userland/otps/sudo'
+require_relative 'booth/userland/otps/update'
+require_relative 'booth/userland/password_resets/create'
+require_relative 'booth/userland/password_resets/new'
+require_relative 'booth/userland/password_resets/show'
+require_relative 'booth/userland/password_resets/update'
+require_relative 'booth/userland/passwords/destroy'
+require_relative 'booth/userland/passwords/edit'
+require_relative 'booth/userland/passwords/remove'
+require_relative 'booth/userland/passwords/show'
+require_relative 'booth/userland/passwords/sudo'
+require_relative 'booth/userland/passwords/update'
+require_relative 'booth/userland/personal_contests/show'
+require_relative 'booth/userland/personal_contests/update'
+require_relative 'booth/userland/recoveries/create'
+require_relative 'booth/userland/recoveries/new'
+require_relative 'booth/userland/registrations/create'
+require_relative 'booth/userland/registrations/new'
+require_relative 'booth/userland/sessions/destroy_one_or_other'
+require_relative 'booth/userland/sessions/index'
+require_relative 'booth/userland/sessions/show'
+require_relative 'booth/userland/webauths/create'
+require_relative 'booth/userland/webauths/destroy'
+require_relative 'booth/userland/webauths/guards/manageable'
+require_relative 'booth/userland/webauths/guards/sudo'
+require_relative 'booth/userland/webauths/index'
+require_relative 'booth/userland/webauths/new'
+require_relative 'booth/userland/webauths/sudo'
+
+# Adminland Helpers
+require_relative 'booth/adminland'
+require_relative 'booth/adminland/recoveries/consume'
+require_relative 'booth/adminland/credentials/create'
+require_relative 'booth/adminland/onboardings/create'
+require_relative 'booth/adminland/onboardings/destroy'
+require_relative 'booth/adminland/onboardings/find'
+require_relative 'booth/adminland/onboardings/index'

data/lib/generators/booth/migration/migration_generator.rb

@@ -0,0 +1,25 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+
+module Booth
+  module Generators
+    class MigrationGenerator < ::Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+      desc 'Generate the migration file for creating the Booth database tables'
+
+      # See https://github.com/rails/rails/blob/9a2e00e27b87632be3528b53efb8bba504688711/activerecord/lib/rails/generators/active_record/migration.rb#L13-L16
+      def self.next_migration_number(dirname)
+        next_migration_number = current_migration_number(dirname) + 1
+        ActiveRecord::Migration.next_migration_number(next_migration_number)
+      end
+
+      def copy_migrations
+        migration_template 'create_booth_mode_types.erb', 'db/migrate/create_booth_mode_types.rb'
+        migration_template 'create_booth_tables.erb', 'db/migrate/create_booth_tables.rb'
+        migration_template 'add_credential_to_users.erb', 'db/migrate/add_credential_to_users.rb'
+      end
+    end
+  end
+end

data/lib/generators/booth/migration/templates/add_credential_to_users.erb

@@ -0,0 +1,18 @@
+class AddCredentialToUsers < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    # Booth assumes that you already have one or more tables for your users.
+
+    # Add a column to your users table holding a reference to the `booth_credentials` table.
+    # Every user record belongs to one corresponding credential record.
+    # If your table is not called "users", you'll of course have to modify the table name below.
+    add_column :users, :credential_id, :uuid
+    add_index :users, :credential_id, unique: true
+    add_foreign_key :users, :booth_credentials, column: :credential_id, on_delete: :nullify
+
+    # If you have multiple, separate user tables, add a reference to them as well.
+    # By the way, feel free to rename the column. It is yours.
+    add_column :employees, :credential_id, :uuid
+    add_index :employees, :credential_id, unique: true
+    add_foreign_key :employees, :booth_credentials, column: :credential_id, on_delete: :nullify
+  end
+end

data/lib/generators/booth/migration/templates/create_booth_mode_types.erb

@@ -0,0 +1,20 @@
+# Don't change anything in this file.
+
+class CreateBoothModeTypes < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def up
+    execute <<-SQL
+      CREATE TYPE booth_credential_mode AS ENUM
+        ('first_time',
+         'username_and_password',
+         'username_password_and_otp',
+         'username_password_and_webauth',
+         'username_and_webauth');
+    SQL
+  end
+
+  def down
+    execute <<-SQL
+      DROP TYPE booth_credential_mode;
+    SQL
+  end
+end

data/lib/generators/booth/migration/templates/create_booth_tables.erb

@@ -0,0 +1,135 @@
+class CreateBoothTables < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    # In order for Postgres to generate UUIDs, you may have to enable this extension first.
+    enable_extension 'pgcrypto'
+    # To register timestamps belonging to IPs we use an hstore field.
+    enable_extension 'hstore'
+
+    ####################################################################################
+    # The following tables are owned by Booth. Do not change anything below this line. #
+    ####################################################################################
+
+    # ------------------------------------------------------------
+    # There is one credential record per user.
+    # This is where login secrets such as the password are stored.
+    # ------------------------------------------------------------
+
+    create_table :booth_credentials, id: :uuid do |t|
+      t.string :scope, null: false, default: 'default'
+      t.string :username, null: false, index: { unique: true }
+      t.string :password_digest, null: false
+      t.string :otp_secret_key, null: false
+      t.column :allowed_modes, :booth_credential_mode, array: true, null: false, default: []
+      t.column :mode, :booth_credential_mode, null: false, default: :first_time
+      t.datetime :flagged_pwned_at
+      t.timestamps
+    end
+    add_index :booth_credentials, %i[username scope], unique: true
+
+    create_table :booth_authenticators, id: :uuid do |t|
+      t.references :credential, foreign_key: { to_table: :booth_credentials }, type: :uuid, null: false, index: true, on_delete: :cascade
+      t.string :webauthn_id, unique: true, null: false # I.e. our username presented to the hardware key
+      t.string :device_id # I.e. what the hardware key says its technical name is
+      t.string :nickname # I.e. what the user says its hardware key is called
+      t.string :public_key
+      t.string :challenge, null: false
+      t.bigint :sign_count
+      t.datetime :confirmed_at
+      t.boolean :supports_user_verification, null: false, default: false
+      t.timestamps
+    end
+    add_index :booth_authenticators, %i[credential_id webauthn_id], unique: true
+    add_index :booth_authenticators, %i[credential_id confirmed_at], where: 'confirmed_at IS NULL', unique: true
+
+    create_table :booth_password_resets, id: :uuid do |t|
+      t.references :credential, foreign_key: { to_table: :booth_credentials }, type: :uuid, null: false, index: true, on_delete: :cascade
+      t.string :secret_key, null: false, index: { unique: true }
+      t.inet :creator_ip, null: false
+      t.inet :consumer_ip
+      t.datetime :accessed_at
+      t.string :password_digest
+      t.datetime :password_chosen_at
+      t.datetime :password_confirmed_at
+      t.datetime :propagated_at
+      t.datetime :revoked_at
+      t.timestamps
+    end
+
+    create_table :booth_recoveries, id: :uuid do |t|
+      t.string :scope, null: false, index: true
+      t.string :email, null: false, index: true
+      t.inet :creator_ip, null: false
+      t.datetime :consumed_at
+      t.datetime :revoked_at
+      t.timestamps
+    end
+
+    # ------------------------------------------------------------
+    # To give a new user the opportunity to choose a login method,
+    # they go through an onboarding process.
+    # ------------------------------------------------------------
+
+    create_table :booth_onboardings, id: :uuid do |t|
+      t.references :credential, foreign_key: { to_table: :booth_credentials }, type: :uuid, null: false, index: { unique: true }, on_delete: :cascade
+      t.string :secret_key, null: false, index: { unique: true }
+      t.datetime :accessed_at
+      t.column :mode, :booth_credential_mode, null: false, default: :first_time
+      t.string :password_digest
+      t.datetime :password_chosen_at
+      t.datetime :password_confirmed_at
+      t.string :otp_secret_key
+      t.datetime :otp_registered_at
+      t.datetime :otp_confirmed_at
+      t.string :webauthn_id
+      t.string :authenticator_id
+      t.string :authenticator_nickname
+      t.string :authenticator_challenge
+      t.string :authenticator_public_key
+      t.bigint :authenticator_sign_count
+      t.datetime :authenticator_confirmed_at
+      t.datetime :propagated_at
+      t.timestamps
+    end
+
+    # ------------------------------------------------------------
+    # Once logged in with a credential, a server-side session will
+    # be generated and its use continuously verified.
+    # ------------------------------------------------------------
+
+    create_table :booth_sessions, id: :uuid do |t|
+      t.references :credential, foreign_key: { to_table: :booth_credentials }, type: :uuid, null: false, index: true, on_delete: :cascade
+      t.references :incognito_credential, foreign_key: { to_table: :booth_credentials }, type: :uuid, index: { unique: true }, on_delete: :cascade
+      t.datetime :activity_at, null: false, index: true
+      t.datetime :revoked_at
+      t.string :revoke_reason
+      t.inet :most_recent_ip, null: false
+      t.hstore :historical_ips, null: false, default: {}
+      t.string :agent
+      t.string :location
+      t.hstore :historical_locations, null: false, default: {}
+      t.timestamps
+    end
+
+    create_table :booth_contests, id: :uuid do |t|
+      t.references :credential, foreign_key: { to_table: :booth_credentials }, type: :uuid, null: false, index: { unique: true }, on_delete: :cascade
+      t.string :code, null: false, index: true
+      t.string :reason, null: false, index: true
+      t.inet :ip, null: false
+      t.string :agent
+      t.string :location
+      t.datetime :responded_at
+      t.timestamps
+    end
+
+    create_table :booth_audits, id: :uuid do |t|
+      t.references :credential, foreign_key: { to_table: :booth_credentials }, type: :uuid, index: true, on_delete: :cascade
+      t.inet :ip, null: false
+      t.string :agent
+      t.string :location
+      t.string :event, null: false, index: true
+      t.datetime :deleted_at
+      t.timestamps
+    end
+    add_index :booth_audits, %i[ip event]
+  end
+end