devise-hashable 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8cc3972042af2d23dffab06688a7e06ca4cb234462604b58a50fb414ffc67c75
+  data.tar.gz: b43cf0a5b2224eefdb855c37f09e1970501abfa5eaddb21af6fc1c228e535260
+SHA512:
+  metadata.gz: 599c080a854b523c0e8db52ce617e8dcf6b9b1424a0190eb36612e91772ee6ca168482fb075d0174fc544067f2976dea2a8303cf0159be58631675e73fbfefa8
+  data.tar.gz: 7231d7215726aa2531deca8c232051571241af2b666e5620df8ddc34ca10278229b19298652b0445be8b68bed348e7e68880a3abdd4dda228d983e231c6e2f2f

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-08-23
+
+First public release.
+
+### Added
+
+- `:password_hashable` Devise module, which transparently re-hashes a user's
+  password to the configured strategy on successful sign-in.
+- Hashing strategies for bcrypt, PBKDF2 and Argon2id, under
+  `Devise::Hashable::Strategy`.
+- Configuration via `Devise.hashing_strategy`, `Devise.digest_algorithm`,
+  `Devise.hash_iterations` and `Devise.argon2_profile`.
+- `Devise::Hashable::InvalidPasswordHash`, raised when a stored hash cannot be
+  parsed by the configured strategy.
+- Guides under `docs/` covering configuration, the migration process, each
+  hashing strategy, and writing a custom strategy.
+- CI matrix covering Rails 7.1, 7.2, 8.0 and 8.1 against Devise 4.9 and 5.0,
+  on Ruby 3.3 through 4.0.
+
+### Requirements
+
+- Ruby >= 3.3. Older rubies are end-of-life and are not supported.
+
+[1.0.0]: https://github.com/MatthewKennedy/devise-hashable/releases/tag/v1.0.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Matthew Kennedy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,78 @@
+# Devise::Hashable
+
+[![CI](https://github.com/MatthewKennedy/devise-hashable/actions/workflows/ci.yml/badge.svg)](https://github.com/MatthewKennedy/devise-hashable/actions/workflows/ci.yml)
+[![RuboCop](https://github.com/MatthewKennedy/devise-hashable/actions/workflows/rubocop.yml/badge.svg)](https://github.com/MatthewKennedy/devise-hashable/actions/workflows/rubocop.yml)
+[![Gem Version](https://badge.fury.io/rb/devise-hashable.svg)](https://rubygems.org/gems/devise-hashable)
+
+Modern password hashing for Devise, with no forced password reset.
+
+Devise stores passwords with bcrypt. This gem adds PBKDF2 and Argon2id, and
+migrates your existing users onto them one at a time, as each signs in. Nobody is
+locked out, nothing is reset, and you can change your mind and move back.
+
+Requires Ruby 3.3 or newer. Tested against Rails 7.1, 7.2, 8.0 and 8.1, on
+Devise 4.9 and 5.0.
+
+## Installation
+
+```bash
+bundle add devise-hashable
+```
+
+## Usage
+
+Add `:password_hashable` to your Devise model and name a strategy:
+
+```ruby
+class User < ApplicationRecord
+  devise :database_authenticatable, :registerable
+  devise :password_hashable, hashing_strategy: :argon2
+end
+```
+
+That is the whole setup. The next time each user signs in, their password is
+verified against its existing hash and then re-hashed with Argon2id.
+
+If you would rather confirm the wiring before anything changes, start by naming
+the scheme you already use. Nothing will be re-hashed:
+
+```ruby
+devise :password_hashable, hashing_strategy: :bcrypt
+```
+
+## Strategies
+
+| Strategy | Choose it when |
+| --- | --- |
+| [Argon2id](https://github.com/MatthewKennedy/devise-hashable/blob/main/docs/strategies/argon2.md) | You are free to pick on security grounds. Memory-hard, RFC 9106 |
+| [PBKDF2](https://github.com/MatthewKennedy/devise-hashable/blob/main/docs/strategies/pbkdf2.md) | You need a FIPS-aligned KDF |
+| [Bcrypt](https://github.com/MatthewKennedy/devise-hashable/blob/main/docs/strategies/bcrypt.md) | You want Devise's existing behaviour, unchanged |
+
+## Documentation
+
+- [Configuration](https://github.com/MatthewKennedy/devise-hashable/blob/main/docs/configuration.md) — every setting, and where to put it
+- [Migrating passwords](https://github.com/MatthewKennedy/devise-hashable/blob/main/docs/migrating-passwords.md) — how the migration runs, when it is skipped, and how to roll it out
+- [Custom strategies](https://github.com/MatthewKennedy/devise-hashable/blob/main/docs/custom-strategies.md) — read hashes from a system you are migrating off
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then run
+`rake test` to run the tests, or `bin/console` for an interactive prompt.
+
+The suite is written in Minitest, deliberately, so that public Devise modules can
+be imported and plugged straight into it. It is held at 100% line and branch
+coverage — raise the floors in `test/test_helper.rb` when coverage improves,
+never lower one to make a run pass.
+
+`bundle exec appraisal install` sets up the Rails and Devise combinations that CI
+runs; `bundle exec appraisal rake test` runs the whole matrix locally.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/MatthewKennedy/devise-hashable/issues.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/docs/configuration.md

@@ -0,0 +1,64 @@
+# Configuration
+
+`:password_hashable` reads four settings. Each has a global default that you can
+override per model.
+
+| Setting | Default | Used by | Meaning |
+| --- | --- | --- | --- |
+| `hashing_strategy` | `nil` | all | Which strategy new hashes are written with |
+| `digest_algorithm` | `:sha256` | PBKDF2 | `:sha1`, `:sha256` or `:sha512` |
+| `hash_iterations` | `50_000` | PBKDF2 | Iteration count, must be greater than zero |
+| `argon2_profile` | `:rfc_9106_low_memory` | Argon2id | Cost profile, see [Argon2id](strategies/argon2.md) |
+
+Bcrypt has no setting of its own — it uses Devise's existing `stretches`.
+
+## Where to set them
+
+Per model, which is the usual place, since the strategy is a property of that
+model's password column:
+
+```ruby
+class User < ApplicationRecord
+  devise :database_authenticatable, :registerable
+  devise :password_hashable, hashing_strategy: :argon2
+end
+```
+
+Or globally, in `config/initializers/devise.rb`, for every model that enables the
+module:
+
+```ruby
+Devise.setup do |config|
+  config.hashing_strategy = :argon2
+  config.argon2_profile = :rfc_9106_low_memory
+end
+```
+
+A per-model value wins over the global one. Settings not named on the model fall
+back to the global value, so a model can take the global strategy and override
+only its cost.
+
+## `hashing_strategy` is required
+
+There is no default strategy. Enabling the module without one raises on the
+first password operation:
+
+```
+You need to specify a hashing_strategy: in Devise configuration to use :password_hashable
+```
+
+A name that does not resolve to a strategy class raises:
+
+```
+Configured password hashing_strategy 'whatever' could not be found for :password_hashable
+```
+
+## Reading a hash is not configured
+
+Configuration decides how passwords are **written**. Reading is driven by the
+stored hash itself: each hash records the scheme that produced it, so existing
+passwords keep verifying no matter what is configured. That is what lets you
+change strategy without locking anyone out.
+
+See [Migrating passwords](migrating-passwords.md) for how and when a stored hash
+is rewritten.

data/docs/custom-strategies.md

@@ -0,0 +1,120 @@
+# Custom strategies
+
+A custom strategy lets you read hashes from a system you are migrating off, so
+that users can sign in with their existing password and be re-hashed to a modern
+scheme on the way through.
+
+It takes two pieces: a strategy class, and a way for the model to recognise the
+hashes it owns.
+
+## 1. The strategy class
+
+Subclass `Devise::Hashable::Strategy::Base` and implement its four methods. The
+class **must** be defined inside `Devise::Hashable::Strategy`, because that is
+where the strategy is looked up by name.
+
+```ruby
+# config/initializers/legacy_sha1_strategy.rb
+require "digest"
+
+module Devise
+  module Hashable
+    module Strategy
+      # Reads the "$legacy-sha1$<salt>$<hex digest>" hashes written by the old
+      # PHP application. Only ever used to verify; new hashes are written by
+      # whichever strategy is configured.
+      class LegacySha1 < Base
+        class << self
+          def compare(_klass, encrypted_password, password)
+            parts = split_password_hash(encrypted_password)
+
+            Devise.secure_compare(
+              parts[:checksum],
+              Digest::SHA1.hexdigest(parts[:salt] + password)
+            )
+          end
+
+          def digest(_klass, _password)
+            raise NotImplementedError, "legacy hashes are read-only"
+          end
+
+          # Never current, so any user on a legacy hash is re-hashed to the
+          # configured strategy the first time they sign in.
+          def password_configurations_match?(_klass, _encrypted_password)
+            false
+          end
+
+          def split_password_hash(encrypted_password)
+            parts = encrypted_password.split("$")
+
+            raise InvalidPasswordHash, "Invalid password hash for LegacySha1" unless parts.length == 4
+
+            _, strategy, salt, checksum = parts
+
+            raise InvalidPasswordHash, "Invalid password hash strategy for LegacySha1" unless strategy == "legacy-sha1"
+
+            { strategy: strategy, salt: salt, checksum: checksum }
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+Returning `false` from `password_configurations_match?` is what drives the
+migration: the hash is never considered current, so it is rewritten on the next
+successful sign-in.
+
+## 2. Teach the model to recognise it
+
+Override the private `encrypted_password_strategy_check` and call `super` for
+anything you do not handle:
+
+```ruby
+class User < ApplicationRecord
+  devise :database_authenticatable
+  devise :password_hashable, hashing_strategy: :argon2
+
+  private
+
+  def encrypted_password_strategy_check
+    return :legacy_sha1 if encrypted_password&.start_with?("$legacy-sha1$")
+
+    super
+  end
+end
+```
+
+Returning `nil` — which `super` does for anything unrecognised — marks the hash
+unknown, and verification fails without raising.
+
+## Naming
+
+The symbol is turned into a class name with ActiveSupport's `classify`, which
+**singularises**:
+
+| Symbol | Class looked up |
+| --- | --- |
+| `:legacy_sha1` | `Devise::Hashable::Strategy::LegacySha1` |
+| `:my_custom` | `Devise::Hashable::Strategy::MyCustom` |
+| `:credentials` | `Devise::Hashable::Strategy::Credential` |
+
+Avoid plural names, or the lookup will search for a class you did not define.
+
+## Loading
+
+An initializer is the simplest home for the class. The four built-in strategies
+are autoloaded; a custom one is not, so make sure the file is loaded before the
+first sign-in. If you put it under `app/`, Rails will reload it in development
+and the constant will resolve normally.
+
+## Checklist
+
+- Raise `Devise::Hashable::InvalidPasswordHash` from `split_password_hash` when a
+  hash does not parse, rather than returning something incomplete.
+- Use `Devise.secure_compare` for checksum comparison, never `==`.
+- Return `false` from `password_configurations_match?` for a read-only legacy
+  strategy so its hashes always migrate away.
+- Never make a legacy strategy the configured `hashing_strategy`, or new
+  passwords will be written with it.

data/docs/migrating-passwords.md

@@ -0,0 +1,86 @@
+# Migrating passwords
+
+A password hash cannot be converted from one scheme to another — the plain-text
+password is needed to produce the new hash. `:password_hashable` therefore
+migrates lazily: it re-hashes each user at the moment they next sign in
+successfully, because that is the only time the password is available.
+
+No batch job, no forced reset, no downtime. Users who never return keep their old
+hash indefinitely, which is why old hashes must stay readable.
+
+## What happens on sign-in
+
+`valid_password?` runs this sequence:
+
+1. **Verify** the password against the stored hash, using the scheme that hash
+   records — not the configured one. A wrong password returns `false` and
+   nothing else happens.
+2. **Skip** the migration if `password_confirmation` is present, which means the
+   user is in the middle of changing their password. The new password is about
+   to be written with the current settings anyway.
+3. **Compare** the stored hash's parameters against the configured ones. If they
+   already match, stop.
+4. **Re-hash** the password with the current strategy and settings, and save.
+
+Step 3 is why changing a cost parameter is enough to trigger a migration. Raising
+`hash_iterations`, or switching Argon2 profile, re-hashes everyone on their next
+sign-in without any change of strategy.
+
+## Migration is reversible
+
+Nothing about this is one-way. Set `hashing_strategy` back and users migrate back
+on their next sign-in. There is no separate rollback path — the same mechanism
+runs in both directions, which makes it safe to try a strategy and change your
+mind.
+
+## Rolling it out
+
+Start by naming the strategy you already use, so that nothing re-hashes and you
+can confirm the module is wired up correctly:
+
+```ruby
+devise :password_hashable, hashing_strategy: :bcrypt
+```
+
+Once that is deployed and sign-ins are healthy, change the strategy. Migration
+begins on the next sign-in for each user.
+
+## Interaction with Devise's Validatable
+
+Devise's `Validatable` gates password presence and confirmation on
+`password_required?`. While a re-hash is in progress this module returns `false`
+from that method, so a re-hash cannot be rejected by a validation intended for
+user-supplied passwords.
+
+That suspension lasts only for the re-hash. Once it finishes, presence and
+confirmation validations apply again as normal.
+
+## Records with no password
+
+A user whose `encrypted_password` is blank — an OAuth-only account, or an
+invitation that has not been accepted — is never migrated and never verifies a
+password. `authenticatable_salt` returns `nil` for such a record rather than
+raising.
+
+## Unreadable hashes
+
+If a stored hash cannot be parsed by the strategy that owns its prefix, the
+strategy raises `Devise::Hashable::InvalidPasswordHash`. A hash whose scheme is
+not recognised at all is treated as unknown and simply fails verification,
+returning `false` rather than raising.
+
+```ruby
+begin
+  user.valid_password?(params[:password])
+rescue Devise::Hashable::InvalidPasswordHash => e
+  Rails.logger.warn("Unreadable password hash for user #{user.id}: #{e.message}")
+  false
+end
+```
+
+## Session tokens
+
+Devise builds its session token from `authenticatable_salt`. Bcrypt hashes use
+Devise's own implementation. The other strategies return the salt decoded out of
+the stored hash, so a re-hash changes the salt and therefore invalidates that
+user's existing sessions — they sign in again as normal.

data/docs/strategies/argon2.md

@@ -0,0 +1,75 @@
+# Argon2id
+
+Winner of the Password Hashing Competition and the scheme RFC 9106 recommends.
+Unlike PBKDF2 it is memory-hard, which is what makes it expensive to attack with
+GPUs and ASICs. Prefer it unless you need a FIPS-aligned KDF, in which case use
+[PBKDF2](pbkdf2.md).
+
+```ruby
+devise :password_hashable,
+       hashing_strategy: :argon2,
+       argon2_profile: :rfc_9106_low_memory
+```
+
+Only the `argon2id` variant is supported. `argon2i` and `argon2d` hashes raise
+`Devise::Hashable::InvalidPasswordHash`.
+
+## Profiles
+
+Cost is chosen by naming a profile rather than by setting parameters
+individually. The values come from the `argon2` gem's own profile table.
+
+| Profile | Memory | Time | Lanes | Use |
+| --- | --- | --- | --- | --- |
+| `:rfc_9106_high_memory` | 2 GiB | 1 | 4 | RFC 9106 FIRST RECOMMENDED |
+| `:rfc_9106_low_memory` | 64 MiB | 3 | 4 | RFC 9106 SECOND RECOMMENDED — the default |
+| `:unsafe_cheapest` | 8 KiB | 1 | 1 | Test suites only. Offers no real protection |
+
+Any other value raises `ArgumentError`.
+
+### Sizing
+
+The memory figure is per hash **in flight**, not per process. `:rfc_9106_high_memory`
+needs 2 GiB for every password being hashed at that moment, so ten concurrent
+sign-ins want 20 GiB. It is a realistic choice for a low-traffic admin system and
+an unrealistic one for a busy public site.
+
+`:rfc_9106_low_memory` is the default because 64 MiB stays workable under
+concurrency while remaining memory-hard. Size your web workers against
+`64 MiB x concurrent sign-ins` before raising it.
+
+Use `:unsafe_cheapest` in your test environment. A test suite that signs users in
+repeatedly at 64 MiB a time is needlessly slow:
+
+```ruby
+devise :password_hashable,
+       hashing_strategy: :argon2,
+       argon2_profile: Rails.env.test? ? :unsafe_cheapest : :rfc_9106_low_memory
+```
+
+## Stored format
+
+```
+$argon2id$v=19$m=65536,t=3,p=4$c29tZXNhbHQ$RdescudvJCsgt3ub+b+dWRWJTmaaJObG
+    |      |         |            |         |
+    |      |         |            |         checksum
+    |      |         |            salt
+    |      |         cost parameters
+    |      Argon2 version
+    variant
+```
+
+Because the parameters travel inside the hash, verification does not depend on
+the configured profile. Changing profile never invalidates existing passwords.
+
+## When a hash is considered current
+
+The `m`, `t` and `p` recorded in the hash must equal those of the configured
+profile. Those expected values are read from the `argon2` gem at comparison time
+rather than being hardcoded here — a profile that the gem later revises would
+otherwise stop matching its own output, and every user would be re-hashed on
+every sign-in.
+
+## Session tokens
+
+`authenticatable_salt` returns the salt segment of the hash.

data/docs/strategies/bcrypt.md

@@ -0,0 +1,57 @@
+# Bcrypt
+
+Devise's own scheme. This strategy wraps `Devise::Encryptor`, so enabling it
+changes nothing about how passwords are stored — which makes it the right value
+to start with when you are only checking the module is wired up correctly.
+
+```ruby
+devise :password_hashable, hashing_strategy: :bcrypt
+```
+
+## Cost
+
+Bcrypt has no setting of its own here. It uses Devise's existing `stretches`:
+
+```ruby
+Devise.setup do |config|
+  config.stretches = Rails.env.test? ? 1 : 12
+end
+```
+
+Raising `stretches` re-hashes each user on their next sign-in.
+
+## Stored format
+
+```
+$2a$12$LQv3c1yqBWVHxkd0LHAkCOYz6TtxMQJqhN8/LewCUlNwjBUOSNILe
+ |  |  |
+ |  |  22-character salt followed by a 31-character checksum
+ |  cost
+ identifier
+```
+
+## When a hash is considered current
+
+The cost recorded in the hash must equal the configured `stretches`, floored at
+4. Bcrypt's own minimum cost is 4, so a configuration of `stretches = 1` still
+produces a hash with cost 4, and comparing against the raw setting would
+re-hash every user on every sign-in forever. Comparing against the floor is what
+stops that.
+
+## Limits
+
+Only the `$2a$` identifier is recognised. A hash written by an implementation
+that uses `$2b$` or `$2y$` raises `Devise::Hashable::InvalidPasswordHash` rather
+than being silently accepted. If you are importing hashes from another system,
+check the identifier first.
+
+`stretches` of zero or less raises `ArgumentError`.
+
+Bcrypt also truncates input at 72 bytes, which is a property of bcrypt itself
+rather than of this gem. If that matters to you, use
+[PBKDF2](pbkdf2.md) or [Argon2id](argon2.md), neither of which truncates.
+
+## Session tokens
+
+`authenticatable_salt` falls through to Devise's own implementation, so session
+handling is unchanged from a stock Devise application.

data/docs/strategies/pbkdf2.md

@@ -0,0 +1,58 @@
+# PBKDF2
+
+PBKDF2-HMAC, the scheme named by FIPS 140 and by NIST SP 800-132. Choose it when
+you need a FIPS-aligned KDF; choose [Argon2id](argon2.md) when you are free to
+pick on security grounds alone, since PBKDF2 is much cheaper to attack with
+purpose-built hardware.
+
+```ruby
+devise :password_hashable,
+       hashing_strategy: :pbkdf2,
+       digest_algorithm: :sha256,
+       hash_iterations: 600_000
+```
+
+## Settings
+
+| Setting | Default | Accepts |
+| --- | --- | --- |
+| `digest_algorithm` | `:sha256` | `:sha1`, `:sha256`, `:sha512` |
+| `hash_iterations` | `50_000` | any integer greater than zero |
+
+Anything else raises `ArgumentError`.
+
+The `50_000` default is low for current guidance. OWASP recommends 600,000
+iterations for PBKDF2-HMAC-SHA256 and 210,000 for SHA-512. Set a value
+deliberately rather than relying on the default.
+
+`:sha1` exists for reading hashes produced by older systems. Do not choose it for
+new hashes.
+
+## Stored format
+
+Passlib's `$pbkdf2-<digest>$` format, so hashes written here can be read by
+Python's `passlib` and vice versa:
+
+```
+$pbkdf2-sha256$50000$IKHmYkjgKpM$OElxCJoQ1r3oYbLSFTsf0i/whOFimbGBEw0ZH7BfFek
+       |        |        |        |
+       |        |        |        checksum
+       |        |        salt
+       |        iterations
+       digest
+```
+
+Salt and checksum use passlib's Base64 variant: standard Base64 with `+`
+replaced by `.` and the `=` padding removed. The salt is 16 bytes from
+`Devise.friendly_token`.
+
+## When a hash is considered current
+
+Both the iteration count and the digest algorithm recorded in the hash must match
+the configured values. Changing either re-hashes each user on their next sign-in,
+so raising iterations over time costs nothing but a deploy.
+
+## Session tokens
+
+`authenticatable_salt` returns the salt decoded out of the hash, not the encoded
+form stored in the column.

data/lib/devise/hashable/strategy/argon2.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "argon2"
+
+module Devise
+  module Hashable
+    module Strategy
+      # Argon2 password hashing
+      class Argon2 < Base
+        class << self
+          # Verifies a plain-text password against an Argon2id hash.
+          #
+          # @param _klass [Class] the Devise model class (unused; Argon2 encodes
+          #   its own parameters in the hash)
+          # @param encrypted_password [String] the stored Argon2id hash
+          # @param password [String] the plain-text password to verify
+          # @return [Boolean] true when the password matches
+          def compare(_klass, encrypted_password, password)
+            ::Argon2::Password.verify_password(password, encrypted_password)
+          end
+
+          # Hashes a plain-text password with Argon2id.
+          #
+          # @param klass [Class] the Devise model class, read for +argon2_profile+
+          # @param password [String] the plain-text password to hash
+          # @return [String] the encoded Argon2id hash
+          # @raise [ArgumentError] when +argon2_profile+ is not a known profile
+          def digest(klass, password)
+            ::Argon2::Password.new(profile: base_configs(klass)[:argon2_profile]).create(password)
+          end
+
+          def password_configurations_match?(klass, encrypted_password)
+            current_password_configs = split_password_hash(encrypted_password)
+            required_password_configs = base_configs(klass)
+
+            current_password_configs[:mtp] == profile_parameters(required_password_configs[:argon2_profile])
+          end
+
+          def split_password_hash(encrypted_password) # rubocop:disable Metrics/MethodLength
+            split_digest = encrypted_password.split("$")
+
+            raise InvalidPasswordHash, "Invalid password hash for Argon2" unless split_digest.length == 6
+
+            _, strategy, version, mtp, salt, digest = split_digest
+
+            raise InvalidPasswordHash, "Invalid password hash strategy for Argon2" unless strategy == "argon2id"
+
+            {
+              strategy: strategy,
+              version: version,
+              mtp: mtp,
+              salt: salt,
+              digest: digest
+            }
+          end
+
+          private
+
+          # The cost parameters as Argon2 encodes them in the hash, read from the
+          # argon2 gem's own profile table rather than hardcoded here, so they
+          # cannot drift when that gem revises a profile.
+          def profile_parameters(profile)
+            costs = ::Argon2::Profiles[profile]
+
+            "m=#{2**costs[:m_cost]},t=#{costs[:t_cost]},p=#{costs[:p_cost]}"
+          end
+
+          def base_configs(klass)
+            unless %i[rfc_9106_high_memory rfc_9106_low_memory unsafe_cheapest].include?(klass.argon2_profile)
+              raise(ArgumentError, "argon2_profile: must be one of the following options -> :rfc_9106_high_memory, :rfc_9106_low_memory, :unsafe_cheapest")
+            end
+
+            {
+              argon2_profile: klass.argon2_profile
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/devise/hashable/strategy/base.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Devise
+  module Hashable
+    module Strategy
+      # The base class for each hashing strategy.
+      #
+      # Subclasses implement the four class methods below. Every strategy is
+      # stateless: the Devise model class is passed in so the strategy can read
+      # the configuration (stretches, iterations, profile) it needs.
+      #
+      # @abstract Subclass and override {compare}, {digest},
+      #   {password_configurations_match?} and {split_password_hash}.
+      class Base
+        class << self
+          # Verifies a plain-text password against an existing hash.
+          #
+          # @param _klass [Class] the Devise model class
+          # @param _encrypted_password [String] the stored password hash
+          # @param _password [String] the plain-text password to verify
+          # @return [Boolean] true when the password matches
+          # @raise [NotImplementedError] always, on the base class
+          def compare(_klass, _encrypted_password, _password)
+            raise NotImplementedError, "You need to implement the 'compare' method in your custom hashing strategy"
+          end
+
+          # Hashes a plain-text password using the strategy's configuration.
+          #
+          # @param _klass [Class] the Devise model class
+          # @param _password [String] the plain-text password to hash
+          # @return [String] the encoded password hash
+          # @raise [NotImplementedError] always, on the base class
+          def digest(_klass, _password)
+            raise NotImplementedError, "You need to implement the 'digest' method in your custom hashing strategy"
+          end
+
+          # Whether an existing hash was produced with the currently configured
+          # parameters. A false result means the password needs re-hashing.
+          #
+          # @param _klass [Class] the Devise model class
+          # @param _encrypted_password [String] the stored password hash
+          # @return [Boolean] true when the hash matches the current config
+          # @raise [NotImplementedError] always, on the base class
+          def password_configurations_match?(_klass, _encrypted_password)
+            raise NotImplementedError, "You need to implement the 'password_configurations_match?' method in your custom hashing strategy"
+          end
+
+          # Splits an encoded password hash into its component parts.
+          #
+          # @param _encrypted_password [String] the stored password hash
+          # @return [Hash] the decoded components of the hash
+          # @raise [NotImplementedError] always, on the base class
+          def split_password_hash(_encrypted_password)
+            raise NotImplementedError, "You need to implement the 'split_password_hash' method in your custom hashing strategy"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/devise/hashable/strategy/bcrypt.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Devise
+  module Hashable
+    module Strategy
+      # Wrapper for the Devise' standard encryption strategy Bcrypt
+      class Bcrypt < Base
+        class << self
+          # Verifies a plain-text password against a bcrypt hash.
+          #
+          # @param klass [Class] the Devise model class
+          # @param encrypted_password [String] the stored bcrypt hash
+          # @param password [String] the plain-text password to verify
+          # @return [Boolean] true when the password matches
+          def compare(klass, encrypted_password, password)
+            Devise::Encryptor.compare(klass, encrypted_password, password)
+          end
+
+          # Hashes a plain-text password with bcrypt.
+          #
+          # @param klass [Class] the Devise model class, read for +stretches+
+          # @param password [String] the plain-text password to hash
+          # @return [String] the encoded bcrypt hash
+          def digest(klass, password)
+            Devise::Encryptor.digest(klass, password)
+          end
+
+          def password_configurations_match?(klass, encrypted_password)
+            current_password_configs = split_password_hash(encrypted_password)
+            required_password_configs = base_configs(klass)
+
+            return false if current_password_configs[:stretches] != [required_password_configs[:stretches], 4].max
+
+            true
+          end
+
+          def split_password_hash(encrypted_password)
+            split_digest = encrypted_password.split("$")
+
+            raise InvalidPasswordHash, "Invalid password hash for Bcrypt" unless split_digest.length == 4
+
+            _, strategy, stretches, _checksum = split_digest
+
+            raise InvalidPasswordHash, "Invalid password hash strategy for Bcrypt" unless strategy == "2a"
+
+            {
+              stretches: stretches.to_i
+            }
+          end
+
+          private
+
+          def base_configs(klass)
+            raise(ArgumentError, "stretches: must be greater than zero") if klass.stretches.to_i <= 0
+
+            {
+              stretches: klass.stretches.to_i
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/devise/hashable/strategy/pbkdf2.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Devise
+  module Hashable
+    module Strategy
+      # Pbkdf2 hashing
+      class Pbkdf2 < Base
+        class << self
+          # Verifies a plain-text password against a PBKDF2 hash.
+          #
+          # @param _klass [Class] the Devise model class (unused; the iteration
+          #   count and digest are read from the hash itself)
+          # @param encrypted_password [String] the stored PBKDF2 hash
+          # @param password [String] the plain-text password to verify
+          # @return [Boolean] true when the password matches
+          def compare(_klass, encrypted_password, password)
+            split_digest = split_password_hash(encrypted_password)
+            value_to_test = digest_checksum(password, split_digest[:hash_iterations], split_digest[:salt], split_digest[:digest_algorithm])
+
+            Devise.secure_compare(split_digest[:checksum], value_to_test)
+          end
+
+          # Hashes a plain-text password with PBKDF2.
+          #
+          # @param klass [Class] the Devise model class, read for +hash_iterations+
+          #   and +digest_algorithm+
+          # @param password [String] the plain-text password to hash
+          # @return [String] the encoded PBKDF2 hash, in passlib format
+          def digest(klass, password)
+            configs = base_configs(klass)
+            salt = Devise.friendly_token(16)
+            checksum = digest_checksum(password, configs[:hash_iterations], salt, configs[:digest_algorithm])
+
+            format_hash("pbkdf2-#{configs[:digest_algorithm]}", configs[:hash_iterations], salt, checksum)
+          end
+
+          def password_configurations_match?(klass, encrypted_password)
+            current_password_configs = split_password_hash(encrypted_password)
+            required_password_configs = base_configs(klass)
+
+            return false if current_password_configs[:hash_iterations] != required_password_configs[:hash_iterations]
+            return false if current_password_configs[:digest_algorithm] != required_password_configs[:digest_algorithm]
+
+            true
+          end
+
+          def split_password_hash(encrypted_password) # rubocop:disable Metrics/MethodLength
+            split_digest = encrypted_password.split("$")
+
+            raise InvalidPasswordHash, "Invalid password hash for PBKDF2" unless split_digest.length == 5
+
+            _, strategy, hash_iterations, salt, checksum = split_digest
+
+            raise InvalidPasswordHash, "Invalid password hash strategy for PBKDF2" unless strategy.start_with?("pbkdf2-")
+
+            split_strategy = strategy.split("-")
+            base_strategy, digest_algorithm = split_strategy
+
+            {
+              strategy: strategy,
+              base_strategy: base_strategy,
+              digest_algorithm: digest_algorithm,
+              hash_iterations: hash_iterations.to_i,
+              salt: passlib_decode64(salt),
+              checksum: passlib_decode64(checksum)
+            }
+          end
+
+          private
+
+          def base_configs(klass)
+            raise(ArgumentError, "digest_algorithm: must be one of the following options -> :sha1, :sha256, :sha512") unless %i[sha1 sha256 sha512].include?(klass.digest_algorithm)
+            raise(ArgumentError, "hash_iterations: must be greater than zero") if klass.hash_iterations.to_i <= 0
+
+            {
+              hash_iterations: klass.hash_iterations.to_i,
+              digest_algorithm: klass.digest_algorithm.to_s
+            }
+          end
+
+          def digest_checksum(password, hash_iterations, salt, digest_algorithm)
+            hash = OpenSSL::Digest.new(digest_algorithm)
+
+            pbkdf2_checksum(hash, password, hash_iterations, salt)
+          end
+
+          def pbkdf2_checksum(hash, password, hash_iterations, salt)
+            OpenSSL::KDF.pbkdf2_hmac(
+              password.to_s,
+              salt: [salt].pack("H*"),
+              iterations: hash_iterations,
+              hash: hash,
+              length: hash.digest_length
+            ).unpack1("H*")
+          end
+
+          def format_hash(strategy, hash_iterations, salt, checksum)
+            encoded_salt = passlib_encode64(salt)
+            encoded_checksum = passlib_encode64(checksum)
+
+            "$#{strategy}$#{hash_iterations}$#{encoded_salt}$#{encoded_checksum}"
+          end
+
+          # Passlib-style Base64 encoding:
+          # - Replaces '+' with '.'
+          # - Strips trailing newline and '=='
+          def passlib_encode64(value)
+            Base64.strict_encode64([value].pack("H*")).tr("+", ".").delete("=")
+          end
+
+          def passlib_decode64(value)
+            enc = value.tr(".", "+")
+            Base64.decode64(enc).unpack1("H*")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/devise/hashable/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Devise
+  module Hashable
+    # The version of the devise-hashable gem.
+    VERSION = "1.0.0"
+  end
+end

data/lib/devise/hashable.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "devise"
+require_relative "hashable/version"
+
+module Devise # :nodoc:
+  mattr_accessor(:hashing_strategy)
+  @@hashing_strategy = nil
+
+  mattr_accessor(:digest_algorithm)
+  @@digest_algorithm = :sha256
+
+  mattr_accessor(:hash_iterations)
+  @@hash_iterations = 50_000
+
+  mattr_accessor(:argon2_profile)
+  @@argon2_profile = :rfc_9106_low_memory
+
+  module Hashable # :nodoc:
+    # Raised when a stored password hash cannot be parsed by the strategy that
+    # was asked to read it, either because it has the wrong number of segments
+    # or because it names a different algorithm.
+    class InvalidPasswordHash < StandardError; end
+
+    module Strategy # :nodoc:
+      autoload(:Argon2, "devise/hashable/strategy/argon2")
+      autoload(:Base, "devise/hashable/strategy/base")
+      autoload(:Bcrypt, "devise/hashable/strategy/bcrypt")
+      autoload(:Pbkdf2, "devise/hashable/strategy/pbkdf2")
+    end
+  end
+end
+
+Devise.add_module(:password_hashable, model: "devise/models/password_hashable")

data/lib/devise/models/password_hashable.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require("devise/strategies/database_authenticatable")
+
+module Devise
+  # Namespace for the model concerns Devise mixes into your models.
+  module Models
+    # Devise module that transparently re-hashes a user's password to the
+    # configured strategy the next time they sign in successfully.
+    #
+    # Enable it on a model with:
+    #
+    #   devise :password_hashable, hashing_strategy: :argon2
+    module PasswordHashable
+      extend(ActiveSupport::Concern)
+
+      included do
+        after_validation :unset_migrating_password_hashing_strategy
+      end
+
+      def valid_password?(password)
+        return false unless password_matches?(password)
+        return true if skip_password_migration?
+
+        migrate_password!(password)
+      end
+
+      # The salt used to build the Devise session token.
+      #
+      # Bcrypt hashes fall through to Devise's own implementation; the other
+      # strategies return the salt decoded out of the stored hash.
+      #
+      # @return [String, nil] the salt, or nil when no password is set
+      def authenticatable_salt
+        # Devise's schema declares encrypted_password as null: false, default: "",
+        # so a user who has never set a password holds "" rather than nil.
+        return if encrypted_password.blank?
+        return super if encrypted_password_strategy == :bcrypt
+
+        devise_rehash_class(encrypted_password_strategy).split_password_hash(encrypted_password)[:salt]
+      end
+
+      protected
+
+      def password_digest(password)
+        devise_rehash_class.digest(self.class, password)
+      end
+
+      # skip the password_migration when
+      # updating or resetting password
+      def skip_password_migration?
+        password_confirmation.present?
+      end
+
+      private
+
+      ##
+      # Provides a check list for identifying the encrypted_password hashing strategy
+      # to match against, the returned symbol is then used to look up the Class.
+      # Return nil if nothing is matched. You should override this method when adding
+      # a custom hashing strategy.
+      #   Example
+      #
+      #   def encrypted_password_strategy_check
+      #     return :my_custom if encrypted_password&.start_with?("$custom-")
+      #
+      #     super
+      #   end
+      #
+      def encrypted_password_strategy_check
+        return :bcrypt if encrypted_password&.start_with?("$2a$")
+        return :pbkdf2 if encrypted_password&.start_with?("$pbkdf2-")
+        return :argon2 if encrypted_password&.start_with?("$argon2")
+
+        nil
+      end
+
+      def encrypted_password_strategy
+        return encrypted_password_strategy_check if encrypted_password_strategy_check.present?
+
+        :unknown
+      end
+
+      def password_matches?(password)
+        return false if encrypted_password_strategy == :unknown
+
+        devise_rehash_class(encrypted_password_strategy).compare(self.class, encrypted_password, password)
+      end
+
+      def migrate_password!(password)
+        return true if password_configurations_match?
+
+        migrating_password_hashing_strategy
+
+        begin
+          update_attribute(:password, password)
+        ensure
+          # update_attribute saves without validating, so after_validation does
+          # not fire here. Clearing the flag explicitly stops it leaking past the
+          # re-hash and disabling Validatable's password checks on this record.
+          unset_migrating_password_hashing_strategy
+        end
+      end
+
+      # Sets the instance variable @migrating_password_hashing_strategy to true while the password hashing strategy update is taking place.
+      # this can be used as you require to ensure a your password hashing strategy process happens smoothly without any custom validations
+      # interfering.
+      #
+      def migrating_password_hashing_strategy
+        @migrating_password_hashing_strategy = true
+      end
+
+      # Skip password validation when migrating the password hashing strategy if Devise Validatable is used.
+      # from https://github.com/heartcombo/devise/blob/bb18f4d3805be0bf5f45e21be39625c7cfd9c1d6/lib/devise/models/validatable.rb#L55
+      #
+      def password_required?
+        return false if @migrating_password_hashing_strategy
+
+        super
+      end
+
+      def unset_migrating_password_hashing_strategy
+        remove_instance_variable(:@migrating_password_hashing_strategy) if defined?(@migrating_password_hashing_strategy)
+      end
+
+      def password_configurations_match?
+        return false if encrypted_password_strategy != self.class.hashing_strategy
+
+        devise_rehash_class.password_configurations_match?(self.class, encrypted_password)
+      end
+
+      def devise_rehash_class(strategy_choice = nil)
+        return self.class.rehash_class if strategy_choice.nil?
+
+        Devise::Hashable::Strategy.const_get(strategy_choice.to_s.classify)
+      end
+
+      module ClassMethods # :nodoc:
+        Devise::Models.config(self, :hashing_strategy, :digest_algorithm, :hash_iterations, :argon2_profile)
+
+        # Returns the class for the configured strategy. strategy
+        def rehash_class
+          @rehash_class ||=
+            case hashing_strategy
+            when nil
+              raise("You need to specify a hashing_strategy: in Devise configuration to use :password_hashable")
+            else
+              Devise::Hashable::Strategy.const_get(hashing_strategy.to_s.classify)
+            end
+        rescue NameError
+          raise("Configured password hashing_strategy '#{hashing_strategy.to_sym}' could not be found for :password_hashable")
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: devise-hashable
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Matthew Kennedy
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: argon2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: devise
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+description: Allows Devise passwords to be re-encrypted with various hashing strategies
+  and configurations.
+email:
+- m.kennedy@me.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- docs/configuration.md
+- docs/custom-strategies.md
+- docs/migrating-passwords.md
+- docs/strategies/argon2.md
+- docs/strategies/bcrypt.md
+- docs/strategies/pbkdf2.md
+- lib/devise/hashable.rb
+- lib/devise/hashable/strategy/argon2.rb
+- lib/devise/hashable/strategy/base.rb
+- lib/devise/hashable/strategy/bcrypt.rb
+- lib/devise/hashable/strategy/pbkdf2.rb
+- lib/devise/hashable/version.rb
+- lib/devise/models/password_hashable.rb
+homepage: https://github.com/MatthewKennedy/devise-hashable
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/MatthewKennedy/devise-hashable
+  source_code_uri: https://github.com/MatthewKennedy/devise-hashable
+  changelog_uri: https://github.com/MatthewKennedy/devise-hashable/releases
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: A password hashing tool for Devise
+test_files: []