Track HiveGrid Cloud planning reference
This commit is contained in:
1 parent
b3d5ea6764
commit
e341c5938a
5784 files changed
+1104929
-3
No files matched your search
@@ -0,0 +1,170 @@
|
||||
# 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.
|
||||
Reference in new issue
Block a user