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 +avorgit 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):
-
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ährtrequireUserId(liestuserId) keinen Zugriff — Gate hält. -
Verify-Route (neu, tenant-fähig; Muster:
apps/web/app/routeModules/admin/mfa-challenge.impl.ts). LiestpendingMfaUserIdaus 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(setztuserId, löschtpendingMfaUserId). Rate-Limit viaapps/web/app/utils/auth/mfa/challenge-rate-limit.server.ts. Routen sind folder-convention-autoregistriert (createRoutesFromFolders) — neue Datei = neue Route. -
session.server.ts:pendingMfaUserId?: string(+pendingMfaRedirectTo?) in denUserSession-Typ, increateUserSession/getUserInfodurchreichen.requireUserIdnicht ändern (liestuserId). -
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-Cookietrusted-device(HMAC über userId+random, serverseitig gegen eineTrustedDevice-Tabelle geprüft) oder eineTrustedDevice-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(+ Testsession.server.test.tsmockt 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.
requireUserIdlehnt den Pending-Zustand ab (kein Zugriff vor Verify) — unverändert (liest nuruserId).- 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 testgrü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 inapps/web/public/locales/{de,en}/*.json(Parität!).auth.jsonfür Auth-Fehler,settings.json(flache Dot-Keys). - Login-Tests haben Nicht-TOTP-User → der neue Zweig greift dort nicht (additiv, kein Bruch).
verifyTotpCodenimmt das verschlüsselte Secret (siehe Admin-impl Z.135 wie es geholt wird).- AD-21: Schema-Änderungen (falls
TrustedDevice-Tabelle) viaprisma db pushauf dem Branch; lokale DB war down → Dockerpgvector/pgvector:pg16(Setup-Muster im Header vonapps/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(oderPLANE_API_KEY). Basehttps://project.tool-ctrl.de, Workspacetoolctrl, Projekt35d0d968-8ab3-40cc-97b8-b81d917dc5df. Identität prüfen viaGET /api/v1/users/me/(mussraffaelsein). - 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.