v1.3.0 — 2FA-Login-Challenge

Mini-Sprint A des 2FA-Vollausbaus. Apps mit aktivem TOTP-2FA können
sich nativ einloggen. Komplett additiv.

AuthClient.Status um .twoFactorRequired(token, methods, email)
erweitert. signIn() erkennt automatisch den Server-Pfad
{twoFactorRequired: true, ...} und routet zum neuen Status.

Neue Methoden in AuthClient+Account:
- verifyTotp(code:trustDevice:) — 6-stellige Codes aus Authenticator-
  App. Bei Erfolg .signedIn, bei Fehler bleibt Status im Challenge
  (User kann retry mit anderem Code).
- verifyBackupCode(code:trustDevice:) — einmalige Codes als Fallback.

Wire-Format: Client schickt {code, twoFactorToken, trustDevice} an
/api/v1/auth/two-factor/verify-{totp,backup-code}. Server (mana-auth)
re-injectet den twoFactorToken als better-auth.two_factor-Cookie und
delegiert an Better Auths Plugin.

5 neue Tests, 59/59 grün.

Setzt mana-auth-Server mit den entsprechenden Custom-Endpoints
voraus — siehe gleichzeitiger Commit im mana-Repo.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Sources/ManaCore/Auth/AuthClient+Account.swift

@@ -388,3 +388,96 @@ private struct ChangePasswordRequest: Encodable {
 private struct DeleteAccountRequest: Encodable {
     let password: String
 }
+
+// MARK: - Two-Factor (Login-Challenge)
+
+public extension AuthClient {
+    /// Verifiziert einen TOTP-Code im 2FA-Login-Flow. Vorbedingung:
+    /// Status ist ``Status/twoFactorRequired(token:methods:email:)``
+    /// (typisch nach `signIn(...)`).
+    ///
+    /// Bei Erfolg setzt der Server die Session, ManaCore persistiert
+    /// Tokens und der Status wird `.signedIn(email:)`.
+    ///
+    /// - Parameters:
+    ///   - code: 6-stelliger TOTP-Code aus der Authenticator-App.
+    ///   - trustDevice: Wenn `true`, setzt der Server einen
+    ///     `trust_device`-Cookie. Bei Native heute ohne Effekt
+    ///     (Cookies werden nicht persistiert) — wir spiegeln das Flag
+    ///     trotzdem für künftige Erweiterungen.
+    ///
+    /// - Throws: ``AuthError/twoFactorFailed`` bei falschem Code,
+    ///   ``AuthError/tokenExpired`` wenn der Challenge-Token alt ist,
+    ///   plus Standard-Netzwerk-Fehler.
+    func verifyTotp(code: String, trustDevice: Bool = false) async throws {
+        try await verifyTwoFactor(
+            path: "/api/v1/auth/two-factor/verify-totp",
+            code: code,
+            trustDevice: trustDevice
+        )
+    }
+
+    /// Verifiziert einen Backup-Code im 2FA-Login-Flow. Same Pre-/
+    /// Postconditions wie ``verifyTotp(code:trustDevice:)`` — der
+    /// Server entscheidet anhand des Endpoints, welches Verfahren er
+    /// nutzt. Backup-Codes werden vom Server beim Setup generiert
+    /// und einmalig konsumiert.
+    func verifyBackupCode(code: String, trustDevice: Bool = false) async throws {
+        try await verifyTwoFactor(
+            path: "/api/v1/auth/two-factor/verify-backup-code",
+            code: code,
+            trustDevice: trustDevice
+        )
+    }
+
+    private func verifyTwoFactor(
+        path: String,
+        code: String,
+        trustDevice: Bool
+    ) async throws {
+        guard case let .twoFactorRequired(token, _, email) = status else {
+            throw AuthError.validation(
+                message: "Kein 2FA-Challenge aktiv — verifyTotp setzt eine vorherige signIn-Antwort mit .twoFactorRequired voraus"
+            )
+        }
+        guard !code.isEmpty else {
+            throw AuthError.validation(message: "Code ist erforderlich")
+        }
+
+        let body = TwoFactorVerifyRequest(
+            code: code,
+            twoFactorToken: token,
+            trustDevice: trustDevice
+        )
+        let (data, http) = try await postJSON(path: path, body: body)
+        guard http.statusCode == 200 else {
+            throw AuthError.classify(
+                status: http.statusCode,
+                data: data,
+                retryAfterHeader: http.retryAfterSeconds
+            )
+        }
+
+        let token2 = try JSONDecoder().decode(TwoFactorVerifyResponse.self, from: data)
+        guard let access = token2.accessToken, let refresh = token2.refreshToken else {
+            // Server hat 200 zurück, aber keine Tokens. Sollte nicht
+            // passieren — UI bleibt im 2FA-Required-Zustand.
+            throw AuthError.decoding("Tokens fehlen in 2FA-Verify-Antwort")
+        }
+
+        try persistSession(email: email, accessToken: access, refreshToken: refresh)
+        CoreLog.auth.info("2FA verify successful — signed in")
+    }
+}
+
+private struct TwoFactorVerifyRequest: Encodable {
+    let code: String
+    let twoFactorToken: String
+    let trustDevice: Bool
+}
+
+private struct TwoFactorVerifyResponse: Decodable {
+    let success: Bool?
+    let accessToken: String?
+    let refreshToken: String?
+}

Sources/ManaCore/Auth/AuthClient.swift

@@ -28,6 +28,14 @@ public final class AuthClient {
         /// Status erreichbar; schreibende Endpoints nicht.
         case guest(id: String)
         case signingIn
+        /// Sign-In war erfolgreich aber der Account hat 2FA aktiviert.
+        /// UI fragt nun den TOTP-Code (oder einen Backup-Code) ab und
+        /// ruft `verifyTotp(code:trustDevice:)` / `verifyBackupCode(...)`
+        /// mit dem hier gespeicherten Token auf.
+        ///
+        /// `token` ist der Better-Auth-`two_factor`-Cookie-Wert, vom
+        /// Server in der Login-Response als `twoFactorToken` mitgeliefert.
+        case twoFactorRequired(token: String, methods: [String], email: String)
         case signedIn(email: String)
         case error(String)
     }
@@ -160,6 +168,23 @@ public final class AuthClient {
                 return
             }
 
+            // 2FA-Pfad: Server hat statt Tokens einen
+            // `twoFactorRequired`-Response geliefert. UI muss jetzt
+            // den TOTP-Code abfragen und `verifyTotp(...)` aufrufen.
+            if let twoFactor = try? JSONDecoder().decode(TwoFactorChallenge.self, from: data),
+               twoFactor.twoFactorRequired == true,
+               let tfToken = twoFactor.twoFactorToken
+            {
+                status = .twoFactorRequired(
+                    token: tfToken,
+                    methods: twoFactor.twoFactorMethods ?? ["totp"],
+                    email: trimmed
+                )
+                lastError = nil
+                CoreLog.auth.info("Sign-in needs 2FA challenge")
+                return
+            }
+
             let token = try JSONDecoder().decode(TokenResponse.self, from: data)
             try keychain.setString(token.accessToken, for: .accessToken)
             try keychain.setString(token.refreshToken, for: .refreshToken)
@@ -339,6 +364,16 @@ struct TokenResponse: Decodable {
     let refreshToken: String
 }
 
+/// 2FA-Pfad aus `/api/v1/auth/login`. Wenn `twoFactorRequired == true`,
+/// kein Token-Paar — UI muss `verifyTotp(...)` / `verifyBackupCode(...)`
+/// aufrufen. `twoFactorToken` ist der Server-injecten `two_factor`-Cookie-
+/// Wert (opaque).
+struct TwoFactorChallenge: Decodable {
+    let twoFactorRequired: Bool?
+    let twoFactorMethods: [String]?
+    let twoFactorToken: String?
+}
+
 extension HTTPURLResponse {
     /// Liest `Retry-After` als Anzahl Sekunden. Server schickt Integer-
     /// Sekunden (siehe `lib/auth-errors.ts`). HTTP-Datum-Variante wird