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

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.ts und AuthService.ts — Registration prüft length >= 4
  • apps/web/app/routes/...reset.tsx:67-70 — Reset prüft length >= 6
  • apps/web/app/routes/app.$tenant/settings/profile.tsx:282-296 — Profile-Update prüft length >= 8 + Klassen-Mix
  • apps/web/app/routes/admin/accounts/users.tsx:196-201 — Admin-Reset prüft eigene Variante
  • apps/web/app/routes/invitation.$id.tsx — keine explizite Prüfung
  • apps/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 — default 12 (OWASP-empfohlen)
  • AUTH_PASSWORD_REQUIRE_UPPER — default true
  • AUTH_PASSWORD_REQUIRE_LOWER — default true
  • AUTH_PASSWORD_REQUIRE_DIGIT — default true
  • AUTH_PASSWORD_REQUIRE_SPECIAL — default false (UX-Trade-off)
  • AUTH_PASSWORD_HIBP_CHECK — default true (k-Anonymity-API gegen https://api.pwnedpasswords.com/range/)
  • AUTH_PASSWORD_HIBP_MAX_OCCURRENCES — default 0 (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

  1. Modul password-policy.server.ts schreiben

    • 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
  2. 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
  3. 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, bei valid: false Error mit den errors[]-Strings zurückgeben.
    • Commit: 01/password-policy: enforce in registration flow
  4. Reset-Pfad migrieren

    • Files: apps/web/app/routes/reset.tsx:67-70 (und ggf. das zugehörige Action-File)
    • Aktion: Inline-Check raus, validatePassword rein.
    • Commit: 01/password-policy: enforce in password reset
  5. Profile-Update-Pfad migrieren

    • Files: apps/web/app/routes/app.$tenant/settings/profile.tsx:282-296
    • Aktion: Inline-Check raus, validatePassword rein.
    • Commit: 01/password-policy: enforce in profile update
  6. Admin-Reset-Pfad migrieren

    • Files: apps/web/app/routes/admin/accounts/users.tsx:196-201
    • Aktion: Inline-Check raus, validatePassword rein. Admin-Override-Flag NICHT einführen (Admins sollen die Policy ebenfalls einhalten).
    • Commit: 01/password-policy: enforce in admin user reset
  7. Invitation-Pfad migrieren

    • Files: apps/web/app/routes/invitation.$id.tsx
    • Aktion: bei Invitation-Acceptance mit Passwort-Setup → validatePassword aufrufen.
    • Commit: 01/password-policy: enforce in invitation acceptance
  8. 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 mit silent: true-Mode. Bei valid: false → Session-Flag passwordPolicyOutdated: true setzen → Dashboard zeigt Banner.
    • Commit: 01/password-policy: add soft-check on login with dashboard banner
  9. 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

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.email gegeben)
    • 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.ts 100%
  • 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.ts existiert und exportiert validatePassword
  • 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/web liefert keine Auth-Stellen)
  • HIBP-Check ist via Env aktivierbar/deaktivierbar
  • Dashboard-Banner zeigt sich bei Login mit Policy-violating Password
  • Env-Keys in .env.example dokumentiert
  • docs/auth/password-policy.md erstellt
  • Unit-Test-Coverage 100% für password-policy.server.ts
  • pnpm lint, pnpm typecheck, pnpm test grü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: boolean und Error-Counts.

Subagent Recommendations

  • Planning: unnötig.
  • Research: general-purpose fü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-purpose für Acceptance-Criteria-Check.
  • Code-Review: gsd-code-reviewer nach Phase-Abschluss, speziell Security-Pfade.

Staging-Deployment-Steps

  1. Branch agent/01-password-policy pushen.
  2. Coolify-Auto-Deploy.
  3. 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)
  4. HIBP-Outage-Simulation: AUTH_PASSWORD_HIBP_CHECK=false setzen + Restart → Registration mit "Password123!" sollte durchgehen (fail-open-Verifizierung).
  5. 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.loginFromRequest calls validatePassword(plain, { email }) non-throwing right after credential verification, capturing any policy violation into a new passwordPolicyOutdated session flag without blocking the login. The app.$tenant tenant-layout loader evaluates a pure helper (apps/web/app/services/auth/password-policy-banner.server.ts) that combines that flag with the pwPolicyRemindAfter snooze cookie and returns a passwordPolicyBanner: { show } field for the component. A new PasswordPolicyBanner (yellow WarningBanner-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 route api.password-policy-remind (sets pwPolicyRemindAfter=<unix-millis>; Path=/; Max-Age=604800; SameSite=Lax), and a per-page-load dismiss button. Auth namespace gets new passwordPolicyBanner.* 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 when validatePassword throws), 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-existing uiInventory.test.ts failure documented in PROGRESS.md remains untouched). No DB schema changes; no background scan job; policy-non-compliance is decided lazily at login time.