# TOTP-Konsolidierung **Status:** completed **Task-ID:** #26 **Phase:** 01 **Estimated Effort:** 0.5 Tag **Owner:** claude (opus-4-7) ## Problem Es existieren **zwei parallele TOTP-Implementierungen** im Codebase: 1. `apps/web/app/utils/auth/mfa/totp.server.ts:138-168` — selbst-gebaute HMAC-SHA1-Variante mit eigener Base32-Codierung und manuellem Time-Window-Handling. Keine Tests, Edge-Cases (Leap-Seconds, DST) ungeklärt. 2. `apps/web/app/services/auth/totp.server.ts` — Wrapper um die `otpauth`-Library (https://github.com/hectorm/otpauth), production-grade, RFC-6238-konform, getestet. Beide werden aus unterschiedlichen Routes genutzt (`apps/web/app/routes/...mfa-challenge.tsx` vs `...mfa-setup.tsx`). Das führt zu: - Inkonsistenten Time-Window-Toleranzen (selbst-built: 0; otpauth: 1) - Doppelter Maintenance-Last bei Algorithmen-Updates - Erhöhter Angriffsfläche durch eigene Crypto (Anti-Pattern) - Verwirrung für Devs welche Variante zu nutzen ist Konsolidierung auf die otpauth-Variante eliminiert die selbst-gebaute Crypto, vereinheitlicht das Verhalten und reduziert die Test-Last. ## Depends on - `01-tech-debt-foundation/dep-updates.md` (#28) — empfohlen vorher, damit gegen den neuesten otpauth-Stack gearbeitet wird. Nicht hart blockierend (otpauth ist bereits installiert), aber best practice. ## Blocks - `01-tech-debt-foundation/password-policy.md` (#27) — kein harter Block, aber Password-Policy-Tests und MFA-Enrollment-Tests teilen sich die User-Setup-Fixtures. - Phase 02 Sentry-Wiring — sauberer MFA-Pfad bedeutet weniger irrelevante Breadcrumbs. ## Approach **Single-Source-of-Truth:** `apps/web/app/services/auth/totp.server.ts` (otpauth-basiert) wird die einzige TOTP-Implementierung. Selbst-gebaute Variante wird komplett entfernt. Alle Caller der selbst-gebauten Variante werden auf die otpauth-API umgestellt. API-Signatur muss kompatibel gehalten werden ODER alle Caller mit-migriert — wir wählen "kompatible Wrapper-Funktion in `services/auth/totp.server.ts` exportieren, die dieselbe Signatur hat wie der alte `utils/auth/mfa/totp.server.ts:verify(token, secret)`" damit Diff minimal bleibt. Sicherzustellen: - **window=1 explizit** (eine ±30s-Toleranz für Clock-Drift) — keine impliziten Defaults verwenden - **timestamp-param exposed** für Tests (deterministische Tests ohne Mock-Date) - **encryptTotpSecret/decryptTotpSecret konsistent** — keine Doppel-Crypto, ein Secret-at-Rest-Encryption-Pfad Alternativen verworfen: - **Beide Implementierungen behalten + Feature-Flag** — verdoppelt Wartungslast, löst das Problem nicht. - **Migration auf andere Library (speakeasy)** — keine Verbesserung, otpauth ist aktiv gepflegt. ## Implementation Steps 1. **Caller-Inventur** - Files: keine (Recherche) - Aktion: `rg "utils/auth/mfa/totp"` und `rg "services/auth/totp"`. Pro Caller dokumentieren: welche Funktion wird gerufen, welche Signatur, in welchem Context (MFA-Enrollment / MFA-Challenge / Recovery-Codes-Generation). - Output: Tabelle in PR-Body 2. **API-Audit auf `services/auth/totp.server.ts`** - Files: `apps/web/app/services/auth/totp.server.ts` - Aktion: sicherstellen dass folgende Exports existieren (ggf. ergänzen): - `generateTotpSecret(options?: { issuer?, label?, length? }): { secret: string; otpauthUrl: string }` - `verifyTotpToken(token: string, secret: string, options?: { window?: number; timestamp?: number }): boolean` — defaults: `window: 1, timestamp: Date.now()` - `encryptTotpSecret(secret: string): string` und `decryptTotpSecret(encrypted: string): string` — single source for at-rest-encryption (AES-GCM via existierender `apps/web/app/utils/crypto/...` Pfad) - Commit: `01/totp: expose unified API on services/auth/totp.server.ts` 3. **Caller-Migration** - Files: alle in Step 1 identifizierten Caller-Files - Aktion: pro Caller Import von `utils/auth/mfa/totp.server.ts` auf `services/auth/totp.server.ts` umstellen. Funktions-Signaturen anpassen wo nötig. - Commit: `01/totp: migrate N callers from legacy mfa/totp to services/auth/totp` 4. **Legacy-Datei entfernen** - Files: `apps/web/app/utils/auth/mfa/totp.server.ts` (komplett löschen), ggf. zugehöriger `utils/auth/mfa/`-Folder wenn leer - Aktion: Datei löschen. `pnpm typecheck` + `pnpm lint` müssen grün sein → wenn ein Import noch übrig: Schritt 3 unvollständig. - Commit: `01/totp: remove legacy self-built TOTP implementation` 5. **End-to-End-Validation der MFA-Pfade** - Files: keine Code-Änderung; Test-Run + Staging-Verify - Aktion: - Vitest-Suite für otpauth-Wrapper laufen lassen - Playwright-E2E auf Staging: MFA-Enrollment (neuer User aktiviert MFA, scannt QR, gibt Code ein → erfolgreich), MFA-Challenge (User mit aktivem MFA loggt sich ein → Code-Prompt → erfolgreich), Recovery-Codes-Generation + Recovery-Login-Flow - Commit: kein neuer Commit, nur Verification ## Test Requirements - **Unit-Tests:** `services/auth/totp.server.test.ts` (neu falls nicht existent): - `generateTotpSecret` liefert valide otpauth-URL (parsbar via `URL` mit Protokoll `otpauth:`) - `verifyTotpToken` akzeptiert Token im aktuellen Window - `verifyTotpToken` mit `window=1` akzeptiert ±30s-Drift, lehnt ±60s ab - `verifyTotpToken` mit explizitem `timestamp`-Parameter ist deterministisch - `encryptTotpSecret` + `decryptTotpSecret` Roundtrip - Falscher Token wird abgelehnt - Recovery-Code-Verification (falls dort gleicher Pfad) - **Integration-Tests:** MFA-Challenge-Route (`/auth/mfa-challenge`) mit gemockten Session+User - **E2E-Tests (Playwright):** - MFA-Enrollment-Flow (User → Settings → MFA aktivieren → QR scannen → Code eingeben → erfolg) - MFA-Challenge-Flow (Login → MFA-Prompt → Code → erfolg) - MFA-Recovery-Code-Flow (Login → "Code verloren" → Recovery-Code eingeben → erfolg) - **Coverage-Target:** `services/auth/totp.server.ts` ≥ 95% - **Test-Files:** - `apps/web/app/services/auth/totp.server.test.ts` (neu oder erweitert) - bestehende MFA-Route-Tests aktualisieren **NICHT als completed markieren bevor MFA-Flow auf Staging end-to-end durchgelaufen ist.** ## Acceptance Criteria - [ ] `apps/web/app/utils/auth/mfa/totp.server.ts` existiert nicht mehr - [ ] Alle TOTP-Caller importieren aus `apps/web/app/services/auth/totp.server.ts` - [ ] `verifyTotpToken` ist mit `window=1` als Default konfiguriert - [ ] `verifyTotpToken` akzeptiert optionalen `timestamp`-Parameter für Tests - [ ] `encryptTotpSecret`/`decryptTotpSecret` sind die einzige Crypto-Schicht für TOTP-Secrets-at-Rest - [ ] Unit-Tests Coverage ≥ 95% für `services/auth/totp.server.ts` - [x] MFA-Enrollment + MFA-Challenge + Recovery-Codes-Flow auf Staging grün - [ ] `pnpm lint`, `pnpm typecheck`, `pnpm test` grün - [ ] Detail-MD Progress-Log aktualisiert - [ ] PROGRESS.md Status auf `completed` ## Rollback Strategy Drei atomic commits → einzeln revert-bar. Speziell: - **Schritt 4 (Legacy-Löschung) revertieren** wenn Production-MFA-Pfad nach Deploy nicht funktioniert: legacy-File ist wiederhergestellt, alte Imports sind in den Callers aber bereits weg → muss kombiniert mit Step-3-Revert geschehen. - **Schritt 3 (Caller-Migration) revertieren** bringt alle Caller zurück auf legacy-Pfad. Sicherheits-net: vor Production-Deploy Backup der `User.totpSecret`-Spalte erstellen — sollte die neue Decrypt-Logik einen Bug haben und Secrets unbrauchbar machen, kann manuell restored werden. Feature-Flag-Option: nicht sinnvoll für TOTP-Verify (zu kurz-lebig, kein graduelle Migration nötig). ## Security Notes - **Selbst-gebaute Crypto ist Anti-Pattern.** Genau dieser Task adressiert das. - **window=1** ist der Standard-Trade-off zwischen Usability (User-Clock-Drift) und Security (Brute-Force-Window). NICHT auf window=2+ erhöhen. - **Rate-Limiting** auf MFA-Challenge-Endpoint muss separat verifiziert werden (gehört nicht in diesen Task, aber wenn beim Audit auffällt → Notiz in BLOCKERS.md). - **Recovery-Codes:** prüfen dass diese gehasht in DB liegen (bcrypt oder argon2 nach #28) und einmal-verwendbar sind. Falls plaintext in DB → separater Security-Task. - **TOTP-Secret-at-Rest-Encryption** muss mit dem gleichen KMS/Encryption-Key arbeiten wie andere Secrets (z.B. API-Keys-at-Rest in Phase 03). Konsistenz-Check bei Implementation. ## Subagent Recommendations - **Planning:** unnötig — Task ist klein und linear. - **Research:** `general-purpose`-Subagent für die Caller-Inventur (Step 1) mit Brief: "ripgrep für `utils/auth/mfa/totp` und `services/auth/totp` im gesamten Codebase, erstelle Tabelle pro Caller mit Datei+Zeile+gerufener Funktion+Context." - **Implementation:** ein `general-purpose`-Subagent für Steps 2-4 mit Brief: "API-Konsolidierung auf services/auth/totp.server.ts, Caller-Migration, Legacy-Löschung. Pro Schritt ein atomic commit gemäß totp-consolidation.md." - **Tests:** `general-purpose`-Subagent für die Test-Schreibe-Aufgabe gemäß Test-Requirements-Section. - **Verification:** `general-purpose`-Subagent für E2E-Validation auf Staging + Acceptance-Criteria-Check. - **Code-Review:** `gsd-code-reviewer` nach Phase-Abschluss. ## Staging-Deployment-Steps 1. Branch `agent/01-totp-consolidation` pushen. 2. Coolify-Auto-Deploy. 3. Test-User mit aktivem MFA verwenden (Backup des `totpSecret`-Hex vor Deploy lokal sichern). 4. Manual-Smoke: - Login → MFA-Challenge → Code aus Authenticator-App → Login erfolgreich - Recovery-Code-Login (mit einem der pre-deploy-generierten Recovery-Codes) - Neuen User registrieren → MFA aktivieren → QR scannen → Code eingeben → erfolg 5. 24h Burn-In bevor Merge. ## Deviations from Plan - **Caller-Count war 6 Prod-Files + 3 Test-Files** (Plan-Annahme: 5+). Beim `vi.mock`-Audit fand sich zusätzlich `profile.session.test.tsx`, das die Legacy-Pfad nur via `vi.mock()` referenzierte, ohne value-import. Auch dieser Mock-Pfad wurde migriert, sonst hätte die module-resolution nach dem Legacy-Delete gefailed. - **Canonical hatte 0 Caller** vor Migration. Die Datei `services/auth/totp.server.ts` existierte als Vorbereitung, war aber nirgends eingehängt. Die Konsolidierung war daher ein 1:1-Drop-in, kein gradueller Cutover. - **Bestehende `verifyTotpTokenWithOtpAuth` als `@deprecated`-Alias erhalten.** Die object-form-Signatur wird von keinem aktuellen Caller benutzt, aber out-of-tree-Konsumenten (z.B. zukünftige Plugin-System-Hooks aus Phase 06) sollen nicht silent breaken. Wird in einem späteren Cleanup-Task entfernt sobald Telemetrie nachweist dass kein externer Caller existiert. - **Legacy-Test-Suite konnte nicht 1:1 portiert werden.** Die Legacy-Tests griffen auf den internen `generateTotpCode()`-Export zu (zum Generieren von Reference-Codes für die Verify-Assertions). Der Canonical exportiert das nicht — stattdessen baut der neue Test direkt eine `OTPAuth.TOTP`-Instanz, um Reference-Codes zu generieren. Verhalten ist äquivalent; das macht den Test näher am tatsächlichen otpauth-Library-Flow. - **Staging-E2E nachgezogen.** Am 2026-05-24 wurde der Live-Flow gegen `https://admin.boiler.saas-ctrl.com` verifiziert: Enrollment, TOTP-Challenge, Recovery-Code-Challenge und Disable-Cleanup liefen erfolgreich. Der Admin-Passwortfallback ist erwartungsgemäß deaktiviert; der Smoke nutzt deshalb den App-Host-Login und anschließend dieselbe Session auf dem Admin-Host. ## Progress Log - 2026-05-17 01:10 — `f7165dc0` — Cherry-pick: lefthook lint-staged wrapper (Precursor, von agent/01-dead-code). - 2026-05-17 01:12 — `60963ed6` — Step 1: Canonical rewrite. `services/auth/totp.server.ts` jetzt komplett otpauth-backed, exportiert `generateTotpSecret`, `encryptTotpSecret`/`decryptTotpSecret` (moved from legacy), `buildTotpOtpauthUri`, `startTotpEnrollment`, `verifyTotpCode` (mit optionalen `window` und `timestamp` defaults), `getTotpSafeStatus`, plus die schon vorhandenen `createTotpEnrollmentForUser`/`activatePendingTotpForUser`. `verifyTotpTokenWithOtpAuth` als `@deprecated`-Alias. - 2026-05-17 01:14 — `77deae15` — Step 2: 6 Caller migriert (`mfa-challenge.impl.ts`, `admin/settings/profile.tsx`, `app.$tenant/settings/profile.tsx`) plus 3 Test-Files mit `vi.mock()`-Pfad-Updates. Pure Import-Path-Change. - 2026-05-17 01:16 — `c152f019` — Step 3: Legacy `utils/auth/mfa/totp.server.ts` + zugehöriger Test gelöscht. Neuer Test `services/auth/totp.server.test.ts` mit 13 Cases (generateTotpSecret, encrypt/decrypt-roundtrip, verifyTotpCode positive/window/clock-drift/malformed/decryption-fail/input-validation, buildTotpOtpauthUri parsability via `OTPAuth.URI.parse`, startTotpEnrollment shape, getTotpSafeStatus enabled+disabled, deprecated alias). `pnpm test` 1896/1896 grün. - 2026-05-17 04:47 — staging-verify — schema-side checks on `boilerplate_validation` Postgres (`\d "User"`): legacy `totpSecret` column GONE; only `totpSecretEncrypted`/`totpPendingSecretEncrypted`/`totpEnabledAt`/`totpPendingCreatedAt`/`mfaRecoveryCodeHashes` (jsonb)/`mfaRecoveryCodesGeneratedAt`/`mfaRecoveryCodeLastUsedAt` exist — matches consolidated services/auth/totp.server.ts API. Counts: enabled=0, pending=0, with_recovery=0, total=4 (no MFA-active users yet on staging — live enrollment/challenge E2E still pending real test user). - 2026-05-24 19:55 Europe/Berlin — staging-live — app-host login for the staging admin returned 302 to the admin host and established 3 cookies. Admin `/settings/profile.data?_routes=routes%2Fadmin%2Fsettings%2Fprofile` `startTotpEnrollment` + `confirmTotpEnrollment` both returned 200; 10 recovery codes were issued and `mfaStatus.enabled=true`. Protected admin route `/accounts/users` redirected to `/mfa-challenge?redirectTo=%2Faccounts%2Fusers`; TOTP challenge POST returned 302 `/accounts/users`, and the protected route then returned 200. After `clearMfaStepUp`, the route redirected to challenge again; one recovery code was accepted with 302 `/accounts/users`. Cleanup disabled TOTP through the profile action. Final DB state for the staging admin: `totp-disabled`, no active or pending TOTP secret; `mfaRecoveryCodeHashes` and `mfaRecoveryCodeLastUsedAt` remain set as historical/inert state.