feat(auth): migrate password hashing from bcrypt to Argon2id

 Replace has_secure_password with a custom PasswordHasher service backed by Argon2id (m=64MiB, t=3, p=2), following the OWASP preferred profile.

  Lazy migration: existing bcrypt digests are verified as-is and silently re-hashed on the next successful login. No schema changes, no forced logouts, clean rollback.

  - Add gem argon2 ~> 2.3
  - Add Authentication::PasswordHasher with bcrypt/argon2id detection,
    rescue BCrypt::Errors::InvalidHash and Argon2::Error, test-env fast
    params (m=16, t=1, p=1)
  - Add UpgradeablePassword concern used by User and Player
  - Remove has_secure_password from User and Player; replicate presence validation and virtual attr explicitly
  - Hash via before_validation callback, not in the setter
  - Add scripts/benchmark_argon2.rb for pre-deploy calibration

Author: Bulletdev

Gemfile

@@ -30,6 +30,9 @@ gem 'redis', '~> 5.0'
 # Use Active Model has_secure_password [https://guides.rubyonrails.org/active_model_basics.html#securepassword]
 gem 'bcrypt', '~> 3.1.7'
 
+# Argon2id password hashing (OWASP recommended, PHC winner 2015)
+gem 'argon2', '~> 2.3'
+
 # Windows does not include zoneinfo files, so bundle the tzinfo-data gem
 gem 'tzinfo-data', platforms: %i[mingw mswin x64_mingw jruby]
 

Gemfile.lock

@@ -79,6 +79,9 @@ GEM
     annotate (3.2.0)
       activerecord (>= 3.2, < 8.0)
       rake (>= 10.4, < 14.0)
+    argon2 (2.3.3)
+      ffi (~> 1.15)
+      ffi-compiler (~> 1.0)
     ast (2.4.3)
     aws-eventstream (1.4.0)
     aws-partitions (1.1229.0)
@@ -171,6 +174,10 @@ GEM
       net-http (~> 0.5)
     faraday-retry (2.3.2)
       faraday (~> 2.0)
+    ffi (1.17.4-x86_64-linux-gnu)
+    ffi-compiler (1.4.2)
+      ffi (>= 1.15.5)
+      rake
     fugit (1.12.1)
       et-orbi (~> 1.4)
       raabro (~> 1.4)
@@ -471,6 +478,7 @@ PLATFORMS
 
 DEPENDENCIES
   annotate
+  argon2 (~> 2.3)
   aws-sdk-s3 (~> 1.0)
   bcrypt (~> 3.1.7)
   blueprinter

README.md

@@ -47,6 +47,7 @@
 ```
 ┌─────────────────────────────────────────────────────────────────────────────┐
 │  [■] JWT Authentication       — Refresh tokens + token blacklisting         │
+│  [■] Argon2id Password Hashing— OWASP preferred · lazy migration from bcrypt│
 │  [■] HashID URLs              — Base62 encoding for obfuscated URLs         │
 │  [■] Swagger Docs             — 200+ endpoints documented interactively     │
 │  [■] Riot Games API           — Automatic match and player import           │
@@ -182,7 +183,7 @@ open http://localhost:3333/api-docs
 ║  Language            ║  Ruby 3.4.8                                        ║
 ║  Framework           ║  Rails 7.2.3.1 (API-only mode)                     ║
 ║  Database            ║  PostgreSQL 14+                                    ║
-║  Authentication      ║  JWT (access + refresh tokens)                     ║
+║  Authentication      ║  JWT (access + refresh tokens) + Argon2id hashing  ║
 ║  URL Obfuscation     ║  HashID with Base62 encoding                       ║
 ║  Background Jobs     ║  Sidekiq                                           ║
 ║  Caching             ║  Redis (port 6380)                                 ║
@@ -1037,6 +1038,7 @@ All cached responses include `X-Cache-Hit: true/false` header.
 [✓] Timing oracle: login/register user enumeration
 [✓] Mass assignment: StrongParameters coverage
 [✓] CI/CD: security gates on every push + weekly CodeQL
+[✓] Password hashing: Argon2id (m=64MiB, t=3, p=2) — bcrypt lazy migration on login
 ```
 
 ### Security Status

app/models/concerns/upgradeable_password.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module UpgradeablePassword
+  extend ActiveSupport::Concern
+
+  # Verifies plain_password against the stored digest and, if the digest still
+  # uses bcrypt, transparently re-hashes with Argon2id on the same request.
+  #
+  # @param plain_password [String] the password to verify
+  # @param digest_attr [Symbol] the attribute name holding the stored digest
+  # @param digest_setter [Symbol] the column name to write the upgraded digest
+  # @return [self, nil] returns self on success, nil on failure
+  def authenticate_with_upgrade(plain_password, digest_attr:, digest_setter:)
+    digest = send(digest_attr)
+    return nil unless Authentication::PasswordHasher.verify(plain_password, digest)
+
+    if Authentication::PasswordHasher.needs_upgrade?(digest)
+      new_digest = Authentication::PasswordHasher.hash(plain_password)
+      # Two separate update_column calls instead of update_columns so that Rails
+      # dirty tracking is cleared field-by-field — avoids unexpected behavior on
+      # read-replica setups where a bulk UPDATE could interleave with pending reads.
+      # update_column bypasses callbacks intentionally (no before_save/after_save
+      # during a transparent hash upgrade).
+      update_column(digest_setter, new_digest)
+      update_column(:updated_at, Time.current)
+    end
+
+    self
+  end
+end

app/models/user.rb

@@ -2,10 +2,9 @@
 
 # Authenticated user within an organization, with role-based access and notification support.
 class User < ApplicationRecord
-  has_secure_password
-
   # Concerns
   include Constants
+  include UpgradeablePassword
 
   # Associations
   belongs_to :organization
@@ -21,7 +20,24 @@ class User < ApplicationRecord
   has_many :password_reset_tokens, dependent: :destroy
   has_many :messages, dependent: :nullify
 
+  # Virtual password attribute — set when changing password, nil otherwise.
+  # has_secure_password is not used; hashing is handled by Authentication::PasswordHasher.
+  attr_reader :password
+
+  def password=(plain_password)
+    @password = plain_password.blank? ? nil : plain_password
+  end
+
+  def authenticate(plain_password)
+    authenticate_with_upgrade(
+      plain_password,
+      digest_attr: :password_digest,
+      digest_setter: :password_digest
+    )
+  end
+
   # Validations
+  validates :password_digest, presence: true
   validates :email, presence: true, uniqueness: true, format: { with: URI::MailTo::EMAIL_REGEXP }
   validates :full_name, presence: true, length: { maximum: 255 }
   validates :role, presence: true, inclusion: { in: Constants::User::ROLES }
@@ -42,6 +58,7 @@ class User < ApplicationRecord
 
   # Callbacks
   before_validation :downcase_email
+  before_validation :hash_password, if: -> { password.present? }
   after_update :log_audit_trail, if: :saved_changes?
 
   # Scopes
@@ -92,6 +109,10 @@ def downcase_email
     self.email = email.downcase.strip if email.present?
   end
 
+  def hash_password
+    self.password_digest = Authentication::PasswordHasher.hash(password)
+  end
+
   def log_audit_trail
     AuditLog.create!(
       organization: organization,

app/modules/players/models/player.rb

@@ -35,6 +35,7 @@ class Player < ApplicationRecord # rubocop:disable Metrics/ClassLength
   include OrganizationScoped
   include SoftDeletable
   include Searchable
+  include UpgradeablePassword
 
   # Associations
   belongs_to :organization, optional: true
@@ -46,8 +47,21 @@ class Player < ApplicationRecord # rubocop:disable Metrics/ClassLength
   has_many :vod_timestamps, foreign_key: 'target_player_id', dependent: :nullify
   has_many :password_reset_tokens, dependent: :destroy
 
-  # Password authentication for individual player access
-  has_secure_password :player_password, validations: false
+  # Virtual attribute for the player password — has_secure_password is not used;
+  # hashing is handled by Authentication::PasswordHasher.
+  attr_reader :player_password
+
+  def player_password=(plain_password)
+    @player_password = plain_password.blank? ? nil : plain_password
+  end
+
+  def authenticate_player_password(plain_password)
+    authenticate_with_upgrade(
+      plain_password,
+      digest_attr: :player_password_digest,
+      digest_setter: :player_password_digest
+    )
+  end
 
   # Validations
   validates :source_app, inclusion: { in: Constants::SOURCE_APPS }
@@ -68,6 +82,7 @@ class Player < ApplicationRecord # rubocop:disable Metrics/ClassLength
   validates :player_password, length: { minimum: 8 }, if: -> { player_password.present? }
 
   # Callbacks
+  before_validation :hash_player_password, if: -> { player_password.present? }
   before_save :normalize_summoner_name
   after_update_commit :enqueue_audit_log, if: :saved_changes?
   after_commit :clear_organization_cache, on: %i[create destroy]
@@ -222,6 +237,10 @@ def normalize_summoner_name
     self.summoner_name = summoner_name.strip if summoner_name.present?
   end
 
+  def hash_player_password
+    self.player_password_digest = Authentication::PasswordHasher.hash(player_password)
+  end
+
   def enqueue_audit_log
     AuditLogJob.perform_later(
       organization_id: organization_id,

app/services/authentication/password_hasher.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Authentication
+  # Handles password hashing and verification with support for lazy migration
+  # from bcrypt to Argon2id. The hash format is self-describing, so no extra
+  # column or flag is needed to detect which algorithm was used.
+  class PasswordHasher
+    # Ultra-fast params in test to avoid adding 150-250ms per RSpec example
+    # that touches authentication. Production values follow OWASP preferred profile.
+    ARGON2_PARAMS = if Rails.env.test?
+                      { m_cost: 16, t_cost: 1, p_cost: 1 }.freeze
+                    else
+                      { m_cost: 65_536, t_cost: 3, p_cost: 2 }.freeze
+                    end
+
+    # Covers $2a$ (standard), $2b$ (canonical), $2x$/$2y$ (legacy JRuby/PHP variants)
+    BCRYPT_PREFIX = /\A\$2[abxy]\$/
+
+    def self.hash(plain_password)
+      Argon2::Password.create(plain_password, **ARGON2_PARAMS)
+    end
+
+    def self.verify(plain_password, digest)
+      return false if plain_password.blank? || digest.blank?
+
+      bcrypt?(digest) ? verify_bcrypt(plain_password, digest) : verify_argon2(plain_password, digest)
+    end
+
+    def self.needs_upgrade?(digest)
+      bcrypt?(digest)
+    end
+
+    def self.bcrypt?(digest)
+      digest.to_s.match?(BCRYPT_PREFIX)
+    end
+
+    def self.verify_bcrypt(plain_password, digest)
+      result = BCrypt::Password.new(digest) == plain_password
+      Rails.logger.info('[PasswordHasher] bcrypt digest detected — upgrade queued') if result
+      result
+    rescue BCrypt::Errors::InvalidHash
+      false
+    end
+    private_class_method :verify_bcrypt
+
+    def self.verify_argon2(plain_password, digest)
+      Argon2::Password.verify_password(plain_password, digest)
+    rescue Argon2::Error
+      false
+    end
+    private_class_method :verify_argon2
+  end
+end