+ <% if current_identity.two_factor_enrollment_required? %>
+
+ <%= t ".enrollment_required_heading" %>
+ <%= t ".enrollment_required_description" %>
+
+ <% end %>
+
<%= t ".sessions" %>
<%= render Components::BootlegTurbo.new(identity_sessions_path, id: "sessions-container", hx_swap: "innerHTML") %>
diff --git a/config/locales/en.yml b/config/locales/en.yml
index 188d18f4..bb4e6c87 100644
--- a/config/locales/en.yml
+++ b/config/locales/en.yml
@@ -479,6 +479,8 @@ en:
security_link: Security
security:
heading: Security
+ enrollment_required_heading: Two-factor authentication required
+ enrollment_required_description: Your account requires two-factor authentication. Set up an authenticator app or passkey below to continue using Hack Club Auth.
sessions: Active Sessions
mfa: Authenticator App
webauthn: Passkeys
@@ -514,6 +516,7 @@ en:
require_2fa_description: When enabled, you must use a second factor (authenticator app or backup code) when signing in with an email code.
disable_requirement: Disable Requirement
enable_requirement: Enable Requirement
+ required_by_hq: Required by Hack Club HQ — this can't be disabled.
setup_description: Add an extra layer of security to email sign-ins by requiring a code from an authenticator app.
setup_authenticator: Set up two-factor authentication
show:
diff --git a/db/migrate/20260703000002_add_two_factor_required_to_identities.rb b/db/migrate/20260703000002_add_two_factor_required_to_identities.rb
new file mode 100644
index 00000000..c8e4f741
--- /dev/null
+++ b/db/migrate/20260703000002_add_two_factor_required_to_identities.rb
@@ -0,0 +1,5 @@
+class AddTwoFactorRequiredToIdentities < ActiveRecord::Migration[8.0]
+ def change
+ add_column :identities, :two_factor_required, :boolean, default: false, null: false
+ end
+end
diff --git a/db/schema.rb b/db/schema.rb
index 45336f93..e714716d 100644
--- a/db/schema.rb
+++ b/db/schema.rb
@@ -10,7 +10,7 @@
#
# It's strongly recommended that you check this file into your version control system.
-ActiveRecord::Schema[8.0].define(version: 2026_06_22_000001) do
+ActiveRecord::Schema[8.0].define(version: 2026_07_03_000002) do
# These are extensions that must be enabled in order to support this database
enable_extension "pg_catalog.plpgsql"
enable_extension "pg_trgm"
@@ -318,6 +318,7 @@
t.boolean "can_hq_officialize", default: false, null: false
t.string "persona_account_id"
t.boolean "disallow_slack", default: false, null: false
+ t.boolean "two_factor_required", default: false, null: false
t.index "lower((primary_email)::text)", name: "idx_identities_unique_primary_email", unique: true, where: "(deleted_at IS NULL)"
t.index ["aadhaar_number_bidx"], name: "index_identities_on_aadhaar_number_bidx", unique: true
t.index ["deleted_at"], name: "index_identities_on_deleted_at"
diff --git a/spec/models/identity_spec.rb b/spec/models/identity_spec.rb
index 8c809683..c67ec400 100644
--- a/spec/models/identity_spec.rb
+++ b/spec/models/identity_spec.rb
@@ -88,4 +88,49 @@
expect(other).not_to be_valid
end
end
+
+ describe "#requires_two_factor?" do
+ it "is false by default" do
+ expect(identity.requires_two_factor?).to be false
+ end
+
+ it "is true when the user enabled 2FA and has a method" do
+ identity.update!(use_two_factor_authentication: true)
+ identity.totps.create!.mark_verified!
+
+ expect(identity.requires_two_factor?).to be true
+ end
+
+ it "is true when the admin override is set and a method exists, even without the user flag" do
+ identity.update!(two_factor_required: true)
+ identity.totps.create!.mark_verified!
+
+ expect(identity.requires_two_factor?).to be true
+ end
+
+ it "is false when the admin override is set but no method exists" do
+ identity.update!(two_factor_required: true)
+
+ expect(identity.requires_two_factor?).to be false
+ end
+ end
+
+ describe "#two_factor_enrollment_required?" do
+ it "is true when the override is set and no method is enrolled" do
+ identity.update!(two_factor_required: true)
+
+ expect(identity.two_factor_enrollment_required?).to be true
+ end
+
+ it "is false once a method is enrolled" do
+ identity.update!(two_factor_required: true)
+ identity.totps.create!.mark_verified!
+
+ expect(identity.two_factor_enrollment_required?).to be false
+ end
+
+ it "is false without the override" do
+ expect(identity.two_factor_enrollment_required?).to be false
+ end
+ end
end
diff --git a/spec/requests/two_factor_enrollment_gate_spec.rb b/spec/requests/two_factor_enrollment_gate_spec.rb
new file mode 100644
index 00000000..438e6ab3
--- /dev/null
+++ b/spec/requests/two_factor_enrollment_gate_spec.rb
@@ -0,0 +1,92 @@
+require "rails_helper"
+
+RSpec.describe "Two-factor enrollment gate", type: :request do
+ let(:identity) { create(:identity, two_factor_required: true) }
+ let(:session) do
+ identity.sessions.create!(
+ session_token: SecureRandom.hex(32),
+ expires_at: 1.week.from_now
+ )
+ end
+
+ before do
+ allow_any_instance_of(ApplicationController).to receive(:current_identity).and_return(identity)
+ allow_any_instance_of(ApplicationController).to receive(:current_session).and_return(session)
+ allow_any_instance_of(ApplicationController).to receive(:identity_signed_in?).and_return(true)
+ end
+
+ context "when the identity has no 2FA method enrolled" do
+ it "redirects the home page to the security page" do
+ get "/"
+
+ expect(response).to redirect_to(security_path)
+ expect(flash[:error]).to include("requires two-factor authentication")
+ end
+
+ it "blocks OAuth authorization" do
+ get "/oauth/authorize"
+
+ expect(response).to redirect_to(security_path)
+ end
+
+ it "responds to HTMX requests with an HX-Redirect header" do
+ get "/", headers: { "HX-Request" => "true" }
+
+ expect(response).to have_http_status(:ok)
+ expect(response.headers["HX-Redirect"]).to eq(security_path)
+ end
+
+ it "allows the security page" do
+ get "/security"
+
+ expect(response).to have_http_status(:ok)
+ end
+
+ it "allows TOTP enrollment" do
+ get "/identity_totps"
+
+ expect(response).to have_http_status(:ok)
+ end
+
+ it "allows the authorized applications panel on the security page" do
+ get "/authorized_applications", headers: { "HX-Request" => "true" }
+
+ expect(response).to have_http_status(:ok)
+ expect(response.headers["HX-Redirect"]).to be_nil
+ end
+
+ it "allows passkey enrollment" do
+ get "/passkeys"
+
+ expect(response).to have_http_status(:ok)
+ end
+
+ it "allows logging out" do
+ delete "/logout"
+
+ expect(response).to redirect_to(welcome_path)
+ end
+ end
+
+ context "when the identity has a verified TOTP" do
+ before do
+ identity.totps.create!.mark_verified!
+ end
+
+ it "does not redirect" do
+ get "/"
+
+ expect(response).to have_http_status(:ok)
+ end
+ end
+
+ context "when the identity does not have the override" do
+ let(:identity) { create(:identity) }
+
+ it "does not redirect" do
+ get "/"
+
+ expect(response).to have_http_status(:ok)
+ end
+ end
+end
diff --git a/spec/requests/two_factor_required_disable_spec.rb b/spec/requests/two_factor_required_disable_spec.rb
new file mode 100644
index 00000000..c4469cb6
--- /dev/null
+++ b/spec/requests/two_factor_required_disable_spec.rb
@@ -0,0 +1,71 @@
+require "rails_helper"
+
+RSpec.describe "Disabling 2FA when required by admin", type: :request do
+ let(:identity) { create(:identity, two_factor_required: true, use_two_factor_authentication: true) }
+ let(:session) do
+ identity.sessions.create!(
+ session_token: SecureRandom.hex(32),
+ expires_at: 1.week.from_now
+ )
+ end
+ let!(:totp) do
+ t = identity.totps.create!
+ t.mark_verified!
+ t
+ end
+
+ before do
+ allow_any_instance_of(ApplicationController).to receive(:current_identity).and_return(identity)
+ allow_any_instance_of(ApplicationController).to receive(:current_session).and_return(session)
+ allow_any_instance_of(ApplicationController).to receive(:identity_signed_in?).and_return(true)
+ end
+
+ describe "POST /identity/toggle_2fa" do
+ it "refuses to start the disable flow" do
+ post toggle_2fa_identity_path
+
+ expect(response).to redirect_to(security_path)
+ expect(flash[:error]).to include("can't be disabled")
+ expect(identity.reload.use_two_factor_authentication).to be true
+ end
+ end
+
+ describe "step-up disable_2fa completion" do
+ it "refuses to disable the 2FA requirement" do
+ code = ROTP::TOTP.new(totp.secret).now
+
+ post "/step_up/verify", params: { action_type: "disable_2fa", method: "totp", code: code }
+
+ expect(response).to redirect_to(security_path)
+ expect(flash[:alert]).to include("can't be disabled")
+ expect(identity.reload.use_two_factor_authentication).to be true
+ end
+ end
+
+ describe "step-up remove_totp completion" do
+ it "refuses to remove the last 2FA method" do
+ code = ROTP::TOTP.new(totp.secret).now
+
+ post "/step_up/verify", params: { action_type: "remove_totp", method: "totp", code: code }
+
+ expect(response).to redirect_to(security_path)
+ expect(flash[:alert]).to include("Add another method")
+ expect(identity.reload.totp).to be_present
+ end
+
+ it "allows removing the TOTP when a passkey remains" do
+ identity.webauthn_credentials.create!(
+ external_id: SecureRandom.hex(16),
+ public_key: SecureRandom.hex(32),
+ nickname: "test key",
+ sign_count: 0
+ )
+ code = ROTP::TOTP.new(totp.secret).now
+
+ post "/step_up/verify", params: { action_type: "remove_totp", method: "totp", code: code }
+
+ expect(response).to redirect_to(security_path)
+ expect(identity.reload.totp).to be_nil
+ end
+ end
+end