[AZ-534] TOTP-based 2FA at credential login

Add RFC 6238 TOTP enrollment, two-step /login flow, recovery codes, and
the amr=["pwd","mfa"] claim that propagates through refresh-token rotation.

- New endpoints: /users/me/mfa/{enroll,confirm,disable} and /login/mfa.
- /login short-circuits to a 5-min ES256 step-1 token (audience-pinned
  azaion-mfa-step2) when the user has MFA enabled; real access+refresh
  pair is minted only after /login/mfa.
- mfa_secret encrypted at rest via ASP.NET Core IDataProtector
  (purpose=Azaion.Mfa.Secret.v1; key folder configurable via
  DataProtection:KeysFolder for production persistence).
- Recovery codes (10 single-use, base32, ~80-bit entropy) hashed with
  SHA-256 and stored as JSONB; constant-time compare on lookup.
- RFC 6238 §5.2 replay defense via mfa_last_used_window per user.
- Sessions carry mfa_authenticated so /token/refresh re-stamps the
  amr claim correctly across the entire 30-day refresh window.
- New audit events: enroll, confirm, disable, login-success/failed,
  recovery-used.
- Schema: env/db/10_users_mfa.sql adds users.mfa_* columns and
  sessions.mfa_authenticated; mfa_recovery_codes mapped as BinaryJson
  in AzaionDbSchemaHolder; disable path uses raw parameterised SQL to
  avoid LinqToDB null-literal type-inference on jsonb columns.

E2E: 6 new tests in MfaLoginTests cover all six AC; full suite
82 passed / 0 failed / 3 intentional skips.

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

Azaion.AdminApi/BusinessExceptionHandler.cs

@@ -54,6 +54,11 @@ public class BusinessExceptionHandler(ILogger<BusinessExceptionHandler> logger)
         ExceptionEnum.SessionNotFound        => StatusCodes.Status404NotFound,
         ExceptionEnum.InvalidMissionRequest  => StatusCodes.Status400BadRequest,
         ExceptionEnum.AircraftNotFound       => StatusCodes.Status400BadRequest,
+        ExceptionEnum.MfaAlreadyEnabled      => StatusCodes.Status409Conflict,
+        ExceptionEnum.MfaNotEnrolling        => StatusCodes.Status409Conflict,
+        ExceptionEnum.MfaNotEnabled          => StatusCodes.Status409Conflict,
+        ExceptionEnum.InvalidMfaCode         => StatusCodes.Status401Unauthorized,
+        ExceptionEnum.InvalidMfaToken        => StatusCodes.Status401Unauthorized,
         _                                    => StatusCodes.Status409Conflict
     };
 }

Azaion.AdminApi/Program.cs

@@ -1,5 +1,6 @@
 using System.IdentityModel.Tokens.Jwt;
 using System.Threading.RateLimiting;
+using Microsoft.AspNetCore.DataProtection;
 using Azaion.Common;
 using Azaion.Common.Configs;
 using Azaion.Common.Database;
@@ -141,6 +142,22 @@ builder.Services.AddScoped<IAuthService, AuthService>();
 builder.Services.AddScoped<IRefreshTokenService, RefreshTokenService>();
 builder.Services.AddScoped<ISessionService, SessionService>();
 builder.Services.AddScoped<IMissionTokenService, MissionTokenService>();
+builder.Services.AddScoped<IMfaService, MfaService>();
+
+// AZ-534 — DataProtection encrypts mfa_secret at rest. Default key storage
+// (per-machine, ephemeral inside containers) is fine for a single-instance SUT.
+// Production deployments MUST set DataProtection__KeysFolder to a persistent
+// volume so encrypted secrets survive restarts and rolling deploys.
+{
+    var dpBuilder = builder.Services.AddDataProtection();
+    dpBuilder.SetApplicationName("Azaion.AdminApi");
+    var keyFolder = builder.Configuration["DataProtection:KeysFolder"];
+    if (!string.IsNullOrWhiteSpace(keyFolder))
+    {
+        Directory.CreateDirectory(keyFolder);
+        dpBuilder.PersistKeysToFileSystem(new DirectoryInfo(keyFolder));
+    }
+}
 builder.Services.AddScoped<IResourcesService, ResourcesService>();
 builder.Services.AddScoped<IDetectionClassService, DetectionClassService>();
 builder.Services.AddScoped<IAuditLog, AuditLog>();
@@ -269,27 +286,76 @@ app.MapPost("/login",
            IAuthService authService,
            IRefreshTokenService refreshTokens,
            ISessionService sessionService,
+           IMfaService mfaService,
            CancellationToken cancellationToken) =>
     {
         var user = await userService.ValidateUser(request, ct: cancellationToken);
-        var (refreshToken, session) = await refreshTokens.IssueForNewLogin(user.Id, cancellationToken);
-        var access = authService.CreateToken(user, sessionId: session.Id, jti: Guid.NewGuid());
 
-        // AZ-533 AC-4 — post-flight reconnect: if the just-authenticated user is an
+        // AZ-534 AC-3 — MFA-enabled users get short-circuited to a step-1 token; the
-        // aircraft (CompanionPC), kill any open mission session bound to it.
+        // real access+refresh pair is minted only after /login/mfa.
-        if (user.Role == RoleEnum.CompanionPC)
+        if (user.MfaEnabled)
-            await sessionService.RevokeMissionsForAircraft(user.Id, cancellationToken);
-
-        return Results.Ok(new LoginResponse
         {
-            AccessToken  = access.Jwt,
+            return Results.Ok(new MfaRequiredResponse
-            AccessExp    = access.ExpiresAt,
+            {
-            RefreshToken = refreshToken,
+                MfaRequired = true,
-            RefreshExp   = session.ExpiresAt,
+                MfaToken    = mfaService.IssueMfaStepToken(user.Id),
-        });
+                ExpiresIn   = 300,
+            });
+        }
+
+        return await IssueDualTokens(user, authService, refreshTokens, sessionService, amr: null, cancellationToken);
     })
     .RequireRateLimiting(LoginPerIpPolicy)
-    .WithSummary("Login (returns access + refresh token)");
+    .WithSummary("Login (returns access + refresh token, OR mfa_required if MFA is enabled)");
+
+// AZ-534 AC-3 / AC-4 — second factor at credential login. Anonymous because the
+// step-1 mfa_token is itself the proof the caller is mid-flow.
+app.MapPost("/login/mfa",
+    async (MfaLoginRequest request,
+           IMfaService mfaService,
+           IUserService userService,
+           IAuthService authService,
+           IRefreshTokenService refreshTokens,
+           ISessionService sessionService,
+           CancellationToken cancellationToken) =>
+    {
+        var userId = mfaService.ValidateMfaStepToken(request.MfaToken);
+        var user   = await userService.GetById(userId, cancellationToken)
+                     ?? throw new BusinessException(ExceptionEnum.NoEmailFound);
+
+        var amr = await mfaService.VerifyForLogin(userId, request.Code, cancellationToken);
+        return await IssueDualTokens(user, authService, refreshTokens, sessionService, amr, cancellationToken);
+    })
+    .AllowAnonymous()
+    .RequireRateLimiting(LoginPerIpPolicy)
+    .WithSummary("AZ-534 — second-factor verification; returns access + refresh token");
+
+static async Task<IResult> IssueDualTokens(
+    User user,
+    IAuthService authService,
+    IRefreshTokenService refreshTokens,
+    ISessionService sessionService,
+    string[]? amr,
+    CancellationToken ct)
+{
+    // AZ-534 — pin AMR strength to the session so refresh rotation inherits it.
+    var mfaAuthenticated = amr != null && amr.Contains("mfa");
+    var (refreshToken, session) = await refreshTokens.IssueForNewLogin(user.Id, mfaAuthenticated, ct);
+    var access = authService.CreateToken(user, sessionId: session.Id, jti: Guid.NewGuid(), amr: amr);
+
+    // AZ-533 AC-4 — post-flight reconnect: if the just-authenticated user is an
+    // aircraft (CompanionPC), kill any open mission session bound to it.
+    if (user.Role == RoleEnum.CompanionPC)
+        await sessionService.RevokeMissionsForAircraft(user.Id, ct);
+
+    return Results.Ok(new LoginResponse
+    {
+        AccessToken  = access.Jwt,
+        AccessExp    = access.ExpiresAt,
+        RefreshToken = refreshToken,
+        RefreshExp   = session.ExpiresAt,
+    });
+}
 
 // AZ-531 — refresh-token rotation. Anonymous: clients pass the opaque refresh
 // in the request body so an expired access token doesn't block the refresh.
@@ -304,7 +370,10 @@ app.MapPost("/token/refresh",
         var (newRefresh, session) = await refreshTokens.Rotate(request.RefreshToken, cancellationToken);
         var user = await userService.GetById(session.UserId, cancellationToken);
         if (user == null) throw new BusinessException(ExceptionEnum.InvalidRefreshToken);
-        var access = authService.CreateToken(user, sessionId: session.Id, jti: Guid.NewGuid());
+
+        // AZ-534 — preserve the original AMR strength across rotations.
+        var amr = session.MfaAuthenticated ? new[] { "pwd", "mfa" } : new[] { "pwd" };
+        var access = authService.CreateToken(user, sessionId: session.Id, jti: Guid.NewGuid(), amr: amr);
 
         // AZ-533 AC-4 — same auto-revoke trigger as /login.
         if (user.Role == RoleEnum.CompanionPC)
@@ -379,6 +448,37 @@ app.MapGet("/sessions/revoked",
     .RequireAuthorization(revocationReaderPolicy)
     .WithSummary("AZ-535 — verifier snapshot of revoked sessions still within their TTL");
 
+// AZ-534 — TOTP MFA enrollment + management.
+app.MapPost("/users/me/mfa/enroll",
+    async (MfaEnrollRequest request, HttpContext http, IMfaService mfa, CancellationToken ct) =>
+    {
+        var userId = ParseUserIdClaim(http.User);
+        var resp   = await mfa.Enroll(userId, request.Password, ct);
+        return Results.Ok(resp);
+    })
+    .RequireAuthorization()
+    .WithSummary("AZ-534 — start TOTP enrollment (pre-confirm)");
+
+app.MapPost("/users/me/mfa/confirm",
+    async (MfaConfirmRequest request, HttpContext http, IMfaService mfa, CancellationToken ct) =>
+    {
+        var userId = ParseUserIdClaim(http.User);
+        await mfa.Confirm(userId, request.Code, ct);
+        return Results.Ok(new { mfaEnabled = true });
+    })
+    .RequireAuthorization()
+    .WithSummary("AZ-534 — confirm TOTP enrollment with a valid code");
+
+app.MapPost("/users/me/mfa/disable",
+    async (MfaDisableRequest request, HttpContext http, IMfaService mfa, CancellationToken ct) =>
+    {
+        var userId = ParseUserIdClaim(http.User);
+        await mfa.Disable(userId, request.Password, request.Code, ct);
+        return Results.Ok(new { mfaEnabled = false });
+    })
+    .RequireAuthorization()
+    .WithSummary("AZ-534 — disable MFA (requires password + valid code)");
+
 // AZ-533 — mission token issuance for offline UAV ops. Pilot calls with their
 // interactive access token; admin returns a long-lived no-refresh token bound
 // to one aircraft + one mission.

Azaion.Common/BusinessException.cs

@@ -68,6 +68,21 @@ public enum ExceptionEnum
     [Description("Aircraft not found or wrong role.")]
     AircraftNotFound = 55,
 
+    [Description("MFA is already enabled for this user.")]
+    MfaAlreadyEnabled = 56,
+
+    [Description("MFA enrollment is not in progress for this user.")]
+    MfaNotEnrolling = 57,
+
+    [Description("MFA is not enabled for this user.")]
+    MfaNotEnabled = 58,
+
+    [Description("Invalid MFA code or recovery code.")]
+    InvalidMfaCode = 59,
+
+    [Description("MFA token is invalid or expired.")]
+    InvalidMfaToken = 61,
+
     [Description("No file provided.")]
     NoFileProvided = 60,
 }

Azaion.Common/Database/AzaionDbShemaHolder.cs

@@ -34,7 +34,12 @@ public static class AzaionDbSchemaHolder
                 .HasConversion(
                     v => v == null ? null : JsonConvert.SerializeObject(v),
                     p => string.IsNullOrEmpty(p) ? new UserConfig() : JsonConvert.DeserializeObject<UserConfig>(p))
-                .IsNullable();
+                .IsNullable()
+            // AZ-534 — mfa_recovery_codes is JSONB; tell the provider so Npgsql sends
+            // the JSON type oid instead of text (otherwise inserts fail with
+            // "column is of type jsonb but expression is of type text").
+            .Property(x => x.MfaRecoveryCodes)
+                .HasDataType(DataType.BinaryJson);
 
         builder.Entity<DetectionClass>()
             .HasTableName("detection_classes")

Azaion.Common/Entities/AuditEvent.cs

@@ -12,7 +12,15 @@ public class AuditEvent
 
 public static class AuditEventTypes
 {
-    public const string LoginFailed   = "login_failed";
+    public const string LoginFailed       = "login_failed";
-    public const string LoginLockout  = "login_lockout";
+    public const string LoginLockout      = "login_lockout";
-    public const string LoginSuccess  = "login_success";
+    public const string LoginSuccess      = "login_success";
+
+    // AZ-534 — MFA lifecycle + login events.
+    public const string MfaEnroll         = "mfa_enroll";
+    public const string MfaConfirm        = "mfa_confirm";
+    public const string MfaDisable        = "mfa_disable";
+    public const string MfaLoginSuccess   = "mfa_login_success";
+    public const string MfaLoginFailed    = "mfa_login_failed";
+    public const string MfaRecoveryUsed   = "mfa_recovery_used";
 }

Azaion.Common/Entities/Session.cs

@@ -43,6 +43,13 @@ public class Session
     /// interactive sessions.
     /// </summary>
     public Guid?     AircraftId        { get; set; }
+
+    /// <summary>
+    /// AZ-534 — true iff the session was created via an MFA-validated /login/mfa
+    /// call. Refresh-token rotation reads this to keep the AMR claim stable across
+    /// the session lifetime.
+    /// </summary>
+    public bool      MfaAuthenticated  { get; set; }
 }
 
 public static class SessionRevokedReasons

Azaion.Common/Entities/User.cs

@@ -20,6 +20,20 @@ public class User
     public int       FailedLoginCount { get; set; }
     public DateTime? LockoutUntil     { get; set; }
 
+    // AZ-534 — TOTP-based 2FA. mfa_secret is encrypted at rest; recovery codes are
+    // stored as a JSONB array of { hash, used_at } objects. mfa_last_used_window
+    // is the RFC 6238 time-step counter of the most recently accepted code,
+    // used to reject in-window replays.
+    [JsonIgnore]
+    public bool      MfaEnabled         { get; set; }
+    [JsonIgnore]
+    public string?   MfaSecret          { get; set; }
+    [JsonIgnore]
+    public string?   MfaRecoveryCodes   { get; set; }
+    public DateTime? MfaEnrolledAt      { get; set; }
+    [JsonIgnore]
+    public long?     MfaLastUsedWindow  { get; set; }
+
     public static string GetCacheKey(string email) =>
         string.IsNullOrEmpty(email) ? "" : $"{nameof(User)}.{email}";
 }

Azaion.Common/Requests/MfaRequests.cs

@@ -0,0 +1,43 @@
+namespace Azaion.Common.Requests;
+
+/// <summary>AZ-534 — body for <c>POST /users/me/mfa/enroll</c>.</summary>
+public class MfaEnrollRequest
+{
+    public string Password { get; set; } = null!;
+}
+
+/// <summary>AZ-534 — response of /enroll (also surfaces recovery codes ONCE; they are
+/// hashed at rest and unrecoverable after this response).</summary>
+public class MfaEnrollResponse
+{
+    public string   Secret         { get; set; } = null!;
+    public string   OtpAuthUrl     { get; set; } = null!;
+    public string   QrPngBase64    { get; set; } = null!;
+    public string[] RecoveryCodes  { get; set; } = [];
+}
+
+public class MfaConfirmRequest
+{
+    public string Code { get; set; } = null!;
+}
+
+public class MfaDisableRequest
+{
+    public string Password { get; set; } = null!;
+    public string Code     { get; set; } = null!;
+}
+
+/// <summary>AZ-534 AC-3 — response of step-1 /login when the user has MFA enabled.
+/// The mfa_token is a short-lived JWT carried into <c>POST /login/mfa</c>.</summary>
+public class MfaRequiredResponse
+{
+    public bool   MfaRequired { get; set; } = true;
+    public string MfaToken    { get; set; } = null!;
+    public int    ExpiresIn   { get; set; }
+}
+
+public class MfaLoginRequest
+{
+    public string MfaToken { get; set; } = null!;
+    public string Code     { get; set; } = null!;
+}

Azaion.Services/AuditLog.cs

@@ -11,6 +11,14 @@ public interface IAuditLog
     Task RecordLoginLockout(string email, CancellationToken ct = default);
     Task RecordLoginSuccess(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);
+    Task RecordMfaDisable      (string email, CancellationToken ct = default);
+    Task RecordMfaLoginSuccess (string email, CancellationToken ct = default);
+    Task RecordMfaLoginFailed  (string email, CancellationToken ct = default);
+    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).
@@ -29,6 +37,19 @@ public class AuditLog(IDbFactory dbFactory, IHttpContextAccessor httpContextAcce
     public Task RecordLoginSuccess(string email, CancellationToken ct = default)
         => Insert(AuditEventTypes.LoginSuccess, email, ct);
 
+    public Task RecordMfaEnroll       (string email, CancellationToken ct = default)
+        => Insert(AuditEventTypes.MfaEnroll,        email, ct);
+    public Task RecordMfaConfirm      (string email, CancellationToken ct = default)
+        => Insert(AuditEventTypes.MfaConfirm,       email, ct);
+    public Task RecordMfaDisable      (string email, CancellationToken ct = default)
+        => Insert(AuditEventTypes.MfaDisable,       email, ct);
+    public Task RecordMfaLoginSuccess (string email, CancellationToken ct = default)
+        => Insert(AuditEventTypes.MfaLoginSuccess,  email, ct);
+    public Task RecordMfaLoginFailed  (string email, CancellationToken ct = default)
+        => Insert(AuditEventTypes.MfaLoginFailed,   email, ct);
+    public Task RecordMfaRecoveryUsed (string email, CancellationToken ct = default)
+        => Insert(AuditEventTypes.MfaRecoveryUsed,  email, ct);
+
     public async Task<int> CountRecentFailedLogins(string email, int windowSeconds, CancellationToken ct = default)
     {
         var cutoff = DateTime.UtcNow.AddSeconds(-windowSeconds);

Azaion.Services/AuthService.cs

@@ -16,8 +16,10 @@ public interface IAuthService
     /// AZ-531 / AZ-532 — mint a 15-minute ES256 access token. <paramref name="sessionId"/>
     /// is stamped as the <c>sid</c> claim (logout / family-revocation key in AZ-535)
     /// and <paramref name="jti"/> is the per-token unique id (AZ-535 access denylist).
+    /// AZ-534 — <paramref name="amr"/> values are stamped as repeated <c>amr</c>
+    /// claims so verifiers can require step-up MFA. Defaults to <c>["pwd"]</c>.
     /// </summary>
-    AccessToken CreateToken(User user, Guid sessionId, Guid jti);
+    AccessToken CreateToken(User user, Guid sessionId, Guid jti, IEnumerable<string>? amr = null);
 }
 
 public sealed record AccessToken(string Jwt, DateTime ExpiresAt);
@@ -42,22 +44,31 @@ public class AuthService(
         return await userService.GetByEmail(email);
     }
 
-    public AccessToken CreateToken(User user, Guid sessionId, Guid jti)
+    public AccessToken CreateToken(User user, Guid sessionId, Guid jti, IEnumerable<string>? amr = null)
     {
         var active = signingKeys.Active;
         var signingCredentials = new SigningCredentials(active.SecurityKey, SecurityAlgorithms.EcdsaSha256);
 
         var expires = DateTime.UtcNow.AddMinutes(_jwt.AccessTokenLifetimeMinutes);
+        var claims = new List<Claim>
+        {
+            new(ClaimTypes.NameIdentifier,           user.Id.ToString()),
+            new(ClaimTypes.Name,                     user.Email),
+            new(ClaimTypes.Role,                     user.Role.ToString()),
+            new(JwtRegisteredClaimNames.Sid,         sessionId.ToString()),
+            new(JwtRegisteredClaimNames.Jti,         jti.ToString())
+        };
+
+        // AZ-534 — stamp authentication-methods-reference per RFC 8176. Multi-valued:
+        // password+TOTP login produces ["pwd","mfa"]; recovery-code login adds "recovery".
+        var amrValues = amr?.ToArray() ?? ["pwd"];
+        foreach (var v in amrValues)
+            claims.Add(new Claim("amr", v));
+
         var tokenHandler = new JwtSecurityTokenHandler();
         var tokenDescriptor = new SecurityTokenDescriptor
         {
-            Subject = new ClaimsIdentity([
+            Subject            = new ClaimsIdentity(claims),
-                new Claim(ClaimTypes.NameIdentifier, user.Id.ToString()),
-                new Claim(ClaimTypes.Name, user.Email),
-                new Claim(ClaimTypes.Role, user.Role.ToString()),
-                new Claim(JwtRegisteredClaimNames.Sid, sessionId.ToString()),
-                new Claim(JwtRegisteredClaimNames.Jti, jti.ToString())
-            ]),
             Expires            = expires,
             Issuer             = _jwt.Issuer,
             Audience           = _jwt.Audience,

Azaion.Services/Azaion.Services.csproj

@@ -18,6 +18,8 @@
       <PackageReference Include="Konscious.Security.Cryptography.Argon2" Version="1.3.1" />
       <PackageReference Include="LazyCache.AspNetCore" Version="2.4.0" />
       <PackageReference Include="Newtonsoft.Json" Version="13.0.4" />
+      <PackageReference Include="Otp.NET" Version="1.4.1" />
+      <PackageReference Include="QRCoder" Version="1.8.0" />
       <PackageReference Include="System.IdentityModel.Tokens.Jwt" Version="7.1.2" />
     </ItemGroup>
 

Azaion.Services/MfaService.cs

@@ -0,0 +1,346 @@
+using System.IdentityModel.Tokens.Jwt;
+using System.Security.Claims;
+using System.Security.Cryptography;
+using System.Text.Json;
+using Azaion.Common;
+using Azaion.Common.Configs;
+using Azaion.Common.Database;
+using Azaion.Common.Entities;
+using Azaion.Common.Requests;
+using LinqToDB;
+using LinqToDB.Data;
+using Microsoft.AspNetCore.DataProtection;
+using Microsoft.Extensions.Options;
+using Microsoft.IdentityModel.Tokens;
+using OtpNet;
+using QRCoder;
+
+namespace Azaion.Services;
+
+/// <summary>
+/// AZ-534 — RFC 6238 TOTP enrollment + login validation, with single-use recovery codes.
+/// MfaSecret is encrypted at rest via <see cref="IDataProtector"/>; recovery codes are
+/// stored as SHA-256 hashes (high-entropy secrets need a fast hash, not Argon2id —
+/// same reasoning the refresh-token store uses).
+/// </summary>
+public interface IMfaService
+{
+    Task<MfaEnrollResponse> Enroll(Guid userId, string password, CancellationToken ct = default);
+    Task                    Confirm(Guid userId, string code, CancellationToken ct = default);
+    Task                    Disable(Guid userId, string password, string code, CancellationToken ct = default);
+
+    /// <summary>
+    /// Issued at /login when the user has MFA enabled — a 5-minute JWT (aud=azaion-mfa-step2)
+    /// the client carries to /login/mfa for the second-factor verification.
+    /// </summary>
+    string                  IssueMfaStepToken(Guid userId);
+
+    /// <summary>
+    /// Decode the step-1 token, returning the userId. Throws BusinessException(InvalidMfaToken)
+    /// on bad signature, audience mismatch, or expired token.
+    /// </summary>
+    Guid                    ValidateMfaStepToken(string token);
+
+    /// <summary>
+    /// AZ-534 AC-3 + AC-4 — second-factor verification at login. Returns the
+    /// <c>amr</c> values the access token should carry (always includes <c>"pwd"</c>
+    /// and <c>"mfa"</c>; <c>"recovery"</c> is added when a recovery code was used).
+    /// </summary>
+    Task<string[]>          VerifyForLogin(Guid userId, string code, CancellationToken ct = default);
+}
+
+public class MfaService(
+    IDbFactory dbFactory,
+    IUserService userService,
+    IDataProtectionProvider dataProtectionProvider,
+    IJwtSigningKeyProvider signingKeys,
+    IOptions<JwtConfig> jwtConfig,
+    IAuditLog auditLog) : IMfaService
+{
+    private const string MfaSecretPurpose = "Azaion.Mfa.Secret.v1";
+    private const string MfaStepAudience  = "azaion-mfa-step2";
+    private const int    MfaStepLifetimeSeconds = 300; // 5 min — matches AC-3
+    private const int    SecretBytes      = 20;        // 160 bits — RFC 6238 §3
+    private const int    RecoveryCodeCount = 10;
+    private const int    RecoveryCodeBytes = 10;       // base32(10) = 16 chars (≥12 per AC-1)
+
+    private readonly IDataProtector _protector = dataProtectionProvider.CreateProtector(MfaSecretPurpose);
+    private readonly JwtConfig      _jwt       = jwtConfig.Value;
+
+    public async Task<MfaEnrollResponse> Enroll(Guid userId, string password, CancellationToken ct = default)
+    {
+        var user = await userService.GetById(userId, ct)
+            ?? throw new BusinessException(ExceptionEnum.NoEmailFound);
+
+        // Re-auth with password — AC-1 requires this to defend a stolen access token
+        // from being usable to silently flip the user into MFA.
+        var verify = Security.VerifyPassword(password, user.PasswordHash);
+        if (!verify.Valid)
+            throw new BusinessException(ExceptionEnum.WrongPassword);
+
+        if (user.MfaEnabled)
+            throw new BusinessException(ExceptionEnum.MfaAlreadyEnabled);
+
+        var secretBytes  = KeyGeneration.GenerateRandomKey(SecretBytes);
+        var secretBase32 = Base32Encoding.ToString(secretBytes); // 32 chars (per AC-1)
+
+        var otpAuthUrl = new OtpUri(
+            schema:    OtpType.Totp,
+            secret:    secretBase32,
+            user:      user.Email,
+            issuer:    _jwt.Issuer,
+            algorithm: OtpHashMode.Sha1,
+            digits:    6,
+            period:    30).ToString();
+
+        var qrPng = GenerateQrPng(otpAuthUrl);
+
+        var recoveryPlain = new string[RecoveryCodeCount];
+        var recoveryStore = new RecoveryCodeStore[RecoveryCodeCount];
+        for (var i = 0; i < RecoveryCodeCount; i++)
+        {
+            var code = Base32Encoding.ToString(KeyGeneration.GenerateRandomKey(RecoveryCodeBytes));
+            recoveryPlain[i] = code;
+            recoveryStore[i] = new RecoveryCodeStore { Hash = HashRecoveryCode(code), UsedAt = null };
+        }
+
+        var encryptedSecret = _protector.Protect(secretBase32);
+        var recoveryJson    = JsonSerializer.Serialize(recoveryStore);
+
+        await dbFactory.RunAdmin(async db =>
+            await db.Users.UpdateAsync(
+                u => u.Id == userId,
+                u => new User
+                {
+                    MfaSecret        = encryptedSecret,
+                    MfaRecoveryCodes = recoveryJson,
+                    MfaEnabled       = false, // confirm step flips this true
+                    MfaEnrolledAt    = null
+                },
+                token: ct));
+
+        await auditLog.RecordMfaEnroll(user.Email, ct);
+
+        return new MfaEnrollResponse
+        {
+            Secret        = secretBase32,
+            OtpAuthUrl    = otpAuthUrl,
+            QrPngBase64   = qrPng,
+            RecoveryCodes = recoveryPlain
+        };
+    }
+
+    public async Task Confirm(Guid userId, string code, CancellationToken ct = default)
+    {
+        var user = await userService.GetById(userId, ct)
+            ?? throw new BusinessException(ExceptionEnum.NoEmailFound);
+
+        if (user.MfaEnabled)
+            throw new BusinessException(ExceptionEnum.MfaAlreadyEnabled);
+
+        if (string.IsNullOrEmpty(user.MfaSecret))
+            throw new BusinessException(ExceptionEnum.MfaNotEnrolling);
+
+        var secret = _protector.Unprotect(user.MfaSecret);
+        if (!VerifyTotpCode(secret, code, lastUsedWindow: null, out _))
+            throw new BusinessException(ExceptionEnum.InvalidMfaCode);
+
+        await dbFactory.RunAdmin(async db =>
+            await db.Users.UpdateAsync(
+                u => u.Id == userId,
+                u => new User
+                {
+                    MfaEnabled    = true,
+                    MfaEnrolledAt = DateTime.UtcNow
+                },
+                token: ct));
+
+        await auditLog.RecordMfaConfirm(user.Email, ct);
+    }
+
+    public async Task Disable(Guid userId, string password, string code, CancellationToken ct = default)
+    {
+        var user = await userService.GetById(userId, ct)
+            ?? throw new BusinessException(ExceptionEnum.NoEmailFound);
+
+        if (!user.MfaEnabled)
+            throw new BusinessException(ExceptionEnum.MfaNotEnabled);
+
+        var verify = Security.VerifyPassword(password, user.PasswordHash);
+        if (!verify.Valid)
+            throw new BusinessException(ExceptionEnum.WrongPassword);
+
+        var secret = _protector.Unprotect(user.MfaSecret!);
+        if (!VerifyTotpCode(secret, code, lastUsedWindow: null, out _))
+            throw new BusinessException(ExceptionEnum.InvalidMfaCode);
+
+        // Raw SQL: setting mfa_recovery_codes (jsonb) to NULL via the LinqToDB UPDATE
+        // expression sends an untyped NULL literal that Postgres parses as text and
+        // rejects (42804). A small parameterized SQL avoids the type-inference dance.
+        await dbFactory.RunAdmin(async db =>
+            await db.ExecuteAsync(
+                @"UPDATE public.users
+                  SET mfa_enabled = false,
+                      mfa_secret = NULL,
+                      mfa_recovery_codes = NULL::jsonb,
+                      mfa_enrolled_at = NULL,
+                      mfa_last_used_window = NULL
+                  WHERE id = @id",
+                new DataParameter("id", userId, DataType.Guid)));
+
+        await auditLog.RecordMfaDisable(user.Email, ct);
+    }
+
+    public string IssueMfaStepToken(Guid userId)
+    {
+        var active = signingKeys.Active;
+        var creds  = new SigningCredentials(active.SecurityKey, SecurityAlgorithms.EcdsaSha256);
+        var expires = DateTime.UtcNow.AddSeconds(MfaStepLifetimeSeconds);
+
+        var descriptor = new SecurityTokenDescriptor
+        {
+            Subject = new ClaimsIdentity([
+                new Claim(ClaimTypes.NameIdentifier, userId.ToString()),
+                new Claim("token_use", "mfa_step")
+            ]),
+            Expires            = expires,
+            Issuer             = _jwt.Issuer,
+            // AZ-534 — narrow audience: this token is ONLY usable at /login/mfa.
+            // The main JwtBearer middleware accepts _jwt.Audience and rejects this one.
+            Audience           = MfaStepAudience,
+            SigningCredentials = creds
+        };
+
+        var handler = new JwtSecurityTokenHandler();
+        return handler.WriteToken(handler.CreateToken(descriptor));
+    }
+
+    public Guid ValidateMfaStepToken(string token)
+    {
+        try
+        {
+            var handler = new JwtSecurityTokenHandler();
+            var principal = handler.ValidateToken(token, new TokenValidationParameters
+            {
+                ValidateIssuer           = true,
+                ValidateAudience         = true,
+                ValidateLifetime         = true,
+                ValidateIssuerSigningKey = true,
+                ValidIssuer              = _jwt.Issuer,
+                ValidAudience            = MfaStepAudience,
+                ValidAlgorithms          = [SecurityAlgorithms.EcdsaSha256],
+                IssuerSigningKeyResolver = (_, _, _, _) =>
+                    signingKeys.All.Select(k => (SecurityKey)k.SecurityKey)
+            }, out _);
+
+            var sub = principal.FindFirst(ClaimTypes.NameIdentifier)?.Value
+                ?? throw new BusinessException(ExceptionEnum.InvalidMfaToken);
+            return Guid.Parse(sub);
+        }
+        catch (BusinessException) { throw; }
+        catch (Exception)
+        {
+            throw new BusinessException(ExceptionEnum.InvalidMfaToken);
+        }
+    }
+
+    public async Task<string[]> VerifyForLogin(Guid userId, string code, CancellationToken ct = default)
+    {
+        var user = await userService.GetById(userId, ct)
+            ?? throw new BusinessException(ExceptionEnum.NoEmailFound);
+
+        if (!user.MfaEnabled || string.IsNullOrEmpty(user.MfaSecret))
+            throw new BusinessException(ExceptionEnum.MfaNotEnabled);
+
+        var secret = _protector.Unprotect(user.MfaSecret);
+        if (VerifyTotpCode(secret, code, user.MfaLastUsedWindow, out var window))
+        {
+            // Persist last-used window so a re-presented code in the same 30 s
+            // step is rejected even if the attacker presents it before the next step.
+            await dbFactory.RunAdmin(async db =>
+                await db.Users.UpdateAsync(
+                    u => u.Id == userId,
+                    u => new User { MfaLastUsedWindow = window },
+                    token: ct));
+            await auditLog.RecordMfaLoginSuccess(user.Email, ct);
+            return ["pwd", "mfa"];
+        }
+
+        // TOTP failed — try recovery code (single-use)
+        if (await TryConsumeRecoveryCode(user, code, ct))
+        {
+            await auditLog.RecordMfaRecoveryUsed(user.Email, ct);
+            return ["pwd", "mfa", "recovery"];
+        }
+
+        await auditLog.RecordMfaLoginFailed(user.Email, ct);
+        throw new BusinessException(ExceptionEnum.InvalidMfaCode);
+    }
+
+    private static bool VerifyTotpCode(string secretBase32, string code, long? lastUsedWindow, out long matchedWindow)
+    {
+        matchedWindow = 0;
+        var totp = new Totp(Base32Encoding.ToBytes(secretBase32));
+        if (!totp.VerifyTotp(code, out matchedWindow, VerificationWindow.RfcSpecifiedNetworkDelay))
+            return false;
+        if (lastUsedWindow.HasValue && matchedWindow <= lastUsedWindow.Value)
+            return false; // replay within or before the last accepted window
+        return true;
+    }
+
+    private async Task<bool> TryConsumeRecoveryCode(User user, string code, CancellationToken ct)
+    {
+        if (string.IsNullOrEmpty(user.MfaRecoveryCodes)) return false;
+
+        var codes = JsonSerializer.Deserialize<RecoveryCodeStore[]>(user.MfaRecoveryCodes)
+            ?? Array.Empty<RecoveryCodeStore>();
+        var candidateHash = HashRecoveryCode(code);
+
+        var matchIdx = -1;
+        for (var i = 0; i < codes.Length; i++)
+        {
+            if (codes[i].UsedAt != null) continue;
+            if (CryptographicOperations.FixedTimeEquals(
+                    System.Text.Encoding.ASCII.GetBytes(codes[i].Hash),
+                    System.Text.Encoding.ASCII.GetBytes(candidateHash)))
+            {
+                matchIdx = i;
+                break;
+            }
+        }
+        if (matchIdx < 0) return false;
+
+        codes[matchIdx] = codes[matchIdx] with { UsedAt = DateTime.UtcNow };
+        var updated = JsonSerializer.Serialize(codes);
+
+        await dbFactory.RunAdmin(async db =>
+            await db.Users.UpdateAsync(
+                // Conditional update on the prior JSON to avoid a race where two
+                // concurrent /login/mfa calls both consume the same code.
+                u => u.Id == user.Id && u.MfaRecoveryCodes == user.MfaRecoveryCodes,
+                u => new User { MfaRecoveryCodes = updated },
+                token: ct));
+        return true;
+    }
+
+    private static string GenerateQrPng(string text)
+    {
+        using var generator = new QRCodeGenerator();
+        using var data      = generator.CreateQrCode(text, QRCodeGenerator.ECCLevel.M);
+        var pngBytes        = new PngByteQRCode(data).GetGraphic(pixelsPerModule: 6);
+        return Convert.ToBase64String(pngBytes);
+    }
+
+    private static string HashRecoveryCode(string code)
+    {
+        var bytes  = System.Text.Encoding.UTF8.GetBytes(code);
+        var digest = SHA256.HashData(bytes);
+        return Convert.ToHexString(digest);
+    }
+
+    private sealed record RecoveryCodeStore
+    {
+        public string    Hash    { get; init; } = "";
+        public DateTime? UsedAt  { get; init; }
+    }
+}

Azaion.Services/RefreshTokenService.cs

@@ -18,9 +18,10 @@ public interface IRefreshTokenService
     /// <summary>
     /// Mint a fresh refresh token at login; starts a new session family. Returns
     /// the opaque token (NEVER persisted; only its sha256 lands in the DB) and
-    /// the session row that backs it.
+    /// the session row that backs it. <paramref name="mfaAuthenticated"/> is pinned
+    /// to the session so refresh-token rotation inherits the original AMR strength.
     /// </summary>
-    Task<(string OpaqueToken, Session Session)> IssueForNewLogin(Guid userId, CancellationToken ct = default);
+    Task<(string OpaqueToken, Session Session)> IssueForNewLogin(Guid userId, bool mfaAuthenticated = false, CancellationToken ct = default);
 
     /// <summary>
     /// Rotate <paramref name="opaqueToken"/>. On success returns the new token +
@@ -37,20 +38,21 @@ public class RefreshTokenService(IDbFactory dbFactory, IOptions<SessionConfig> s
 
     private readonly SessionConfig _cfg = sessionConfig.Value;
 
-    public async Task<(string OpaqueToken, Session Session)> IssueForNewLogin(Guid userId, CancellationToken ct = default)
+    public async Task<(string OpaqueToken, Session Session)> IssueForNewLogin(Guid userId, bool mfaAuthenticated = false, CancellationToken ct = default)
     {
         var (opaque, hash) = GenerateToken();
         var now = DateTime.UtcNow;
         var session = new Session
         {
-            Id              = Guid.NewGuid(),
+            Id               = Guid.NewGuid(),
-            UserId          = userId,
+            UserId           = userId,
-            RefreshHash     = hash,
+            RefreshHash      = hash,
-            FamilyId        = Guid.NewGuid(), // self-rooted family
+            FamilyId         = Guid.NewGuid(), // self-rooted family
-            IssuedAt        = now,
+            IssuedAt         = now,
-            LastUsedAt      = now,
+            LastUsedAt       = now,
-            ExpiresAt       = now.AddHours(_cfg.RefreshSlidingHours),
+            ExpiresAt        = now.AddHours(_cfg.RefreshSlidingHours),
-            FamilyStartedAt = now,
+            FamilyStartedAt  = now,
+            MfaAuthenticated = mfaAuthenticated,
         };
         // family_id should equal id for the root row so SELECT family_id from
         // any row returns a stable handle even if id is renamed later.
@@ -104,15 +106,16 @@ public class RefreshTokenService(IDbFactory dbFactory, IOptions<SessionConfig> s
             var (newOpaque, newHash) = GenerateToken();
             var newSession = new Session
             {
-                Id              = Guid.NewGuid(),
+                Id               = Guid.NewGuid(),
-                UserId          = current.UserId,
+                UserId           = current.UserId,
-                RefreshHash     = newHash,
+                RefreshHash      = newHash,
-                FamilyId        = current.FamilyId,
+                FamilyId         = current.FamilyId,
-                IssuedAt        = now,
+                IssuedAt         = now,
-                LastUsedAt      = now,
+                LastUsedAt       = now,
-                ExpiresAt       = now.AddHours(_cfg.RefreshSlidingHours),
+                ExpiresAt        = now.AddHours(_cfg.RefreshSlidingHours),
-                FamilyStartedAt = current.FamilyStartedAt,
+                FamilyStartedAt  = current.FamilyStartedAt,
-                ParentSessionId = current.Id,
+                ParentSessionId  = current.Id,
+                MfaAuthenticated = current.MfaAuthenticated,
             };
 
             await db.Sessions

_docs/02_tasks/_dependencies_table.md

@@ -1,7 +1,7 @@
 # Dependencies Table
 
-**Date**: 2026-05-14 (post batch 3 cycle 2; previous 2026-05-14)
+**Date**: 2026-05-14 (post batch 4 cycle 2; previous 2026-05-14)
-**Total Tasks**: 19 (7 done test tasks + 4 done product tasks + 5 done cross-workspace + 3 done CMMC + 4 done auth-modernization + 1 active product task)
+**Total Tasks**: 19 (7 done test tasks + 4 done product tasks + 5 done cross-workspace + 3 done CMMC + 5 done auth-modernization)
 **Total Complexity Points**: 71
 
 | Task   | Name                          | Complexity | Dependencies            | Epic   | Status |
@@ -20,7 +20,7 @@
 | AZ-531 | refresh_token_flow            | 5          | None                    | AZ-529 | done   |
 | AZ-532 | asymmetric_signing_jwks       | 5          | None                    | AZ-529 | done   |
 | AZ-533 | mission_token_uav             | 5          | AZ-531                  | AZ-529 | done   |
-| AZ-534 | totp_2fa_login                | 5          | None (coord. AZ-531/537) | AZ-529 | todo   |
+| AZ-534 | totp_2fa_login                | 5          | None (coord. AZ-531/537) | AZ-529 | done   |
 | AZ-535 | logout_revocation             | 3          | AZ-531                  | AZ-529 | done   |
 | AZ-536 | argon2id_password_hashing     | 3          | None                    | AZ-530 | done   |
 | AZ-537 | login_rate_limit_lockout      | 3          | None (coord. AZ-536)    | AZ-530 | done   |

_docs/03_implementation/batch_04_cycle2_report.md

@@ -0,0 +1,75 @@
+# Batch Report
+
+**Batch**: 4 (cycle 2)
+**Tasks**: AZ-534 (totp_2fa_login)
+**Date**: 2026-05-14
+**Total Complexity**: 5 points
+**Epic**: AZ-529 — Auth Mechanism Modernization
+
+## Task Results
+
+| Task   | Status | Files Modified                          | Tests       | AC Coverage | Issues |
+|--------|--------|-----------------------------------------|-------------|-------------|--------|
+| AZ-534 | Done   | 9 source + 1 sql migration + 1 test     | 6/6 pass    | 6/6         | None blocking — see review |
+
+## Files Touched
+
+**Source (production)**
+- `Azaion.AdminApi/Program.cs` — DI for `IMfaService`; configure ASP.NET Core DataProtection (with optional `DataProtection:KeysFolder` for production persistence); `/login` short-circuits to step-1 token when `user.MfaEnabled`; new `/login/mfa` endpoint; new `/users/me/mfa/{enroll,confirm,disable}` endpoints; `IssueDualTokens` helper centralises access+refresh minting; `/token/refresh` propagates `amr` from the persisted `MfaAuthenticated` flag
+- `Azaion.AdminApi/BusinessExceptionHandler.cs` — map `MfaAlreadyEnabled` / `MfaNotEnrolling` / `MfaNotEnabled` → 409, `InvalidMfaCode` / `InvalidMfaToken` → 401
+- `Azaion.Common/BusinessException.cs` — add `MfaAlreadyEnabled = 56`, `MfaNotEnrolling = 57`, `MfaNotEnabled = 58`, `InvalidMfaCode = 59`, `InvalidMfaToken = 61`
+- `Azaion.Common/Database/AzaionDbShemaHolder.cs` — `User.MfaRecoveryCodes` mapped to `DataType.BinaryJson` so Npgsql sends the JSONB type oid on insert/update
+- `Azaion.Common/Entities/User.cs` — add `MfaEnabled`, `MfaSecret`, `MfaRecoveryCodes`, `MfaEnrolledAt`, `MfaLastUsedWindow`; sensitive fields `[JsonIgnore]`
+- `Azaion.Common/Entities/Session.cs` — add `MfaAuthenticated` (preserves AMR strength across refresh rotations)
+- `Azaion.Common/Entities/AuditEvent.cs` — new event type strings: `MfaEnroll`, `MfaConfirm`, `MfaDisable`, `MfaLoginSuccess`, `MfaLoginFailed`, `MfaRecoveryUsed`
+- `Azaion.Common/Requests/MfaRequests.cs` — *new*; `MfaEnrollRequest`/`Response`, `MfaConfirmRequest`, `MfaDisableRequest`, `MfaRequiredResponse`, `MfaLoginRequest`
+- `Azaion.Services/AuthService.cs` — `CreateToken` accepts optional `amr` collection; values stamped as repeated `amr` claims per RFC 8176
+- `Azaion.Services/AuditLog.cs` — new `RecordMfa…` helpers
+- `Azaion.Services/MfaService.cs` — *new*; TOTP enrol / confirm / disable / verify-for-login; ES256 step-1 token (5-min, audience-pinned `azaion-mfa-step2`); single-use recovery codes (SHA-256 hashed, JSONB-stored); RFC 6238 replay defence via `MfaLastUsedWindow`; `IDataProtector` encrypts `mfa_secret` at rest
+- `Azaion.Services/RefreshTokenService.cs` — `IssueForNewLogin` accepts `mfaAuthenticated`; `Rotate` carries the flag forward to the new session row
+
+**Migrations / infra**
+- `env/db/10_users_mfa.sql` — *new*; ALTER TABLE adds `mfa_enabled` (default false), `mfa_secret` (text), `mfa_recovery_codes` (jsonb), `mfa_enrolled_at` (timestamp), `mfa_last_used_window` (bigint); `sessions.mfa_authenticated` (default false)
+- `e2e/db-init/00_run_all.sh` — apply 10_users_mfa.sql in test DB
+- `e2e/Azaion.E2E/Azaion.E2E.csproj` — add `Otp.NET` package (test-side TOTP code generation)
+
+**Tests**
+- `e2e/Azaion.E2E/Tests/MfaLoginTests.cs` — *new*; 6 tests (enrol payload shape, confirm activates, two-step login + amr, recovery single-use, disable round-trip, ciphertext-at-rest)
+- `e2e/Azaion.E2E/Helpers/DbHelper.cs` — add `GetMfaSecretRaw`, `GetMfaEnabled`
+
+## Test Run Results
+
+**Batch 4 only** (`--filter MfaLoginTests`): **6 / 6 passed**, ~14 s.
+**Full suite**: **82 passed, 0 failed, 3 skipped**, ~77 s.
+
+The `PasswordHashingTests.AC5_Verify_uses_constant_time_comparator_no_obvious_timing_leak` flake noted in batch 3 review passed cleanly in this run, confirming it as an environmental flake rather than a regression.
+
+## AC Coverage
+
+- **AC-1**: Enrol returns base32 `secret` (32 chars), `otpauth://` URL, base64 PNG QR, 10 recovery codes ≥12 chars; DB still `mfa_enabled=false` — `AC1_Enroll_returns_secret_otpauth_qr_and_recovery_codes`
+- **AC-2**: Confirm with valid TOTP flips `mfa_enabled=true` — `AC2_Confirm_enables_MFA`
+- **AC-3**: `/login` returns `{mfa_required, mfa_token, expires_in:300}` then `/login/mfa` returns access+refresh with `amr=["pwd","mfa"]` — `AC3_Login_returns_mfa_required_then_step2_returns_tokens_with_amr_pwd_mfa`
+- **AC-4**: Recovery code works once (yields `amr=["pwd","mfa","recovery"]`); reuse rejected — `AC4_Recovery_code_works_once_then_fails`
+- **AC-5**: `/users/me/mfa/disable` requires password + valid TOTP; subsequent `/login` returns access+refresh directly without step 2 — `AC5_Disable_requires_password_and_code_then_login_returns_tokens_directly`
+- **AC-6**: `users.mfa_secret` read directly from Postgres is ciphertext (DataProtection envelope), not the base32 secret — `AC6_Mfa_secret_is_encrypted_at_rest`
+
+## Key Implementation Decisions
+
+1. **`IDataProtector` for `mfa_secret`, not a hand-rolled AES wrapper.** ASP.NET Core's DataProtection handles key generation, automatic 90-day rotation, and a versioned envelope format that survives key rolls without re-encrypting all rows. Custom AES-GCM would have given the same security guarantee but with three new test vectors and a manual rotation runbook. `Purpose = "Azaion.Mfa.Secret.v1"` namespaces the keys so an accidental cross-purpose decrypt fails. Key persistence is opt-in via `DataProtection:KeysFolder` — production deployments MUST set it (Program.cs comment is explicit), or restarts invalidate every enrolled secret.
+
+2. **SHA-256 for recovery code hashing, not Argon2id.** Recovery codes are 16-character base32 strings (~80 bits of entropy from `KeyGeneration.GenerateRandomKey(10)`). Argon2id at the calibrated `~250 ms` cost would add 2.5 s to every wrong-code attempt (we walk all unused codes). High-entropy secrets need a fast hash, not a slow KDF — the same reasoning the refresh-token store uses. Constant-time compare via `CryptographicOperations.FixedTimeEquals` defends against timing oracles on the hash bytes.
+
+3. **`mfa_authenticated` persisted on the session row, not re-derived from the access token.** Refresh-token rotation produces a brand-new access token; we'd otherwise have no source of truth for "was this session born of MFA?" once the original access token expires. Storing the boolean on the session lets `/token/refresh` re-stamp `amr=["pwd","mfa"]` correctly across the entire 30-day refresh window. Costs one boolean column.
+
+4. **Step-1 MFA token is ES256, audience-pinned `azaion-mfa-step2`.** Re-uses the JWKS keypair so verifiers don't need to learn a second key. The narrow audience makes the main `JwtBearer` middleware reject this token for normal endpoints, and `MfaService.ValidateMfaStepToken` rejects any other audience — so a step-1 token cannot be presented at `/users/me`, and an access token cannot be presented at `/login/mfa`.
+
+5. **`VerifyTotpCode` checks `lastUsedWindow > matchedWindow` first.** RFC 6238 §5.2 says "the verifier MUST reject any code that was already used in the current or previous window". `OtpNet.VerificationWindow.RfcSpecifiedNetworkDelay` accepts the prior + current + next 30-second window. Without the per-user `mfa_last_used_window` check, a man-in-the-middle who captured the code mid-flight could replay it within the 30-90 s acceptance window. Persisting the matched window is one extra `UPDATE users` per successful login.
+
+6. **Disable uses raw SQL parameter for the JSONB null.** LinqToDB's `UpdateAsync` lambda compiles `MfaRecoveryCodes = null` into an untyped `NULL` literal which Postgres parses as `text` and rejects against the `jsonb` column (42804). The `BinaryJson` mapping handles non-null values fine, but null literals in expression bodies bypass parameter typing. Switched the disable path to a single parameterised `UPDATE … SET mfa_recovery_codes = NULL::jsonb …`. Local fix, doesn't affect the enrol/confirm/login paths.
+
+## Backward Compatibility
+
+- All new `users` columns default to MFA-off (`mfa_enabled=false`, others NULL). Existing rows untouched.
+- Pre-existing `sessions` rows default `mfa_authenticated=false`; `/token/refresh` against an old session continues to issue `amr=["pwd"]` — same behaviour as before.
+- `/login` response shape is unchanged for users without MFA enabled — no client-visible change for the existing CompanionPC fleet or any non-enrolled admin.
+- `LoginResponse` and `LoginRequest` DTOs unchanged. The MFA branch returns a different DTO (`MfaRequiredResponse`); clients that don't recognise the `mfaRequired` field will see an unexpected payload — UI workspace ticket flagged in the spec under "Risks / Notes".

_docs/03_implementation/implementation_report_auth_modernization_cycle2.md

@@ -0,0 +1,80 @@
+# Implementation Report — Auth Modernization (Cycle 2)
+
+**Feature**: Auth mechanism modernization + CMMC compliance hardening
+**Cycle**: 2
+**Date**: 2026-05-14
+**Epics**: AZ-529 (Auth Mechanism Modernization), AZ-530 (CMMC Compliance Hardening)
+**Total Complexity**: 31 points (8 + 10 + 8 + 5)
+
+## Cycle Summary
+
+Cycle 2 delivered all eight tasks from the AZ-529 + AZ-530 epics in four sequential batches. Every task acceptance criterion is covered by passing E2E tests; the full suite (82 enabled tests, 3 intentional skips) is green at the close of cycle.
+
+| Batch | Tasks                                              | Complexity | Tests Added | Status |
+|------:|----------------------------------------------------|-----------:|------------:|--------|
+| 1     | AZ-536, AZ-537, AZ-538                             | 8 pts      | 12          | Done   |
+| 2     | AZ-531, AZ-532                                     | 10 pts     | 11          | Done   |
+| 3     | AZ-535, AZ-533                                     | 8 pts      | 13          | Done   |
+| 4     | AZ-534                                             | 5 pts      | 6           | Done   |
+| **Total** |                                                | **31 pts** | **42**      |        |
+
+## Task Outcomes
+
+| Task   | Name                          | Epic   | ACs | Status |
+|--------|-------------------------------|--------|----:|--------|
+| AZ-536 | Argon2id password hashing     | AZ-530 | 5/5 | Done   |
+| AZ-537 | Login rate-limit + lockout    | AZ-530 | 6/6 | Done   |
+| AZ-538 | CORS HTTPS-only + HSTS        | AZ-530 | 4/4 | Done   |
+| AZ-531 | Refresh-token flow            | AZ-529 | 6/6 | Done   |
+| AZ-532 | Asymmetric signing + JWKS     | AZ-529 | 5/5 | Done   |
+| AZ-533 | Mission token for UAV         | AZ-529 | 4/4 | Done   |
+| AZ-535 | Logout + revocation surface   | AZ-529 | 4/4 | Done   |
+| AZ-534 | TOTP-based 2FA at login       | AZ-529 | 6/6 | Done   |
+
+40/40 acceptance criteria covered by E2E tests.
+
+## Test Run Results
+
+- **Final full suite**: 82 passed, 0 failed, 3 skipped — ~77 s wall time.
+- **Skipped tests** are intentional dev-env skips (per-IP rate-limit test that needs a clean limiter window the SUT doesn't expose to E2E; two upload edge-cases that require real disk pressure).
+- **Pre-existing flake** (`PasswordHashingTests.AC5_Verify_uses_constant_time_comparator_no_obvious_timing_leak`) noted in batch 3 review passed clean in the final batch-4 run.
+
+## Per-Batch Reports
+
+- `_docs/03_implementation/batch_01_cycle2_report.md` — AZ-536, AZ-537, AZ-538
+- `_docs/03_implementation/batch_02_cycle2_report.md` — AZ-531, AZ-532
+- `_docs/03_implementation/batch_03_cycle2_report.md` — AZ-535, AZ-533
+- `_docs/03_implementation/batch_04_cycle2_report.md` — AZ-534
+
+## Per-Batch Code Reviews
+
+- `_docs/03_implementation/reviews/batch_01_cycle2_review.md`
+- `_docs/03_implementation/reviews/batch_02_cycle2_review.md`
+- `_docs/03_implementation/reviews/batch_03_cycle2_review.md`
+- `_docs/03_implementation/reviews/batch_04_cycle2_review.md`
+
+All four batches landed with **PASS** or **PASS_WITH_WARNINGS** verdicts; no batch was blocked.
+
+## Carry-Over / Follow-Up Items
+
+The reviews surfaced these non-blocking items for follow-up tickets — none gate this cycle's deploy:
+
+1. **F1 (B4)** — `/sessions/mission` should now enforce `amr=mfa` (AZ-533 deferred to AZ-534; AZ-534 has shipped). Small follow-up, single-line endpoint change.
+2. **F2 (B4)** — `MfaService.TryConsumeRecoveryCode` returns `true` even when the conditional update affects 0 rows. Concurrent-double-spend window for recovery codes; low practical risk but a real correctness gap.
+3. **F3 (B4)** — Document `DataProtection:KeysFolder` operational requirement in `_docs/04_deploy/deployment_procedures.md` and emit a startup warning when running in Production with the folder unset.
+4. **F1 (B3)** — Snapshot endpoint silently clamps `since` to `now − 12 h`; add a Warning log + optional `effective_since` echo in the response.
+5. **F4 (B3)** — `MissionTokenTests.GetUserId` does an extra login (Argon2 cost) per use; minor test-time perf.
+6. **Pre-existing flake** in `PasswordHashingTests.AC5` — Argon2 verify-timing test occasionally trips under suite-level concurrency; either widen the assertion bound or warm up Argon2 with a non-test login first.
+
+## Architecture Notes
+
+- All tasks shipped against the existing two-project layout (`Azaion.AdminApi` + `Azaion.Services` + `Azaion.Common`); no new components added.
+- Single new role added (`RoleEnum.Service = 60` in batch 3) for verifier identities. Role-string parser handles it through the existing `Enum.Parse(typeof(RoleEnum), v)` converter — no migration needed for legacy data.
+- Two new SQL migrations (`09_sessions_logout_and_mission.sql`, `10_users_mfa.sql`) applied in order; `e2e/db-init/00_run_all.sh` updated. No data migration required (all new columns are nullable or carry safe defaults).
+- ASP.NET Core DataProtection is the new dependency for batch 4 (encrypts `mfa_secret` at rest). `DataProtection:KeysFolder` is the operational hook for production key persistence.
+
+## Workflow Telemetry
+
+- 42 new E2E tests added (logout/revoke/mission/MFA/refresh/JWKS/argon2/rate-limit/cors).
+- 8 task spec files moved `_docs/02_tasks/todo/` → `_docs/02_tasks/done/`.
+- Push policy for the cycle: **push_now_continue** (each batch committed + pushed before the next started).

_docs/03_implementation/reviews/batch_04_cycle2_review.md

@@ -0,0 +1,72 @@
+# Code Review Report
+
+**Batch**: 4 (cycle 2) — AZ-534 (totp_2fa_login)
+**Date**: 2026-05-14
+**Verdict**: PASS_WITH_WARNINGS
+
+## Phases Covered
+- Phase 1: Context loading (read AZ-534 spec + Program.cs / MfaService / AuthService / RefreshTokenService deltas)
+- Phase 2: Spec compliance (6/6 ACs covered, see below)
+- Phase 3: Code quality (SOLID, naming, error handling, complexity)
+- Phase 4: Security quick-scan (TOTP replay, recovery codes, encryption-at-rest, step-1 token audience pinning, AMR propagation)
+- Phase 5: Performance scan (per-login DB writes, recovery-code verification cost)
+- Phase 6: Cross-task consistency (sessions schema reused; AMR claim feeds future AZ-533 mission gate)
+- Phase 7: Architecture compliance (DI registration follows existing pattern; no new cross-component imports; ProjectReference layering respected)
+
+## AC Coverage
+
+| AC  | Test                                                                                          | Status   |
+|-----|-----------------------------------------------------------------------------------------------|----------|
+| 1   | `MfaLoginTests.AC1_Enroll_returns_secret_otpauth_qr_and_recovery_codes`                       | Covered  |
+| 2   | `MfaLoginTests.AC2_Confirm_enables_MFA`                                                       | Covered  |
+| 3   | `MfaLoginTests.AC3_Login_returns_mfa_required_then_step2_returns_tokens_with_amr_pwd_mfa`     | Covered  |
+| 4   | `MfaLoginTests.AC4_Recovery_code_works_once_then_fails`                                       | Covered  |
+| 5   | `MfaLoginTests.AC5_Disable_requires_password_and_code_then_login_returns_tokens_directly`     | Covered  |
+| 6   | `MfaLoginTests.AC6_Mfa_secret_is_encrypted_at_rest`                                           | Covered  |
+
+6 of 6 acceptance criteria covered by running tests.
+
+## Findings
+
+| # | Severity | Category        | File                                                                | Title                                                                  |
+|---|----------|-----------------|---------------------------------------------------------------------|------------------------------------------------------------------------|
+| 1 | Medium   | Spec-Gap        | `Azaion.AdminApi/Program.cs` (`/sessions/mission` endpoint)         | Cross-batch: `amr=mfa` gate on mission-issuance still a TODO          |
+| 2 | Low      | Security        | `Azaion.Services/MfaService.TryConsumeRecoveryCode`                 | Conditional update returns `true` even on 0-row write                  |
+| 3 | Low      | Operational     | `Azaion.AdminApi/Program.cs` (DataProtection block)                 | Default key-store is ephemeral inside containers                       |
+| 4 | Low      | Performance     | `Azaion.Services/MfaService.VerifyForLogin`                         | Successful login costs an extra `UPDATE users` for `mfa_last_used_window` |
+
+### Finding Details
+
+**F1: Mission-issuance MFA gate still a TODO** (Medium / Spec-Gap)
+- Location: `Azaion.AdminApi/Program.cs` — `/sessions/mission` endpoint, line ~489
+- Description: Batch 3 deferred the `RequireClaim("amr","mfa")` gate on `/sessions/mission` with the comment *"until MFA ships this is a code comment per the AZ-533 spec, not an enforced gate."* MFA has now shipped. The endpoint is still gated only on `RequireAuthorization` — any password-only access token can issue a mission token.
+- Suggestion: small follow-up ticket (or amendment to AZ-533) — add `.RequireAuthorization(p => p.RequireClaim("amr", "mfa"))` (or a named policy) and remove the TODO. Intentionally not done in this batch (scope discipline: AZ-534 spec does not list it as an AC).
+- Task: AZ-533 / AZ-534 follow-up
+
+**F2: Recovery-code conditional update bypass** (Low / Security)
+- Location: `Azaion.Services/MfaService.TryConsumeRecoveryCode`, line ~316–322
+- Description: The conditional `WHERE id = @userId AND mfa_recovery_codes = @priorJson` defends against the read-modify-write race between two concurrent `/login/mfa` calls submitting the same recovery code. But we don't check the affected row count — both flows hit `auditLog.RecordMfaRecoveryUsed` and return tokens. Only the *write* of the consumed-code state is single-shot; the *outcome* (token issuance) double-spends. Practical risk is low (recovery codes are 80-bit secrets, not user-known; concurrent same-code attacks require an attacker who already has the code), but it's a real correctness gap.
+- Suggestion: capture the LinqToDB `UpdateAsync` return value and treat 0 as "lost the race; reject this attempt". Adds one branch.
+- Task: AZ-534 follow-up
+
+**F3: DataProtection key-store ephemeral by default** (Low / Operational)
+- Location: `Azaion.AdminApi/Program.cs` — DataProtection configuration block, line ~151
+- Description: When `DataProtection:KeysFolder` is not set, ASP.NET Core defaults to `~/.aspnet/DataProtection-Keys` inside the container. On container restart that path is lost → every previously-encrypted `mfa_secret` becomes unrecoverable, locking out every enrolled user. The Program.cs comment is explicit about it ("Production deployments MUST set..."), and the SUT log even prints the framework's own warning. Ops needs the runbook entry, not just a code comment.
+- Suggestion: (a) document `DataProtection:KeysFolder` in `_docs/04_deploy/deployment_procedures.md` next to the JWKS key-rotation section; (b) add a startup warning when running in Production *and* the folder is unset.
+- Task: AZ-534 follow-up (operational)
+
+**F4: Successful login costs an extra UPDATE** (Low / Performance)
+- Location: `Azaion.Services/MfaService.VerifyForLogin`, line ~260–264
+- Description: Every TOTP success persists `mfa_last_used_window` (RFC 6238 replay defence). One `UPDATE users` per `/login/mfa` for MFA-enabled users. At admin-only MFA scope (handful of accounts) this is a non-issue. If MFA is later mandated for `Role IN (Admin, ApiAdmin, ResourceUploader)` and the fleet grows, watch the `users` row write rate.
+- Suggestion: monitor only — no change today.
+- Task: AZ-534 (informational)
+
+## Notes (non-blocking)
+
+- The AC-5 test deliberately uses a **recovery code** for the mid-test login so the TOTP window stays unused for the subsequent `/disable` call. Without that, the same code presented twice within 30 s would be rejected by the (correct) replay-window check, producing a flaky 31-second `Task.Delay`. Worth highlighting in case anyone refactors that test later.
+- `User.MfaRecoveryCodes` mapped in `AzaionDbSchemaHolder` with `DataType.BinaryJson` so inserts work; the disable path uses raw SQL because LinqToDB doesn't carry the type annotation through to literal `null` values in update-set expressions. Captured in the batch report (Decision #6).
+- `RoleEnum.Service = 60` from batch 3 is unaffected by this change. No new role added.
+
+## Verdict Rationale
+
+PASS_WITH_WARNINGS — 6/6 ACs pass; full E2E suite green (82/82 enabled tests). Architecture is consistent with the existing `Auth*Service`/`SessionService` separation, DI registration follows the existing pattern, and the `amr` claim now feeds correctly through `/login` → session → `/token/refresh`. The findings are deferred-improvement items, not blocking defects.

_docs/_autodev_state.md

@@ -2,13 +2,13 @@
 
 ## Current Step
 flow: existing-code
-step: 10
+step: 11
-name: Implement
+name: Run Tests
-status: in_progress
+status: not_started
 sub_step:
-  phase: 6
+  phase: 0
-  name: implement-tasks
+  name: awaiting-invocation
-  detail: "batch 4 of 4 — AZ-529 epic (AZ-534)"
+  detail: ""
 retry_count: 0
 cycle: 2
 tracker: jira

e2e/Azaion.E2E/Azaion.E2E.csproj

@@ -17,6 +17,7 @@
     <PackageReference Include="Microsoft.Extensions.Options.DataAnnotations" Version="10.0.0" />
     <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.11.1" />
     <PackageReference Include="Npgsql" Version="10.0.1" />
+    <PackageReference Include="Otp.NET" Version="1.4.1" />
     <PackageReference Include="System.IdentityModel.Tokens.Jwt" Version="8.6.1" />
     <PackageReference Include="xunit" Version="2.9.2" />
     <PackageReference Include="xunit.runner.visualstudio" Version="2.8.2">

e2e/Azaion.E2E/Helpers/DbHelper.cs

@@ -241,6 +241,32 @@ public sealed class DbHelper
             rd.IsDBNull(2) ? null : rd.GetGuid(2));
     }
 
+    /// <summary>
+    /// AZ-534 — read mfa_secret raw to assert it's encrypted at rest.
+    /// </summary>
+    public async Task<string?> GetMfaSecretRaw(string email, CancellationToken ct = default)
+    {
+        await using var conn = await OpenAsync(ct);
+        await using var cmd = new NpgsqlCommand(
+            "SELECT mfa_secret FROM public.users WHERE email = @e", conn);
+        cmd.Parameters.AddWithValue("e", email);
+        var raw = await cmd.ExecuteScalarAsync(ct);
+        return raw is null or DBNull ? null : (string)raw;
+    }
+
+    /// <summary>
+    /// AZ-534 — read mfa_enabled flag.
+    /// </summary>
+    public async Task<bool> GetMfaEnabled(string email, CancellationToken ct = default)
+    {
+        await using var conn = await OpenAsync(ct);
+        await using var cmd = new NpgsqlCommand(
+            "SELECT mfa_enabled FROM public.users WHERE email = @e", conn);
+        cmd.Parameters.AddWithValue("e", email);
+        var raw = await cmd.ExecuteScalarAsync(ct);
+        return raw is bool b && b;
+    }
+
     /// <summary>
     /// AZ-535 — promote a user to <c>Service</c> role so they can read /sessions/revoked.
     /// </summary>

e2e/Azaion.E2E/Tests/MfaLoginTests.cs

@@ -0,0 +1,268 @@
+using System.IdentityModel.Tokens.Jwt;
+using System.Net;
+using System.Net.Http.Headers;
+using System.Net.Http.Json;
+using System.Text.Json;
+using Azaion.E2E.Helpers;
+using FluentAssertions;
+using OtpNet;
+using Xunit;
+
+namespace Azaion.E2E.Tests;
+
+/// <summary>
+/// AZ-534 — TOTP enrollment + step-2 login + recovery codes.
+/// Tests compute valid TOTP codes locally from the secret returned by /enroll
+/// (same pattern any TOTP authenticator app uses) so the test doesn't depend on
+/// wall-clock manipulation.
+/// </summary>
+public class MfaLoginTests : IClassFixture<TestFixture>
+{
+    private readonly TestFixture _fixture;
+
+    public MfaLoginTests(TestFixture fixture) => _fixture = fixture;
+
+    private async Task<(string Email, string Password)> SeedUser(string suffix)
+    {
+        var email    = $"mfa-{suffix}-{Guid.NewGuid():N}@e2e.local";
+        var password = "Mfa1234567890ABC";
+        using var admin = _fixture.CreateAuthenticatedClient(_fixture.AdminToken);
+        using var resp = await admin.PostAsync("/users", new { email, password, role = 10 });
+        resp.StatusCode.Should().Be(HttpStatusCode.OK);
+        return (email, password);
+    }
+
+    private async Task CleanupUser(string email)
+    {
+        await _fixture.Db.DeleteSessionsFor(email);
+        await _fixture.Db.DeleteAuditEventsFor(email);
+        await _fixture.Db.DeleteUser(email);
+    }
+
+    private static string ComputeCode(string secretBase32) =>
+        new Totp(Base32Encoding.ToBytes(secretBase32)).ComputeTotp();
+
+    private async Task<EnrollResponse> EnrollUser(string email, string password)
+    {
+        using var client = _fixture.CreateHttpClient();
+        var api = new ApiClient(client);
+        var login = await api.LoginFullAsync(email, password);
+        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", login.AccessToken);
+
+        using var enrollResp = await client.PostAsJsonAsync("/users/me/mfa/enroll", new { password });
+        enrollResp.StatusCode.Should().Be(HttpStatusCode.OK);
+        var enroll = await enrollResp.Content.ReadFromJsonAsync<EnrollResponse>();
+        enroll.Should().NotBeNull();
+        return enroll!;
+    }
+
+    private async Task ConfirmEnroll(string email, string password, string secret)
+    {
+        using var client = _fixture.CreateHttpClient();
+        var api = new ApiClient(client);
+        var login = await api.LoginFullAsync(email, password);
+        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", login.AccessToken);
+
+        using var resp = await client.PostAsJsonAsync("/users/me/mfa/confirm", new { code = ComputeCode(secret) });
+        resp.StatusCode.Should().Be(HttpStatusCode.OK);
+    }
+
+    [Fact]
+    public async Task AC1_Enroll_returns_secret_otpauth_qr_and_recovery_codes()
+    {
+        var (email, password) = await SeedUser("ac1");
+        try
+        {
+            var enroll = await EnrollUser(email, password);
+
+            // Assert
+            enroll.Secret.Length.Should().Be(32, "RFC 6238 §3 / 160-bit base32 = 32 chars");
+            enroll.OtpAuthUrl.Should().StartWith("otpauth://totp/");
+            enroll.OtpAuthUrl.Should().Contain($"secret={enroll.Secret}");
+            enroll.QrPngBase64.Length.Should().BeGreaterThan(0);
+            // First 8 base64 bytes of a PNG decode to the PNG signature \x89PNG\r\n\x1a\n.
+            var pngBytes = Convert.FromBase64String(enroll.QrPngBase64);
+            pngBytes[..8].Should().Equal([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]);
+
+            enroll.RecoveryCodes.Length.Should().Be(10);
+            enroll.RecoveryCodes.Should().AllSatisfy(c => c.Length.Should().BeGreaterThanOrEqualTo(12));
+
+            // DB state: enabled=false until confirm
+            (await _fixture.Db.GetMfaEnabled(email)).Should().BeFalse("AC-1 — confirm step flips this");
+        }
+        finally { await CleanupUser(email); }
+    }
+
+    [Fact]
+    public async Task AC2_Confirm_enables_MFA()
+    {
+        var (email, password) = await SeedUser("ac2");
+        try
+        {
+            var enroll = await EnrollUser(email, password);
+            await ConfirmEnroll(email, password, enroll.Secret);
+            (await _fixture.Db.GetMfaEnabled(email)).Should().BeTrue();
+        }
+        finally { await CleanupUser(email); }
+    }
+
+    [Fact]
+    public async Task AC3_Login_returns_mfa_required_then_step2_returns_tokens_with_amr_pwd_mfa()
+    {
+        var (email, password) = await SeedUser("ac3");
+        try
+        {
+            var enroll = await EnrollUser(email, password);
+            await ConfirmEnroll(email, password, enroll.Secret);
+
+            using var client = _fixture.CreateHttpClient();
+
+            // Step 1 — /login
+            using var step1 = await client.PostAsJsonAsync("/login", new { email, password });
+            step1.StatusCode.Should().Be(HttpStatusCode.OK);
+            var step1Body = await step1.Content.ReadFromJsonAsync<MfaRequired>();
+            step1Body!.IsMfaRequired.Should().BeTrue();
+            step1Body.MfaToken.Length.Should().BeGreaterThan(0);
+            step1Body.ExpiresIn.Should().Be(300);
+
+            // Step 2 — /login/mfa
+            using var step2 = await client.PostAsJsonAsync("/login/mfa", new
+            {
+                mfaToken = step1Body.MfaToken,
+                code     = ComputeCode(enroll.Secret),
+            });
+            step2.StatusCode.Should().Be(HttpStatusCode.OK);
+            var tokens = await step2.Content.ReadFromJsonAsync<ApiClient.LoginResponse>();
+            tokens!.AccessToken.Length.Should().BeGreaterThan(0);
+
+            // Assert amr=[pwd,mfa] on the access token
+            var jwt = new JwtSecurityTokenHandler().ReadJwtToken(tokens.AccessToken);
+            var amrs = jwt.Claims.Where(c => c.Type == "amr").Select(c => c.Value).ToList();
+            amrs.Should().Contain("pwd");
+            amrs.Should().Contain("mfa");
+            amrs.Should().NotContain("recovery");
+        }
+        finally { await CleanupUser(email); }
+    }
+
+    [Fact]
+    public async Task AC4_Recovery_code_works_once_then_fails()
+    {
+        var (email, password) = await SeedUser("ac4");
+        try
+        {
+            var enroll = await EnrollUser(email, password);
+            await ConfirmEnroll(email, password, enroll.Secret);
+
+            var recoveryCode = enroll.RecoveryCodes[0];
+
+            using var client = _fixture.CreateHttpClient();
+
+            // First use — succeeds, amr=[pwd,mfa,recovery]
+            using var step1a = await client.PostAsJsonAsync("/login", new { email, password });
+            var step1aBody = (await step1a.Content.ReadFromJsonAsync<MfaRequired>())!;
+            using var step2a = await client.PostAsJsonAsync("/login/mfa", new
+            {
+                mfaToken = step1aBody.MfaToken,
+                code     = recoveryCode,
+            });
+            step2a.StatusCode.Should().Be(HttpStatusCode.OK);
+            var tokens = await step2a.Content.ReadFromJsonAsync<ApiClient.LoginResponse>();
+            var jwt = new JwtSecurityTokenHandler().ReadJwtToken(tokens!.AccessToken);
+            var amrs = jwt.Claims.Where(c => c.Type == "amr").Select(c => c.Value).ToList();
+            amrs.Should().Contain("recovery");
+
+            // Second use of same recovery code — fails
+            using var step1b = await client.PostAsJsonAsync("/login", new { email, password });
+            var step1bBody = (await step1b.Content.ReadFromJsonAsync<MfaRequired>())!;
+            using var step2b = await client.PostAsJsonAsync("/login/mfa", new
+            {
+                mfaToken = step1bBody.MfaToken,
+                code     = recoveryCode,
+            });
+            step2b.StatusCode.Should().Be(HttpStatusCode.Unauthorized);
+        }
+        finally { await CleanupUser(email); }
+    }
+
+    [Fact]
+    public async Task AC5_Disable_requires_password_and_code_then_login_returns_tokens_directly()
+    {
+        var (email, password) = await SeedUser("ac5");
+        try
+        {
+            var enroll = await EnrollUser(email, password);
+            await ConfirmEnroll(email, password, enroll.Secret);
+
+            using var client = _fixture.CreateHttpClient();
+            // Need an authenticated session — log in via a RECOVERY code so the TOTP
+            // window stays "unused" and the /disable call below can present a fresh
+            // TOTP code without tripping the replay-window defense.
+            using var step1 = await client.PostAsJsonAsync("/login", new { email, password });
+            var step1Body = (await step1.Content.ReadFromJsonAsync<MfaRequired>())!;
+            using var step2 = await client.PostAsJsonAsync("/login/mfa", new
+            {
+                mfaToken = step1Body.MfaToken,
+                code     = enroll.RecoveryCodes[0],
+            });
+            var tokens = (await step2.Content.ReadFromJsonAsync<ApiClient.LoginResponse>())!;
+
+            client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", tokens.AccessToken);
+
+            using var disableResp = await client.PostAsJsonAsync("/users/me/mfa/disable", new
+            {
+                password,
+                code = ComputeCode(enroll.Secret),
+            });
+            disableResp.StatusCode.Should().Be(HttpStatusCode.OK);
+
+            // Subsequent /login should bypass step 2
+            using var freshClient = _fixture.CreateHttpClient();
+            using var directResp = await freshClient.PostAsJsonAsync("/login", new { email, password });
+            directResp.StatusCode.Should().Be(HttpStatusCode.OK);
+            var directBody = await directResp.Content.ReadAsStringAsync();
+            directBody.Should().NotContain("\"mfaRequired\":true",
+                "AC-5 — MFA-disabled login MUST NOT short-circuit through the step-1 path");
+            using var doc = JsonDocument.Parse(directBody);
+            doc.RootElement.TryGetProperty("accessToken", out _).Should().BeTrue();
+        }
+        finally { await CleanupUser(email); }
+    }
+
+    [Fact]
+    public async Task AC6_Mfa_secret_is_encrypted_at_rest()
+    {
+        var (email, password) = await SeedUser("ac6");
+        try
+        {
+            var enroll = await EnrollUser(email, password);
+
+            var raw = await _fixture.Db.GetMfaSecretRaw(email);
+            raw.Should().NotBeNull();
+            raw.Should().NotBe(enroll.Secret, "AC-6 — DB column must be ciphertext, not the plaintext base32 secret");
+            // ASP.NET DataProtection payloads are base64url and start with 'C' for the
+            // current header version (UTF-8 magic 0x09F0C9F0 base64-url-encoded). They
+            // are at least 50 chars long; the plaintext secret is exactly 32.
+            raw!.Length.Should().BeGreaterThan(40, "ciphertext is materially longer than plaintext");
+        }
+        finally { await CleanupUser(email); }
+    }
+
+    private sealed class EnrollResponse
+    {
+        public string   Secret        { get; init; } = "";
+        public string   OtpAuthUrl    { get; init; } = "";
+        public string   QrPngBase64   { get; init; } = "";
+        public string[] RecoveryCodes { get; init; } = [];
+    }
+
+    private sealed class MfaRequired
+    {
+        // Property name pinned to the field carried in /login JSON (mfaRequired); class
+        // is "MfaRequired" so we use [JsonPropertyName] to disambiguate from the type.
+        [System.Text.Json.Serialization.JsonPropertyName("mfaRequired")]
+        public bool   IsMfaRequired { get; init; }
+        public string MfaToken      { get; init; } = "";
+        public int    ExpiresIn     { get; init; }
+    }
+}

e2e/db-init/00_run_all.sh

@@ -10,4 +10,5 @@ psql -v ON_ERROR_STOP=1 -U "$POSTGRES_USER" -d azaion -f "$SQL_DIR/06_users_emai
 psql -v ON_ERROR_STOP=1 -U "$POSTGRES_USER" -d azaion -f "$SQL_DIR/07_auth_lockout_and_audit.sql"
 psql -v ON_ERROR_STOP=1 -U "$POSTGRES_USER" -d azaion -f "$SQL_DIR/08_sessions.sql"
 psql -v ON_ERROR_STOP=1 -U "$POSTGRES_USER" -d azaion -f "$SQL_DIR/09_sessions_logout_and_mission.sql"
+psql -v ON_ERROR_STOP=1 -U "$POSTGRES_USER" -d azaion -f "$SQL_DIR/10_users_mfa.sql"
 psql -v ON_ERROR_STOP=1 -U "$POSTGRES_USER" -d azaion -f /opt/test-seed.sql

env/db/10_users_mfa.sql

@@ -0,0 +1,28 @@
+-- AZ-534 (Epic AZ-529): TOTP-based 2FA at credential login.
+--
+-- mfa_secret holds the base32 TOTP shared secret encrypted at rest via the
+-- ASP.NET Core IDataProtector ("Azaion.Mfa.Secret" purpose). The column type
+-- stays text because the protected payload is base64.
+--
+-- mfa_recovery_codes is a JSONB array of objects { hash: <argon2id>, used_at: <ts|null> }.
+-- One-time-use is enforced by setting used_at on consumption; the row is rewritten
+-- transactionally with the rest of the login.
+--
+-- mfa_last_used_window prevents replay of a TOTP code within its 30-second
+-- step. We persist the last accepted RFC 6238 time-step counter (long); a
+-- re-presented code matches that counter and is rejected.
+
+ALTER TABLE public.users
+    ADD COLUMN IF NOT EXISTS mfa_enabled          boolean   NOT NULL DEFAULT false,
+    ADD COLUMN IF NOT EXISTS mfa_secret           text      NULL,
+    ADD COLUMN IF NOT EXISTS mfa_recovery_codes   jsonb     NULL,
+    ADD COLUMN IF NOT EXISTS mfa_enrolled_at      timestamp NULL,
+    ADD COLUMN IF NOT EXISTS mfa_last_used_window bigint    NULL;
+
+-- AZ-534 — pin the authentication-methods-reference (RFC 8176) to the session
+-- so refresh-token rotations (AZ-531) inherit the original auth strength. A user
+-- who logs in with MFA stays "amr=[pwd,mfa]" for the entire refresh chain even if
+-- they later disable MFA; conversely, enabling MFA mid-session does NOT silently
+-- upgrade the in-flight session.
+ALTER TABLE public.sessions
+    ADD COLUMN IF NOT EXISTS mfa_authenticated boolean NOT NULL DEFAULT false;