Files
HiveGrid-Wireframes/hivegrid-cloud/.planning/HANDOFF-D1-login-2fa-gate.md
T

6.9 KiB

Handoff — D1: Login-2FA-Gate + Trust-Device (Backend)

Temporäres Handoff (löschbar nach Erledigung). Für einen frischen Agenten, der nur D1 fertigbaut. Lies zuerst AGENTS.md + .planning/ticket-docs/R-P2a.md + R-P2b.md. Stand: 2026-06-18.

Mission

Erzwinge 2FA (TOTP) beim Tenant-Login (Produktentscheidung 18.06.). Heute fragt der Login keinen TOTP-Code ab (2FA nur als Step-up für sensible Aktionen). Baue das Login-Gate als Backend; die Code-Eingabe-Screen liefert David (D-P2) — baue eine minimale funktionale Inline-UI als Swap-Ziel.

Arbeitsbranch

p2b-rls (auf origin, enthält Upstream-Merge + komplettes R-P2a inkl. S4b + R-P2b RLS/Lifecycle/Rollen + D2/D3). Bau D1 auf p2b-rls weiter (oder eigener Branch off p2b-rls). Nicht nach main mergen/pushen (main auto-deployt auf Staging). Alles ist grün: pnpm test = 3758 passed | 6 skipped (RLS-Integration skippt ohne DB).

Toolchain / Befehle (WICHTIG)

  • Node 22.12.0 via fnm — vor JEDEM pnpm: eval "$(fnm env)"; fnm use 22.12.0
  • pnpm typecheck · pnpm lint (--max-warnings=0) · pnpm test · pnpm run verify:i18n
  • Pre-Push-Hook braucht DB-URLs: set -a; . ./.env; set +a vor git push origin p2b-rls
  • Commits enden mit: Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Das Design (so umsetzen)

Zwei-Schritt-Login (die bestehende Step-up-Infra reicht NICHT — die setzt schon eingeloggten userId voraus):

  1. loginFromRequest (apps/web/app/modules/users/services/AuthService.ts, ~Z.156). Nach erfolgreichem Passwort-Check + clearFailedLogins(...), vor der Session-Erstellung:

    const totpStatus = await getUserTotpStatus(user.id); // users.db.server.ts
    if (totpStatus?.enabled) {
      // KEINE Session. Pending-MFA-Zustand ins SIGNIERTE Cookie: pendingMfaUserId (NICHT userId!)
      // + pendingMfaRedirectTo (rohes redirectTo). Antwort { requiresMfa: true } + Set-Cookie.
      return beginPendingMfaLogin({ userId: user.id, redirectTo });
    }
    // sonst: bisheriger Pfad (startServerSession + createUserSession)
    

    Da pendingMfaUserId ≠ userId, gewährt requireUserId (liest userId) keinen Zugriff — Gate hält.

  2. Verify-Route (neu, tenant-fähig; Muster: apps/web/app/routeModules/admin/mfa-challenge.impl.ts). Liest pendingMfaUserId aus dem Cookie → verifyTotpCode(encryptedSecret, code) oder Recovery-Code (apps/web/app/utils/auth/mfa/recovery-codes.server.ts) → bei Erfolg: setLoggedUser + getHome + startServerSession (services/auth/sessionLifecycle.server.ts) + createUserSession (setzt userId, löscht pendingMfaUserId). Rate-Limit via apps/web/app/utils/auth/mfa/challenge-rate-limit.server.ts. Routen sind folder-convention-autoregistriert (createRoutesFromFolders) — neue Datei = neue Route.

  3. session.server.ts: pendingMfaUserId?: string (+ pendingMfaRedirectTo?) in den UserSession-Typ, in createUserSession/getUserInfo durchreichen. requireUserId nicht ändern (liest userId).

  4. Trust-Device (kann Folgeschritt sein): „diesem Gerät vertrauen → künftig Code überspringen" braucht einen PERSISTENTEN Geräte-Marker, der den Logout überlebt — NICHT UserSession.trustedAt (das ist per Session!). Vorschlag: signierter Long-Lived-Cookie trusted-device (HMAC über userId+random, serverseitig gegen eine TrustedDevice-Tabelle geprüft) oder eine TrustedDevice-Tabelle (userId, tokenHash, expiresAt). In Schritt 1 vor dem Gate prüfen → wenn vertrauenswürdig, MFA überspringen. In Schritt 2 bei „remember" setzen.

Schlüssel-Dateien

  • Login: apps/web/app/modules/users/services/AuthService.ts (loginFromRequest)
  • TOTP: apps/web/app/services/auth/totp.server.ts (verifyTotpCode, getTotpSafeStatus)
  • TOTP-Status/Secret: apps/web/app/utils/db/users.db.server.ts (getUserTotpStatus, getUserTotpPendingEnrollment)
  • Recovery-Codes: apps/web/app/utils/auth/mfa/recovery-codes.server.ts
  • MFA-Rate-Limit: apps/web/app/utils/auth/mfa/challenge-rate-limit.server.ts
  • Admin-Muster (spiegeln): apps/web/app/routeModules/admin/mfa-challenge.impl.ts
  • Cookie/Session: apps/web/app/utils/session.server.ts (+ Test session.server.test.ts mockt store/lifecycle)
  • Server-Session: apps/web/app/services/auth/sessionLifecycle.server.ts (startServerSession)
  • Enrollment (existiert, Tenant): apps/web/app/routes/app.$tenant/settings/profile.tsx

DoD (D1) — ERLEDIGT 2026-06-18 (Details in .planning/ticket-docs/R-P2a.md, Abschnitt „D1")

  • TOTP-User bekommt mit Passwort allein keine Session (Gate); Antwort requiresMfa.
  • Verify-Route schließt Login ab (TOTP und Recovery-Code), inkl. Server-Session-Erzeugung.
  • requireUserId lehnt den Pending-Zustand ab (kein Zugriff vor Verify) — unverändert (liest nur userId).
  • Trust-Device-Skip via persistentem Marker (signiertes RJ_trusted_device-Cookie, 30 Tage; ohne DB-Tabelle).
  • Minimale Code-Eingabe-UI (data-ui-id) als Swap-Ziel für Davids D-P2 (routeModules/auth/login-mfa.component.tsx).
  • i18n-Keys (de+en) für alle UI-Texte (account.loginMfa.*). Tests: TOTP-User→requiresMfa, Verify-OK→Session, Verify-Falsch→Reject, Nicht-TOTP-User→normaler Login (Regression). Bestehende Login-Tests bleiben grün.
  • pnpm typecheck + pnpm lint + pnpm run verify:i18n + pnpm test grün (3777 passed | 6 skipped).

Restpunkt (Folge): tabellengestützte Einzel-Geräte-Widerrufbarkeit (TrustedDevice-Tabelle). Handoff kann nach Plane-Pflege gelöscht werden.

Gotchas

  • i18n-Guard: user-facing Strings MÜSSEN i18n-Keys sein (kein Klartext auf description/title/Label-Props). Keys in apps/web/public/locales/{de,en}/*.json (Parität!). auth.json für Auth-Fehler, settings.json (flache Dot-Keys).
  • Login-Tests haben Nicht-TOTP-User → der neue Zweig greift dort nicht (additiv, kein Bruch).
  • verifyTotpCode nimmt das verschlüsselte Secret (siehe Admin-impl Z.135 wie es geholt wird).
  • AD-21: Schema-Änderungen (falls TrustedDevice-Tabelle) via prisma db push auf dem Branch; lokale DB war down → Docker pgvector/pgvector:pg16 (Setup-Muster im Header von apps/web/app/utils/db/.server/rls-tenant-isolation.integration.test.ts).

Plane (Ticket-Pflege)

  • R-P2a #18 = 4b52fe1d-eb78-42b2-a169-ad410553d86f; R-P2b #19 = 1a0471a4-3a68-41b6-a21c-421200267230.
  • Token: ~/.cli-tokens/plane (oder PLANE_API_KEY). Base https://project.tool-ctrl.de, Workspace toolctrl, Projekt 35d0d968-8ab3-40cc-97b8-b81d917dc5df. Identität prüfen via GET /api/v1/users/me/ (muss raffael sein).
  • Kommentar-Stil: Prefix „Claude: ", 1. Person (= raffael), schlicht, kein AI-Sprech, keine Em-Dashes (—), korrekte Umlaute.
  • Abschluss: Ticket-Doc (.planning/ticket-docs/R-P2a.md) Umsetzungsstand + Proof ergänzen, dann Plane-Kommentar.