Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/01-tech-debt-foundation/totp-consolidation.md
T

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:

  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
  • 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.