Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/R-P2a.md
T

19 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 Done (Plane; Stand-Audit 2026-07-17: 6/6 DoD im Code belegt)

🎨 design-nachzug: offen (seit 2026-07-06) — Interim-UI (new-account „Workspace anlegen / ohne Tenant") aus ~/ui steht; finale Subframe-Optik aus D-P2 (Signup/2FA/Geräteliste/Tenant-Auswahl/new-account) ausstehend, nicht Done-blockierend (AD-28).

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

Alle Bausteine code-seitig gebaut + getestet (3741 Tests grün, Branch p2a-auth-tenant). Haken = umgesetzt; finale Screen-Optik/Abnahme läuft über D-P2 (Ticket steht daher auf Blocked / wartet-auf-screen, nicht Done).

  • Self-Service-Signup + Auto-Slug (Reserved-Words geblockt) + Auto-SHK-Seed (Signup+Slug fertig; Auto-SHK-Seed bewusst → P6, da CRM-Entitäten erst dort existieren)
  • 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 (Backend + Routen fertig; finale Screen-Optik via D-P2)
  • 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 · Milestones: (M018/M020/M021/M022)
  • designer-briefs/P02-identitaet-mandantentrennung.md · Ticket-Doc D-P2.md

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

  • Interim-UI aus ~/ui gebaut (AD-28, 2026-07-06, Akeshan-Beitrag). Der bisher einzige handgeschriebene Auth-Screen new-account („Workspace anlegen / ohne Tenant") ist jetzt aus ~/ui komponiert (apps/web/app/components/screens/auth/CreateWorkspacePage.tsx, AuthShell + ~/ui, VM/Props als Prop, kein handgeschriebenes Tailwind, Fehler als inline Alert statt Legacy-ErrorModal); die Route rendert nur noch <CreateWorkspacePage … />, die Legacy-TenantNew wurde abgelöst/gelöscht. Die übrigen sechs Auth-Screens (Signup/Login/2FA/Forgot/Tenant-Auswahl/Security/Profil) liefen bereits auf ~/ui (Davids WF-P2/D-P2). Zusätzlich M015/M017-Hot-Swap-Stack für die zwei VM-Screens nachgezogen (session-list, select-tenant): view-models-Mapper + ui-subframe/ui-mock-Renderer + ui-app-Adapter + Tests. Stabile Marker (ui.account.create.*) erhalten, Smoke tests/e2e/new-account.spec.ts ergänzt.
  • Finale Subframe-Optik aus D-P2 (Signup/2FA/Geräteliste/Tenant-Auswahl/new-account) — Swap hinter der stabilen VM/Loader-Grenze; design-nachzug: offen, Plane-Label design-nachzug. Nicht Done-blockierend (AD-28).
  • Auth-Flows an Davids UI-Entscheidungen angepasst (Signup-Felder, 2FA-Flow)
  • REQUIREMENTS/ROADMAP nachgezogen
  • Plane-Ticket R-P2a aktualisiert (Kommentar + Label design-nachzug)

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).

Umsetzungsstand (Akeshan, 2026-07-06 — Interim-UI aus ~/ui (AD-28) + Hot-Swap-Layer)

Branch p2a-newaccount-interim-ui (Akeshan-Beitrag auf Raffaels Ticket). Bestandsaufnahme: die in der 06-19-Notiz als „minimale Inline-UI als Swap-Ziel" beschriebenen Auth-Screens waren im Arbeitsbaum bereits auf ~/ui gehoben (Davids WF-P2/D-P2) — Signup/Login/2FA/Forgot/Tenant-Auswahl/Security/ Profil. Einziger echter handgeschriebener Rest: new-account.

Gebaut:

  • Interim-Screen CreateWorkspacePage (apps/web/app/components/screens/auth/) aus AuthShell + ~/ui (TextInput/Button/Alert/LinkButton), VM/Props als Prop, kein handgeschriebenes Tailwind. Route new-account.tsx verschlankt (Loader/Action unverändert), Legacy TenantNew abgelöst/gelöscht. Fehler jetzt inline Alert statt ErrorModal; e2e-Fehlerpfad + Smoke tests/e2e/new-account.spec.ts nachgezogen.
  • M015/M017-Hot-Swap-Stack für die zwei VM-Screens: toSessionListModel/toSelectTenantModel + Model-Typen (view-models), renderSessionList/renderSelectTenant (ui-subframe), …Mock (ui-mock), sessionListAdapter/selectTenantAdapter (ui-app) + .hot-swap.test.ts. Schließt DoD D18/D20 für die zwei VM-gestützten Auth-Screens (session-list, select-tenant).

Proof (2026-07-06): isolierte vitest-Suiten grün (39/39: CreateWorkspacePage 3 · adapter hot-swap 6 · model-mapper 8 · VM 14 · ui-subframe/ui-mock index 4 · acquisition 4) · Typecheck web/view-models/ ui-subframe/ui-mock/ui-app grün (ui-app-Fixture filterOptions nachgezogen) · verify:i18n 0 · verify:cross-cutting-models 178/178 · verify:sidebar-routes 27/27 · Lint grün, keine neuen Escape-Hatches. Windows-Umgebung: test:hot-swap (tsx-ESM) + einige undici-new Request-Tests fallen environmental (Node 22.15) → CI (Node 22.12) grün. Nicht nach main gemergt (PR-Review folgt).

Offen (nicht Done-blockierend, AD-28): finale Subframe-Optik aus D-P2 (design-nachzug: offen).

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.

Dependency-Nachzug 2026-07-15 · R-P20b

  • Der hier bewusst verschobene Auto-SHK-Default ist jetzt zentral in R-P20b umgesetzt. Es sind echte Workspace-Defaults, keine Demo-/Seed-Daten.
  • Self-Service bleibt der Primärpfad: Signup erzeugt User, Owner-Mitgliedschaft, globale Admin-Zuweisung und SHK-Defaults atomar und aktiviert den Tenant erst als letzten DB-Schritt.
  • Die sichtbaren AGB-/Datenschutz-Checkboxen werden zusätzlich serverseitig erzwungen; ein direkt gebauter POST kann die UI-Sperre nicht umgehen.

Regression-Nachzug 2026-07-29 · konfigurierte Pflichtfelder

Der Live-Audit des Staging-Registrierungsflows hat eine serverseitige Lücke gezeigt: Bei direkter Registrierung übersprang ein gültiges Passwort wegen einer else if-Kette die nachfolgenden Prüfungen für Firma sowie Vor- und Nachname. Leerstrings galten außerdem als vorhanden.

  • Passwort-, Organisations- und Namensprüfung laufen jetzt unabhängig voneinander.
  • requireOrganization verlangt eine nicht-leere Firma; requireName verlangt nicht-leeren Vor- und Nachnamen.
  • Das Registrierungsformular markiert Vor- und Nachname passend zur Serverkonfiguration als required; Firma nutzte diesen Vertrag bereits.
  • Regressionstests decken Direktregistrierung, initialen E-Mail-Verifizierungs-POST, Leerstrings und die Formularattribute ab.

Proof: pnpm typecheck, pnpm lint, pnpm test (7.847 grün, 60 übersprungen), 34 fokussierte Registrierungs-/Screen-Tests, verify:i18n, verify:source-health, verify:ci-baseline und git diff --check grün.

Fortschritt: R-P2a bleibt bei 6/6 DoD = 100 % done. Der Nachzug härtet den bestehenden Signup-Vertrag; er erweitert weder Scope noch Datenmodell.