Files
HiveGrid-Wireframes/hivegrid-cloud/.planning/ticket-docs/R-P2a.md
T

13 KiB

R-P2a · P2 Mandant + Auth (Email/PW/HIBP) + Sessions + TOTP

Typ Dev (Code)
Owner Raffael
Phase P2 — Identität & Mandantentrennung
Cycle/Fenster W1 — Fundament & Identität · fällig 2026-06-19 · Gate W1
Status geplant

Abhängigkeiten & Parallelität

  • Blocked by: R-P1b (Service-Kerne + Konnektor), EXT-12 (Geo-IP + HIBP anbinden), AK-INFRA2 (mCaptcha per ENV)
  • Blocks: R-P2b (RLS-Härtung baut auf dem Auth-/Tenant-Kern auf)
  • Läuft parallel zu: Akeshans P4-Schiene (AK-P4a/AK-P4b, Files/Tasks) — erstes echtes Code-Paar P2‖P4. Disjunkte Domänen (Identität vs. Files/Tasks), eigene prisma/schema/*.prisma je Modul → kein Schema-Konflikt (AD-21).
  • Konflikt-Risiko: gering — Berührung an core.prisma/accounts.prisma (Tenant/User), aber Felder additiv; db push auf Branch, Migration erst beim Merge.

Was wir bauen

Den Auth- und Mandanten-Kern: Self-Service-Signup, der Tenant + auto-generierten Slug (Reserved-Words geblockt) + Auto-SHK-Seed erzeugt; Login mit Email+Passwort (NIST-konform, Have-I-Been-Pwned-Breach-Block + Brute-Force-Schutz mit mCaptcha ab 3. Fehlversuch); TOTP-2FA (RFC 6238, QR-Setup + Trust-Device); serverseitige Sessions in Postgres (Source-of-Truth, Geräte-Liste, Revoke einzeln / „überall abmelden") mit Redis-Cache (AD-4). Multi-Tenant-Membership inkl. Tenant-Auswahl.

Benötigte Screens (Backend bedient — Design liefert D-P2 aus D-D0a/D-D0b)

Screen [Route] Kern-Inhalt Liefert (Design)
Signup [/signup] Email, PW (Stärke + Breach-Hinweis), Firmenname, Name, Telefon, USt-ID, AGB/DSGVO/AVV → Tenant + Auto-SHK-Seed D-P2 (A4)
Login [/login] Email, PW, mCaptcha ab 3. Fehlversuch, Magic-Link-Alternative D-P2 (A4)
2FA-Eingabe 6-stelliger TOTP-Code, Trust-Device D-P2 (A4/A5)
Passwort vergessen [/forgot-password] Email → Magic-Link D-P2 (A4)
Tenant-Auswahl + „ohne Tenant" Tenant-Liste (zuletzt genutzt, Suche) / Workspace anlegen / auf Einladung warten D-P2 (A2)
Session-Verwaltung [/settings/security] Aktive Sessions (Gerät/Browser/IP/Standort) + Revoke + „überall abmelden" + Trust-Device-Revoke D-P2 (A2/A6)
Profil [/settings/profile] Name, Avatar, Telefon, PW ändern, 2FA (QR), Hell/Dunkel (Sprache fest DE) D-P2 (A6)

(Davids P2-Screens werden über das Ticket D-P2 geliefert — komponiert aus D-D0a/D-D0b.)

Definition of Done

  • Self-Service-Signup + Auto-Slug (Reserved-Words geblockt) + Auto-SHK-Seed
  • Login Email/PW + HIBP-Breach-Block (NIST) + Brute-Force (mCaptcha ab 3. Fehlversuch) + Magic-Link-Alternative
  • TOTP-2FA (RFC 6238, QR-Setup + Trust-Device)
  • Sessions Postgres-SoT + Redis-Cache (AD-4): Geräte-Liste, Revoke einzeln, „überall abmelden"
  • Multi-Tenant-Membership + Tenant-Auswahl-Screen
  • Konnektor: alle Auth-/Settings-Routen sitzen im App-Shell-Gating (R-P1c)

Technische Bausteine

  • Entities (eigene prisma/schema/accounts.prisma bzw. auth.prisma): Tenant (slug, status trial/active/past_due/frozen/suspended/deletion_pending, default_language), User (email, language, timezone, theme_preference — global, kein RLS), TenantUser, Session (Postgres-SoT + Redis-Cache, browser_fingerprint), TenantUserInvitation (48h, Anlage hier vorbereitet). Boilerplate-ApiKey-Modell bleibt ungenutzt (Scope-Schnitt → v2, nicht in Sidebar).
  • RLS auf Tenant/TenantUser/Session (AD-1); User global ohne RLS.
  • Auth-Block hat HIGH-Boilerplate-Coverage (apps/web/app/services/auth/) — wiederverwenden; RLS = Eigenbau (Boilerplate nur App-Level-Scoping).
  • is_demo_data-Flag am Auto-SHK-Seed (Bulk-Lösch beim Echt-Start).

Quellen (granular)

  • ENTITY-MODEL.md → Domäne 1: Identität & Mandanten (Tenant/User/TenantUser/Session/Invitation) + Tenant/User-Achse
  • REQUIREMENTS.md → REQ-auth-multi-tenancy, REQ-auth-methoden
  • ROADMAP.md → Phase 2 · PHASE-SOURCES.md → Phase 2 (M018/M020/M021/M022)
  • designer-briefs/P02-identitaet-mandantentrennung.md · Ticket-Doc D-P2.md
  • _bmad-output/specs/M27-auth-multi-tenancy.md

Dev-Nachzug (nach Davids D-P2-Delta)

  • Auth-Flows an Davids UI-Entscheidungen angepasst (Signup-Felder, 2FA-Flow)
  • REQUIREMENTS/PHASE-SOURCES nachgezogen
  • Plane-Ticket R-P2a aktualisiert

Umsetzungsstand (Claude, 2026-06-18 — Code-seitig, finale Abnahme mit Davids D-P2 morgen)

Branch p2a-auth-tenant (db push auf Branch, Migration beim Merge — AD-21). Bestandsaufnahme vorab: rund 80 % der Auth-Infrastruktur lag bereits vor (Argon2id, TOTP-Kern, Magic-Link, HIBP aus EXT-12, mCaptcha-Paket, Rate-Limit, Tenant/User/TenantUser-Modelle), meist nur unverdrahtet. Vorab den Upstream-Merge (Subframe-Design-System) eingespielt + auf Staging deployt, damit auf dem frischen Stand gebaut wird. Den finalen DoD-Haken/Done macht Raffael.

Gebaut (code-seitig, Slices, je grün + Tests):

  • S1 — Slug + Reserved-Words (tenantService.ts): validateDesiredTenantSlug() (pure, typisierte Gründe empty/too-short/reserved) + Degenerate-Name-Härtung in getAvailableTenantSlug. Der Reserved-Block selbst lag vor (isReservedTenantSlug/getExistingSlug). Commit 26b5f90b.
  • S2 — Signup (authService.ts): validateDesiredTenantSlug im Signup verdrahtet → reservierte/ zu-kurze Slugs werden mit Klartext (slugReserved/slugTooShort, de+en) abgelehnt statt still umgeschrieben. Befund: Self-Service-Signup, mCaptcha-Verify im Signup und HIBP/Passwort-Policy waren bereits vorhanden + verdrahtet. Commit e0390908.
  • S3 — Login-Härtung (login-captcha-gate.server.ts): eigener Fehlversuch-Counter (IP+Email, 15min), der ab dem 3. Fehlversuch ein mCaptcha verlangt, bevor der Passwort-Check läuft, und bei Erfolg zurücksetzt; in loginFromRequest verdrahtet (no-op ohne mCaptcha-ENV). Harter Rate-Limit (10/min) und HIBP-Soft-Check lagen bereits vor. Commit 63e95552.
  • S4a — serverseitige Sessions (prisma/schema/auth.prisma + sessionStore.server.ts): neues UserSession-Modell (Postgres-SoT, nur Token-Hash gespeichert) + Store (create/get-active/touch/ list/revoke-einzeln/revoke-alle-außer-aktuell/trust) mit kurzlebigem Cache (LRU, Redis-swappable, AD-4). 15 Tests, additiv/non-breaking. Commit 44d87ae2.
  • S5 — TOTP-Enrollment: verifiziert bereits komplett in app/$tenant/settings/profile.tsx (Start→QR, Verify→Recovery-Codes, Disable, Step-Up, Audit; 26 Tests grün). Kein neuer Code nötig.
  • S6 — Geräteliste-VM (packages/view-models/src/auth/session-list.vm.ts, M013): mappt die aktiven Sessions auf ein Geräteliste-VM (current-Flag, Trust, relative Last-Seen als i18n-Bucket, „überall abmelden"-Count). 11 Tests. Befund: Tenant-Auswahl (new-account.tsx/getMyTenants) + Konnektor-Gating (R-P1c in appData/AppSidebar, Settings unter App-Shell) bestehen. Commit 942db7b0.

S4b — Session-Hot-Path-Wiring (nachgezogen 2026-06-18, additiv):

  • S4b-1 (191f1877): Login/Signup/Verify legen die UserSession-Zeile mit Geräte-Kontext an (best-effort) und geben den Token ins Cookie; requireUserId honoriert Revoke (Cookie zerstören + /login, fail-open bei Store-Fehler, Alt-Cookies ohne Token unberührt); logout revoked die Zeile. Cookie bleibt primärer Auth-Mechanismus (kein Bruch). + Revoke-Durchsetzungs-/Lifecycle-Tests.
  • S4b-2 (a4e1f9ca): Route app/$tenant/settings/security — Loader baut das Geräteliste-VM (S6), Action-Callbacks revoke/revoke-all/trust gegen den Store (CSRF). Minimale Inline-UI als Swap-Ziel für Davids D-P2 (M015). i18n settings.security.* (de+en). Loader/Action-Test.
  • Damit ist die Session-Kette end-to-end nutzbar (Login legt an → Revoke/„überall abmelden" greifen).

D1 — 2FA-Login-Gate + Trust-Device (nachgezogen 2026-06-18, additiv):

  • Produktentscheidung 18.06.: TOTP wird beim Tenant-Login erzwungen (vorher fragte der Login keinen Code ab; 2FA lief nur als Step-up für sensible Aktionen). Zweig ist additiv — Nicht-TOTP- Nutzer loggen sich unverändert ein (Regressionstest).
  • Gate (AuthService.loginFromRequest): nach Passwort-OK + clearFailedLogins, vor der Session-Erstellung, prüft getUserTotpStatus. Ist TOTP aktiv (und das Gerät nicht vertrauenswürdig), wird keine Session erzeugt; stattdessen ein signierter Pending-Zustand ins Cookie (pendingMfaUserId, NICHT userId → requireUserId verweigert weiterhin Zugriff) und die Antwort { requiresMfa: true, mfaVerifyPath: "/login-mfa" } + Set-Cookie. Helper commitPendingMfaLoginCookie (session.server.ts) erhält den csrf-Token (Verify-CSRF besteht).
  • Verify-Route (/login-mfa, tenant-fähig; routeModules/auth/login-mfa.{impl,component} + routes/login-mfa.tsx, Ordner-Konvention): Loader liest den Pending-Zustand (kein Pending → /login, schon eingeloggt → /); AuthService.verifyMfaLoginFromRequest prüft TOTP oder Recovery-Code (Rate-Limit via challenge-rate-limit.server), schließt bei Erfolg den Login ab (setLoggedUser + startServerSession + createUserSession, das userId setzt und den Pending-Zustand löscht). Minimale Inline-Code-UI mit data-ui-id als Swap-Ziel für Davids D-P2. i18n account.loginMfa.* (de+en).
  • Trust-Device (tabellengestützt + widerrufbar, 2026-06-19): Modell TrustedDevice (prisma/schema/auth.prisma, Muster UserSession: nur tokenHash, expiresAt, revokedAt, Geräte- Kontext AD-22). „diesem Gerät vertrauen" legt eine widerrufbare Zeile an; das eigene, langlebige, signierte Cookie (RJ_trusted_device, 30 Tage) trägt nur den opaken Token, Autorität ist die Tabelle (trusted-device.server.ts: rememberDeviceForUser/isTrustedDevice/list/revoke/revokeAll/ forgetCurrent). Überlebt den Logout (bewusst NICHT UserSession.trustedAt). Das Login-Gate überspringt bei aktivem Marker den zweiten Faktor. Widerruf über Settings > Sicherheit (Liste + „Vertrauen entziehen" einzeln/alle) → erfüllt DoD-Screen „Trust-Device-Revoke". i18n security.trustedDevices.*. prisma db push beim Merge (DB lokal offline; prisma validate+generate grün).
  • Tests: AuthService.mfaLoginGate.test.ts (9: Gate→requiresMfa, Trusted-Skip, Nicht-TOTP- Regression, Verify TOTP/Recovery/Remember/Falsch/429/kein-Pending), trusted-device.server.test.ts (12: Remember/Round-Trip/Touch/fremde userId/abgelaufen/revoked/kein+manipuliertes Cookie/Revoke/ RevokeAll/Forget/Clear), login-mfa.test.tsx (4), security.test.tsx (+2: forget-device/-all). Bestehende Login-Test-Mocks additiv um getUserTotpStatus ergänzt.
  • Proof (D1): Typecheck grün · pnpm lint grün · pnpm run verify:i18n grün · volle Suite grün · Node 22.12.0. Branch p2b-rls, nicht nach main gemergt.

Bewusst ausgelagert / Rest (dokumentiert):

  • Trust-Device-Konsum + Widerruf: vollständig erledigt (TrustedDevice-Tabelle, Login-Skip, Geräteliste + Einzel-/Alle-Widerruf in Settings > Sicherheit).
  • Voll-SoT (statt additiv): Cookie trägt heute Identität + Token (additiv). Reine Token-im-Cookie- SoT-Variante ist eine spätere Härtung.
  • Geräte-Kontext-Anreicherung: aktuell IP+User-Agent; Geo (geoip/EXT-12) + Browser-Fingerprint später.
  • Auto-SHK-Seed: befüllt CRM-Entitäten (Kontakte/Firmen/Projekte), die erst ab P6 existieren → bei P2 nicht baubar; Seed-Inhalt + is_demo_data-Flag folgen mit den Entity-Phasen.
  • RLS-Härtung: ist R-P2b (Gate-Beweis), nicht hier.
  • Davids D-P2-Screens: finale Optik für Signup/2FA/Geräteliste/Tenant-Auswahl (Swap über Adapter).

Proof: voller Typecheck grün · ESLint --max-warnings=0 grün · i18n-Parität grün · volle Suite 3741 grün (647 Files, +43 ggü. Merge-Baseline) · Node 22.12.0 · prisma validate grün (lokale DB war nicht erreichbar, daher db push offen — Migration ohnehin beim Merge). Branch p2a-auth-tenant (10 Commits), noch nicht nach main gemergt (finale Abnahme mit D-P2).

Status (Stand 2026-06-19)

Backend ~100 % · Ticket-Abschluss wartet auf D-P2 (David). Alle eigenständig baubaren Bausteine (Signup, Login+HIBP+Brute-Force, Server-Sessions+Revoke, TOTP-Enrollment, 2FA-Login-Gate, Trust-Device inkl. Tabellen-Widerruf, Session-IP/AD-22) sind fertig + getestet. Selbst machbar offen: 0. Blockiert: Davids D-P2-Screens (finale Optik Signup/2FA/Geräteliste/Tenant-Auswahl) + finale Abnahme/Merge. prisma db push (TrustedDevice/UserSession) beim Merge.