feat(auth): add trusted-device 30-day 2FA skip (backend)

Adds a "trust this device" option to the 2FA challenge: on success, mints a
random token (only its SHA-256 hash is stored), sets it as a new httpOnly,
Secure, SameSite=Strict cookie, and records a TrustedDevice row. AuthController
checks that cookie for the exact signing-in user before gating on 2FA -- a
mismatched user, expired, or revoked device falls through to the normal 2FA
prompt, never errors. TwoFactorController also exposes list/revoke/revoke-all
endpoints for managing trusted devices, scoped to the owning user.

Schema added via the existing raw-SQL reconciler (SQLite + MySQL dialects),
not EF migrations, matching this repo's established pattern.

JobTrackerApi/Controllers/AuthController.cs

@@ -1,5 +1,6 @@
 using System.Text.Json;
 using System.Security.Claims;
+using JobTrackerApi.Data;
 using JobTrackerApi.Models;
 using JobTrackerApi.Services;
 using Microsoft.AspNetCore.Authorization;
@@ -22,8 +23,9 @@ public sealed class AuthController : ControllerBase
     private readonly IMicrosoftTokenValidator _microsoftTokens;
     private readonly ILogger<AuthController> _logger;
     private readonly ITwoFactorPendingTokenService _twoFactorPending;
+    private readonly JobTrackerContext _db;
 
-    public AuthController(IConfiguration cfg, UserManager<ApplicationUser> users, ITokenService tokens, IAppEmailSender email, IGoogleTokenValidator googleTokens, IMicrosoftTokenValidator microsoftTokens, ILogger<AuthController> logger, ITwoFactorPendingTokenService twoFactorPending)
+    public AuthController(IConfiguration cfg, UserManager<ApplicationUser> users, ITokenService tokens, IAppEmailSender email, IGoogleTokenValidator googleTokens, IMicrosoftTokenValidator microsoftTokens, ILogger<AuthController> logger, ITwoFactorPendingTokenService twoFactorPending, JobTrackerContext db)
     {
         _cfg = cfg;
         _users = users;
@@ -33,6 +35,7 @@ public sealed class AuthController : ControllerBase
         _microsoftTokens = microsoftTokens;
         _logger = logger;
         _twoFactorPending = twoFactorPending;
+        _db = db;
     }
 
     [HttpGet("config")]
@@ -671,6 +674,16 @@ public sealed class AuthController : ControllerBase
     // decorative: skipping straight to AppSessionIssuer here would defeat the whole feature.
     private async Task<IActionResult> CompleteSignInAsync(ApplicationUser user, bool rememberMe, string provider, CancellationToken cancellationToken)
     {
+        // "Trust this device" cookie check happens BEFORE the 2FA gate: if it matches a
+        // non-expired row for this exact user, skip straight to a real session, same as if 2FA
+        // weren't required at all. Falls through to the normal gate for any other outcome
+        // (no cookie, wrong user, expired, revoked) -- never errors, just doesn't skip.
+        if (user.TwoFactorEnabled && await TrustedDeviceService.IsDeviceTrustedAsync(_db, Request, user.Id, cancellationToken))
+        {
+            await AppSessionIssuer.IssueAsync(Request, Response, _tokens, user, rememberMe, cancellationToken);
+            return Ok(new AuthSessionResult(true, provider));
+        }
+
         if (user.TwoFactorEnabled)
         {
             var pendingToken = _twoFactorPending.IssuePendingToken(user.Id, rememberMe);

JobTrackerApi/Controllers/TwoFactorController.cs

@@ -44,7 +44,8 @@ public sealed class TwoFactorController : ControllerBase
     public sealed record VerifySetupResult(bool Enabled, IReadOnlyList<string> RecoveryCodes);
     public sealed record StatusResult(bool Enabled, DateTimeOffset? EnabledAtUtc);
     public sealed record RecoveryCodesResult(IReadOnlyList<string> RecoveryCodes);
-    public sealed record ChallengeRequest(string PendingToken, string Code);
+    public sealed record ChallengeRequest(string PendingToken, string Code, bool TrustDevice = false);
+    public sealed record TrustedDeviceDto(int Id, string? DeviceLabel, DateTimeOffset CreatedAtUtc, DateTimeOffset LastSeenAtUtc, DateTimeOffset ExpiresAtUtc, bool IsCurrentDevice);
 
     [HttpPost("setup")]
     [Authorize(AuthenticationSchemes = "local")]
@@ -202,9 +203,74 @@ public sealed class TwoFactorController : ControllerBase
 
         _pending.Resolve(pendingToken, consume: true);
         await AppSessionIssuer.IssueAsync(Request, Response, _tokens, user, session.RememberMe, cancellationToken);
+
+        if (request.TrustDevice)
+        {
+            await TrustedDeviceService.IssueAsync(_db, Request, Response, user.Id, cancellationToken);
+        }
+
         return Ok(new AuthController.AuthSessionResult(true, "local"));
     }
 
+    [HttpGet("trusted-devices")]
+    [Authorize(AuthenticationSchemes = "local")]
+    public async Task<IActionResult> ListTrustedDevices(CancellationToken cancellationToken)
+    {
+        var user = await _users.GetUserAsync(User);
+        if (user is null) return Unauthorized();
+
+        var currentHash = TrustedDeviceService.CurrentDeviceTokenHash(Request);
+        var devices = await _db.TrustedDevices
+            .Where(x => x.UserId == user.Id)
+            .OrderByDescending(x => x.LastSeenAtUtc)
+            .Select(x => new TrustedDeviceDto(x.Id, x.DeviceLabel, x.CreatedAtUtc, x.LastSeenAtUtc, x.ExpiresAtUtc, currentHash != null && x.TokenHash == currentHash))
+            .ToListAsync(cancellationToken);
+
+        return Ok(devices);
+    }
+
+    [HttpDelete("trusted-devices/{id:int}")]
+    [Authorize(AuthenticationSchemes = "local")]
+    public async Task<IActionResult> RevokeTrustedDevice(int id, CancellationToken cancellationToken)
+    {
+        var user = await _users.GetUserAsync(User);
+        if (user is null) return Unauthorized();
+
+        var device = await _db.TrustedDevices.FirstOrDefaultAsync(x => x.Id == id && x.UserId == user.Id, cancellationToken);
+        if (device is null) return NotFound();
+
+        var currentHash = TrustedDeviceService.CurrentDeviceTokenHash(Request);
+        var isCurrentDevice = currentHash != null && string.Equals(device.TokenHash, currentHash, StringComparison.Ordinal);
+
+        _db.TrustedDevices.Remove(device);
+        await _db.SaveChangesAsync(cancellationToken);
+
+        if (isCurrentDevice)
+        {
+            TrustedDeviceService.ClearCookie(Request, Response);
+        }
+
+        return NoContent();
+    }
+
+    [HttpPost("trusted-devices/revoke-all")]
+    [Authorize(AuthenticationSchemes = "local")]
+    public async Task<IActionResult> RevokeAllTrustedDevices(CancellationToken cancellationToken)
+    {
+        var user = await _users.GetUserAsync(User);
+        if (user is null) return Unauthorized();
+
+        var devices = await _db.TrustedDevices.Where(x => x.UserId == user.Id).ToListAsync(cancellationToken);
+        if (devices.Count > 0)
+        {
+            _db.TrustedDevices.RemoveRange(devices);
+            await _db.SaveChangesAsync(cancellationToken);
+        }
+
+        TrustedDeviceService.ClearCookie(Request, Response);
+        return NoContent();
+    }
+
     private static bool VerifyCode(string base32Secret, string? code)
     {
         code = (code ?? string.Empty).Trim();

JobTrackerApi/Services/AuthSessionOptions.cs

@@ -7,6 +7,7 @@ public static class AuthSessionOptions
     public const string SessionCookieName = "jobtracker_auth";
     public const string CsrfCookieName = "XSRF-TOKEN";
     public const string CsrfHeaderName = "X-CSRF-TOKEN";
+    public const string TrustedDeviceCookieName = "jobtracker_td";
 
     public static CookieOptions BuildSessionCookie(bool persistent, bool secure)
     {
@@ -75,4 +76,35 @@ public static class AuthSessionOptions
             MaxAge = TimeSpan.Zero,
         };
     }
+
+    // Stricter than the session cookie (SameSite=Strict, never HttpOnly=false): this cookie's
+    // only job is "skip the 2FA prompt", so it must never be readable by JS and should not even
+    // be sent on cross-site navigations.
+    public static CookieOptions BuildTrustedDeviceCookie(bool secure)
+    {
+        return new CookieOptions
+        {
+            HttpOnly = true,
+            IsEssential = true,
+            SameSite = SameSiteMode.Strict,
+            Secure = secure,
+            Path = "/",
+            Expires = DateTimeOffset.UtcNow.AddDays(30),
+            MaxAge = TimeSpan.FromDays(30),
+        };
+    }
+
+    public static CookieOptions BuildExpiredTrustedDeviceCookie(bool secure)
+    {
+        return new CookieOptions
+        {
+            HttpOnly = true,
+            IsEssential = true,
+            SameSite = SameSiteMode.Strict,
+            Secure = secure,
+            Path = "/",
+            Expires = DateTimeOffset.UnixEpoch,
+            MaxAge = TimeSpan.Zero,
+        };
+    }
 }

JobTrackerApi/Services/StartupInitializationExtensions.cs

@@ -647,11 +647,30 @@ public static class StartupInitializationExtensions
                     Exec(c, """CREATE INDEX IF NOT EXISTS "IX_TwoFactorRecoveryCodes_UserId_UsedAtUtc" ON "TwoFactorRecoveryCodes" ("UserId", "UsedAtUtc");""");
                 }
 
+                static void EnsureTrustedDevicesTable(DbConnection c)
+                {
+                    Exec(c, """
+        CREATE TABLE IF NOT EXISTS "TrustedDevices" (
+            "Id" INTEGER NOT NULL CONSTRAINT "PK_TrustedDevices" PRIMARY KEY AUTOINCREMENT,
+            "UserId" TEXT NOT NULL,
+            "TokenHash" TEXT NOT NULL,
+            "DeviceLabel" TEXT NULL,
+            "CreatedAtUtc" TEXT NOT NULL,
+            "LastSeenAtUtc" TEXT NOT NULL,
+            "ExpiresAtUtc" TEXT NOT NULL
+        );
+        """);
+
+                    Exec(c, """CREATE INDEX IF NOT EXISTS "IX_TrustedDevices_UserId" ON "TrustedDevices" ("UserId");""");
+                    Exec(c, """CREATE INDEX IF NOT EXISTS "IX_TrustedDevices_TokenHash" ON "TrustedDevices" ("TokenHash");""");
+                }
+
                 EnsureGmailConnectionsTable(conn);
                 EnsureMicrosoftGraphConnectionsTable(conn);
                 EnsureImapConnectionsTable(conn);
                 EnsureCvTables(conn);
                 EnsureTwoFactorRecoveryCodesTable(conn);
+                EnsureTrustedDevicesTable(conn);
 
                 // Legacy DB signature: migration history exists (AddCorrespondence applied), but 20260310195000 not recorded,
                 // and at least one of the new columns already exists.
@@ -1028,6 +1047,38 @@ public static class StartupInitializationExtensions
                         cmd.ExecuteNonQuery();
                     }
 
+                    if (!HasMySqlTable(conn, "TrustedDevices"))
+                    {
+                        using var cmd = conn.CreateCommand();
+                        cmd.CommandText = @"CREATE TABLE IF NOT EXISTS `TrustedDevices` (
+        `Id` int NOT NULL AUTO_INCREMENT,
+        `UserId` varchar(255) NOT NULL,
+        `TokenHash` varchar(255) NOT NULL,
+        `DeviceLabel` varchar(255) NULL,
+        `CreatedAtUtc` datetime(6) NOT NULL,
+        `LastSeenAtUtc` datetime(6) NOT NULL,
+        `ExpiresAtUtc` datetime(6) NOT NULL,
+        PRIMARY KEY (`Id`)
+        );";
+                        cmd.ExecuteNonQuery();
+                    }
+
+                    EnsureMySqlAutoIncrementPrimaryKey(conn, "TrustedDevices", "Id");
+
+                    if (!MySqlIndexExists(conn, "TrustedDevices", "IX_TrustedDevices_UserId"))
+                    {
+                        using var cmd = conn.CreateCommand();
+                        cmd.CommandText = "CREATE INDEX `IX_TrustedDevices_UserId` ON `TrustedDevices` (`UserId`);";
+                        cmd.ExecuteNonQuery();
+                    }
+
+                    if (!MySqlIndexExists(conn, "TrustedDevices", "IX_TrustedDevices_TokenHash"))
+                    {
+                        using var cmd = conn.CreateCommand();
+                        cmd.CommandText = "CREATE INDEX `IX_TrustedDevices_TokenHash` ON `TrustedDevices` (`TokenHash`);";
+                        cmd.ExecuteNonQuery();
+                    }
+
                     if (!MySqlIndexExists(conn, "Companies", "IX_Companies_OwnerUserId"))
                     {
                         using var cmd = conn.CreateCommand();

JobTrackerApi/Services/TrustedDeviceService.cs

@@ -0,0 +1,111 @@
+using System.Security.Cryptography;
+using System.Text;
+using JobTrackerApi.Data;
+using JobTrackerApi.Models;
+using Microsoft.AspNetCore.Http;
+using Microsoft.EntityFrameworkCore;
+
+namespace JobTrackerApi.Services;
+
+// "Trust this device for 30 days" -- lets a 2FA challenge be skipped on the same browser for a
+// month. Shared by AuthController (checks the cookie before gating on 2FA) and
+// TwoFactorController (issues/lists/revokes the cookie's backing row). Never stores the
+// plaintext token, only its SHA-256 hash.
+public static class TrustedDeviceService
+{
+    private static readonly TimeSpan Lifetime = TimeSpan.FromDays(30);
+
+    // Only returns true (and thus skips 2FA) when the cookie's hash matches a non-expired row
+    // for THIS SPECIFIC user -- UserId is part of the DB query itself, not a check applied
+    // after the fact, so a trusted-device cookie minted for user A can never skip 2FA for user
+    // B even if somehow presented on their request.
+    public static async Task<bool> IsDeviceTrustedAsync(JobTrackerContext db, HttpRequest request, string userId, CancellationToken cancellationToken)
+    {
+        var token = request.Cookies[AuthSessionOptions.TrustedDeviceCookieName];
+        if (string.IsNullOrWhiteSpace(token)) return false;
+
+        var hash = HashToken(token);
+        var now = DateTimeOffset.UtcNow;
+        var match = await db.TrustedDevices
+            .IgnoreQueryFilters()
+            .FirstOrDefaultAsync(x => x.UserId == userId && x.TokenHash == hash && x.ExpiresAtUtc > now, cancellationToken);
+        if (match is null) return false;
+
+        match.LastSeenAtUtc = now;
+        await db.SaveChangesAsync(cancellationToken);
+        return true;
+    }
+
+    public static async Task IssueAsync(JobTrackerContext db, HttpRequest request, HttpResponse response, string userId, CancellationToken cancellationToken)
+    {
+        var token = Convert.ToHexString(RandomNumberGenerator.GetBytes(32)).ToLowerInvariant();
+        var now = DateTimeOffset.UtcNow;
+
+        db.TrustedDevices.Add(new TrustedDevice
+        {
+            UserId = userId,
+            TokenHash = HashToken(token),
+            DeviceLabel = DescribeUserAgent(request.Headers["User-Agent"].ToString()),
+            CreatedAtUtc = now,
+            LastSeenAtUtc = now,
+            ExpiresAtUtc = now.Add(Lifetime),
+        });
+        await db.SaveChangesAsync(cancellationToken);
+
+        var secure = request.IsHttps || string.Equals(request.Headers["X-Forwarded-Proto"], "https", StringComparison.OrdinalIgnoreCase);
+        response.Cookies.Append(AuthSessionOptions.TrustedDeviceCookieName, token, AuthSessionOptions.BuildTrustedDeviceCookie(secure));
+    }
+
+    public static void ClearCookie(HttpRequest request, HttpResponse response)
+    {
+        var secure = request.IsHttps || string.Equals(request.Headers["X-Forwarded-Proto"], "https", StringComparison.OrdinalIgnoreCase);
+        response.Cookies.Delete(AuthSessionOptions.TrustedDeviceCookieName, AuthSessionOptions.BuildExpiredTrustedDeviceCookie(secure));
+    }
+
+    // Used to flag "this device" in the trusted-devices list without ever sending a token or
+    // hash to the client -- just a boolean per row.
+    public static string? CurrentDeviceTokenHash(HttpRequest request)
+    {
+        var token = request.Cookies[AuthSessionOptions.TrustedDeviceCookieName];
+        return string.IsNullOrWhiteSpace(token) ? null : HashToken(token);
+    }
+
+    public static string HashToken(string token)
+    {
+        return Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(token.Trim()))).ToLowerInvariant();
+    }
+
+    private static readonly (string Needle, string Label)[] BrowserMarkers =
+    {
+        ("Edg/", "Edge"),
+        ("OPR/", "Opera"),
+        ("Chrome/", "Chrome"),
+        ("Firefox/", "Firefox"),
+        ("Safari/", "Safari"),
+    };
+
+    private static readonly (string Needle, string Label)[] OsMarkers =
+    {
+        ("Windows", "Windows"),
+        ("Mac OS X", "Mac"),
+        ("iPhone", "iOS"),
+        ("iPad", "iOS"),
+        ("Android", "Android"),
+        ("Linux", "Linux"),
+    };
+
+    // ponytail: substring sniffing, not a real UA parser -- this only feeds a display label in
+    // a security-settings list ("Chrome on Windows"), nothing security-relevant depends on it.
+    private static string? DescribeUserAgent(string? userAgent)
+    {
+        if (string.IsNullOrWhiteSpace(userAgent)) return null;
+
+        var browser = BrowserMarkers.FirstOrDefault(m => userAgent.Contains(m.Needle, StringComparison.Ordinal)).Label;
+        var os = OsMarkers.FirstOrDefault(m => userAgent.Contains(m.Needle, StringComparison.Ordinal)).Label;
+
+        if (browser is null && os is null) return userAgent.Length > 80 ? userAgent[..80] : userAgent;
+        if (browser is null) return os;
+        if (os is null) return browser;
+        return $"{browser} on {os}";
+    }
+}