13 KiB
Passwort-Policy-Konsolidierung
Status: completed Task-ID: #27 Phase: 01 Estimated Effort: 1 Tag Owner: claude (opus-4-7)
Problem
Im Codebase existieren mindestens fünf verschiedene Passwort-Validierungen mit inkonsistenten Regeln:
apps/web/app/utils/db/users.db.server.tsundAuthService.ts— Registration prüftlength >= 4apps/web/app/routes/...reset.tsx:67-70— Reset prüftlength >= 6apps/web/app/routes/app.$tenant/settings/profile.tsx:282-296— Profile-Update prüftlength >= 8+ Klassen-Mixapps/web/app/routes/admin/accounts/users.tsx:196-201— Admin-Reset prüft eigene Varianteapps/web/app/routes/invitation.$id.tsx— keine explizite Prüfungapps/web/app/routes/login.tsx— keine Soft-Check- HIBP-Check (haveibeenpwned) komplett unimplementiert
Konsequenz:
- Ein User kann sein Passwort auf "1234" via Registration setzen, aber bei Profile-Update wird ihm dasselbe Passwort verweigert.
- Compliance-Risiko (GDPR §32, ISO 27001 A.9.4.3 verlangen konsistente Password-Hygiene).
- Wartungslast bei Policy-Anpassungen → 5 Stellen.
Depends on
01-tech-debt-foundation/dep-updates.md(#28) — bcryptjs → argon2 muss vorher fertig sein, damit die neue Policy gegen den argon2-Hasher arbeitet (Konsistenz-Check beim Reset: alter bcrypt-Hash wird beim erfolgreichen Verify mit dem neuen Passwort durch argon2 ersetzt).01-tech-debt-foundation/totp-consolidation.md(#26) — empfohlen vorher (saubere Auth-Foundation), nicht hart blockierend.
Blocks
01-tech-debt-foundation/magic-link-reset.md(#19) — Magic-Link-Reset-Flow soll die neue Policy ebenfalls erzwingen wenn User danach ein Passwort setzt.01-tech-debt-foundation/magic-link-invitation.md(#20) — Invitation-Flow setzt Passwort beim Onboarding → muss die neue Policy nutzen.- Phase 10 Compliance — Compliance-Audit wird die konsistente Password-Policy als Pflicht-Kontrolle prüfen.
Approach
Single-Source-of-Truth: apps/web/app/services/auth/password-policy.server.ts als zentrale Validierungs-Funktion. Env-konfigurierbar, server-only, exportiert eine validatePassword(plain: string, context?: { email?: string; previousHash?: string }): Promise<{ valid: boolean; errors: string[] }>.
Env-Variables (mit Defaults):
AUTH_PASSWORD_MIN_LENGTH— default12(OWASP-empfohlen)AUTH_PASSWORD_REQUIRE_UPPER— defaulttrueAUTH_PASSWORD_REQUIRE_LOWER— defaulttrueAUTH_PASSWORD_REQUIRE_DIGIT— defaulttrueAUTH_PASSWORD_REQUIRE_SPECIAL— defaultfalse(UX-Trade-off)AUTH_PASSWORD_HIBP_CHECK— defaulttrue(k-Anonymity-API gegen https://api.pwnedpasswords.com/range/)AUTH_PASSWORD_HIBP_MAX_OCCURRENCES— default0(jeder Treffer blockt)
Alle existierenden Inline-Checks (>=4, >=6, >=8) werden gelöscht und durch validatePassword()-Aufrufe ersetzt.
Login-Soft-Check: optional ein Logger-Hint wenn das eingegebene Passwort die aktuelle Policy nicht erfüllt (z.B. "Dein Passwort entspricht nicht mehr unserer aktuellen Sicherheits-Policy. Bitte aktualisieren.") — Anzeige im Dashboard-Banner nach Login. KEIN harter Block (würde User aussperren).
Alternativen verworfen:
- Zod-Schema-only — kann HIBP-Async-Check nicht abbilden, scheidet aus.
- Client-only Validation — bypassbar via API-Call, unsicher.
- Library
zxcvbn— gut für Strength-Meter, aber kein Ersatz für deterministische Regeln. Optional als Zusatz-Feature in Phase 10.
Implementation Steps
-
Modul
password-policy.server.tsschreiben- Files:
apps/web/app/services/auth/password-policy.server.ts(neu) - Aktion:
- Env-Read-Helper (Default-Werte einsetzen wenn nicht gesetzt)
validatePassword(plain, ctx?)-Funktion: prüft Länge, Klassen, optional HIBP via k-Anonymity-API, optional contextual checks (z.B. Passwort darf nicht die Email enthalten).- HIBP-Helper: SHA-1-Hash vom Passwort, erste 5 Chars an
https://api.pwnedpasswords.com/range/<prefix>schicken, Suffix-Match in Response prüfen. Plaintext-Passwort verlässt niemals den Server. - HIBP-Failure-Mode: bei Timeout/5xx vom HIBP-Service →
valid: true(fail-open, damit Service-Downtime keine User aussperrt), Log-Entry mit Severity warning. - Klare Error-Strings (i18n-keys statt hardcoded Strings, damit Phase 10 i18n-foundation diese später ersetzen kann).
- Commit:
01/password-policy: add central validation service
- Files:
-
Unit-Tests für
password-policy.server.ts- Files:
apps/web/app/services/auth/password-policy.server.test.ts(neu) - Aktion: Tests für alle Env-Kombinationen, HIBP-mock (fetch-mock), Edge-Cases (leerer String, Unicode, sehr lange Passwörter).
- Commit:
01/password-policy: add unit tests
- Files:
-
Registration-Pfad migrieren
- Files:
apps/web/app/utils/db/users.db.server.ts,apps/web/app/services/auth/AuthService.ts(oder wo immer Registration läuft) - Aktion: alte Inline-Length-Checks entfernen,
validatePassword(plain, { email })aufrufen, beivalid: falseError mit denerrors[]-Strings zurückgeben. - Commit:
01/password-policy: enforce in registration flow
- Files:
-
Reset-Pfad migrieren
- Files:
apps/web/app/routes/reset.tsx:67-70(und ggf. das zugehörige Action-File) - Aktion: Inline-Check raus,
validatePasswordrein. - Commit:
01/password-policy: enforce in password reset
- Files:
-
Profile-Update-Pfad migrieren
- Files:
apps/web/app/routes/app.$tenant/settings/profile.tsx:282-296 - Aktion: Inline-Check raus,
validatePasswordrein. - Commit:
01/password-policy: enforce in profile update
- Files:
-
Admin-Reset-Pfad migrieren
- Files:
apps/web/app/routes/admin/accounts/users.tsx:196-201 - Aktion: Inline-Check raus,
validatePasswordrein. Admin-Override-Flag NICHT einführen (Admins sollen die Policy ebenfalls einhalten). - Commit:
01/password-policy: enforce in admin user reset
- Files:
-
Invitation-Pfad migrieren
- Files:
apps/web/app/routes/invitation.$id.tsx - Aktion: bei Invitation-Acceptance mit Passwort-Setup →
validatePasswordaufrufen. - Commit:
01/password-policy: enforce in invitation acceptance
- Files:
-
Login-Soft-Check
- Files:
apps/web/app/routes/login.tsx(Action), neuer Hook/Component für Dashboard-Banner - Aktion: nach erfolgreichem Login
validatePassword(plain, { email })aufrufen mitsilent: true-Mode. Beivalid: false→ Session-FlagpasswordPolicyOutdated: truesetzen → Dashboard zeigt Banner. - Commit:
01/password-policy: add soft-check on login with dashboard banner
- Files:
-
Env-Dokumentation
- Files:
.env.example,docs/auth/password-policy.md(neu) - Aktion: alle neuen
AUTH_PASSWORD_*-Keys mit Defaults und Begründung dokumentieren. - Commit:
01/password-policy: document env keys
- Files:
Test Requirements
- Unit-Tests:
password-policy.server.test.ts:- Length-Validation (genau am Boundary +/- 1)
- Each character-class flag in isolation
- HIBP-mock: gefundener Treffer → valid:false; nicht gefunden → valid:true; HIBP-5xx → valid:true (fail-open)
- Email-Substring-Check (wenn
ctx.emailgegeben) - Unicode-Passwörter
- Default-Env-Values produzieren die erwarteten Constraints
- Integration-Tests: pro migriertem Endpoint (Registration, Reset, Profile, Admin-Reset, Invitation):
- Schwaches Passwort wird mit konkretem Error-String abgelehnt
- Starkes Passwort wird akzeptiert
- E2E-Tests (Playwright):
- Registration mit "test1234" → Error sichtbar
- Registration mit "ZqK9$pXvL3mNw!" → erfolg
- Login mit aktuell schwachem Passwort → Banner sichtbar nach Login
- Coverage-Target:
password-policy.server.ts100% - Test-Files:
apps/web/app/services/auth/password-policy.server.test.ts(neu)- bestehende Route-Tests erweitern
NICHT als completed markieren bevor alle migrierten Endpoints in Integration-Tests gegen die neue Policy laufen.
Acceptance Criteria
apps/web/app/services/auth/password-policy.server.tsexistiert und exportiertvalidatePassword- Alle 6 Inline-Password-Checks (Registration, Reset, Profile, Admin-Reset, Invitation, Login-Soft) sind ersetzt
- Keine Inline-Length-Checks (>=4/>=6/>=8) mehr im Codebase (
rg "length\\s*>=\\s*(4|6|8)" apps/webliefert keine Auth-Stellen) - HIBP-Check ist via Env aktivierbar/deaktivierbar
- Dashboard-Banner zeigt sich bei Login mit Policy-violating Password
- Env-Keys in
.env.exampledokumentiert docs/auth/password-policy.mderstellt- Unit-Test-Coverage 100% für
password-policy.server.ts pnpm lint,pnpm typecheck,pnpm testgrün- Detail-MD Progress-Log aktualisiert
- PROGRESS.md Status auf
completed
Rollback Strategy
9 atomic commits → einzeln revert-bar. Praktischer Rollback:
- Bei False-Positive-Reports (User wird abgelehnt obwohl Passwort ok): Env-Tweak via Coolify (z.B.
AUTH_PASSWORD_HIBP_CHECK=false) ohne Code-Deploy. Sofort wirksam nach App-Restart. - Bei kompletter Policy-Regression: Commits 3-8 revert + Re-Deploy.
- Datenbank: keine Schema-Changes → kein DB-Rollback nötig.
Feature-Flag-Option: Policy könnte hinter AUTH_PASSWORD_POLICY_ENFORCE=true gesteckt werden für graduelle Aktivierung. Empfohlen für Production-Rollout-Woche.
Security Notes
- HIBP via k-Anonymity — Plaintext-Passwort verlässt niemals den Server. Nur erste 5 Chars des SHA-1-Hashes werden gesendet. Suffix-Match passiert lokal.
- Fail-Open bei HIBP-Down ist eine bewusste Sicherheits-Entscheidung: Service-Disruption vs Policy-Bypass-Window. Wir wählen "User können sich registrieren wenn HIBP down" — alternative wäre "User können sich nicht registrieren bei HIBP-Outage". Im Audit-Log soll die HIBP-Bypass-Situation explizit getrackt werden (Counter).
- Minimum-Length 12 ist OWASP-Empfehlung 2023+ — niedrigere Werte (8) gelten als nicht mehr sicher gegen GPU-Brute-Force.
- Klassen-Requirements (Upper/Lower/Digit) haben begrenzten Sicherheits-Nutzen wenn Länge ausreichend ist — wir aktivieren sie aber als defense-in-depth + Compliance-Erwartung.
- Login-Soft-Check darf User nicht aussperren — kritisch wichtig. Nur Hint via Banner.
- Logging: validatePassword darf NIEMALS das Plaintext-Passwort oder dessen Hash loggen. Nur
valid: booleanund Error-Counts.
Subagent Recommendations
- Planning: unnötig.
- Research:
general-purposefür Endpoint-Inventur — Brief: "Identifiziere alle Stellen im Codebase wo ein Passwort als Form-Input akzeptiert wird (Registration, Reset, Profile, Admin, Invitation, Login). Pro Endpoint: File+Action-Function+aktuelle Validierungs-Logik." - Implementation: ein
general-purpose-Subagent für Steps 1+2 (Modul+Tests), dann ein zweiter für Steps 3-8 (Endpoint-Migration), dann ein dritter für Step 9 (Doku). - Tests: mit dem Modul-Schreib-Subagent kombiniert (TDD).
- Verification:
general-purposefür Acceptance-Criteria-Check. - Code-Review:
gsd-code-reviewernach Phase-Abschluss, speziell Security-Pfade.
Staging-Deployment-Steps
- Branch
agent/01-password-policypushen. - Coolify-Auto-Deploy.
- Smoke-Tests:
- Registration mit schwachem Passwort → Error
- Registration mit starkem Passwort → erfolg
- Login mit Legacy-User (4-Zeichen-Passwort aus Test-Fixtures) → Login erfolgreich + Banner sichtbar
- HIBP-Check: Registration mit "Password123!" → sollte abgelehnt werden (in HIBP-Top-Liste)
- HIBP-Outage-Simulation:
AUTH_PASSWORD_HIBP_CHECK=falsesetzen + Restart → Registration mit "Password123!" sollte durchgehen (fail-open-Verifizierung). - Audit-Log auf Staging prüfen: HIBP-Bypass-Counter wird erhöht wenn API nicht erreichbar.
Deviations from Plan
(leer)
Progress Log
- 2026-05-25 — Login soft-check banner landed (
a1c4532b). The deferred step 8 of the implementation plan is now in.AuthService.loginFromRequestcallsvalidatePassword(plain, { email })non-throwing right after credential verification, capturing any policy violation into a newpasswordPolicyOutdatedsession flag without blocking the login. Theapp.$tenanttenant-layout loader evaluates a pure helper (apps/web/app/services/auth/password-policy-banner.server.ts) that combines that flag with thepwPolicyRemindAftersnooze cookie and returns apasswordPolicyBanner: { show }field for the component. A newPasswordPolicyBanner(yellowWarningBanner-style, reuses the existing palette) renders above<Outlet />with three controls: "Change password now" linking to/app/<tenant>/settings/profile, "Remind me in 7 days" POSTing to the new resource routeapi.password-policy-remind(setspwPolicyRemindAfter=<unix-millis>; Path=/; Max-Age=604800; SameSite=Lax), and a per-page-load dismiss button. Auth namespace gets newpasswordPolicyBanner.*keys in en/de. New tests: 13 unit tests on the decision helper, 3 integration tests on the AuthService soft-check (flag-set, flag-not-set, fail-open whenvalidatePasswordthrows), 2 resource-route tests covering the 204 + Set-Cookie roundtrip and the 405 GET guard — 18/18 green. Typecheck green. No new test failures introduced (the pre-existinguiInventory.test.tsfailure documented in PROGRESS.md remains untouched). No DB schema changes; no background scan job; policy-non-compliance is decided lazily at login time.