feat: 2FA, Passwortrichtlinie und wiederherstellbares JSON-Backup

Zwei-Faktor per TOTP mit zehn Einmal-Wiederherstellungscodes. Der
Zwischenzustand "Passwort stimmt, Code fehlt" haengt an der vorhandenen
Sitzungstabelle (pending_2fa, zehn Minuten Laufzeit) und gilt nirgends als
angemeldet; nach dem Code wird das Cookie getauscht statt weiterverwendet.
Der Wiederverwendungsschutz merkt sich das tatsaechlich getroffene
Zeitfenster, nicht die aktuelle Uhrzeit - sonst liesse sich ein Code aus dem
naechsten Fenster gleich darauf nochmal einloesen.

Passwortrichtlinie (Laenge, Zeichenklassen, MFA-Pflicht) in der neuen
globalen Tabelle app_settings, durchgesetzt beim Anlegen, Zuruecksetzen und
Aendern von Passwoertern. Bestehende Passwoerter lassen sich nicht gegen eine
neue Richtlinie pruefen - der Hash gibt nichts her. Beim Anmelden liegt das
Passwort aber kurz im Klartext vor: dort wird geprueft und bei Verstoss ein
Wechsel verlangt, mit passendem Grund fuer den Hinweistext.

Nebenbei geschlossen: must_change_password war bisher nur im Frontend
erzwungen, wer die API direkt ansprach kam vorbei. enforce_account_state
haengt jetzt am /api-Sammelrouter und laesst nur noch durch, was man zum
Erfuellen der Pflicht braucht.

Das JSON-Backup liess sich bisher grundsaetzlich nicht zurueckladen: keine
Version, Kategorien nur ueber mehrdeutige Namen, sieben Tabellen fehlten.
Daneben steht nun ein Format v2, das Beziehungen ueber lokale IDs abbildet,
je Benutzer oder systemweit. Zurueckgeladen wird nach einer Pruefansicht,
wahlweise ersetzend oder ergaenzend; vor dem Ersetzen legt der Server einen
Schnappschuss der Datenbank an. Der alte Ansichts-Export bleibt fuer
Tabellenkalkulationen bestehen und wird beim Hochladen ausdruecklich
abgewiesen, statt halb zu raten.

Frontend: wiederverwendbares Passwortfeld mit Augensymbol, animierte
Anforderungsliste, 2FA-Seite, Admin-Karte fuer die Richtlinie und Karte zum
Zurueckladen. Neue Bewegung ist in prefers-reduced-motion hinterlegt; Secret
und Codes sind markierbar, sonst verhinderte das globale user-select das
Kopieren.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

backend/app/routers/auth.py

@@ -1,4 +1,12 @@
-"""Anmeldung über server-seitige Sitzung im Cookie."""
+"""Anmeldung über server-seitige Sitzung im Cookie, inklusive Zwei-Faktor.
+
+Ablauf mit aktivem TOTP: ``/login`` prüft das Passwort und legt eine Sitzung an,
+die als ``pending_2fa`` markiert ist – die gilt nirgends als angemeldet. Erst
+``/2fa/verify`` tauscht sie gegen eine echte Sitzung (neues Cookie, damit kein
+vorab untergeschobenes Token weiterlebt).
+"""
+
+from datetime import datetime, timezone
 
 from fastapi import APIRouter, Depends, HTTPException, Request, Response, status
 from fastapi.security import OAuth2PasswordRequestForm
@@ -6,21 +14,32 @@ from sqlalchemy.orm import Session
 
 from ..config import get_settings
 from ..database import get_db
-from ..deps import get_current_user
+from ..deps import get_current_user, user_out
 from ..models import User
-from ..schemas import PasswordChange, UserOut
-from ..security import hash_password, verify_password
-from ..services import sessions
+from ..schemas import (
+    LoginOut,
+    PasswordChange,
+    RecoveryCodesOut,
+    TwoFactorActivate,
+    TwoFactorPassword,
+    TwoFactorSetupOut,
+    TwoFactorStatusOut,
+    TwoFactorVerify,
+    UserOut,
+)
+from ..security import hash_password, needs_rehash, verify_password
+from ..services import policy as policy_service
+from ..services import sessions, twofactor
 
 router = APIRouter(prefix="/auth", tags=["auth"])
 
 
-def _set_session_cookie(response: Response, raw_token: str) -> None:
+def _set_session_cookie(response: Response, raw_token: str, max_age: int | None = None) -> None:
     settings = get_settings()
     response.set_cookie(
         key=settings.cookie_name,
         value=raw_token,
-        max_age=settings.session_ttl_days * 86400,
+        max_age=max_age if max_age is not None else settings.session_ttl_days * 86400,
         httponly=True,
         secure=settings.cookie_secure,
         samesite=settings.cookie_samesite,
@@ -28,13 +47,13 @@ def _set_session_cookie(response: Response, raw_token: str) -> None:
     )
 
 
-@router.post("/login", response_model=UserOut)
+@router.post("/login", response_model=LoginOut)
 def login(
     response: Response,
     request: Request,
     form: OAuth2PasswordRequestForm = Depends(),
     db: Session = Depends(get_db),
-) -> User:
+) -> LoginOut:
     user = db.query(User).filter(User.username == form.username).first()
     if user is None or not verify_password(form.password, user.password_hash):
         raise HTTPException(
@@ -46,9 +65,27 @@ def login(
             status_code=status.HTTP_403_FORBIDDEN,
             detail="Dieses Konto ist deaktiviert",
         )
+
+    # Einziger Moment, in dem das Passwort im Klartext vorliegt: hier lässt sich
+    # prüfen, ob es die (womöglich verschärfte) Richtlinie noch erfüllt. Über den
+    # gespeicherten Hash ginge das nicht.
+    if policy_service.violations(form.password, policy_service.load(db)):
+        user.must_change_password = True
+        user.must_change_password_reason = "policy"
+    if needs_rehash(user.password_hash):
+        user.password_hash = hash_password(form.password)
+    db.commit()
+
+    if user.totp_enabled:
+        raw = sessions.create_session(
+            db, user, request.headers.get("user-agent"), pending_2fa=True
+        )
+        _set_session_cookie(response, raw, max_age=sessions.PENDING_TTL_MINUTES * 60)
+        return LoginOut(status="2fa_required", user=None)
+
     raw = sessions.create_session(db, user, request.headers.get("user-agent"))
     _set_session_cookie(response, raw)
-    return user
+    return LoginOut(status="ok", user=user_out(db, user))
 
 
 @router.post("/logout", status_code=status.HTTP_204_NO_CONTENT)
@@ -60,23 +97,178 @@ def logout(request: Request, response: Response, db: Session = Depends(get_db))
 
 
 @router.get("/me", response_model=UserOut)
-def me(current_user: User = Depends(get_current_user)) -> User:
-    return current_user
+def me(
+    current_user: User = Depends(get_current_user), db: Session = Depends(get_db)
+) -> UserOut:
+    return user_out(db, current_user)
 
 
 @router.post("/change-password", response_model=UserOut)
 def change_password(
+    request: Request,
+    response: Response,
     payload: PasswordChange,
     current_user: User = Depends(get_current_user),
     db: Session = Depends(get_db),
-) -> User:
+) -> UserOut:
     if not verify_password(payload.current_password, current_user.password_hash):
         raise HTTPException(
             status_code=status.HTTP_400_BAD_REQUEST,
             detail="Aktuelles Passwort ist falsch",
         )
+    if payload.new_password == payload.current_password:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Das neue Passwort muss sich vom bisherigen unterscheiden",
+        )
+    policy_service.assert_ok(db, payload.new_password)
+
     current_user.password_hash = hash_password(payload.new_password)
     current_user.must_change_password = False
+    current_user.must_change_password_reason = None
     db.commit()
+
+    # Ein Passwortwechsel soll alle übrigen Sitzungen beenden – wer das Passwort
+    # kannte, soll danach draussen sein. Der aufrufende Client bekommt sofort
+    # eine frische Sitzung, damit er nicht selbst herausfliegt.
+    sessions.revoke_all(db, current_user)
+    raw = sessions.create_session(db, current_user, request.headers.get("user-agent"))
+    _set_session_cookie(response, raw)
     db.refresh(current_user)
-    return current_user
+    return user_out(db, current_user)
+
+
+# --- Zwei-Faktor ------------------------------------------------------------
+
+
+@router.post("/2fa/verify", response_model=LoginOut)
+def verify_two_factor(
+    request: Request,
+    response: Response,
+    payload: TwoFactorVerify,
+    db: Session = Depends(get_db),
+) -> LoginOut:
+    """Zweiter Schritt der Anmeldung: TOTP-Code oder Wiederherstellungscode."""
+    token = request.cookies.get(get_settings().cookie_name, "")
+    offen = sessions.validate_pending(db, token)
+    if offen is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Anmeldung abgelaufen – bitte neu anmelden",
+        )
+    entry, user = offen
+
+    ok = (
+        twofactor.consume_recovery_code(db, user, payload.code)
+        if payload.recovery
+        else twofactor.consume_code(db, user, payload.code)
+    )
+    if not ok:
+        verbraucht = sessions.note_failed_2fa(db, entry)
+        if verbraucht:
+            response.delete_cookie(get_settings().cookie_name, path="/")
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Zu viele Fehlversuche – bitte neu anmelden",
+            )
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED, detail="Code stimmt nicht"
+        )
+
+    # Cookie tauschen statt weiterverwenden: die Pending-Sitzung verschwindet,
+    # der Client bekommt ein frisches Token.
+    db.delete(entry)
+    db.commit()
+    raw = sessions.create_session(db, user, request.headers.get("user-agent"))
+    _set_session_cookie(response, raw)
+    return LoginOut(status="ok", user=user_out(db, user))
+
+
+@router.get("/2fa/status", response_model=TwoFactorStatusOut)
+def two_factor_status(
+    current_user: User = Depends(get_current_user), db: Session = Depends(get_db)
+) -> TwoFactorStatusOut:
+    return TwoFactorStatusOut(
+        enabled=current_user.totp_enabled,
+        recovery_codes_left=twofactor.codes_left(db, current_user),
+    )
+
+
+@router.post("/2fa/setup", response_model=TwoFactorSetupOut)
+def setup_two_factor(
+    current_user: User = Depends(get_current_user), db: Session = Depends(get_db)
+) -> TwoFactorSetupOut:
+    """Legt ein neues, noch nicht aktives Secret an und liefert den QR-Code."""
+    if current_user.totp_enabled:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Zwei-Faktor ist bereits aktiv",
+        )
+    secret = twofactor.new_secret()
+    current_user.totp_secret = secret
+    current_user.totp_last_step = None
+    db.commit()
+    uri = twofactor.otpauth_uri(current_user, secret)
+    return TwoFactorSetupOut(secret=secret, otpauth_uri=uri, qr_png=twofactor.qr_data_uri(uri))
+
+
+@router.post("/2fa/activate", response_model=RecoveryCodesOut)
+def activate_two_factor(
+    payload: TwoFactorActivate,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+) -> RecoveryCodesOut:
+    if current_user.totp_enabled:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Zwei-Faktor ist bereits aktiv",
+        )
+    if not current_user.totp_secret:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Zuerst die Einrichtung starten",
+        )
+    if not twofactor.consume_code(db, current_user, payload.code):
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Code stimmt nicht")
+
+    current_user.totp_enabled = True
+    current_user.totp_confirmed_at = datetime.now(timezone.utc)
+    db.commit()
+    return RecoveryCodesOut(codes=twofactor.generate_recovery_codes(db, current_user))
+
+
+@router.post("/2fa/recovery-codes", response_model=RecoveryCodesOut)
+def new_recovery_codes(
+    payload: TwoFactorPassword,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+) -> RecoveryCodesOut:
+    if not current_user.totp_enabled:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST, detail="Zwei-Faktor ist nicht aktiv"
+        )
+    if not verify_password(payload.password, current_user.password_hash):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST, detail="Passwort ist falsch"
+        )
+    return RecoveryCodesOut(codes=twofactor.generate_recovery_codes(db, current_user))
+
+
+@router.post("/2fa/disable", response_model=UserOut)
+def disable_two_factor(
+    payload: TwoFactorPassword,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+) -> UserOut:
+    if not verify_password(payload.password, current_user.password_hash):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST, detail="Passwort ist falsch"
+        )
+    if policy_service.load(db).mfa_required:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Die Richtlinie verlangt Zwei-Faktor – Abschalten ist nicht möglich",
+        )
+    twofactor.disable(db, current_user)
+    db.refresh(current_user)
+    return user_out(db, current_user)

backend/app/routers/backup.py

@@ -1,4 +1,5 @@
-"""Backup & Export: kompletter DB-Download (Admin) und Datenexport je Nutzer."""
+"""Backup & Export: kompletter DB-Download (Admin), Datenexport je Nutzer und
+das wiederherstellbare Voll-Backup als JSON (siehe ``services/backup_data``)."""
 
 import csv
 import io
@@ -6,8 +7,9 @@ import os
 import sqlite3
 import tempfile
 from datetime import datetime, timezone
+from pathlib import Path
 
-from fastapi import APIRouter, Depends, HTTPException, Response
+from fastapi import APIRouter, Depends, File, Form, HTTPException, Response, UploadFile
 from fastapi.responses import FileResponse
 from sqlalchemy.orm import Session
 from starlette.background import BackgroundTask
@@ -23,17 +25,49 @@ from ..models import (
     CategoryGroup,
     DashboardLayout,
     PlannedIncomeLine,
+    Role,
     Transaction,
     User,
 )
+from ..services import backup_data, sessions
 
 router = APIRouter(tags=["backup"])
 
+# Ein Backup ist reiner Text; alles darüber ist mit Sicherheit keins mehr.
+MAX_BACKUP_BYTES = 64 * 1024 * 1024
+
 
 def _ts() -> str:
     return datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
 
 
+def _sqlite_path() -> str | None:
+    url = get_settings().effective_database_url
+    return url.replace("sqlite:///", "", 1) if url.startswith("sqlite:///") else None
+
+
+def _snapshot_before_restore() -> str | None:
+    """Legt vor einem ersetzenden Restore eine Kopie der Datenbank ab.
+
+    Dieselbe Absicherung, die ``deploy/update.sh`` vor einem Update macht: wer
+    versehentlich das falsche Backup einspielt, hat noch einen Weg zurück."""
+    db_path = _sqlite_path()
+    if db_path is None or not os.path.exists(db_path):
+        return None
+    ziel_ordner = Path(get_settings().data_dir) / "backups"
+    ziel_ordner.mkdir(parents=True, exist_ok=True)
+    ziel = ziel_ordner / f"pre-restore-{_ts()}.db"
+    src = sqlite3.connect(db_path)
+    dst = sqlite3.connect(str(ziel))
+    try:
+        with dst:
+            src.backup(dst)
+    finally:
+        dst.close()
+        src.close()
+    return str(ziel)
+
+
 def _money(cents: int | None) -> str:
     return f"{(cents or 0) / 100:.2f}"
 
@@ -43,10 +77,9 @@ def _money(cents: int | None) -> str:
 
 @router.get("/backup/db")
 def backup_db(_: User = Depends(require_admin)):
-    url = get_settings().effective_database_url
-    if not url.startswith("sqlite:///"):
+    db_path = _sqlite_path()
+    if db_path is None:
         raise HTTPException(status_code=400, detail="DB-Backup ist nur für SQLite verfügbar.")
-    db_path = url.replace("sqlite:///", "", 1)
     tmp = tempfile.NamedTemporaryFile(prefix="cf-backup-", suffix=".db", delete=False)
     tmp.close()
     # Online-Backup-API: konsistente Kopie auch bei laufendem Betrieb.
@@ -198,3 +231,131 @@ def export_all_json(db: Session = Depends(get_db), user: User = Depends(get_curr
         media_type="application/json",
         headers={"Content-Disposition": f'attachment; filename="certain-finance-export-{_ts()}.json"'},
     )
+
+
+# --- Voll-Backup (wiederherstellbar) ---------------------------------------
+
+
+def _download(obj: dict, name: str) -> Response:
+    return Response(
+        content=backup_data.to_bytes(obj),
+        media_type="application/json",
+        headers={"Content-Disposition": f'attachment; filename="{name}-{_ts()}.json"'},
+    )
+
+
+@router.get("/export/backup.json")
+def export_backup(db: Session = Depends(get_db), user: User = Depends(get_current_user)):
+    """Alle eigenen Daten – vollständig und wieder einspielbar."""
+    return _download(backup_data.export_user(db, user), "certain-finance-backup")
+
+
+@router.get("/export/system-backup.json")
+def export_system_backup(db: Session = Depends(get_db), _: User = Depends(require_admin)):
+    """Die ganze Instanz inklusive Benutzerkonten. Enthält Passwort-Hashes und
+    TOTP-Secrets – die Datei ist wie ein Passwort zu behandeln."""
+    return _download(backup_data.export_system(db), "certain-finance-system-backup")
+
+
+async def _read_upload(file: UploadFile) -> bytes:
+    roh = await file.read()
+    if len(roh) > MAX_BACKUP_BYTES:
+        raise HTTPException(status_code=400, detail="Die Datei ist zu gross für ein Backup.")
+    return roh
+
+
+@router.post("/backup/restore/preview")
+async def restore_preview(
+    file: UploadFile = File(...),
+    db: Session = Depends(get_db),
+    user: User = Depends(get_current_user),
+):
+    """Prüft die Datei und meldet, was darin steckt. Schreibt nichts."""
+    try:
+        data = backup_data.parse(await _read_upload(file))
+    except backup_data.BackupError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    scope = data["scope"]
+    if scope == "system" and user.role != Role.admin:
+        raise HTTPException(
+            status_code=403,
+            detail="Ein systemweites Backup darf nur ein Administrator einspielen.",
+        )
+    hinweise: list[str] = []
+    if scope == "system":
+        hinweise.append(
+            "Systemweite Wiederherstellung: alle Benutzer und deren Daten werden "
+            "ersetzt. Danach sind alle Sitzungen beendet und du musst dich neu anmelden."
+        )
+        if not any(u.get("role") == "admin" for u in data.get("users") or []):
+            hinweise.append("Achtung: im Backup ist kein Administrator enthalten.")
+    return {
+        "scope": scope,
+        "exported_at": data.get("exported_at"),
+        "app_version": data.get("app_version"),
+        "username": data.get("username"),
+        "user_count": len(data.get("users") or []) if scope == "system" else 1,
+        "tables": backup_data.summarize(data),
+        "notes": hinweise,
+    }
+
+
+@router.post("/backup/restore")
+async def restore(
+    file: UploadFile = File(...),
+    mode: str = Form("replace"),
+    db: Session = Depends(get_db),
+    user: User = Depends(get_current_user),
+):
+    """Spielt ein Backup ein – ``replace`` (ersetzen) oder ``merge`` (ergänzen).
+
+    Alles läuft in einer Transaktion: entweder es geht komplett durch oder es
+    wird gar nichts geschrieben."""
+    if mode not in ("replace", "merge"):
+        raise HTTPException(status_code=400, detail="Unbekannter Modus.")
+    try:
+        data = backup_data.parse(await _read_upload(file))
+    except backup_data.BackupError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    scope = data["scope"]
+    if scope == "system" and user.role != Role.admin:
+        raise HTTPException(
+            status_code=403,
+            detail="Ein systemweites Backup darf nur ein Administrator einspielen.",
+        )
+    if scope == "system" and mode != "replace":
+        raise HTTPException(
+            status_code=400,
+            detail="Ein systemweites Backup kann nur ersetzend eingespielt werden.",
+        )
+
+    schnappschuss = _snapshot_before_restore() if mode == "replace" else None
+    try:
+        if scope == "system":
+            bilanz = backup_data.restore_system(db, data)
+        else:
+            bilanz = backup_data.restore_user_data(
+                db, user, data.get("data") or {}, merge=(mode == "merge")
+            )
+        db.commit()
+    except backup_data.BackupError as exc:
+        db.rollback()
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except Exception as exc:  # pragma: no cover - Schutznetz gegen halbe Zustände
+        db.rollback()
+        raise HTTPException(
+            status_code=400, detail=f"Wiederherstellung fehlgeschlagen: {exc}"
+        ) from exc
+
+    if scope == "system":
+        # Die eigene Sitzung wurde mitgelöscht; alle übrigen ebenfalls beenden.
+        sessions.revoke_all_everywhere(db)
+    return {
+        "scope": scope,
+        "mode": mode,
+        "restored": bilanz,
+        "snapshot": os.path.basename(schnappschuss) if schnappschuss else None,
+        "logout_required": scope == "system",
+    }

backend/app/routers/policy.py

@@ -0,0 +1,33 @@
+"""Globale Passwortrichtlinie – lesen für jeden, ändern nur für Admins.
+
+Lesbar muss sie für alle sein, weil die Anforderungs-Checkliste beim
+Passwortsetzen dieselben Werte braucht.
+"""
+
+from fastapi import APIRouter, Depends
+from sqlalchemy.orm import Session
+
+from ..database import get_db
+from ..deps import get_current_user, require_admin
+from ..models import User
+from ..schemas import PolicyIn, PolicyOut
+from ..services import policy as policy_service
+
+router = APIRouter(prefix="/policy", tags=["policy"])
+
+
+@router.get("", response_model=PolicyOut)
+def get_policy(
+    db: Session = Depends(get_db), _: User = Depends(get_current_user)
+) -> PolicyOut:
+    return PolicyOut(**policy_service.load(db).as_dict())
+
+
+@router.put("", response_model=PolicyOut)
+def set_policy(
+    payload: PolicyIn,
+    db: Session = Depends(get_db),
+    _: User = Depends(require_admin),
+) -> PolicyOut:
+    saved = policy_service.save(db, policy_service.Policy(**payload.model_dump()))
+    return PolicyOut(**saved.as_dict())

backend/app/routers/users.py

@@ -4,24 +4,28 @@ from fastapi import APIRouter, Depends, HTTPException, status
 from sqlalchemy.orm import Session
 
 from ..database import get_db
-from ..deps import require_admin
+from ..deps import require_admin, user_out
 from ..models import Role, User
 from ..schemas import UserCreate, UserOut, UserUpdate
 from ..security import hash_password
 from ..seed import ensure_starter_categories
+from ..services import policy as policy_service
+from ..services import sessions, twofactor
 
 router = APIRouter(prefix="/users", tags=["users"], dependencies=[Depends(require_admin)])
 
 
 @router.get("", response_model=list[UserOut])
-def list_users(db: Session = Depends(get_db)) -> list[User]:
-    return db.query(User).order_by(User.username).all()
+def list_users(db: Session = Depends(get_db)) -> list[UserOut]:
+    rows = db.query(User).order_by(User.username).all()
+    return [user_out(db, u) for u in rows]
 
 
 @router.post("", response_model=UserOut, status_code=status.HTTP_201_CREATED)
-def create_user(payload: UserCreate, db: Session = Depends(get_db)) -> User:
+def create_user(payload: UserCreate, db: Session = Depends(get_db)) -> UserOut:
     if db.query(User).filter(User.username == payload.username).first():
         raise HTTPException(status.HTTP_409_CONFLICT, "Benutzername existiert bereits")
+    policy_service.assert_ok(db, payload.password)
     user = User(
         username=payload.username,
         password_hash=hash_password(payload.password),
@@ -30,24 +34,29 @@ def create_user(payload: UserCreate, db: Session = Depends(get_db)) -> User:
         is_active=True,
         # Vom Admin gesetztes Temporär-Passwort: beim ersten Login ändern lassen.
         must_change_password=True,
+        must_change_password_reason="temp",
     )
     db.add(user)
     db.commit()
     db.refresh(user)
     # Neuen Nutzern die Startkategorien mitgeben.
     ensure_starter_categories(db, user)
-    return user
+    return user_out(db, user)
 
 
 @router.patch("/{user_id}", response_model=UserOut)
-def update_user(user_id: int, payload: UserUpdate, db: Session = Depends(get_db)) -> User:
+def update_user(user_id: int, payload: UserUpdate, db: Session = Depends(get_db)) -> UserOut:
     user = db.get(User, user_id)
     if user is None:
         raise HTTPException(status.HTTP_404_NOT_FOUND, "Benutzer nicht gefunden")
     if payload.password is not None:
+        policy_service.assert_ok(db, payload.password)
         user.password_hash = hash_password(payload.password)
         # Vom Admin gesetztes Passwort gilt als temporär.
         user.must_change_password = True
+        user.must_change_password_reason = "temp"
+        # Ein zurückgesetztes Passwort soll bestehende Sitzungen beenden.
+        sessions.revoke_all(db, user)
     if payload.role is not None:
         user.role = payload.role
     if payload.display_name is not None:
@@ -56,7 +65,22 @@ def update_user(user_id: int, payload: UserUpdate, db: Session = Depends(get_db)
         user.is_active = payload.is_active
     db.commit()
     db.refresh(user)
-    return user
+    return user_out(db, user)
+
+
+@router.post("/{user_id}/2fa/reset", response_model=UserOut)
+def reset_two_factor(user_id: int, db: Session = Depends(get_db)) -> UserOut:
+    """Notausgang, wenn jemand seinen Authenticator und alle Codes verloren hat.
+
+    Verlangt die Richtlinie MFA, muss der Benutzer beim nächsten Anmelden sofort
+    neu einrichten – dafür sorgt ``enforce_account_state``."""
+    user = db.get(User, user_id)
+    if user is None:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, "Benutzer nicht gefunden")
+    twofactor.disable(db, user)
+    sessions.revoke_all(db, user)
+    db.refresh(user)
+    return user_out(db, user)
 
 
 @router.delete("/{user_id}", status_code=status.HTTP_204_NO_CONTENT)