diff --git a/CHANGELOG.md b/CHANGELOG.md index 8376473..1d25f93 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,39 @@ Alle Änderungen werden hier dokumentiert. Format orientiert an [Keep a Changelog](https://keepachangelog.com), Versionierung nach [Semver](https://semver.org). +## [1.4.0] — 2026-05-14 + +Minor — 2FA-Enrollment (Mini-Sprint B). Setzt Mini-Sprint A +(`v1.3.0`) voraus. Komplett additiv. + +### ManaCore — 2FA-Enrollment + +- `TotpEnrollment` (public struct) — `totpURI` (für QR-Code-Display) + + `backupCodes` (Liste). +- `AuthClient.enrollTotp(password:) -> TotpEnrollment` — aktiviert + TOTP-2FA; Server generiert Secret + Backup-Codes. +- `AuthClient.disableTotp(password:)` — deaktiviert wieder. +- `AuthClient.getTotpUri(password:) -> String` — Re-Display für + zweites Authenticator-Gerät. +- `AuthClient.regenerateBackupCodes(password:) -> [String]` — neue + Codes, alte werden ungültig. + +Alle vier Methoden senden Bearer-Header mit Session-Token (Wire- +Konvention für mana-auth-Account-Endpoints). + +### Server-Side Voraussetzung + +`mana-auth` ≥ Commit der Wrapper-Endpoints: +- `POST /api/v1/auth/two-factor/enable` +- `POST /api/v1/auth/two-factor/disable` +- `POST /api/v1/auth/two-factor/get-totp-uri` +- `POST /api/v1/auth/two-factor/generate-backup-codes` + +### Tests + +- 7 neue Tests (Success-Pfade aller vier Methoden, leeres Passwort, + ohne Session, falsches Passwort). 66/66 grün. + ## [1.3.0] — 2026-05-14 Minor — 2FA-Login-Challenge (Mini-Sprint A). Apps mit aktiviertem diff --git a/Sources/ManaCore/Auth/AuthClient+Account.swift b/Sources/ManaCore/Auth/AuthClient+Account.swift index 08a6a45..06bf86b 100644 --- a/Sources/ManaCore/Auth/AuthClient+Account.swift +++ b/Sources/ManaCore/Auth/AuthClient+Account.swift @@ -481,3 +481,157 @@ private struct TwoFactorVerifyResponse: Decodable { let accessToken: String? let refreshToken: String? } + +// MARK: - Two-Factor (Enrollment) + +/// Ergebnis von ``AuthClient/enrollTotp(password:)``: enthält die +/// otpauth-URI (für QR-Code-Display) und die Backup-Codes. Backup- +/// Codes sind einmalig nutzbar und sollten dem User zum Sichern +/// (Kopieren/Drucken) angeboten werden — der Server zeigt sie nie +/// mehr. +public struct TotpEnrollment: Sendable, Equatable { + /// `otpauth://totp/Issuer:email?secret=...&...`-URI. Direkt als + /// QR-Code rendern (z.B. via `CIFilter.qrCodeGenerator`). + public let totpURI: String + + /// Liste der Backup-Codes (üblich 10 Stück). Der User sollte sie + /// sicher aufbewahren — bei Verlust des TOTP-Geräts sind sie der + /// einzige Fallback. Server merkt sich nur Hashes; bei Verbrauch + /// werden sie als consumed markiert. + public let backupCodes: [String] +} + +public extension AuthClient { + /// Aktiviert TOTP-2FA für den aktuellen Account. + /// + /// Re-Auth via aktuellem Passwort. Bei Erfolg generiert der Server + /// ein TOTP-Secret und gibt die otpauth-URI + Backup-Codes zurück. + /// Die App rendert die URI als QR-Code, der User scannt mit + /// Authenticator-App und gibt zur Bestätigung den ersten Code ein — + /// dieser zweite Schritt läuft über die regulären + /// ``verifyTotp(code:trustDevice:)``-Methode oder einen Re-Auth + /// signIn → twoFactorRequired-Flow (der Server entscheidet). + /// + /// - Important: Nutzt den Session-Token als Bearer (Wire-Konvention + /// für mana-auth-Account-Endpoints, siehe Doc-Header dieser Datei). + func enrollTotp(password: String) async throws -> TotpEnrollment { + guard !password.isEmpty else { + throw AuthError.validation(message: "Passwort ist erforderlich") + } + + let body = TotpEnableRequest(password: password) + let (data, http) = try await postJSON( + path: "/api/v1/auth/two-factor/enable", + body: body, + authenticated: true + ) + guard http.statusCode == 200 else { + throw AuthError.classify( + status: http.statusCode, + data: data, + retryAfterHeader: http.retryAfterSeconds + ) + } + + let decoded = try JSONDecoder().decode(TotpEnableResponse.self, from: data) + guard let uri = decoded.totpURI else { + throw AuthError.decoding("totpURI fehlt in Enroll-Antwort") + } + CoreLog.auth.info("2FA TOTP enrollment initiated") + return TotpEnrollment(totpURI: uri, backupCodes: decoded.backupCodes ?? []) + } + + /// Deaktiviert TOTP-2FA für den aktuellen Account. Re-Auth via + /// Passwort. + func disableTotp(password: String) async throws { + guard !password.isEmpty else { + throw AuthError.validation(message: "Passwort ist erforderlich") + } + + let body = TotpEnableRequest(password: password) + let (data, http) = try await postJSON( + path: "/api/v1/auth/two-factor/disable", + body: body, + authenticated: true + ) + guard http.statusCode == 200 else { + throw AuthError.classify( + status: http.statusCode, + data: data, + retryAfterHeader: http.retryAfterSeconds + ) + } + CoreLog.auth.info("2FA TOTP disabled") + } + + /// Liefert die otpauth-URI des aktuellen TOTP-Secrets. Nützlich + /// wenn der User den QR-Code erneut sehen will (z.B. zweites + /// Gerät einrichten). Re-Auth via Passwort. + /// + /// - Returns: `otpauth://totp/…`-URI, direkt als QR-Code renderbar. + func getTotpUri(password: String) async throws -> String { + guard !password.isEmpty else { + throw AuthError.validation(message: "Passwort ist erforderlich") + } + + let body = TotpEnableRequest(password: password) + let (data, http) = try await postJSON( + path: "/api/v1/auth/two-factor/get-totp-uri", + body: body, + authenticated: true + ) + guard http.statusCode == 200 else { + throw AuthError.classify( + status: http.statusCode, + data: data, + retryAfterHeader: http.retryAfterSeconds + ) + } + + let decoded = try JSONDecoder().decode(TotpEnableResponse.self, from: data) + guard let uri = decoded.totpURI else { + throw AuthError.decoding("totpURI fehlt in get-totp-uri-Antwort") + } + return uri + } + + /// Regeneriert die Backup-Codes. Alte Codes werden ungültig. Der + /// User sollte die neuen direkt sichern. + func regenerateBackupCodes(password: String) async throws -> [String] { + guard !password.isEmpty else { + throw AuthError.validation(message: "Passwort ist erforderlich") + } + + let body = TotpEnableRequest(password: password) + let (data, http) = try await postJSON( + path: "/api/v1/auth/two-factor/generate-backup-codes", + body: body, + authenticated: true + ) + guard http.statusCode == 200 else { + throw AuthError.classify( + status: http.statusCode, + data: data, + retryAfterHeader: http.retryAfterSeconds + ) + } + + let decoded = try JSONDecoder().decode(TotpEnableResponse.self, from: data) + guard let codes = decoded.backupCodes else { + throw AuthError.decoding("backupCodes fehlen in Antwort") + } + return codes + } +} + +private struct TotpEnableRequest: Encodable { + let password: String +} + +/// Antwort-Format für alle Enrollment-Endpoints. Felder sind optional +/// damit derselbe Type für `enable` (beide), `get-totp-uri` (nur URI) +/// und `generate-backup-codes` (nur Codes) dekodierbar ist. +private struct TotpEnableResponse: Decodable { + let totpURI: String? + let backupCodes: [String]? +} diff --git a/Tests/ManaCoreTests/AuthClientTwoFactorEnrollmentTests.swift b/Tests/ManaCoreTests/AuthClientTwoFactorEnrollmentTests.swift new file mode 100644 index 0000000..b749c28 --- /dev/null +++ b/Tests/ManaCoreTests/AuthClientTwoFactorEnrollmentTests.swift @@ -0,0 +1,119 @@ +import Foundation +import Testing +@testable import ManaCore + +@Suite("AuthClient 2FA-Enrollment") +@MainActor +struct AuthClientTwoFactorEnrollmentTests { + /// Bringt den AuthClient in den `.signedIn`-Status mit einem + /// Session-Token für authenticated Calls. + private func signedInAuth() async -> MockedAuth { + let mocked = makeMockedAuth() + let access = "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1MSIsImV4cCI6MjAwMDAwMDAwMH0.sig" + mocked.setHandler { _ in + (200, Data(#"{"accessToken":"\#(access)","refreshToken":"session-tok"}"#.utf8)) + } + await mocked.auth.signIn(email: "u@x.de", password: "pw") + return mocked + } + + @Test("enrollTotp liefert URI + Backup-Codes") + func enrollSuccess() async throws { + let mocked = await signedInAuth() + let captured = MockURLProtocol.Capture() + mocked.setHandler { request in + captured.store(request) + return (200, Data(#""" + {"totpURI":"otpauth://totp/Mana:u@x.de?secret=ABC&issuer=Mana","backupCodes":["a-b-c","d-e-f","g-h-i"]} + """#.utf8)) + } + + let enrollment = try await mocked.auth.enrollTotp(password: "pw") + #expect(enrollment.totpURI.hasPrefix("otpauth://totp/")) + #expect(enrollment.backupCodes == ["a-b-c", "d-e-f", "g-h-i"]) + + let request = try #require(captured.request) + #expect(request.url?.path == "/api/v1/auth/two-factor/enable") + // Bearer-Header trägt den Session-Token (nicht JWT) + #expect(request.value(forHTTPHeaderField: "Authorization") == "Bearer session-tok") + } + + @Test("enrollTotp mit leerem Passwort → validation, kein Server-Call") + func enrollEmptyPassword() async { + let mocked = await signedInAuth() + mocked.setHandler { _ in + Issue.record("Server darf nicht aufgerufen werden") + return (500, Data()) + } + + await #expect(throws: AuthError.validation(message: "Passwort ist erforderlich")) { + try await mocked.auth.enrollTotp(password: "") + } + } + + @Test("enrollTotp ohne Session → notSignedIn") + func enrollNoSession() async { + let mocked = makeMockedAuth() + await #expect(throws: AuthError.notSignedIn) { + try await mocked.auth.enrollTotp(password: "pw") + } + } + + @Test("disableTotp success") + func disableSuccess() async throws { + let mocked = await signedInAuth() + let captured = MockURLProtocol.Capture() + mocked.setHandler { request in + captured.store(request) + return (200, Data(#"{"success":true}"#.utf8)) + } + + try await mocked.auth.disableTotp(password: "pw") + let request = try #require(captured.request) + #expect(request.url?.path == "/api/v1/auth/two-factor/disable") + } + + @Test("disableTotp mit falschem Passwort → invalidCredentials") + func disableWrongPassword() async { + let mocked = await signedInAuth() + mocked.setHandler { _ in + (401, Data(#"{"error":"INVALID_CREDENTIALS","status":401}"#.utf8)) + } + + await #expect(throws: AuthError.invalidCredentials) { + try await mocked.auth.disableTotp(password: "wrong") + } + } + + @Test("getTotpUri liefert URI ohne Backup-Codes") + func getUriSuccess() async throws { + let mocked = await signedInAuth() + mocked.setHandler { _ in + (200, Data(#""" + {"totpURI":"otpauth://totp/Mana:u@x.de?secret=XYZ&issuer=Mana"} + """#.utf8)) + } + + let uri = try await mocked.auth.getTotpUri(password: "pw") + #expect(uri.hasPrefix("otpauth://totp/")) + #expect(uri.contains("secret=XYZ")) + } + + @Test("regenerateBackupCodes liefert neue Codes") + func regenerateSuccess() async throws { + let mocked = await signedInAuth() + let captured = MockURLProtocol.Capture() + mocked.setHandler { request in + captured.store(request) + return (200, Data(#""" + {"backupCodes":["new-1","new-2","new-3","new-4","new-5"]} + """#.utf8)) + } + + let codes = try await mocked.auth.regenerateBackupCodes(password: "pw") + #expect(codes.count == 5) + #expect(codes.first == "new-1") + let request = try #require(captured.request) + #expect(request.url?.path == "/api/v1/auth/two-factor/generate-backup-codes") + } +}