custos 0.1.0

data/lib/custos/plugins/lockout.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Custos
+  module Plugins
+    module Lockout
+      DEFAULT_MAX_ATTEMPTS = 3
+      DEFAULT_LOCKOUT_DURATION = 30 * 60 # 30 minutes in seconds
+      DEFAULT_MAX_MFA_ATTEMPTS = 5
+
+      def self.apply(model_class, **_options)
+        model_class.include(InstanceMethods)
+
+        model_class.custos_config.hook(:after_authentication) do |record, success|
+          if success
+            record.reset_failed_attempts!
+          else
+            record.record_failed_attempt!
+          end
+        end
+
+        model_class.custos_config.hook(:after_mfa_verification) do |record, success|
+          if success
+            record.reset_failed_mfa_attempts!
+          else
+            record.record_failed_mfa_attempt!
+          end
+        end
+      end
+
+      module InstanceMethods
+        def locked?
+          return false if locked_at.nil?
+
+          options = self.class.custos_config.plugin_options(:lockout)
+          duration = options.fetch(:lockout_duration, DEFAULT_LOCKOUT_DURATION)
+          locked_at > duration.seconds.ago
+        end
+
+        def mfa_locked?
+          return false unless respond_to?(:mfa_locked_at)
+          return false if mfa_locked_at.nil?
+
+          options = self.class.custos_config.plugin_options(:lockout)
+          duration = options.fetch(:mfa_lockout_duration,
+                                   options.fetch(:lockout_duration, DEFAULT_LOCKOUT_DURATION))
+          mfa_locked_at > duration.seconds.ago
+        end
+
+        def record_failed_attempt!
+          options = self.class.custos_config.plugin_options(:lockout)
+          max = options.fetch(:max_attempts, DEFAULT_MAX_ATTEMPTS)
+          duration = options.fetch(:lockout_duration, DEFAULT_LOCKOUT_DURATION)
+          now = Time.current
+
+          self.class.where(id: id).update_all(
+            [
+              'failed_auth_count = CASE WHEN locked_at IS NOT NULL AND locked_at <= ? THEN 1 ' \
+              'ELSE failed_auth_count + 1 END, ' \
+              'locked_at = CASE WHEN locked_at IS NOT NULL AND locked_at <= ? THEN NULL ' \
+              'WHEN (CASE WHEN locked_at IS NOT NULL AND locked_at <= ? THEN 1 ' \
+              'ELSE failed_auth_count + 1 END) >= ? THEN ? ELSE locked_at END',
+              duration.seconds.ago, duration.seconds.ago, duration.seconds.ago, max, now
+            ]
+          )
+          reload
+        end
+
+        def record_failed_mfa_attempt!
+          return unless respond_to?(:failed_mfa_count)
+
+          options = self.class.custos_config.plugin_options(:lockout)
+          max = options.fetch(:max_mfa_attempts, DEFAULT_MAX_MFA_ATTEMPTS)
+          duration = options.fetch(:mfa_lockout_duration,
+                                   options.fetch(:lockout_duration, DEFAULT_LOCKOUT_DURATION))
+          now = Time.current
+
+          self.class.where(id: id).update_all(
+            [
+              'failed_mfa_count = CASE WHEN mfa_locked_at IS NOT NULL AND mfa_locked_at <= ? THEN 1 ' \
+              'ELSE failed_mfa_count + 1 END, ' \
+              'mfa_locked_at = CASE WHEN mfa_locked_at IS NOT NULL AND mfa_locked_at <= ? THEN NULL ' \
+              'WHEN (CASE WHEN mfa_locked_at IS NOT NULL AND mfa_locked_at <= ? THEN 1 ' \
+              'ELSE failed_mfa_count + 1 END) >= ? THEN ? ELSE mfa_locked_at END',
+              duration.seconds.ago, duration.seconds.ago, duration.seconds.ago, max, now
+            ]
+          )
+          reload
+        end
+
+        def reset_failed_attempts!
+          return unless failed_auth_count.positive? || locked_at.present?
+
+          update!(failed_auth_count: 0, locked_at: nil)
+        end
+
+        def reset_failed_mfa_attempts!
+          return unless respond_to?(:failed_mfa_count)
+          return unless failed_mfa_count.positive? || mfa_locked_at.present?
+
+          update!(failed_mfa_count: 0, mfa_locked_at: nil)
+        end
+
+        def unlock!
+          attrs = { failed_auth_count: 0, locked_at: nil }
+          if respond_to?(:failed_mfa_count)
+            attrs[:failed_mfa_count] = 0
+            attrs[:mfa_locked_at] = nil
+          end
+          update!(attrs)
+        end
+      end
+    end
+  end
+end
+
+Custos::Plugin.register(:lockout, Custos::Plugins::Lockout)

data/lib/custos/plugins/magic_link.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Custos
+  module Plugins
+    module MagicLink
+      DEFAULT_EXPIRY = 15 * 60 # 15 minutes in seconds
+      DEFAULT_COOLDOWN = 60 # 1 minute between requests
+
+      def self.apply(model_class, **_options)
+        model_class.has_many :custos_magic_link_tokens,
+                             class_name: 'Custos::MagicLinkToken',
+                             as: :authenticatable,
+                             dependent: :destroy
+
+        model_class.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def generate_magic_link(email)
+          record = find_by(email: email)
+          return nil unless record
+
+          options = custos_config.plugin_options(:magic_link)
+          cooldown = options.fetch(:cooldown, DEFAULT_COOLDOWN)
+          if cooldown.positive?
+            last_token = record.custos_magic_link_tokens.order(created_at: :desc).first
+            return nil if last_token && last_token.created_at > cooldown.seconds.ago
+          end
+
+          record.custos_magic_link_tokens.valid_tokens.update_all(used_at: Time.current)
+
+          token = Custos::TokenGenerator.generate
+          expiry = options.fetch(:expiry, DEFAULT_EXPIRY)
+
+          record.custos_magic_link_tokens.create!(
+            token_digest: Custos::TokenGenerator.digest(token),
+            expires_at: Time.current + expiry
+          )
+
+          Custos::CallbackRegistry.fire(self, :magic_link_created, record, token)
+          token
+        end
+
+        def authenticate_magic_link(token)
+          digest = Custos::TokenGenerator.digest(token)
+          magic_link = Custos::MagicLinkToken.valid_tokens.find_by(
+            token_digest: digest,
+            authenticatable_type: name
+          )
+          return nil unless magic_link
+
+          magic_link.update!(used_at: Time.current)
+          magic_link.authenticatable
+        end
+      end
+    end
+  end
+end
+
+Custos::Plugin.register(:magic_link, Custos::Plugins::MagicLink)

data/lib/custos/plugins/mfa.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require 'rotp'
+require 'json'
+require 'time'
+
+module Custos
+  module Plugins
+    module Mfa
+      SMS_CODE_LENGTH = 6
+      SMS_CODE_EXPIRY = 5 * 60 # 5 minutes
+      BACKUP_CODES_COUNT = 10
+
+      def self.apply(model_class, **_options)
+        model_class.has_many :custos_mfa_credentials,
+                             class_name: 'Custos::MfaCredential',
+                             as: :authenticatable,
+                             dependent: :destroy
+
+        model_class.include(InstanceMethods)
+      end
+
+      module InstanceMethods
+        def setup_totp(issuer: 'Custos')
+          secret = ROTP::Base32.random
+          credential = find_or_build_mfa_credential('totp')
+          credential.update!(secret_data: secret, enabled_at: nil)
+
+          totp = ROTP::TOTP.new(secret, issuer: issuer)
+          totp.provisioning_uri(respond_to?(:email) ? email : id.to_s)
+        end
+
+        def verify_totp(code)
+          return false if respond_to?(:mfa_locked?) && mfa_locked?
+
+          credential = enabled_mfa_credential('totp')
+          return false unless credential
+
+          secret = credential.secret_data
+          return false unless secret
+
+          totp = ROTP::TOTP.new(secret)
+          result = totp.verify(code.to_s, drift_behind: 30, drift_ahead: 30).present?
+          fire_mfa_verification_hook(result)
+          result
+        end
+
+        def confirm_totp!(code)
+          credential = custos_mfa_credentials.by_method('totp').first
+          return false unless credential
+
+          secret = credential.secret_data
+          return false unless secret
+
+          totp = ROTP::TOTP.new(secret)
+          return false unless totp.verify(code.to_s, drift_behind: 30, drift_ahead: 30)
+
+          credential.update!(enabled_at: Time.current)
+          true
+        end
+
+        def totp_enabled?
+          enabled_mfa_credential('totp').present?
+        end
+
+        def generate_backup_codes(count: BACKUP_CODES_COUNT)
+          codes = Array.new(count) { SecureRandom.hex(6) }
+          digests = codes.map { |code| Custos::TokenGenerator.digest(code) }
+
+          credential = find_or_build_mfa_credential('backup_codes')
+          credential.update!(secret_data: JSON.generate(digests), enabled_at: Time.current)
+
+          codes
+        end
+
+        def verify_backup_code(code)
+          return false if respond_to?(:mfa_locked?) && mfa_locked?
+
+          credential = enabled_mfa_credential('backup_codes')
+          return false unless credential
+
+          result = consume_backup_code(credential, code)
+          fire_mfa_verification_hook(result)
+          result
+        end
+
+        def send_sms_code
+          code = SecureRandom.random_number(10**SMS_CODE_LENGTH).to_s.rjust(SMS_CODE_LENGTH, '0')
+          digest = Custos::TokenGenerator.digest(code)
+          expiry = Time.current + SMS_CODE_EXPIRY
+
+          credential = find_or_build_mfa_credential('sms')
+          credential.update!(
+            secret_data: JSON.generate({ digest: digest, expires_at: expiry.iso8601 }),
+            enabled_at: Time.current
+          )
+
+          Custos::CallbackRegistry.fire(self.class, :sms_code_created, self, code)
+          true
+        end
+
+        def verify_sms_code(code)
+          return false if respond_to?(:mfa_locked?) && mfa_locked?
+
+          credential = enabled_mfa_credential('sms')
+          return false unless credential
+
+          raw = credential.secret_data
+          return false unless raw
+
+          data = parse_json_hash(raw)
+          return false if data.empty?
+          return false if Time.iso8601(data['expires_at']) < Time.current
+
+          result = Custos::TokenGenerator.secure_compare(
+            data['digest'],
+            Custos::TokenGenerator.digest(code)
+          )
+
+          invalidate_sms_credential(credential) if result
+          fire_mfa_verification_hook(result)
+          result
+        rescue ArgumentError
+          false
+        end
+
+        def mfa_enabled?
+          totp_enabled? || enabled_mfa_credential('sms').present?
+        end
+
+        private
+
+        def fire_mfa_verification_hook(success)
+          Custos::CallbackRegistry.fire_hooks(self.class, :after_mfa_verification, self, success)
+        end
+
+        def consume_backup_code(credential, code)
+          credential.with_lock do
+            digest = Custos::TokenGenerator.digest(code)
+            raw = credential.secret_data
+            return false unless raw
+
+            remaining = parse_json_array(raw)
+            matched_index = remaining.index { |stored| Custos::TokenGenerator.secure_compare(stored, digest) }
+            return false unless matched_index
+
+            remaining.delete_at(matched_index)
+            credential.update!(secret_data: JSON.generate(remaining))
+          end
+
+          true
+        end
+
+        def find_or_build_mfa_credential(method_name)
+          custos_mfa_credentials.by_method(method_name).first ||
+            custos_mfa_credentials.build(method: method_name)
+        end
+
+        def enabled_mfa_credential(method_name)
+          custos_mfa_credentials.enabled.by_method(method_name).first
+        end
+
+        def invalidate_sms_credential(credential)
+          credential.update!(secret_data: JSON.generate({ digest: '', expires_at: Time.current.iso8601 }))
+        end
+
+        def parse_json_array(json_string)
+          parsed = JSON.parse(json_string)
+          parsed.is_a?(Array) ? parsed : []
+        rescue JSON::ParserError
+          []
+        end
+
+        def parse_json_hash(json_string)
+          parsed = JSON.parse(json_string)
+          parsed.is_a?(Hash) ? parsed : {}
+        rescue JSON::ParserError
+          {}
+        end
+      end
+    end
+  end
+end
+
+Custos::Plugin.register(:mfa, Custos::Plugins::Mfa)

data/lib/custos/plugins/password.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'argon2'
+
+module Custos
+  module Plugins
+    module Password
+      DEFAULT_MIN_LENGTH = 8
+      DEFAULT_MAX_LENGTH = 128
+      DUMMY_PASSWORD_DIGEST = Argon2::Password.create('custos-timing-protection')
+
+      def self.apply(model_class, **options)
+        model_class.include(InstanceMethods)
+        model_class.extend(ClassMethods)
+
+        min = options.fetch(:min_length, DEFAULT_MIN_LENGTH)
+        max = options.fetch(:max_length, DEFAULT_MAX_LENGTH)
+        model_class.validates :password, length: { minimum: min, maximum: max }, if: :password_changed?
+
+        if options[:require_uppercase]
+          model_class.validates :password, format: { with: /[A-Z]/, message: 'must contain an uppercase letter' },
+                                           if: :password_changed?
+        end
+
+        if options[:require_digit]
+          model_class.validates :password, format: { with: /\d/, message: 'must contain a digit' },
+                                           if: :password_changed?
+        end
+
+        if options[:require_special]
+          model_class.validates :password,
+                                format: { with: /[^A-Za-z0-9]/, message: 'must contain a special character' },
+                                if: :password_changed?
+        end
+
+        model_class.after_save :clear_password_instance_variable, if: :password_changed?
+      end
+
+      module InstanceMethods
+        attr_reader :password
+
+        def password=(plain_password)
+          @password = plain_password
+          @password_changed = true
+          self.password_digest = plain_password.present? ? create_argon2_hash(plain_password) : nil
+        end
+
+        def authenticate_password(plain_password)
+          return false if password_digest.blank?
+
+          verified = Argon2::Password.verify_password(plain_password, password_digest)
+          Custos::CallbackRegistry.fire_hooks(self.class, :after_authentication, self, verified)
+          verified
+        rescue Argon2::ArgonHashFail
+          false
+        end
+
+        private
+
+        def password_changed?
+          @password_changed == true
+        end
+
+        def clear_password_instance_variable
+          @password = nil
+          @password_changed = false
+        end
+
+        def create_argon2_hash(plain_password)
+          options = self.class.custos_config.plugin_options(:password)
+          argon2_params = {}
+          argon2_params[:t_cost] = options[:t_cost] if options.key?(:t_cost)
+          argon2_params[:m_cost] = options[:m_cost] if options.key?(:m_cost)
+          argon2_params[:p_cost] = options[:p_cost] if options.key?(:p_cost)
+
+          Argon2::Password.create(plain_password, **argon2_params)
+        end
+      end
+
+      module ClassMethods
+        def find_by_email_and_password(email:, password:)
+          record = find_by(email: email)
+
+          unless record
+            Argon2::Password.verify_password(password, DUMMY_PASSWORD_DIGEST)
+            return nil
+          end
+
+          return nil if record.respond_to?(:locked?) && record.locked?
+
+          record.authenticate_password(password) ? record : nil
+        end
+      end
+    end
+  end
+end
+
+Custos::Plugin.register(:password, Custos::Plugins::Password)

data/lib/custos/plugins/remember_me.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Custos
+  module Plugins
+    module RememberMe
+      DEFAULT_REMEMBER_DURATION = 30 * 24 * 60 * 60 # 30 days in seconds
+
+      def self.apply(model_class, **_options)
+        model_class.has_many :custos_remember_tokens,
+                             class_name: 'Custos::RememberToken',
+                             as: :authenticatable,
+                             dependent: :destroy
+
+        model_class.include(InstanceMethods)
+        model_class.extend(ClassMethods)
+      end
+
+      module InstanceMethods
+        def generate_remember_token
+          options = self.class.custos_config.plugin_options(:remember_me)
+          duration = options.fetch(:remember_duration, DEFAULT_REMEMBER_DURATION)
+          token = Custos::TokenGenerator.generate
+
+          custos_remember_tokens.create!(
+            token_digest: Custos::TokenGenerator.digest(token),
+            expires_at: Time.current + duration
+          )
+
+          token
+        end
+
+        def forget_me!(token = nil)
+          if token
+            digest = Custos::TokenGenerator.digest(token)
+            custos_remember_tokens.where(token_digest: digest).destroy_all
+          else
+            custos_remember_tokens.destroy_all
+          end
+        end
+      end
+
+      module ClassMethods
+        def authenticate_remember_token(token)
+          digest = Custos::TokenGenerator.digest(token)
+          remember = Custos::RememberToken.not_expired.find_by(
+            token_digest: digest,
+            authenticatable_type: name
+          )
+          remember&.authenticatable
+        end
+      end
+    end
+  end
+end
+
+Custos::Plugin.register(:remember_me, Custos::Plugins::RememberMe)

data/lib/custos/railtie.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Custos
+  class Railtie < Rails::Railtie
+    initializer 'custos.controller_helpers' do
+      ActiveSupport.on_load(:action_controller) do
+        include Custos::ControllerHelpers
+      end
+    end
+
+    rake_tasks do
+      load 'custos/tasks/cleanup.rake'
+    end
+  end
+end

data/lib/custos/session.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Custos
+  class Session < ActiveRecord::Base
+    self.table_name = 'custos_sessions'
+
+    belongs_to :authenticatable, polymorphic: true
+
+    scope :active, lambda {
+      where(revoked_at: nil)
+        .where('last_active_at > ?', Custos.configuration.session_expiry.seconds.ago)
+    }
+
+    scope :revoked, -> { where.not(revoked_at: nil) }
+  end
+end

data/lib/custos/session_manager.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Custos
+  class SessionManager
+    class << self
+      def create(authenticatable, request:)
+        token = TokenGenerator.generate
+        session = Custos::Session.create!(
+          authenticatable: authenticatable,
+          session_token_digest: TokenGenerator.digest(token),
+          ip_address: request.remote_ip,
+          user_agent: request.user_agent,
+          last_active_at: Time.current
+        )
+        [session, token]
+      end
+
+      def find_by_token(token, authenticatable_type: nil)
+        return nil if token.blank?
+
+        digest = TokenGenerator.digest(token)
+        scope = Custos::Session.active.where(session_token_digest: digest)
+        scope = scope.where(authenticatable_type: authenticatable_type) if authenticatable_type
+        session = scope.first
+        touch_session(session) if session
+        session
+      end
+
+      def revoke(session)
+        session.update!(revoked_at: Time.current)
+      end
+
+      def revoke_all(authenticatable)
+        authenticatable.custos_sessions.active.update_all(revoked_at: Time.current)
+      end
+
+      def active_for(authenticatable)
+        authenticatable.custos_sessions.active.order(last_active_at: :desc)
+      end
+
+      private
+
+      def touch_session(session)
+        renewal = Custos.configuration.session_renewal_interval
+        return if session.last_active_at > renewal.seconds.ago
+
+        session.update_column(:last_active_at, Time.current)
+      end
+    end
+  end
+end

data/lib/custos/tasks/cleanup.rake

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+namespace :custos do
+  desc 'Remove expired sessions, used magic links, and expired tokens'
+  task cleanup: :environment do
+    deleted = Custos::Session.where(created_at: ..Custos.configuration.session_expiry.seconds.ago).delete_all
+    puts "Deleted #{deleted} expired sessions"
+
+    deleted = Custos::Session.revoked.where(revoked_at: ..30.days.ago).delete_all
+    puts "Deleted #{deleted} old revoked sessions"
+
+    if defined?(Custos::MagicLinkToken)
+      deleted = Custos::MagicLinkToken.where.not(used_at: nil).delete_all
+      deleted += Custos::MagicLinkToken.where(expires_at: ..Time.current).delete_all
+      puts "Deleted #{deleted} used/expired magic links"
+    end
+
+    if defined?(Custos::RememberToken)
+      deleted = Custos::RememberToken.where(expires_at: ..Time.current).delete_all
+      puts "Deleted #{deleted} expired remember tokens"
+    end
+
+    if defined?(Custos::ApiToken)
+      deleted = Custos::ApiToken.where.not(expires_at: nil).where(expires_at: ..Time.current).delete_all
+      puts "Deleted #{deleted} expired API tokens"
+    end
+  end
+end

data/lib/custos/token_generator.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'securerandom'
+require 'active_support/security_utils'
+
+module Custos
+  class TokenGenerator
+    def self.generate(byte_length: nil)
+      length = byte_length || Custos.configuration.token_length
+      SecureRandom.urlsafe_base64(length)
+    end
+
+    def self.digest(token)
+      secret = resolve_token_secret
+      OpenSSL::HMAC.hexdigest('SHA256', secret, token)
+    end
+
+    def self.secure_compare(value_a, value_b)
+      ActiveSupport::SecurityUtils.secure_compare(value_a, value_b)
+    end
+
+    def self.resolve_token_secret
+      secret = Custos.configuration.token_secret
+      return secret if secret
+
+      if defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+        base = Rails.application.secret_key_base
+        return base if base.present?
+      end
+
+      raise Custos::Error, 'Custos.configuration.token_secret must be configured'
+    end
+
+    private_class_method :resolve_token_secret
+  end
+end

data/lib/custos/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Custos
+  VERSION = '0.1.0'
+end