v1.1.0 — Account-Lifecycle in ManaCore

Phase 1 aus dem Native-Auth-Vollausbau-Plan (Option A, siehe
mana/docs/MANA_SWIFT.md). 7 neue AuthClient-Methoden für die
Account-Reise: register, forgotPassword, resetPassword,
resendVerification, changeEmail, changePassword, deleteAccount.

AuthError jetzt mit 19 präzisen Cases gespiegelt aus
AuthErrorCode in mana-auth/lib/auth-errors.ts, plus
AuthError.classify() als public Helper und Equatable-Conformance.

AuthClient.lastError ergänzt — strukturierter Fehler für
ManaAuthUI das den .emailNotVerified-Gate programmatisch braucht.

signIn und refreshAccessToken auf neue Klassifikation umgestellt.

Breaking: AuthError.serverError hat zusätzliches code:-Argument.
Apps (cards-native, memoro-native) sind bereits angepasst.

38/38 Tests grün (26 neu): AuthErrorClassifyTests deckt jeden
ErrorCode + Status-Heuristik + Retry-After ab, AuthClientAccountTests
deckt jede neue Methode via URLProtocol-Mock ab.

🤖 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

@@ -0,0 +1,385 @@
+import Foundation
+
+/// Account-Lifecycle-Methoden: Registrierung, Passwort-Reset,
+/// Email-Verifikation, Account-Management.
+///
+/// Diese Methoden ergänzen die Login-/Refresh-Maschine in ``AuthClient``
+/// um die Flows, die eine native App für eine vollständige Auth-Reise
+/// braucht (vergleichbar mit `mana-auth-web` aber API-basiert statt
+/// Cookie-basiert).
+///
+/// **Server-Endpoints (alle JSON, alle unter `/api/v1/auth/*`):**
+/// - `POST /register` — Sign-Up + (je nach Config) email-verify-required
+/// - `POST /forgot-password` — Reset-Mail anfordern (immer 200, kein Enum-Leak)
+/// - `POST /reset-password` — neues PW mit Token aus Reset-Mail
+/// - `POST /resend-verification` — Verify-Mail erneut senden
+/// - `POST /change-email` — Email ändern (verschickt Verify-Mail an neue Adresse)
+/// - `POST /change-password` — Passwort ändern (current + new)
+/// - `DELETE /account` — Account löschen (App-Store-Pflicht 5.1.1(v))
+///
+/// **Server-Limitation (Stand 2026-05-13):** `change-email`,
+/// `change-password` und `DELETE /account` forwarden Original-Request-
+/// Headers an Better Auth. Better Auth liest Session-Cookies. Der
+/// `bearer`-Plugin von Better Auth ist NICHT installiert, daher
+/// scheitern diese Endpoints heute mit reinem `Authorization: Bearer`.
+/// → Server-Fix in Phase 3 nötig (entweder `bearerPlugin()` in
+/// `better-auth.config.ts` aktivieren oder Custom-Bearer-Resolver in
+/// `mana-auth/src/routes/auth.ts` ergänzen). ManaCore sendet Bearer
+/// bereits korrekt — sobald der Server das akzeptiert, funktionieren
+/// die Methoden ohne Swift-Änderung.
+public extension AuthClient {
+    // MARK: - Registrierung
+
+    /// Registriert einen neuen Account.
+    ///
+    /// - Parameters:
+    ///   - email: Email-Adresse, wird als Login-Identifier genutzt.
+    ///   - password: Klartext-Passwort, Server hasht via Better Auth.
+    ///   - name: Anzeige-Name. Wenn nil, nutzt der Server den Email-Local-Part.
+    ///   - sourceAppUrl: Basis-URL für den Verify-Email-Klick-Redirect.
+    ///     Per-App-spezifisch — z.B. `https://cardecky.mana.how/auth/verify`
+    ///     für einen Universal-Link-Handler. Der Server hängt `?token=…` an.
+    ///
+    /// Bei Erfolg ist mit Default-Server-Config (`requireEmailVerification: true`)
+    /// noch **kein Login** gemacht — der User muss erst die Verify-Mail
+    /// klicken. Ein anschließendes `signIn(...)` mit denselben Credentials
+    /// liefert dann `.emailNotVerified` bis der Klick passiert.
+    ///
+    /// Wenn der Server in der Antwort doch Tokens schickt (kann passieren
+    /// wenn Email-Verifikation off ist), wird die Session persistiert und
+    /// der Status auf `.signedIn` gesetzt.
+    ///
+    /// - Throws: ``AuthError/emailAlreadyRegistered``,
+    ///   ``AuthError/weakPassword(message:)``, ``AuthError/signupLimitReached``,
+    ///   ``AuthError/validation(message:)`` und Netzwerk-Cases.
+    func register(
+        email: String,
+        password: String,
+        name: String? = nil,
+        sourceAppUrl: URL? = nil
+    ) async throws {
+        let trimmed = email.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty, !password.isEmpty else {
+            throw AuthError.validation(message: "Email und Passwort sind erforderlich")
+        }
+
+        let body = RegisterRequest(
+            email: trimmed,
+            password: password,
+            name: name,
+            sourceAppUrl: sourceAppUrl?.absoluteString
+        )
+        let (data, http) = try await postJSON(path: "/api/v1/auth/register", body: body)
+        guard http.statusCode == 200 else {
+            throw AuthError.classify(
+                status: http.statusCode,
+                data: data,
+                retryAfterHeader: http.retryAfterSeconds
+            )
+        }
+
+        let decoded = try JSONDecoder().decode(RegisterResponse.self, from: data)
+        if let access = decoded.accessToken, let refresh = decoded.refreshToken {
+            try persistSession(email: trimmed, accessToken: access, refreshToken: refresh)
+            CoreLog.auth.info("Register successful — auto-signed-in")
+        } else {
+            CoreLog.auth.info("Register successful — awaiting email verification")
+        }
+    }
+
+    // MARK: - Passwort-Reset
+
+    /// Fordert eine Passwort-Reset-Email an.
+    ///
+    /// Der Server antwortet **immer mit 200**, unabhängig davon ob die
+    /// Email existiert (bewusst, um User-Enumeration zu verhindern).
+    /// Die UI sollte daher generisch melden ("Wenn dein Account existiert,
+    /// ist eine Email unterwegs").
+    ///
+    /// - Parameters:
+    ///   - email: Email-Adresse des Accounts.
+    ///   - resetUniversalLink: Universal-Link der App, der die
+    ///     Reset-Seite öffnet. Z.B. `https://cardecky.mana.how/auth/reset`.
+    ///     Der Server hängt `?token=…` an und nutzt diesen Link im
+    ///     Mail-Template.
+    ///
+    /// - Throws: nur Netzwerk-Fehler. Server-Fehler werden vom Server
+    ///   geschluckt (200 trotzdem).
+    func forgotPassword(email: String, resetUniversalLink: URL) async throws {
+        let trimmed = email.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else {
+            throw AuthError.validation(message: "Email ist erforderlich")
+        }
+
+        let body = ForgotPasswordRequest(email: trimmed, redirectTo: resetUniversalLink.absoluteString)
+        let (data, http) = try await postJSON(path: "/api/v1/auth/forgot-password", body: body)
+        guard http.statusCode == 200 else {
+            throw AuthError.classify(
+                status: http.statusCode,
+                data: data,
+                retryAfterHeader: http.retryAfterSeconds
+            )
+        }
+        CoreLog.auth.info("Password reset requested")
+    }
+
+    /// Setzt das Passwort mit einem Reset-Token aus der Reset-Email.
+    ///
+    /// - Parameters:
+    ///   - token: Reset-Token aus der Email (Query-Param `?token=…`).
+    ///   - newPassword: Neues Klartext-Passwort.
+    ///
+    /// Nach Erfolg ist der User **nicht** automatisch eingeloggt — der
+    /// `signIn(...)`-Call muss separat passieren.
+    ///
+    /// - Throws: ``AuthError/tokenExpired``, ``AuthError/tokenInvalid``,
+    ///   ``AuthError/weakPassword(message:)`` und Netzwerk-Cases.
+    func resetPassword(token: String, newPassword: String) async throws {
+        guard !token.isEmpty, !newPassword.isEmpty else {
+            throw AuthError.validation(message: "Token und neues Passwort sind erforderlich")
+        }
+
+        let body = ResetPasswordRequest(token: token, newPassword: newPassword)
+        let (data, http) = try await postJSON(path: "/api/v1/auth/reset-password", body: body)
+        guard http.statusCode == 200 else {
+            throw AuthError.classify(
+                status: http.statusCode,
+                data: data,
+                retryAfterHeader: http.retryAfterSeconds
+            )
+        }
+        CoreLog.auth.info("Password reset completed")
+    }
+
+    // MARK: - Email-Verifikation
+
+    /// Sendet die Email-Verifikations-Mail erneut.
+    ///
+    /// Aufzurufen wenn `signIn(...)` mit ``AuthError/emailNotVerified``
+    /// zurückkommt — die UI bietet einen "Mail erneut senden"-Button.
+    ///
+    /// - Parameters:
+    ///   - email: Email-Adresse des Accounts.
+    ///   - sourceAppUrl: Universal-Link für den Verify-Klick. Gleiche
+    ///     Semantik wie bei ``register(email:password:name:sourceAppUrl:)``.
+    ///
+    /// - Throws: ``AuthError/notFound`` wenn die Email nicht existiert,
+    ///   ``AuthError/rateLimited(retryAfter:)`` bei zu vielen Versuchen.
+    func resendVerification(email: String, sourceAppUrl: URL? = nil) async throws {
+        let trimmed = email.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else {
+            throw AuthError.validation(message: "Email ist erforderlich")
+        }
+
+        let body = ResendVerificationRequest(
+            email: trimmed,
+            sourceAppUrl: sourceAppUrl?.absoluteString
+        )
+        let (data, http) = try await postJSON(path: "/api/v1/auth/resend-verification", body: body)
+        guard http.statusCode == 200 else {
+            throw AuthError.classify(
+                status: http.statusCode,
+                data: data,
+                retryAfterHeader: http.retryAfterSeconds
+            )
+        }
+        CoreLog.auth.info("Verification email resent")
+    }
+
+    // MARK: - Account-Management (erfordert eingeloggte Session)
+
+    /// Ändert die Email des aktuell eingeloggten Accounts.
+    ///
+    /// Der Server schickt eine Verifikations-Mail an die **neue** Adresse.
+    /// Bis der User klickt, bleibt die alte Email aktiv.
+    ///
+    /// - Parameters:
+    ///   - newEmail: Neue Email-Adresse.
+    ///   - callbackUniversalLink: Universal-Link, der nach erfolgter
+    ///     Verifikation geöffnet wird (z.B.
+    ///     `https://cardecky.mana.how/auth/email-changed`).
+    ///
+    /// - Important: Aktuell server-seitig nicht Bearer-fähig — siehe
+    ///   Doc-Header dieser Datei.
+    func changeEmail(newEmail: String, callbackUniversalLink: URL? = nil) async throws {
+        let trimmed = newEmail.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else {
+            throw AuthError.validation(message: "Neue Email ist erforderlich")
+        }
+
+        let body = ChangeEmailRequest(
+            newEmail: trimmed,
+            callbackURL: callbackUniversalLink?.absoluteString
+        )
+        let (data, http) = try await postJSON(
+            path: "/api/v1/auth/change-email",
+            body: body,
+            authenticated: true
+        )
+        guard http.statusCode == 200 else {
+            throw AuthError.classify(
+                status: http.statusCode,
+                data: data,
+                retryAfterHeader: http.retryAfterSeconds
+            )
+        }
+        CoreLog.auth.info("Email change requested — verification email sent")
+    }
+
+    /// Ändert das Passwort des aktuell eingeloggten Accounts.
+    ///
+    /// - Parameters:
+    ///   - currentPassword: Aktuelles Klartext-Passwort (Re-Auth).
+    ///   - newPassword: Neues Klartext-Passwort.
+    ///
+    /// - Important: Aktuell server-seitig nicht Bearer-fähig — siehe
+    ///   Doc-Header dieser Datei.
+    func changePassword(currentPassword: String, newPassword: String) async throws {
+        guard !currentPassword.isEmpty, !newPassword.isEmpty else {
+            throw AuthError.validation(message: "Aktuelles und neues Passwort sind erforderlich")
+        }
+
+        let body = ChangePasswordRequest(currentPassword: currentPassword, newPassword: newPassword)
+        let (data, http) = try await postJSON(
+            path: "/api/v1/auth/change-password",
+            body: body,
+            authenticated: true
+        )
+        guard http.statusCode == 200 else {
+            throw AuthError.classify(
+                status: http.statusCode,
+                data: data,
+                retryAfterHeader: http.retryAfterSeconds
+            )
+        }
+        CoreLog.auth.info("Password changed")
+    }
+
+    /// Löscht den aktuell eingeloggten Account vollständig.
+    ///
+    /// Server löscht alle User-Daten (Auth, Credits, Sync-DB-Records).
+    /// Bei Erfolg wird der lokale Keychain gewiped und der Status auf
+    /// `.signedOut` gesetzt.
+    ///
+    /// **App-Store-Pflicht 5.1.1(v):** jede App mit Account-Erstellung
+    /// muss eine Account-Löschung anbieten.
+    ///
+    /// - Parameter password: Aktuelles Klartext-Passwort als Re-Auth.
+    ///
+    /// - Important: Aktuell server-seitig nicht Bearer-fähig — siehe
+    ///   Doc-Header dieser Datei.
+    func deleteAccount(password: String) async throws {
+        guard !password.isEmpty else {
+            throw AuthError.validation(message: "Passwort ist erforderlich")
+        }
+
+        let body = DeleteAccountRequest(password: password)
+        let (data, http) = try await postJSON(
+            path: "/api/v1/auth/account",
+            method: "DELETE",
+            body: body,
+            authenticated: true
+        )
+        guard http.statusCode == 200 else {
+            throw AuthError.classify(
+                status: http.statusCode,
+                data: data,
+                retryAfterHeader: http.retryAfterSeconds
+            )
+        }
+        clearSession()
+        CoreLog.auth.notice("Account deleted")
+    }
+}
+
+// MARK: - Private Helpers
+
+extension AuthClient {
+    /// Generischer JSON-POST/DELETE-Helper. Wenn `authenticated == true`,
+    /// wird der aktuelle Bearer-Token mitgeschickt.
+    fileprivate func postJSON<Body: Encodable>(
+        path: String,
+        method: String = "POST",
+        body: Body,
+        authenticated: Bool = false
+    ) async throws -> (Data, HTTPURLResponse) {
+        let url = config.authBaseURL.appending(path: path)
+        var request = URLRequest(url: url)
+        request.httpMethod = method
+        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
+        if authenticated {
+            let token = try currentAccessToken()
+            request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
+        }
+        do {
+            request.httpBody = try JSONEncoder().encode(body)
+        } catch {
+            throw AuthError.encoding
+        }
+
+        do {
+            let (data, response) = try await session.data(for: request)
+            guard let http = response as? HTTPURLResponse else {
+                throw AuthError.networkFailure("Keine HTTP-Antwort")
+            }
+            return (data, http)
+        } catch let error as URLError {
+            throw AuthError.networkFailure(error.localizedDescription)
+        } catch let error as AuthError {
+            throw error
+        } catch {
+            throw AuthError.networkFailure(String(describing: error))
+        }
+    }
+}
+
+// MARK: - Wire-Format
+
+private struct RegisterRequest: Encodable {
+    let email: String
+    let password: String
+    let name: String?
+    let sourceAppUrl: String?
+}
+
+/// Server-Antwort auf `/register`. Tokens sind optional weil
+/// `requireEmailVerification: true` (Default) keine Session liefert.
+private struct RegisterResponse: Decodable {
+    let user: RegisterUser?
+    let accessToken: String?
+    let refreshToken: String?
+}
+
+private struct RegisterUser: Decodable {
+    let id: String
+    let email: String?
+}
+
+private struct ForgotPasswordRequest: Encodable {
+    let email: String
+    let redirectTo: String
+}
+
+private struct ResetPasswordRequest: Encodable {
+    let token: String
+    let newPassword: String
+}
+
+private struct ResendVerificationRequest: Encodable {
+    let email: String
+    let sourceAppUrl: String?
+}
+
+private struct ChangeEmailRequest: Encodable {
+    let newEmail: String
+    let callbackURL: String?
+}
+
+private struct ChangePasswordRequest: Encodable {
+    let currentPassword: String
+    let newPassword: String
+}
+
+private struct DeleteAccountRequest: Encodable {
+    let password: String
+}

Sources/ManaCore/Auth/AuthClient.swift

@@ -6,6 +6,11 @@ import Observation
 ///
 /// Eine Instanz pro App, beim App-Start initialisiert. `bootstrap()`
 /// füllt den Status aus dem Keychain (offline möglich).
+///
+/// Die Methoden für Sign-Up, Passwort-Reset, Account-Management etc.
+/// leben in ``AuthClient+Account`` — gleiche Klasse, separate Datei
+/// damit dieser File die Status-Maschine und den Login/Logout/Refresh-
+/// Kern hält.
 @MainActor
 @Observable
 public final class AuthClient {
@@ -19,9 +24,19 @@ public final class AuthClient {
 
     public private(set) var status: Status = .unknown
 
-    private let config: ManaAppConfig
-    private let keychain: KeychainStore
-    private let session: URLSession
+    /// Strukturierter Fehler des letzten Sign-In-/Refresh-/Account-
+    /// Operations. Wird beim nächsten `signIn(...)`-Aufruf gelöscht.
+    ///
+    /// Ergänzt `status == .error(String)`: während `status` einen für
+    /// die UI angezeigten Text trägt (deutsche Lokalisierung), liefert
+    /// `lastError` den klassifizierten ``AuthError``-Case — z.B. um
+    /// `.emailNotVerified` programmatisch zu erkennen und den Resend-
+    /// Mail-Gate freizuschalten.
+    public private(set) var lastError: AuthError?
+
+    let config: ManaAppConfig
+    let keychain: KeychainStore
+    let session: URLSession
 
     public init(config: ManaAppConfig, session: URLSession = .shared) {
         self.config = config
@@ -47,10 +62,13 @@ public final class AuthClient {
     public func signIn(email: String, password: String) async {
         let trimmed = email.trimmingCharacters(in: .whitespacesAndNewlines)
         guard !trimmed.isEmpty, !password.isEmpty else {
-            status = .error("Email und Passwort sind erforderlich")
+            let err = AuthError.validation(message: "Email und Passwort sind erforderlich")
+            lastError = err
+            status = .error(err.errorDescription ?? "")
             return
         }
 
+        lastError = nil
         status = .signingIn
         do {
             let url = config.authBaseURL.appending(path: "/api/v1/auth/login")
@@ -65,13 +83,13 @@ public final class AuthClient {
                 return
             }
             guard http.statusCode == 200 else {
-                let message = (try? JSONDecoder().decode(ServerError.self, from: data))?.message
-                if http.statusCode == 401 {
-                    status = .error("Email oder Passwort falsch")
-                } else {
-                    status =
-                        .error("Login fehlgeschlagen (HTTP \(http.statusCode))" + (message.map { " — \($0)" } ?? ""))
-                }
+                let err = AuthError.classify(
+                    status: http.statusCode,
+                    data: data,
+                    retryAfterHeader: http.retryAfterSeconds
+                )
+                lastError = err
+                status = .error(err.errorDescription ?? "Login fehlgeschlagen")
                 return
             }
 
@@ -80,12 +98,17 @@ public final class AuthClient {
             try keychain.setString(token.refreshToken, for: .refreshToken)
             try keychain.setString(trimmed, for: .email)
             status = .signedIn(email: trimmed)
+            lastError = nil
             CoreLog.auth.info("Sign-in successful")
         } catch let error as URLError {
-            status = .error("Netzwerk: \(error.localizedDescription)")
+            let err = AuthError.networkFailure(error.localizedDescription)
+            lastError = err
+            status = .error(err.errorDescription ?? "Netzwerk-Fehler")
             CoreLog.auth.error("Sign-in network error: \(error.localizedDescription, privacy: .public)")
         } catch {
-            status = .error(String(describing: error))
+            let err = AuthError.networkFailure(String(describing: error))
+            lastError = err
+            status = .error(err.errorDescription ?? String(describing: error))
             CoreLog.auth.error("Sign-in error: \(String(describing: error), privacy: .public)")
         }
     }
@@ -138,9 +161,10 @@ public final class AuthClient {
         guard http.statusCode == 200 else {
             keychain.wipe()
             status = .signedOut
-            throw AuthError.serverError(
+            throw AuthError.classify(
                 status: http.statusCode,
-                message: (try? JSONDecoder().decode(ServerError.self, from: data))?.message
+                data: data,
+                retryAfterHeader: http.retryAfterSeconds
             )
         }
 
@@ -151,22 +175,61 @@ public final class AuthClient {
         }
         return token.accessToken
     }
+
+    // MARK: - Internal Helpers (used by AuthClient+Account)
+
+    /// Persistiert ein frisch erhaltenes Token-Paar und setzt den Status
+    /// auf `.signedIn`. Genutzt von ``AuthClient+Account``-Flows, die
+    /// in den eingeloggten Zustand führen (z.B. `register` wenn der
+    /// Server bereits eine Session liefert).
+    func persistSession(email: String, accessToken: String, refreshToken: String) throws {
+        try keychain.setString(accessToken, for: .accessToken)
+        try keychain.setString(refreshToken, for: .refreshToken)
+        try keychain.setString(email, for: .email)
+        status = .signedIn(email: email)
+    }
+
+    /// Setzt den Status auf `.signedOut` und wirft den Keychain leer.
+    /// Genutzt nach `deleteAccount()`.
+    func clearSession() {
+        keychain.wipe()
+        status = .signedOut
+    }
 }
 
-private struct LoginRequest: Encodable {
+// MARK: - Wire-Format
+
+struct LoginRequest: Encodable {
     let email: String
     let password: String
 }
 
-private struct RefreshRequest: Encodable {
+struct RefreshRequest: Encodable {
     let refreshToken: String
 }
 
-private struct TokenResponse: Decodable {
+/// Antwort von `/login`, `/refresh` und (manchmal) `/register`.
+///
+/// `register` liefert je nach Server-Konfig:
+/// - mit `requireEmailVerification: true` (Default): nur `user`, keine Tokens
+/// - mit `false`: vollständiges Token-Paar
+///
+/// Optionale Felder sind explizit `Optional` damit beide Pfade dekodierbar sind.
+struct TokenResponse: Decodable {
     let accessToken: String
     let refreshToken: String
 }
 
-private struct ServerError: Decodable {
-    let message: String?
+extension HTTPURLResponse {
+    /// Liest `Retry-After` als Anzahl Sekunden. Server schickt Integer-
+    /// Sekunden (siehe `lib/auth-errors.ts`). HTTP-Datum-Variante wird
+    /// nicht unterstützt — mana-auth nutzt sie nicht.
+    var retryAfterSeconds: TimeInterval? {
+        guard let raw = value(forHTTPHeaderField: "Retry-After"),
+              let seconds = TimeInterval(raw)
+        else {
+            return nil
+        }
+        return seconds
+    }
 }

Sources/ManaCore/Auth/AuthError.swift

@@ -1,31 +1,205 @@
 import Foundation
 
 /// Fehler-Typen des Auth- und Transport-Layers.
-public enum AuthError: Error, LocalizedError, Sendable {
+///
+/// Server-Fehler-Codes folgen `AuthErrorCode` aus
+/// `mana/services/mana-auth/src/lib/auth-errors.ts`. Jeder dort
+/// definierte Code hat hier einen passenden Case — neue Codes
+/// auf Server-Seite brauchen einen Minor-Bump dieses Pakets.
+public enum AuthError: Error, LocalizedError, Sendable, Equatable {
+    // MARK: - Client-Side
+
+    /// Kein Token im Keychain — User muss sich einloggen.
     case notSignedIn
-    case invalidCredentials
-    case networkFailure(String)
-    case serverError(status: Int, message: String?)
-    case decoding(String)
-    case keychain(OSStatus)
+    /// Lokales Encoding (z.B. UTF-8-Konvertierung) gescheitert.
     case encoding
+    /// Keychain-Operation gescheitert mit OSStatus.
+    case keychain(OSStatus)
+    /// Antwort konnte nicht dekodiert werden.
+    case decoding(String)
+    /// Netzwerk-Schicht hat geworfen.
+    case networkFailure(String)
+
+    // MARK: - Server-Side (Mapping zu AuthErrorCode in mana-auth)
+
+    /// `INVALID_CREDENTIALS` — Email oder Passwort falsch.
+    case invalidCredentials
+    /// `EMAIL_NOT_VERIFIED` — Account existiert, Email muss bestätigt
+    /// werden. UI bietet "Bestätigungs-Mail erneut senden" an.
+    case emailNotVerified
+    /// `EMAIL_ALREADY_REGISTERED` — Sign-Up mit existierender Email.
+    case emailAlreadyRegistered
+    /// `WEAK_PASSWORD` — Passwort erfüllt Mindest-Policy nicht.
+    case weakPassword(message: String?)
+    /// `ACCOUNT_LOCKED` — zu viele Fehlversuche. `retryAfter` in Sekunden.
+    case accountLocked(retryAfter: TimeInterval?)
+    /// `SIGNUP_LIMIT_REACHED` — tägliches Registrierungs-Limit aus.
+    case signupLimitReached
+    /// `RATE_LIMITED` — generelles Rate-Limit. `retryAfter` in Sekunden.
+    case rateLimited(retryAfter: TimeInterval?)
+    /// `TOKEN_EXPIRED` — z.B. Reset-Token, Verify-Token.
+    case tokenExpired
+    /// `TOKEN_INVALID` — Token nicht parsebar / nicht gefunden.
+    case tokenInvalid
+    /// `TWO_FACTOR_REQUIRED` — Login erfolgreich, aber 2FA-Challenge offen.
+    case twoFactorRequired
+    /// `TWO_FACTOR_FAILED` — TOTP- oder Backup-Code falsch.
+    case twoFactorFailed
+    /// `PASSKEY_NOT_ENABLED` — User hat keinen Passkey registriert.
+    case passkeyNotEnabled
+    /// `PASSKEY_CANCELLED` — User hat den Plattform-Dialog abgebrochen.
+    case passkeyCancelled
+    /// `PASSKEY_VERIFICATION_FAILED` — WebAuthn-Verifikation gescheitert.
+    case passkeyVerificationFailed
+    /// `VALIDATION` — Request-Body ungültig (z.B. fehlendes Feld).
+    case validation(message: String?)
+    /// `UNAUTHORIZED` — fehlender oder ungültiger Authorization-Header.
+    case unauthorized
+    /// `NOT_FOUND` — referenzierte Ressource existiert nicht.
+    case notFound
+    /// `SERVICE_UNAVAILABLE` — Server temporär nicht erreichbar.
+    case serviceUnavailable
+    /// `INTERNAL` — Server-interner Fehler ohne weitere Klassifikation.
+    case serverInternal
+
+    /// Fallback für Server-Fehler ohne bekannten `AuthErrorCode`.
+    case serverError(status: Int, code: String?, message: String?)
 
     public var errorDescription: String? {
         switch self {
         case .notSignedIn:
             "Nicht angemeldet"
-        case .invalidCredentials:
-            "Ungültige Anmeldedaten"
-        case let .networkFailure(message):
-            "Netzwerkfehler: \(message)"
-        case let .serverError(status, message):
-            "Server-Fehler (\(status))" + (message.map { ": \($0)" } ?? "")
-        case let .decoding(detail):
-            "Antwort konnte nicht gelesen werden: \(detail)"
-        case let .keychain(status):
-            "Keychain-Fehler (OSStatus \(status))"
         case .encoding:
             "Datenkodierung fehlgeschlagen"
+        case let .keychain(status):
+            "Keychain-Fehler (OSStatus \(status))"
+        case let .decoding(detail):
+            "Antwort konnte nicht gelesen werden: \(detail)"
+        case let .networkFailure(message):
+            "Netzwerkfehler: \(message)"
+        case .invalidCredentials:
+            "Email oder Passwort falsch"
+        case .emailNotVerified:
+            "Bitte bestätige deine Email-Adresse, bevor du dich anmeldest."
+        case .emailAlreadyRegistered:
+            "Diese Email ist bereits registriert."
+        case let .weakPassword(message):
+            message ?? "Passwort erfüllt die Mindest-Anforderungen nicht."
+        case let .accountLocked(retryAfter):
+            retryAfter
+                .map { "Account temporär gesperrt. Erneut versuchen in \(Int($0))s." }
+                ?? "Account temporär gesperrt."
+        case .signupLimitReached:
+            "Das tägliche Registrierungslimit ist erreicht. Versuche es morgen wieder."
+        case let .rateLimited(retryAfter):
+            retryAfter
+                .map { "Zu viele Versuche. Bitte warte \(Int($0))s." }
+                ?? "Zu viele Versuche. Bitte warte einen Moment."
+        case .tokenExpired:
+            "Der Link ist abgelaufen. Bitte fordere einen neuen an."
+        case .tokenInvalid:
+            "Der Link ist ungültig."
+        case .twoFactorRequired:
+            "Zwei-Faktor-Code erforderlich."
+        case .twoFactorFailed:
+            "Zwei-Faktor-Code falsch."
+        case .passkeyNotEnabled:
+            "Für diesen Account ist kein Passkey eingerichtet."
+        case .passkeyCancelled:
+            "Passkey-Eingabe abgebrochen."
+        case .passkeyVerificationFailed:
+            "Passkey konnte nicht verifiziert werden."
+        case let .validation(message):
+            message ?? "Eingabe ungültig."
+        case .unauthorized:
+            "Nicht autorisiert."
+        case .notFound:
+            "Nicht gefunden."
+        case .serviceUnavailable:
+            "Server temporär nicht erreichbar. Bitte später erneut versuchen."
+        case .serverInternal:
+            "Server-Fehler. Bitte später erneut versuchen."
+        case let .serverError(status, code, message):
+            "Server-Fehler (\(status))"
+                + (code.map { " — \($0)" } ?? "")
+                + (message.map { ": \($0)" } ?? "")
+        }
+    }
+
+    /// Klassifiziert eine `mana-auth`-Fehler-Antwort. `data` ist der
+    /// Response-Body, `status` der HTTP-Status, `retryAfterHeader` der
+    /// `Retry-After`-Header-Wert in Sekunden (falls vorhanden).
+    ///
+    /// Mapping zu `AuthErrorCode` in
+    /// `mana/services/mana-auth/src/lib/auth-errors.ts`. Unbekannte Codes
+    /// fallen auf ``serverError(status:code:message:)`` zurück.
+    public static func classify(
+        status: Int,
+        data: Data,
+        retryAfterHeader: TimeInterval? = nil
+    ) -> AuthError {
+        let body = try? JSONDecoder().decode(ServerErrorBody.self, from: data)
+        let message = body?.message
+        let retryAfter = body?.retryAfterSec ?? retryAfterHeader
+
+        switch body?.error {
+        case "INVALID_CREDENTIALS":
+            return .invalidCredentials
+        case "EMAIL_NOT_VERIFIED":
+            return .emailNotVerified
+        case "EMAIL_ALREADY_REGISTERED":
+            return .emailAlreadyRegistered
+        case "WEAK_PASSWORD":
+            return .weakPassword(message: message)
+        case "ACCOUNT_LOCKED":
+            return .accountLocked(retryAfter: retryAfter)
+        case "SIGNUP_LIMIT_REACHED":
+            return .signupLimitReached
+        case "RATE_LIMITED":
+            return .rateLimited(retryAfter: retryAfter)
+        case "TOKEN_EXPIRED":
+            return .tokenExpired
+        case "TOKEN_INVALID":
+            return .tokenInvalid
+        case "TWO_FACTOR_REQUIRED":
+            return .twoFactorRequired
+        case "TWO_FACTOR_FAILED":
+            return .twoFactorFailed
+        case "PASSKEY_NOT_ENABLED":
+            return .passkeyNotEnabled
+        case "PASSKEY_CANCELLED":
+            return .passkeyCancelled
+        case "PASSKEY_VERIFICATION_FAILED":
+            return .passkeyVerificationFailed
+        case "VALIDATION":
+            return .validation(message: message)
+        case "UNAUTHORIZED":
+            return .unauthorized
+        case "NOT_FOUND":
+            return .notFound
+        case "SERVICE_UNAVAILABLE":
+            return .serviceUnavailable
+        case "INTERNAL":
+            return .serverInternal
+        default:
+            // Status-Heuristik wenn kein Code geliefert wurde.
+            switch status {
+            case 401: return .invalidCredentials
+            case 403: return .emailNotVerified
+            case 404: return .notFound
+            case 429: return .rateLimited(retryAfter: retryAfter)
+            case 503: return .serviceUnavailable
+            default: return .serverError(status: status, code: body?.error, message: message)
+            }
         }
     }
 }
+
+/// Wire-Format der `mana-auth`-Fehler-Antwort. Spiegelt
+/// `AuthErrorResponseBody` aus `lib/auth-errors.ts`.
+struct ServerErrorBody: Decodable, Sendable {
+    let error: String?
+    let message: String?
+    let status: Int?
+    let retryAfterSec: TimeInterval?
+}