two_factor_authentication 2.1.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: ba9192cf04aafc95a917e76b6efef8217fb22152
-  data.tar.gz: fe60bb1323aead63cb3712857e88bf4eaab08cfc
+SHA256:
+  metadata.gz: 3f83f45de8b5992a3311c7d0d47479f7b7121c7460925fa8661d8b7eb98f4f72
+  data.tar.gz: 4df0c76ae151691cec84f1d036d79b93094826c892d01edef5d0a847a92407af
 SHA512:
-  metadata.gz: 9a3d4c7cd0bb5eb3af1bc322ee3cad89a38bb8316178a9050dc5cce11f006930f3c3b916b41e29a1594f3acbc360814d831c6816e453504c21bd93b00b0834d4
-  data.tar.gz: e651f87940c8fc7d55b653c010c30da565cd18e2bcfd7708dc12c657dd953199f389aae800973b1a5bbfb6d09fdadf5d7689e3b28fe11403f7df3fcece5f2e15
+  metadata.gz: cef6991e8c5032e5779ee0c5ec0348ad1b0010f947748b49da40b42dabb9e2d83ff43106b6be09acae3acbf3cefa20fbc1ef257d10012098d287d03dbd94635a
+  data.tar.gz: 509142892d180c5fc74d9da25166a12e45e6570893386a5bba70feb50e91d80212b67ee78dd46451c8d58e7d88a37ed6f081872519bf919fa3757f257fdfdd02

data/.github/workflows/ci.yml

@@ -0,0 +1,77 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Ruby ${{ matrix.ruby }} / Rails ${{ matrix.rails }}
+    runs-on: ubuntu-latest
+    continue-on-error: ${{ matrix.rails == 'main' }}
+    timeout-minutes: 20
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - ruby: "2.3"
+            rails: "5.2"
+          - ruby: "2.4"
+            rails: "5.2"
+          - ruby: "2.5"
+            rails: "5.2"
+          - ruby: "2.5"
+            rails: "6.0"
+          - ruby: "2.7"
+            rails: "6.0"
+          - ruby: "2.5"
+            rails: "6.1"
+          - ruby: "3.1"
+            rails: "6.1"
+          - ruby: "2.7"
+            rails: "7.0"
+          - ruby: "3.2"
+            rails: "7.0"
+          - ruby: "2.7"
+            rails: "7.1"
+          - ruby: "3.3"
+            rails: "7.1"
+          - ruby: "3.1"
+            rails: "7.2"
+          - ruby: "4.0"
+            rails: "7.2"
+          - ruby: "3.2"
+            rails: "8.0"
+          - ruby: "4.0"
+            rails: "8.0"
+          - ruby: "3.2"
+            rails: "8.1"
+          - ruby: "4.0"
+            rails: "8.1"
+          - ruby: "4.0"
+            rails: main
+
+    env:
+      RAILS_VERSION: ${{ matrix.rails }}
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Set up test database
+        run: bundle exec rake app:db:setup
+
+      - name: Run specs
+        run: bundle exec rake spec

data/.gitignore

@@ -21,3 +21,6 @@ dump.rdb
 .rbenv-version
 .ruby-gemset
 .ruby-version
+
+# Generator spec output
+/tmp

data/CHANGELOG.md

@@ -1,8 +1,43 @@
 # Change Log
 
-## [Unreleased](https://github.com/Houdini/two_factor_authentication/tree/HEAD)
+## [v3.0.0](https://github.com/Houdini/two_factor_authentication/tree/v3.0.0) (2026-10-01)
+[Full Changelog](https://github.com/Houdini/two_factor_authentication/compare/v2.2.0...v3.0.0)
 
-[Full Changelog](https://github.com/Houdini/two_factor_authentication/compare/v1.1.5...HEAD)
+See the [Migration Guide](MIGRATION_GUIDE.md#upgrading-from-220-to-300) for upgrade steps.
+
+**Breaking changes:**
+
+- Require Rails 5.0 or newer (was 3.1.1). Tested on Ruby 2.3–4.0 with Rails 5.2 through 8.1
+- `is_fully_authenticated?` checks the current Devise scope (or `Devise.default_scope`) instead of always `:user`, and accepts a scope: `is_fully_authenticated?(:admin)`. Before, it returned `true` for other models before the second factor had been entered
+- A rejected code or reaching the attempt limit now responds with 422 instead of 200, so Turbo renders the error
+- JSON requests that still need the second factor get a 401 with a `{"redirect_to": ...}` body instead of an empty 401 [\#143](https://github.com/Houdini/two_factor_authentication/pull/143) ([Kevinrob](https://github.com/Kevinrob))
+
+**Fixed bugs:**
+
+- Replace `update_attributes` (removed in Rails 6.1) with `update`, which broke `create_direct_otp`, `send_new_otp` and `clear_direct_otp`
+- Store `totp_timestamp` as a `Time`; PostgreSQL rejected the Integer, so every TOTP login failed
+- The generator writes a versioned migration (`ActiveRecord::Migration[x.y]`), which Rails 5.1+ requires
+- The generator no longer uses `File.exists?` (removed in Ruby 3.2) and finds the model relative to the destination root
+- Remove `resend_code` from the route's `only:`, which Rails 8.1 rejects
+- The schema table helpers (`t.second_factor_attempts_count`, `t.totp_timestamp`, ...) no longer call the removed `apply_devise_schema`
+- Remove `totp_timestamp` from the Devise model config; `User.totp_timestamp` raised `NoMethodError`
+- "Sign out" on the two factor page uses `button_to` with `Devise.sign_out_via`, so it works without rails-ujs
+- Support ROTP 5.0, which renamed `ROTP::Base32.random_base32` to `random` [\#171](https://github.com/Houdini/two_factor_authentication/pull/171) ([jaspervandenberg](https://github.com/jaspervandenberg))
+
+**Implemented enhancements:**
+
+- Add the encrypted OTP secret index concurrently on PostgreSQL [\#197](https://github.com/Houdini/two_factor_authentication/pull/197) ([Lackoftactics](https://github.com/Lackoftactics))
+- Autofocus the code field [\#174](https://github.com/Houdini/two_factor_authentication/pull/174) ([gustavokitman](https://github.com/gustavokitman))
+- Add German translations [\#166](https://github.com/Houdini/two_factor_authentication/pull/166) ([JanBussieck](https://github.com/JanBussieck))
+
+**Other changes:**
+
+- Replace Travis CI with GitHub Actions
+- Test TOTP sign-in, resending the code, the attempt counter reset and an encrypted-secret model end to end
+- README updates [\#168](https://github.com/Houdini/two_factor_authentication/pull/168) ([MarkFChavez](https://github.com/MarkFChavez)), [\#139](https://github.com/Houdini/two_factor_authentication/pull/139) ([rmm5t](https://github.com/rmm5t))
+
+## [v2.0](https://github.com/Houdini/two_factor_authentication/tree/v2.0) (2017-05-12)
+[Full Changelog](https://github.com/Houdini/two_factor_authentication/compare/v1.1.5...v2.0)
 
 **Merged pull requests:**
 

data/Gemfile

@@ -1,31 +1,51 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in devise_ip_filter.gemspec
+# Specify your gem's dependencies in two_factor_authentication.gemspec
 gemspec
 
 rails_version = ENV["RAILS_VERSION"] || "default"
 
 rails = case rails_version
-        when "master"
-          {github: "rails/rails"}
+        when "main"
+          {github: "rails/rails", branch: "main"}
         when "default"
-          "~> 4.1"
+          "~> 8.1.0"
         else
-          "~> #{rails_version}"
+          requirement = rails_version.split('.').length == 2 ? "#{rails_version}.0" : rails_version
+          "~> #{requirement}"
         end
 
 gem "rails", rails
 
-if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('2.2.0')
-  gem "test-unit", "~> 3.0"
+# Rails main freezes controller default_url_options; rspec-rails 8.0.4 still
+# mutates it in feature specs. Drop once a release includes rspec/rspec-rails#2907.
+gem "rspec-rails", github: "rspec/rspec-rails", branch: "main" if rails_version == "main"
+
+ruby_version = Gem::Version.new(RUBY_VERSION)
+
+gem "test-unit", "~> 3.0"
+
+if ruby_version < Gem::Version.new('2.5.0')
+  gem 'nokogiri', '~> 1.10.10'
+elsif ruby_version < Gem::Version.new('2.6.0')
+  gem 'nokogiri', '~> 1.12.5'
 end
 
+gem 'loofah', '< 2.21' if ruby_version < Gem::Version.new('2.5.0')
+gem 'psych', '< 5' if rails_version == '7.1' && ruby_version < Gem::Version.new('3.0.0')
+
 group :test, :development do
-  gem 'sqlite3'
+  gem 'ostruct' if ruby_version >= Gem::Version.new('4.0.0')
+  case rails_version
+  when '5.2', '6.0', '6.1', '7.0'
+    gem 'sqlite3', '~> 1.4'
+  else
+    gem 'sqlite3'
+  end
+  gem 'sprockets-rails'
 end
 
 group :test do
   gem 'rack_session_access'
   gem 'ammeter'
-  gem 'pry'
 end

data/MIGRATION_GUIDE.md

@@ -0,0 +1,143 @@
+# Migration Guide
+
+## Upgrading from 2.2.0 to 3.0.0
+
+Version 3.0.0 brings the gem up to date with current Ruby, Rails and Devise, and
+fixes several bugs that made 2.2.0 unusable on Rails 6.1+, Ruby 3.2+ and
+PostgreSQL. Most apps only need to bump the gem version, but a few behaviours
+changed. Go through the checklist below.
+
+### 1. Check your Ruby and Rails versions
+
+- **Rails 5.0 or newer is now required** (it was `>= 3.1.1`). If you are on
+  Rails 3.x or 4.x, stay on 2.2.0.
+- The gem is tested on Ruby 2.3 – 4.0 with Rails 5.2, 6.0, 6.1, 7.0, 7.1,
+  7.2, 8.0 and 8.1. Rails 5.0 and 5.1 are allowed by the gemspec but are not
+  tested.
+
+### 2. Fix old unversioned migrations
+
+Migrations generated by 2.2.0 and earlier inherit from
+`ActiveRecord::Migration` without a version. Rails 5.1+ refuses to run them,
+which breaks `db:migrate` on a fresh database (for example in CI). Add the
+Rails version the migration was written for:
+
+```ruby
+# Before
+class TwoFactorAuthenticationAddToUsers < ActiveRecord::Migration
+
+# After
+class TwoFactorAuthenticationAddToUsers < ActiveRecord::Migration[5.0]
+```
+
+Migrations that have already run are not executed again, so this only matters
+when the database is rebuilt from migrations.
+
+The generator (`rails g two_factor_authentication MODEL`) now writes a
+versioned migration. On PostgreSQL it also builds the
+`encrypted_otp_secret_key` index with `algorithm: :concurrently` and
+`disable_ddl_transaction!` so adding it does not lock the table.
+
+### 3. Pass a scope to `is_fully_authenticated?` for non-`:user` models
+
+`is_fully_authenticated?` used to read the `:user` warden session no matter
+which model was signed in. For any other model (e.g. `Admin`) it returned
+`true` before the second factor had been entered, so a
+`confirm_two_factor_authenticated` guard did not protect that model.
+
+It now checks:
+
+1. the scope of the current Devise controller (`resource_name`), or
+2. `Devise.default_scope` outside Devise controllers, or
+3. the scope you pass in.
+
+Inside a Devise controller, such as the `RegistrationsController` guard in the
+README, nothing changes for `:user` and other models are now protected. In your
+own controllers, pass the scope explicitly if you have more than one 2FA model,
+or if your default scope is not the model you want to check:
+
+```ruby
+# Before: always checked :user
+return if is_fully_authenticated?
+
+# After
+return if is_fully_authenticated?(:admin)
+```
+
+### 4. Expect `422` from the code form
+
+When a submitted code is wrong, or the attempt limit is reached, the
+`update` action now responds with **422 Unprocessable Entity** instead of 200.
+Turbo (the default since Rails 7) ignores a 200 response to a form submission,
+so the error page was never shown.
+
+- Update any request or controller specs that expect a 200 after a wrong code.
+- If you override `after_two_factor_fail_for` in a custom controller, render
+  with `status: 422` as well:
+
+  ```ruby
+  def after_two_factor_fail_for(resource)
+    # ...
+    render :show, status: 422
+  end
+  ```
+
+### 5. Update overridden views
+
+If you copied `app/views/devise/two_factor_authentication/show.html.erb` into
+your app, your copy does not get these changes:
+
+- **Sign out** now uses `button_to` with `Devise.sign_out_via`.
+  `link_to ..., method: :delete` needs `rails-ujs`, which Rails 7+ apps no
+  longer ship, so the link sends a GET and fails.
+
+  ```erb
+  <%# Before %>
+  <%= link_to "Sign out", destroy_user_session_path, :method => :delete %>
+
+  <%# After %>
+  <%= button_to "Sign out", destroy_user_session_path, :method => :delete %>
+  ```
+
+- The code field is autofocused: `text_field_tag :code, '', autofocus: true`.
+- The stray `action: :get` option was removed from the "Resend Code" links.
+
+### 6. Check JSON clients
+
+When a signed-in user still needs the second factor, a JSON request used to
+get an empty `401`. It now gets a `401` with a body that tells the client
+where to send the user:
+
+```json
+{ "redirect_to": "/users/two_factor_authentication" }
+```
+
+The user's return location is set to `root_path(format: :html)`, so **your app
+must define a `root` route** to use this. HTML requests are still redirected,
+and every other format still gets an empty `401`.
+
+### 7. Things that now work without changes
+
+These were broken in 2.2.0 and need no action, but you can remove any
+workarounds you added for them:
+
+- `create_direct_otp`, `send_new_otp` and `clear_direct_otp` no longer raise
+  `NoMethodError` on Rails 6.1+ (they called the removed `update_attributes`).
+- A successful TOTP login no longer fails on PostgreSQL with
+  `PG::DatetimeFieldOverflow`. `totp_timestamp` is now stored as a `Time`;
+  existing values keep working.
+- The schema helpers (`t.second_factor_attempts_count`, `t.totp_timestamp`,
+  ...) work again in `create_table` and `change_table`.
+- `rails g two_factor_authentication MODEL` works on Ruby 3.2+ and no longer
+  has to be run from the app root.
+- The routes load on Rails 8.1 (which rejected `resend_code` in `only:`).
+- ROTP 5.0, which renamed `ROTP::Base32.random_base32` to `random`, is
+  supported.
+- `User.totp_timestamp` is no longer defined as a class method. It read a
+  Devise setting that does not exist and always raised; the
+  `totp_timestamp` column on each record is unaffected.
+
+## Upgrading from 1.x to 2.x
+
+See [Upgrading from version 1.X to 2.X](README.md#upgrading-from-version-1x-to-2x)
+in the README.

data/README.md

@@ -2,14 +2,14 @@
 
 [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/Houdini/two_factor_authentication?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
-[![Build Status](https://travis-ci.org/Houdini/two_factor_authentication.svg?branch=master)](https://travis-ci.org/Houdini/two_factor_authentication)
+[![CI](https://github.com/Houdini/two_factor_authentication/actions/workflows/ci.yml/badge.svg)](https://github.com/Houdini/two_factor_authentication/actions/workflows/ci.yml)
 [![Code Climate](https://codeclimate.com/github/Houdini/two_factor_authentication.svg)](https://codeclimate.com/github/Houdini/two_factor_authentication)
 
 ## Features
 
 * Support for 2 types of OTP codes
- 1. Codes delivered directly to the user
- 2. TOTP (Google Authenticator) codes based on a shared secret (HMAC)
+    1. Codes delivered directly to the user
+    2. TOTP (Google Authenticator) codes based on a shared secret (HMAC)
 * Configurable OTP code digit length
 * Configurable max login attempts
 * Customizable logic to determine if a user needs two factor authentication
@@ -28,7 +28,7 @@ Once that's done, run:
 
     bundle install
 
-Note that Ruby 2.1 or greater is required.
+The gem is tested on Ruby 2.3 – 4.0 with Rails 5.2 through 8.1.
 
 ### Installation
 
@@ -54,7 +54,7 @@ migration in `db/migrate/`, which will add the following columns to your table:
 #### Manual initial setup
 
 If you prefer to set up the model and migration manually, add the
-`:two_factor_authentication` option to your existing devise options, such as:
+`:two_factor_authenticatable` option to your existing devise options, such as:
 
 ```ruby
 devise :database_authenticatable, :registerable, :recoverable, :rememberable,
@@ -69,13 +69,20 @@ rails g migration AddTwoFactorFieldsToUsers second_factor_attempts_count:integer
 
 Open your migration file (it will be in the `db/migrate` directory and will be
 named something like `20151230163930_add_two_factor_fields_to_users.rb`), and
-add `unique: true` to the `add_index` line so that it looks like this:
+set the attempt counter's default to `0` and add `unique: true` to the
+`add_index` line so that they look like this:
 
 ```ruby
+add_column :users, :second_factor_attempts_count, :integer, default: 0
 add_index :users, :encrypted_otp_secret_key, unique: true
 ```
 Save the file.
 
+The counter must contain an integer because failed OTP submissions increment
+it. If you already ran a migration without this default, add a follow-up
+migration that sets the default to `0` and backfills existing `NULL` counters
+to `0`, preserving other counter values.
+
 #### Complete the setup
 
 Run the migration with:
@@ -161,9 +168,13 @@ Below is an example using ERB:
   <%= submit_tag "Log in!" %>
 <% end %>
 
-<%= link_to "Sign out", destroy_user_session_path, :method => :delete %>
+<%= button_to "Sign out", destroy_user_session_path, :method => :delete %>
 ```
 
+#### Upgrading from version 2.2.0 to 3.0.0
+
+See the [Migration Guide](MIGRATION_GUIDE.md#upgrading-from-220-to-300).
+
 #### Upgrading from version 1.X to 2.X
 
 The following database fields are new in version 2.
@@ -224,25 +235,26 @@ steps:
 
    Open the generated file, and replace its contents with the following:
    ```ruby
-   class PopulateEncryptedOtpFields < ActiveRecord::Migration
-      def up
-        User.reset_column_information
-
-        User.find_each do |user|
-          user.otp_secret_key = user.read_attribute('otp_secret_key')
-          user.save!
-        end
-      end
-
-      def down
-        User.reset_column_information
-
-        User.find_each do |user|
-          user.otp_secret_key = ROTP::Base32.random_base32
-          user.save!
-        end
-      end
-    end
+   class PopulateEncryptedOtpFields < ActiveRecord::Migration[8.1]
+     def up
+       User.reset_column_information
+
+       User.find_each do |user|
+         user.otp_secret_key = user.read_attribute('otp_secret_key')
+         user.save!
+       end
+     end
+
+     def down
+       User.reset_column_information
+
+       User.find_each do |user|
+         # Read through the encrypted accessor, then write the plaintext column
+         # directly without invoking the encrypted setter.
+         user.update_columns(otp_secret_key: user.otp_secret_key)
+       end
+     end
+   end
    ```
 
 5. Generate a migration to remove the `:otp_secret_key` column:
@@ -255,14 +267,191 @@ steps:
 If, for some reason, you want to switch back to the old non-encrypted version,
 use these steps:
 
-1. Remove `(encrypted: true)` from `has_one_time_password`
+1. Stop application writes while rolling back and changing the model
+   configuration. Keep `has_one_time_password(encrypted: true)` and the same
+   `otp_secret_encryption_key` configured throughout the rollback.
 
 2. Roll back the last 3 migrations (assuming you haven't added any new ones
-after them):
+   after them):
    ```
    bundle exec rake db:rollback STEP=3
    ```
 
+   This recreates the plaintext column, copies each decrypted secret back into
+   it, and then removes the encryption columns. Existing authenticator secrets
+   are preserved, and users without TOTP retain a `nil` secret.
+
+3. Remove `(encrypted: true)` from `has_one_time_password` and restart the
+   application before allowing writes again.
+
+#### Critical Security Note! Add before_action to your user registration controllers
+
+You should have a file registrations_controller.rb in your controllers folder
+to overwrite/customize user registrations. It should include the lines below, for 2FA protection of user model updates, meaning that users can only access the users/edit page after confirming 2FA fully, not simply by logging in. Otherwise the entire 2FA system can be bypassed!
+
+   ```ruby
+   class RegistrationsController < Devise::RegistrationsController
+     before_action :confirm_two_factor_authenticated, except: [:new, :create, :cancel]
+   
+     protected
+   
+     def confirm_two_factor_authenticated
+       return if is_fully_authenticated?
+
+       flash[:error] = t('devise.errors.messages.user_not_authenticated')
+       redirect_to user_two_factor_authentication_url
+     end
+   end
+   ```
+
+   Route registrations through this controller in `config/routes.rb`:
+
+   ```ruby
+   devise_for :users, controllers: { registrations: 'registrations' }
+   ```
+
+   Update your existing `devise_for :users` declaration. Defining the controller
+   alone does not change Devise's routes, so the callback will not run until
+   this mapping is configured.
+
+   `is_fully_authenticated?` checks the scope of the current Devise controller,
+   or `Devise.default_scope` elsewhere. Pass a scope to check another model,
+   e.g. `is_fully_authenticated?(:admin)`.
+
+#### Critical Security Note! Add 2FA validation to your custom user actions
+
+Require fresh second-factor verification for sensitive account changes,
+including replacing or disabling TOTP. Verify a code against the existing
+secret before assigning a replacement; a code for the replacement secret only
+proves that the user configured the new authenticator.
+
+For initial TOTP enrollment, verify a fresh direct OTP instead. The following
+example generates a pending secret on the server, keeps it separate from the
+active secret, and requires separate `current_code` and `new_code` values:
+
+```ruby
+class AccountController < ApplicationController
+  before_action :authenticate_user!
+
+  def new_totp
+    secret = current_user.generate_totp_secret
+    session[:pending_totp] = { 'user_id' => current_user.id, 'secret' => secret }
+    current_user.send_new_otp unless current_user.totp_enabled?
+    render json: { provisioning_uri: current_user.provisioning_uri(nil, otp_secret_key: secret) }
+  end
+
+  def update_totp
+    codes = params.require(:two_factor).permit(:current_code, :new_code)
+    pending = session[:pending_totp]
+    unless pending && pending['user_id'] == current_user.id
+      render json: { error: 'Start TOTP setup first.' }, status: :unprocessable_entity
+      return
+    end
+
+    updated = false
+    current_user.with_lock do
+      next if current_user.max_login_attempts?
+
+      valid_current_code = if current_user.totp_enabled?
+                             current_user.authenticate_totp(codes[:current_code].to_s)
+                           else
+                             current_user.authenticate_direct_otp(codes[:current_code].to_s)
+                           end
+      unless valid_current_code
+        current_user.increment!(:second_factor_attempts_count)
+        next
+      end
+
+      # Persist consumption of the current code even if the new code is invalid.
+      current_user.save!
+
+      # The new secret has its own replay timestamp, independent of the old one.
+      candidate = current_user.class.new
+      next unless candidate.confirm_totp_secret(pending['secret'], codes[:new_code].to_s)
+
+      current_user.update!(
+        otp_secret_key: candidate.otp_secret_key,
+        totp_timestamp: candidate.totp_timestamp,
+        direct_otp: nil,
+        direct_otp_sent_at: nil,
+        second_factor_attempts_count: 0
+      )
+      updated = true
+    end
+
+    if updated
+      session.delete(:pending_totp)
+      render json: { success: 'TOTP configuration saved.' }
+    else
+      render json: { error: 'Second-factor verification failed.' }, status: :unauthorized
+    end
+  end
+end
+```
+
+Connect these actions in `config/routes.rb`:
+
+```ruby
+post 'account/totp/setup', to: 'account#new_totp'
+patch 'account/totp', to: 'account#update_totp'
+```
+
+Show the provisioning URI as a QR code and ask for both codes before submitting
+the update. Users without TOTP receive a fresh direct code through your
+`send_two_factor_authentication_code` implementation. Apply the same existing
+factor check to other sensitive changes, and save the user after a successful
+TOTP check to persist its replay timestamp.
+
+
 ### Example App
 
 [TwoFactorAuthenticationExample](https://github.com/Houdini/TwoFactorAuthenticationExample)
+
+
+### Example user actions
+
+to use an ENV VAR for the 2FA encryption key:
+
+config.otp_secret_encryption_key = ENV['OTP_SECRET_ENCRYPTION_KEY']
+
+to set up TOTP for Google Authenticator for user:
+
+Use the `new_totp` and `update_totp` actions above to prepare the QR code and
+verify both the current factor and the new authenticator code. Keep the pending
+secret separate from `current_user.otp_secret_key` until both checks succeed.
+
+Encrypted database fields are persisted when the update action saves the user.
+Rails console access also requires `OTP_SECRET_ENCRYPTION_KEY` to be set.
+
+additional note:
+ 
+   ```
+   current_user.otp_secret_key
+   ```
+   
+This returns the OTP secret key in plaintext for the user (if you have set the env var) in the console
+the string used for generating the QR given to the user for their Google Auth is something like:
+
+otpauth://totp/LABEL?secret=p6wwetjnkjnrcmpd    (example secret used here)
+
+where LABEL should be something like "example.com (Username)", which shows up in their GA app to remind them the code is for example.com
+
+to set TOTP to DISABLED for a user account:
+
+After verifying the existing factor as described above:
+
+```ruby
+current_user.update!(
+  otp_secret_key: nil,
+  totp_timestamp: nil,
+  direct_otp: nil,
+  direct_otp_sent_at: nil,
+  second_factor_attempts_count: 0
+)
+current_user.direct_otp? # => false
+current_user.totp_enabled? # => false
+```
+
+This disables TOTP and leaves the attempt counter at an integer value. Direct
+OTP authentication remains required unless `need_two_factor_authentication?`
+returns `false`.

data/app/controllers/devise/two_factor_authentication_controller.rb

@@ -61,11 +61,12 @@ class Devise::TwoFactorAuthenticationController < DeviseController
     resource.save
     set_flash_message :alert, :attempt_failed, now: true
 
+    # 422 lets Turbo (the Rails 7+ default) render the response to a form submission
     if resource.max_login_attempts?
       sign_out(resource)
-      render :max_login_attempts_reached
+      render :max_login_attempts_reached, status: 422
     else
-      render :show
+      render :show, status: 422
     end
   end