14 KiB
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:
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.apps/web/app/services/auth/totp.server.ts— Wrapper um dieotpauth-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
-
Caller-Inventur
- Files: keine (Recherche)
- Aktion:
rg "utils/auth/mfa/totp"undrg "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
-
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): stringunddecryptTotpSecret(encrypted: string): string— single source for at-rest-encryption (AES-GCM via existierenderapps/web/app/utils/crypto/...Pfad)
- Commit:
01/totp: expose unified API on services/auth/totp.server.ts
- Files:
-
Caller-Migration
- Files: alle in Step 1 identifizierten Caller-Files
- Aktion: pro Caller Import von
utils/auth/mfa/totp.server.tsaufservices/auth/totp.server.tsumstellen. Funktions-Signaturen anpassen wo nötig. - Commit:
01/totp: migrate N callers from legacy mfa/totp to services/auth/totp
-
Legacy-Datei entfernen
- Files:
apps/web/app/utils/auth/mfa/totp.server.ts(komplett löschen), ggf. zugehörigerutils/auth/mfa/-Folder wenn leer - Aktion: Datei löschen.
pnpm typecheck+pnpm lintmüssen grün sein → wenn ein Import noch übrig: Schritt 3 unvollständig. - Commit:
01/totp: remove legacy self-built TOTP implementation
- Files:
-
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):generateTotpSecretliefert valide otpauth-URL (parsbar viaURLmit Protokollotpauth:)verifyTotpTokenakzeptiert Token im aktuellen WindowverifyTotpTokenmitwindow=1akzeptiert ±30s-Drift, lehnt ±60s abverifyTotpTokenmit explizitemtimestamp-Parameter ist deterministischencryptTotpSecret+decryptTotpSecretRoundtrip- 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.tsexistiert nicht mehr- Alle TOTP-Caller importieren aus
apps/web/app/services/auth/totp.server.ts verifyTotpTokenist mitwindow=1als Default konfiguriertverifyTotpTokenakzeptiert optionalentimestamp-Parameter für TestsencryptTotpSecret/decryptTotpSecretsind die einzige Crypto-Schicht für TOTP-Secrets-at-Rest- Unit-Tests Coverage ≥ 95% für
services/auth/totp.server.ts - MFA-Enrollment + MFA-Challenge + Recovery-Codes-Flow auf Staging grün
pnpm lint,pnpm typecheck,pnpm testgrü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ürutils/auth/mfa/totpundservices/auth/totpim 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-reviewernach Phase-Abschluss.
Staging-Deployment-Steps
- Branch
agent/01-totp-consolidationpushen. - Coolify-Auto-Deploy.
- Test-User mit aktivem MFA verwenden (Backup des
totpSecret-Hex vor Deploy lokal sichern). - 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
- 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ätzlichprofile.session.test.tsx, das die Legacy-Pfad nur viavi.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.tsexistierte als Vorbereitung, war aber nirgends eingehängt. Die Konsolidierung war daher ein 1:1-Drop-in, kein gradueller Cutover. - Bestehende
verifyTotpTokenWithOtpAuthals@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 eineOTPAuth.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.comverifiziert: 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.tsjetzt komplett otpauth-backed, exportiertgenerateTotpSecret,encryptTotpSecret/decryptTotpSecret(moved from legacy),buildTotpOtpauthUri,startTotpEnrollment,verifyTotpCode(mit optionalenwindowundtimestampdefaults),getTotpSafeStatus, plus die schon vorhandenencreateTotpEnrollmentForUser/activatePendingTotpForUser.verifyTotpTokenWithOtpAuthals@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 mitvi.mock()-Pfad-Updates. Pure Import-Path-Change. - 2026-05-17 01:16 —
c152f019— Step 3: Legacyutils/auth/mfa/totp.server.ts+ zugehöriger Test gelöscht. Neuer Testservices/auth/totp.server.test.tsmit 13 Cases (generateTotpSecret, encrypt/decrypt-roundtrip, verifyTotpCode positive/window/clock-drift/malformed/decryption-fail/input-validation, buildTotpOtpauthUri parsability viaOTPAuth.URI.parse, startTotpEnrollment shape, getTotpSafeStatus enabled+disabled, deprecated alias).pnpm test1896/1896 grün. - 2026-05-17 04:47 — staging-verify — schema-side checks on
boilerplate_validationPostgres (\d "User"): legacytotpSecretcolumn GONE; onlytotpSecretEncrypted/totpPendingSecretEncrypted/totpEnabledAt/totpPendingCreatedAt/mfaRecoveryCodeHashes(jsonb)/mfaRecoveryCodesGeneratedAt/mfaRecoveryCodeLastUsedAtexist — 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%2FprofilestartTotpEnrollment+confirmTotpEnrollmentboth returned 200; 10 recovery codes were issued andmfaStatus.enabled=true. Protected admin route/accounts/usersredirected to/mfa-challenge?redirectTo=%2Faccounts%2Fusers; TOTP challenge POST returned 302/accounts/users, and the protected route then returned 200. AfterclearMfaStepUp, 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;mfaRecoveryCodeHashesandmfaRecoveryCodeLastUsedAtremain set as historical/inert state.