fix(auth): make the second factor obey the operator's lockout policy (#3690)

`twoFactor()` was constructed with a schema and nothing else, so better-auth's
built-in `accountLockout` defaults (on, 10 attempts, 15 minutes) governed
two-factor verification regardless of what the admin configured. An operator who
tightened the account lockout threshold to 3 got a password stage that locked at
3 and a second factor that still locked at 10 — the stricter door was the looser
one, and nothing in the UI said so.

Project `lockoutThreshold` / `lockoutDurationMinutes` onto better-auth's own
`accountLockout` shape rather than adding a parallel `two_factor_lockout_*` pair:
one policy, one mental model, and an upstream addition arrives as a new option
instead of a conflict. The projection runs through `applyConfigPatch`, which
resets the cached instance, so a settings change lands without a restart.

Threshold `0` is deliberately not forwarded as `enabled: false`. It is the
password stage's "off", and a deployment may leave that stage unlocked because
rate limiting or an IdP covers it; the second factor is the last check before a
session is issued, so it keeps better-auth's default instead of being switched
off by a setting that never mentioned it. The threshold field also stops hiding
behind `email_password_enabled` — two-factor verification exists in passwordless
deployments, where it was previously unreachable.

The dogfood test now runs under an explicit policy (7 attempts / 40 minutes),
chosen to differ from every default, and derives its assertions from it — pinned
to better-auth's defaults it could not tell "configured to 10" from
"configuration ignored". Verified by removing the wiring: the lock never engages
and both budget tests fail.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UYLC8TfjzHGwatNxZKdX7H

Author: claude

.changeset/two-factor-lockout-follows-settings.md

@@ -0,0 +1,35 @@
+---
+"@objectstack/plugin-auth": patch
+"@objectstack/service-settings": patch
+---
+
+fix(auth): the second factor now obeys the operator's lockout policy instead of better-auth's defaults (#3690)
+
+`auth-manager.ts` constructed `twoFactor()` with a schema and nothing else, so
+better-auth's built-in `accountLockout` defaults — on, 10 attempts, 15 minutes —
+governed two-factor verification no matter what the admin configured. An operator
+who tightened **Setup → Authentication → Account lockout threshold** to 3 got a
+password stage that locked at 3 and a second factor that still locked at 10: the
+stricter door was the looser one, with nothing in the UI saying so.
+
+`lockout_threshold` / `lockout_duration_minutes` are now projected onto
+better-auth's own `accountLockout` shape (`enabled` / `maxFailedAttempts` /
+`durationSeconds`, minutes converted to seconds) rather than growing a parallel
+`two_factor_lockout_*` pair — one policy, one mental model, and a future upstream
+field arrives as a new option instead of a conflict. The projection goes through
+`applyConfigPatch`, which resets the cached better-auth instance, so a settings
+change takes effect without a restart.
+
+Threshold `0` is deliberately **not** forwarded as `enabled: false`. It is the
+password stage's "off", and a deployment may leave that stage unlocked because
+rate limiting or an IdP covers it; the second factor is the last check before a
+session is issued, so it keeps better-auth's default rather than being switched
+off by a setting that never mentioned it.
+
+The threshold field is also no longer hidden behind `email_password_enabled` —
+two-factor verification exists in passwordless deployments, where the setting was
+previously unreachable.
+
+Note the plugin caps attempts at 5 per challenge (`beginAttempt(5)`), which no
+option reaches; a threshold above 5 forces a fresh challenge rather than raising
+that cap.

content/docs/permissions/authentication.mdx

@@ -455,10 +455,22 @@ code that reads it). Changes take effect immediately; no restart is required.
 
 | Setting | Effect |
 |---|---|
-| `lockout_threshold` | Lock an account after this many consecutive failed sign-ins. |
-| `lockout_duration_minutes` | How long a lockout lasts. Admins can clear it early with the **Unlock** action on the user record. |
+| `lockout_threshold` | Lock an account after this many consecutive failed sign-in attempts. Counts **both** stages: wrong passwords and wrong two-factor codes. |
+| `lockout_duration_minutes` | How long a lockout lasts, at either stage. Admins can clear a password-stage lockout early with the **Unlock** action on the user record. |
 | `rate_limit_max` / `rate_limit_window_seconds` | Per-IP request throttle on auth endpoints. |
 
+The two stages keep **separate counters** — `sys_user.failed_login_count` for the
+password check, `sys_two_factor.failed_verification_count` for the second factor —
+so a locked password stage and a locked second factor are independent states. Each
+counter resets on a success at its own stage.
+
+Setting `lockout_threshold` to `0` disables the **password-stage** lockout only.
+Two-factor verification keeps a built-in limit of 10 attempts per 15 minutes,
+because it is the last check before a session is issued. Two-factor verification
+additionally caps attempts at 5 per challenge, which is not configurable: a
+threshold above 5 simply forces the attacker to restart the sign-in flow more
+often before the account-level lock engages.
+
 ### Multi-factor (enforced MFA)
 
 | Setting | Effect |

packages/plugins/plugin-auth/src/auth-manager.test.ts

@@ -885,6 +885,62 @@ describe('AuthManager', () => {
       expect(tfPlugin._opts.schema.user.fields.twoFactorEnabled).toBe('two_factor_enabled');
     });
 
+    // #3690 — the operator's lockout policy has to reach the SECOND factor too.
+    // Before this, `twoFactor()` got only a schema, so the second factor sat on
+    // better-auth's built-in 10/900s no matter how the admin tuned sign-in:
+    // tightening the threshold to 3 left the last door before a session at 10.
+    describe('two-factor account lockout follows the operator settings (#3690)', () => {
+      const buildTwoFactor = async (extra: Record<string, unknown>) => {
+        let capturedConfig: any;
+        (betterAuth as any).mockImplementation((config: any) => {
+          capturedConfig = config;
+          return { handler: vi.fn(), api: {} };
+        });
+        const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const manager = new AuthManager({
+          secret: 'test-secret-at-least-32-chars-long',
+          baseUrl: 'http://localhost:3000',
+          plugins: { twoFactor: true },
+          ...extra,
+        });
+        await manager.getAuthInstance();
+        warnSpy.mockRestore();
+        return capturedConfig.plugins.find((p: any) => p.id === 'two-factor')._opts.accountLockout;
+      };
+
+      it('projects lockoutThreshold / lockoutDurationMinutes onto better-auth\'s contract', async () => {
+        // Minutes → seconds is the whole reason this needs a test: the two
+        // sides use different units for the same policy.
+        expect(await buildTwoFactor({ lockoutThreshold: 3, lockoutDurationMinutes: 30 })).toEqual({
+          enabled: true,
+          maxFailedAttempts: 3,
+          durationSeconds: 1800,
+        });
+      });
+
+      it('falls back to the password stage\'s 15-minute default when only a threshold is set', async () => {
+        expect(await buildTwoFactor({ lockoutThreshold: 5 })).toEqual({
+          enabled: true,
+          maxFailedAttempts: 5,
+          durationSeconds: 900,
+        });
+      });
+
+      // Threshold 0 is the password stage's "off". It is NOT forwarded as
+      // `enabled: false`: a deployment may leave the password stage unlocked
+      // because rate limiting or an IdP covers it, while the second factor —
+      // the last check before a session — keeps better-auth's default. Leaving
+      // the option unset is what hands that default back.
+      for (const [label, extra] of [
+        ['threshold 0 (lockout explicitly off)', { lockoutThreshold: 0 }],
+        ['no lockout settings at all', {}],
+      ] as Array<[string, Record<string, unknown>]>) {
+        it(`leaves better-auth's own default in place with ${label}`, async () => {
+          expect(await buildTwoFactor(extra)).toBeUndefined();
+        });
+      }
+    });
+
     it('should register magicLink plugin when enabled', async () => {
       let capturedConfig: any;
       (betterAuth as any).mockImplementation((config: any) => {

packages/plugins/plugin-auth/src/auth-manager.ts

@@ -1855,6 +1855,9 @@ export class AuthManager {
       const { twoFactor } = await import('better-auth/plugins/two-factor');
       plugins.push(twoFactor({
         schema: buildTwoFactorPluginSchema(),
+        // ADR-0069 D2 (#3690) — the operator's lockout policy governs BOTH
+        // stages of sign-in, not just the password one.
+        accountLockout: this.resolveTwoFactorAccountLockout(),
       }));
     }
 
@@ -3893,6 +3896,46 @@ export class AuthManager {
     }
   }
 
+  /**
+   * ADR-0069 D2 (#3690) — project the operator's lockout settings onto
+   * better-auth's own `twoFactor({ accountLockout })` contract, so the second
+   * factor obeys the same policy as the password stage above.
+   *
+   * Deliberately reuses `lockoutThreshold` / `lockoutDurationMinutes` rather
+   * than introducing a parallel `two_factor_lockout_*` pair: an admin who
+   * tightens sign-in to 3 attempts reasonably reads that as "the login flow is
+   * tightened", and before this the second factor silently stayed at
+   * better-auth's 10 — the stricter door was the looser one, with nothing in
+   * the UI saying so. Following better-auth's own field shape (rather than
+   * inventing ObjectStack settings on top of it) also means a future upstream
+   * addition here shows up as a new option, not a conflict.
+   *
+   * `undefined` when the threshold is 0/absent — better-auth's defaults (on,
+   * 10 attempts, 15 minutes) then stand. That is NOT mapped to
+   * `enabled: false`: `0` is the password stage's "off", and a deployment may
+   * leave THAT stage unlocked because other controls cover it (per-IP rate
+   * limiting, a captcha, an IdP in front). The second factor is the last door
+   * before a session is issued, so it is not turned off by a setting that
+   * never mentioned it. Both stages remain explicitly configurable; only the
+   * "unset" case differs, and it differs toward locking.
+   *
+   * Note the plugin ALSO caps attempts per challenge at a hardcoded 5
+   * (`beginAttempt(5)` in its totp / backup-code verifiers), which no option
+   * reaches. A threshold above 5 therefore still forces a fresh challenge
+   * every 5 guesses; the account budget is what accumulates across them.
+   */
+  private resolveTwoFactorAccountLockout():
+  { enabled: boolean; maxFailedAttempts: number; durationSeconds: number } | undefined {
+    const threshold = Number(this.config.lockoutThreshold) || 0;
+    if (threshold <= 0) return undefined;
+    const minutes = Number(this.config.lockoutDurationMinutes) || 15;
+    return {
+      enabled: true,
+      maxFailedAttempts: threshold,
+      durationSeconds: minutes * 60,
+    };
+  }
+
   /**
    * ADR-0069 D7 — stamp `last_login_at` (+ `last_login_ip` when known) on a
    * successful sign-in. Best-effort and always fire-and-forget safe: a login

packages/qa/dogfood/test/two-factor-lockout.dogfood.test.ts

@@ -28,6 +28,19 @@
  * would therefore pass while the lockout path stayed completely unexercised —
  * exactly the blind spot that let the missing columns through. Hence the
  * cookie plumbing below: it is what makes this test test anything.
+ *
+ * ## Why it runs under an explicit operator policy (#3690)
+ *
+ * The budget used to be better-auth's own default (10 failures / 15 minutes),
+ * asserted as a literal here. That made this file blind to #3690: the auth
+ * manager passed no `accountLockout` at all, so the second factor ignored the
+ * operator's `lockout_threshold` entirely — and a test pinned to the default
+ * value could not tell "configured to 10" from "configuration ignored".
+ *
+ * So the stack is patched to a policy that is DIFFERENT from every default
+ * below, and every assertion derives from it. If the wiring is ever dropped,
+ * the counts and the lock duration snap back to better-auth's defaults and
+ * these assertions fail — which is the point.
  */
 
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
@@ -38,6 +51,19 @@ import { bootStack, type VerifyStack } from '@objectstack/verify';
 const SYS = { context: { isSystem: true } };
 const ADMIN_PASSWORD = 'admin123';
 
+// [#3690] The operator policy this file runs under. Both values are chosen to
+// differ from better-auth's defaults (10 attempts / 15 minutes) so an assertion
+// cannot pass by accident if the settings stop reaching the plugin.
+//
+// 7 is also deliberately ABOVE the plugin's hardcoded per-challenge cap of 5
+// (`beginAttempt(5)`, not reachable by any option), so spending the budget
+// still has to cross a challenge boundary — the account-level counter is the
+// one backed by the columns under test.
+const LOCKOUT_THRESHOLD = 7;
+const LOCKOUT_DURATION_MINUTES = 40;
+/** better-auth's per-two-factor-cookie cap. Hardcoded upstream, not configurable. */
+const MAX_PER_CHALLENGE = 5;
+
 // ── RFC 6238 TOTP ──────────────────────────────────────────────────────────
 // Hand-rolled rather than imported: `@better-auth/utils/otp` is a transitive
 // dependency, and adding it as a direct one to generate six digits would tie
@@ -100,6 +126,17 @@ describe('#3624 follow-up: better-auth 2FA lockout counts wrong codes', () => {
     stack = await bootStack(showcaseStack, {});
     ql = await stack.kernel.getServiceAsync<any>('objectql');
 
+    // [#3690] Apply the operator policy the same way the settings service does
+    // — `applyConfigPatch` nulls the cached better-auth instance, so the next
+    // request rebuilds with the new `accountLockout`. Going through this seam
+    // (rather than constructing the manager by hand) is what proves a Setup-UI
+    // change actually reaches the second factor.
+    const auth = await stack.kernel.getServiceAsync<any>('auth');
+    auth.applyConfigPatch({
+      lockoutThreshold: LOCKOUT_THRESHOLD,
+      lockoutDurationMinutes: LOCKOUT_DURATION_MINUTES,
+    });
+
     const token = await stack.signIn();
     const me = await (await stack.apiAs(token, 'GET', '/auth/get-session')).json() as any;
     adminEmail = me?.user?.email;
@@ -214,16 +251,18 @@ describe('#3624 follow-up: better-auth 2FA lockout counts wrong codes', () => {
     expect(after.lockedUntil ?? null).toBeNull();
   });
 
-  it('locks the account once the budget is spent, and refuses even a correct code', async () => {
+  it('locks the account once the operator-configured budget is spent, and refuses even a correct code', async () => {
     // Two budgets stack here, and the test has to respect both. better-auth
     // allows MAX_PER_CHALLENGE verifications per two-factor cookie
-    // (`beginAttempt(5)`) and MAX_FAILURES consecutive failures per ACCOUNT
-    // (`accountLockout.maxFailedAttempts`, default 10). Only the second one
-    // touches the columns under test, so reaching it takes a fresh challenge
-    // every MAX_PER_CHALLENGE tries. Both are better-auth's defaults — the
-    // auth manager passes no `accountLockout` config.
-    const MAX_PER_CHALLENGE = 5;
-    const MAX_FAILURES = 10;
+    // (hardcoded), and MAX_FAILURES consecutive failures per ACCOUNT
+    // (`accountLockout.maxFailedAttempts`). Only the second one touches the
+    // columns under test, so reaching it takes a fresh challenge every
+    // MAX_PER_CHALLENGE tries.
+    //
+    // MAX_FAILURES is the operator's threshold, not better-auth's default —
+    // #3690. Were the config dropped, the account would still be unlocked at
+    // failure 7 and the assertion below would fail on a null `locked_until`.
+    const MAX_FAILURES = LOCKOUT_THRESHOLD;
 
     expect((await lockoutState()).count, 'precondition: a clean budget').toBe(0);
 
@@ -246,7 +285,15 @@ describe('#3624 follow-up: better-auth 2FA lockout counts wrong codes', () => {
       locked.lockedUntil ?? null,
       `budget spent (${MAX_FAILURES} failures) but locked_until was never stamped`,
     ).not.toBeNull();
-    expect(new Date(String(locked.lockedUntil)).getTime()).toBeGreaterThan(Date.now());
+
+    // The lock lasts the operator's duration, not better-auth's 15 minutes.
+    // `lockoutDurationMinutes` (minutes) is projected onto the plugin's
+    // `durationSeconds` — the units differ on the two sides, so this is where a
+    // ×60 that went missing would show up. The window is wide enough for the
+    // several seconds of guessing above, and far too narrow to admit 15.
+    const lockedForMs = new Date(String(locked.lockedUntil)).getTime() - Date.now();
+    expect(lockedForMs).toBeGreaterThan((LOCKOUT_DURATION_MINUTES - 5) * 60_000);
+    expect(lockedForMs).toBeLessThanOrEqual(LOCKOUT_DURATION_MINUTES * 60_000);
 
     // The lock has to bite BEFORE the code is checked — otherwise it is not a
     // lockout, just a slower guess loop.
@@ -262,9 +309,9 @@ describe('#3624 follow-up: better-auth 2FA lockout counts wrong codes', () => {
     const before = await lockoutState();
     expect(before.lockedUntil ?? null, 'precondition: carries the lock from the previous test').not.toBeNull();
 
-    // Expire the lock rather than waiting out `durationSeconds` (900 by
-    // default). This is the one place the test reaches past the API: there is
-    // no endpoint that ages a lock.
+    // Expire the lock rather than waiting out `durationSeconds`. This is the
+    // one place the test reaches past the API: there is no endpoint that ages
+    // a lock.
     const users = await ql.find('sys_user', { where: { email: adminEmail }, limit: 1 }, SYS);
     const rows = await ql.find('sys_two_factor', { where: { user_id: String(users[0]?.id) }, limit: 1 }, SYS);
     await ql.update(

packages/services/service-settings/src/manifests/auth.manifest.test.ts

@@ -70,6 +70,24 @@ describe('authSettingsManifest', () => {
     expect(byKey('mfa_grace_period_days').default).toBe(7);
   });
 
+  // #3690 — the same pair now drives the second factor's lockout, not just the
+  // password stage's. Two-factor verification exists without email/password
+  // sign-in, so gating the threshold on `email_password_enabled` would leave a
+  // passwordless deployment unable to tune it at all.
+  it('keeps the lockout pair reachable in passwordless deployments (#3690)', () => {
+    const specs = authSettingsManifest.specifiers as any[];
+    const byKey = (k: string) => specs.find((s) => s.key === k);
+
+    expect(byKey('lockout_threshold').visible).toBeUndefined();
+    // The duration is still meaningless with no threshold, so that condition
+    // stays — but it must no longer depend on the password provider.
+    expect(byKey('lockout_duration_minutes').visible).toBe('${data.lockout_threshold > 0}');
+
+    // The help text is the only place an admin learns the threshold covers
+    // both stages; the wiring is invisible otherwise.
+    expect(byKey('lockout_threshold').description).toMatch(/two-factor/i);
+  });
+
   it('exposes encrypted Google OAuth credential fields', () => {
     const keys = (authSettingsManifest.specifiers as any[])
       .map((s) => s.key)

packages/services/service-settings/src/manifests/auth.manifest.ts

@@ -137,6 +137,10 @@ const manifest = {
       description:
         'Brute-force protection: per-identity account lockout and per-IP rate limiting on auth endpoints.',
     },
+    // [#3690] The threshold/duration pair governs BOTH sign-in stages — the
+    // password check and the second factor. Always visible: two-factor
+    // verification exists in passwordless deployments too, so gating these on
+    // `email_password_enabled` would leave the 2FA lockout untunable there.
     {
       type: 'number',
       key: 'lockout_threshold',
@@ -146,8 +150,7 @@ const manifest = {
       min: 0,
       max: 20,
       description:
-        'Lock an account after this many consecutive failed sign-ins. 0 disables lockout. While locked, sign-in is rejected even with the correct password.',
-      visible: "${data.email_password_enabled !== false}",
+        'Lock an account after this many consecutive failed sign-in attempts — wrong passwords and wrong two-factor codes alike. While locked, sign-in is rejected even with the correct credentials. 0 disables the password-stage lockout; two-factor verification then keeps its built-in limit of 10 attempts per 15 minutes, since it is the last check before a session is issued.',
     },
     {
       type: 'number',
@@ -157,8 +160,8 @@ const manifest = {
       default: 15,
       min: 1,
       max: 1440,
-      description: 'How long an account stays locked once the threshold is crossed.',
-      visible: "${data.email_password_enabled !== false && data.lockout_threshold > 0}",
+      description: 'How long an account stays locked once the threshold is crossed, at either sign-in stage.',
+      visible: '${data.lockout_threshold > 0}',
     },
     {
       type: 'number',