195 lines
13 KiB
Markdown
195 lines
13 KiB
Markdown
# 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/<prefix>)
|
|
- `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.
|