[AZ-556] [AZ-557] Unify login errors + share MFA lockout pipeline

AZ-556 collapses every /login rejection (unknown email, wrong password,
disabled account, lockout, per-account rate limit) to a single opaque
InvalidCredentials (70) → 401 response. Timing equalised by a new
Security.VerifyDummy using the same Argon2id parameters. Audit log keeps
the rejection category internally (login_failed_unknown_email,
login_failed_disabled).

AZ-557 wires /login/mfa into the existing per-account lockout +
rate-limit pipeline. MFA failures now feed UserService's shared failure
accounting (RegisterMfaFailedLogin → RegisterFailedLoginCore) and
CountRecentFailedLogins aggregates both login_failed and
mfa_login_failed rows. Successful TOTP / recovery resets the counter.

Deprecated five legacy ExceptionEnum members (NoEmailFound,
WrongPassword, UserDisabled, AccountLocked, LoginRateLimited) — kept
defined for cross-workspace verifier compatibility during the
deprecation window.

E2E coverage updated: AuthTests (byte-identical body assertion +
disabled-account audit row), LoginRateLimitTests, PasswordHashingTests,
SecurityTests, plus four new MfaLoginTests (AC1, AC2, AC5, AC7).

Code review verdict: PASS_WITH_WARNINGS (batch_06_cycle2_review.md).

Co-authored-by: Cursor <cursoragent@cursor.com>

Azaion.Services/AuditLog.cs

@@ -11,6 +11,11 @@ public interface IAuditLog
     Task RecordLoginLockout(string email, CancellationToken ct = default);
     Task RecordLoginSuccess(string email, CancellationToken ct = default);
 
+    // AZ-556 — per-category internal forensics. Wire response is uniformly
+    // `InvalidCredentials`; these recorders keep SecOps's audit trail honest.
+    Task RecordLoginFailedUnknownEmail(string email, CancellationToken ct = default);
+    Task RecordLoginFailedDisabled    (string email, CancellationToken ct = default);
+
     // AZ-534 — MFA lifecycle + login auth-event audit.
     Task RecordMfaEnroll       (string email, CancellationToken ct = default);
     Task RecordMfaConfirm      (string email, CancellationToken ct = default);
@@ -20,8 +25,12 @@ public interface IAuditLog
     Task RecordMfaRecoveryUsed (string email, CancellationToken ct = default);
 
     /// <summary>
-    /// Number of `login_failed` rows for the given email within the last <paramref name="windowSeconds"/>.
-    /// Used by the per-account sliding-window rate limit (AZ-537 AC-2).
+    /// Count of failure-audit rows for the given email within the last
+    /// <paramref name="windowSeconds"/> that feed the per-account sliding-window rate
+    /// limit. Includes BOTH password (<c>login_failed</c>) and TOTP
+    /// (<c>mfa_login_failed</c>) failures (AZ-537 AC-2 + AZ-557 AC-3). Disabled-account
+    /// and unknown-email rejections are intentionally excluded — they don't reflect an
+    /// account-credential attack that the lockout/rate-limit policy should escalate.
     /// </summary>
     Task<int> CountRecentFailedLogins(string email, int windowSeconds, CancellationToken ct = default);
 }
@@ -37,6 +46,12 @@ public class AuditLog(IDbFactory dbFactory, IHttpContextAccessor httpContextAcce
     public Task RecordLoginSuccess(string email, CancellationToken ct = default)
         => Insert(AuditEventTypes.LoginSuccess, email, ct);
 
+    public Task RecordLoginFailedUnknownEmail(string email, CancellationToken ct = default)
+        => Insert(AuditEventTypes.LoginFailedUnknownEmail, email, ct);
+
+    public Task RecordLoginFailedDisabled(string email, CancellationToken ct = default)
+        => Insert(AuditEventTypes.LoginFailedDisabled, email, ct);
+
     public Task RecordMfaEnroll       (string email, CancellationToken ct = default)
         => Insert(AuditEventTypes.MfaEnroll,        email, ct);
     public Task RecordMfaConfirm      (string email, CancellationToken ct = default)
@@ -54,9 +69,13 @@ public class AuditLog(IDbFactory dbFactory, IHttpContextAccessor httpContextAcce
     {
         var cutoff = DateTime.UtcNow.AddSeconds(-windowSeconds);
         var normalised = email.ToLowerInvariant();
+        // AZ-557 — MFA failures feed the same per-account sliding-window count as
+        // password failures so an attacker who got past factor 1 can't brute-force
+        // factor 2 from rotating IPs without tripping the per-account throttle.
         return await dbFactory.Run(async db =>
             await db.AuditEvents
-                .Where(e => e.EventType == AuditEventTypes.LoginFailed
+                .Where(e => (e.EventType == AuditEventTypes.LoginFailed
+                             || e.EventType == AuditEventTypes.MfaLoginFailed)
                             && e.Email == normalised
                             && e.OccurredAt >= cutoff)
                 .CountAsync(token: ct));

Azaion.Services/MfaService.cs

@@ -55,6 +55,7 @@ public class MfaService(
     IDataProtectionProvider dataProtectionProvider,
     IJwtSigningKeyProvider signingKeys,
     IOptions<JwtConfig> jwtConfig,
+    IOptions<AuthConfig> authConfig,
     IAuditLog auditLog) : IMfaService
 {
     private const string MfaSecretPurpose = "Azaion.Mfa.Secret.v1";
@@ -66,6 +67,7 @@ public class MfaService(
 
     private readonly IDataProtector _protector = dataProtectionProvider.CreateProtector(MfaSecretPurpose);
     private readonly JwtConfig      _jwt       = jwtConfig.Value;
+    private readonly AuthConfig     _auth      = authConfig.Value;
 
     public async Task<MfaEnrollResponse> Enroll(Guid userId, string password, CancellationToken ct = default)
     {
@@ -247,11 +249,29 @@ public class MfaService(
     public async Task<string[]> VerifyForLogin(Guid userId, string code, CancellationToken ct = default)
     {
         var user = await userService.GetById(userId, ct)
-            ?? throw new BusinessException(ExceptionEnum.NoEmailFound);
+            ?? throw new BusinessException(ExceptionEnum.InvalidCredentials);
 
         if (!user.MfaEnabled || string.IsNullOrEmpty(user.MfaSecret))
             throw new BusinessException(ExceptionEnum.MfaNotEnabled);
 
+        // AZ-557 — active lockout from EITHER the password or the MFA side rejects
+        // the request before the TOTP verify runs, with the same wire shape the
+        // password path uses (`InvalidCredentials` + Retry-After).
+        if (user.LockoutUntil is { } until && until > DateTime.UtcNow)
+        {
+            var remaining = (int)Math.Ceiling((until - DateTime.UtcNow).TotalSeconds);
+            throw new BusinessException(ExceptionEnum.InvalidCredentials, Math.Max(remaining, 1));
+        }
+
+        // AZ-557 — per-account sliding-window rate limit applies to MFA failures too
+        // (CountRecentFailedLogins counts login_failed + mfa_login_failed). Without
+        // this an attacker with a leaked password could brute-force the 6-digit TOTP
+        // from rotating IPs without ever tripping the per-account throttle.
+        var recentFailures = await auditLog.CountRecentFailedLogins(
+            user.Email, _auth.RateLimit.PerAccountWindowSeconds, ct);
+        if (recentFailures >= _auth.RateLimit.PerAccountPermitLimit)
+            throw new BusinessException(ExceptionEnum.InvalidCredentials, _auth.RateLimit.PerAccountWindowSeconds);
+
         var secret = _protector.Unprotect(user.MfaSecret);
         if (VerifyTotpCode(secret, code, user.MfaLastUsedWindow, out var window))
         {
@@ -262,19 +282,39 @@ public class MfaService(
                     u => u.Id == userId,
                     u => new User { MfaLastUsedWindow = window },
                     token: ct));
+            // AZ-557 — TOTP success also resets the failure counter so a user who
+            // fat-fingered a few codes before getting it right doesn't drift toward
+            // lockout. Mirrors the password-side reset in RegisterSuccessfulLogin.
+            await dbFactory.RunAdmin(async db =>
+                await db.Users.UpdateAsync(
+                    u => u.Id == userId,
+                    u => new User { FailedLoginCount = 0, LockoutUntil = null },
+                    token: ct));
             await auditLog.RecordMfaLoginSuccess(user.Email, ct);
             return ["pwd", "mfa"];
         }
 
-        // TOTP failed — try recovery code (single-use)
+        // TOTP failed — try recovery code (single-use). Recovery codes are
+        // high-entropy and intentionally NOT counted by the lockout pipeline; a
+        // locked-out user can still escape via a recovery code.
         if (await TryConsumeRecoveryCode(user, code, ct))
         {
+            await dbFactory.RunAdmin(async db =>
+                await db.Users.UpdateAsync(
+                    u => u.Id == user.Id,
+                    u => new User { FailedLoginCount = 0, LockoutUntil = null },
+                    token: ct));
             await auditLog.RecordMfaRecoveryUsed(user.Email, ct);
             return ["pwd", "mfa", "recovery"];
         }
 
-        await auditLog.RecordMfaLoginFailed(user.Email, ct);
-        throw new BusinessException(ExceptionEnum.InvalidMfaCode);
+        // AZ-557 — feed the shared failure-accounting helper. It records the audit
+        // row (mfa_login_failed), bumps failed_login_count, and on threshold-crossing
+        // throws InvalidCredentials + Retry-After (which we let propagate). If it
+        // does NOT throw, we fall through and throw the bare InvalidCredentials so
+        // the wire response is uniform with the password path.
+        await userService.RegisterMfaFailedLogin(user, ct);
+        throw new BusinessException(ExceptionEnum.InvalidCredentials);
     }
 
     private static bool VerifyTotpCode(string secretBase32, string code, long? lastUsedWindow, out long matchedWindow)

Azaion.Services/Security.cs

@@ -23,6 +23,24 @@ public static class Security
 
     public sealed record VerifyResult(bool Valid, bool NeedsRehash);
 
+    // AZ-556 — timing equalizer for unknown-email and disabled-account branches of
+    // `UserService.ValidateUser`. Pre-computed once with the same Argon2id parameters
+    // as a real hash so a `VerifyDummy(plaintext)` call costs ~the same wall-clock as
+    // a real `VerifyPassword(plaintext, user.PasswordHash)`. The result is always
+    // discarded — this is a side-channel mitigation, not a control-flow path.
+    private static readonly string DummyHashForTiming = HashPassword(
+        "az-556-timing-equalizer-dummy-do-not-store-in-db");
+
+    /// <summary>
+    /// AZ-556 — run the same Argon2id work a real verify would do, then discard the
+    /// result. Used to keep the unknown-email and disabled-account login branches
+    /// timing-indistinguishable from a wrong-password branch.
+    /// </summary>
+    public static void VerifyDummy(string plaintext)
+    {
+        _ = VerifyPassword(plaintext, DummyHashForTiming);
+    }
+
     public static string HashPassword(string plaintext)
     {
         if (plaintext == null) throw new ArgumentNullException(nameof(plaintext));

Azaion.Services/UserService.cs

@@ -23,6 +23,18 @@ public interface IUserService
     Task ChangeRole(string email, RoleEnum newRole, CancellationToken ct = default);
     Task SetEnableStatus(string email, bool isEnabled, CancellationToken ct = default);
     Task RemoveUser(string email, CancellationToken ct = default);
+
+    /// <summary>
+    /// AZ-557 — shared failure-accounting path for MFA-side failures. Mirrors what the
+    /// password-side path in <see cref="ValidateUser"/> does on a wrong-password event:
+    /// records the appropriate audit row, increments <c>failed_login_count</c>,
+    /// crosses-the-threshold trips <c>lockout_until</c>, and signals lockout by throwing
+    /// <see cref="BusinessException"/> with <see cref="ExceptionEnum.InvalidCredentials"/>
+    /// + <see cref="BusinessException.RetryAfterSeconds"/>. Callers (e.g.,
+    /// <c>MfaService.VerifyForLogin</c>) MUST handle the throw branch and rethrow their
+    /// own opaque error if the threshold was not crossed.
+    /// </summary>
+    Task RegisterMfaFailedLogin(User user, CancellationToken ct = default);
 }
 
 public class UserService(
@@ -122,34 +134,57 @@ public class UserService(
         var user = await dbFactory.Run(async db =>
             await db.Users.FirstOrDefaultAsync(x => x.Email == request.Email, token: ct));
 
+        // AZ-556 — unknown email: equalize timing with a dummy Argon2id verify so a
+        // wall-clock observer can't distinguish "no such email" from "wrong password".
+        // No counter to increment (there is no row), so this path skips lockout
+        // accounting entirely; the audit row preserves the attempted email for SecOps.
         if (user == null)
-            throw new BusinessException(ExceptionEnum.NoEmailFound);
+        {
+            Security.VerifyDummy(request.Password);
+            await auditLog.RecordLoginFailedUnknownEmail(request.Email, ct);
+            throw new BusinessException(ExceptionEnum.InvalidCredentials);
+        }
 
         // AZ-537 AC-3 — active lockout takes precedence over the password check; even
-        // a correct password is rejected with 423 Locked until the lockout expires.
+        // a correct password is rejected until the lockout expires. AZ-556 collapses
+        // the response code to `InvalidCredentials` while keeping the Retry-After
+        // header so legitimate clients can self-throttle.
         if (user.LockoutUntil is { } until && until > DateTime.UtcNow)
         {
             var remaining = (int)Math.Ceiling((until - DateTime.UtcNow).TotalSeconds);
-            throw new BusinessException(ExceptionEnum.AccountLocked, Math.Max(remaining, 1));
+            throw new BusinessException(ExceptionEnum.InvalidCredentials, Math.Max(remaining, 1));
         }
 
-        // AZ-537 AC-2 — per-account sliding-window rate limit. Counts only failed
-        // logins in the recent window so legitimate retries after success aren't punished.
+        // AZ-537 AC-2 — per-account sliding-window rate limit. Counts only failure
+        // events in the recent window (login_failed + mfa_login_failed per AZ-557) so
+        // legitimate retries after a success aren't punished.
         var recentFailures = await auditLog.CountRecentFailedLogins(
             user.Email, _auth.RateLimit.PerAccountWindowSeconds, ct);
         if (recentFailures >= _auth.RateLimit.PerAccountPermitLimit)
-            throw new BusinessException(ExceptionEnum.LoginRateLimited, _auth.RateLimit.PerAccountWindowSeconds);
+            throw new BusinessException(ExceptionEnum.InvalidCredentials, _auth.RateLimit.PerAccountWindowSeconds);
+
+        // AZ-556 F-AUTH-3 — disabled-account check moved BEFORE password verify. An
+        // attacker who knows the password of a disabled account no longer learns that
+        // fact via a distinct error code (or via the missing-Argon2id timing tell).
+        // Still run the dummy verify so the wall-clock equalises against a real
+        // wrong-password branch.
+        if (!user.IsEnabled)
+        {
+            Security.VerifyDummy(request.Password);
+            await auditLog.RecordLoginFailedDisabled(user.Email, ct);
+            throw new BusinessException(ExceptionEnum.InvalidCredentials);
+        }
 
         var verify = Security.VerifyPassword(request.Password, user.PasswordHash);
         if (!verify.Valid)
         {
+            // RegisterFailedLogin may itself throw InvalidCredentials + Retry-After
+            // when the threshold trips; otherwise we fall through and throw the
+            // non-Retry-After variant below.
             await RegisterFailedLogin(user, ct);
-            throw new BusinessException(ExceptionEnum.WrongPassword);
+            throw new BusinessException(ExceptionEnum.InvalidCredentials);
         }
 
-        if (!user.IsEnabled)
-            throw new BusinessException(ExceptionEnum.UserDisabled);
-
         await RegisterSuccessfulLogin(user, request.Password, verify.NeedsRehash, ct);
         return user;
     }
@@ -198,11 +233,26 @@ public class UserService(
         await auditLog.RecordLoginSuccess(user.Email, ct);
     }
 
-    private async Task RegisterFailedLogin(User user, CancellationToken ct)
-    {
-        await auditLog.RecordLoginFailed(user.Email, ct);
+    private Task RegisterFailedLogin(User user, CancellationToken ct) =>
+        RegisterFailedLoginCore(user, FailureKind.Password, ct);
 
-        var newCount    = user.FailedLoginCount + 1;
+    public Task RegisterMfaFailedLogin(User user, CancellationToken ct = default) =>
+        RegisterFailedLoginCore(user, FailureKind.Mfa, ct);
+
+    // AZ-557 — single accounting path shared by the password-side (`ValidateUser`) and
+    // the MFA-side (`MfaService.VerifyForLogin`) failure branches. The audit row type
+    // diverges (`login_failed` vs `mfa_login_failed`) so SecOps can analyse the two
+    // categories separately, but the counter / lockout / Retry-After semantics are
+    // identical. On lockout-trip we throw `InvalidCredentials` + Retry-After so the
+    // caller can rethrow its opaque wire response without losing the cooldown hint.
+    private async Task RegisterFailedLoginCore(User user, FailureKind kind, CancellationToken ct)
+    {
+        if (kind == FailureKind.Password)
+            await auditLog.RecordLoginFailed(user.Email, ct);
+        else
+            await auditLog.RecordMfaLoginFailed(user.Email, ct);
+
+        var newCount     = user.FailedLoginCount + 1;
         var triggersLock = newCount >= _auth.Lockout.MaxAttempts;
         DateTime? newLockoutUntil = triggersLock
             ? DateTime.UtcNow.AddSeconds(_auth.Lockout.DurationSeconds)
@@ -223,12 +273,19 @@ public class UserService(
         if (triggersLock)
         {
             await auditLog.RecordLoginLockout(user.Email, ct);
-            // Promote a wrong-password into a lockout response so the caller learns the
-            // account is locked the moment the threshold is crossed.
-            throw new BusinessException(ExceptionEnum.AccountLocked, _auth.Lockout.DurationSeconds);
+            // AZ-556 — promote a threshold-crossing failure into the unified lockout
+            // response. The caller sees `InvalidCredentials` + Retry-After regardless
+            // of whether the threshold was crossed by a password or an MFA attempt.
+            throw new BusinessException(ExceptionEnum.InvalidCredentials, _auth.Lockout.DurationSeconds);
         }
     }
 
+    private enum FailureKind
+    {
+        Password,
+        Mfa,
+    }
+
     public async Task UpdateQueueOffsets(string email, UserQueueOffsets queueOffsets, CancellationToken ct = default)
     {
         await dbFactory.RunAdmin(async db =>