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

239 lines
19 KiB
Markdown

# 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).
- [x] 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)_
- [x] Login Email/PW + **HIBP-Breach-Block** (NIST) + Brute-Force (mCaptcha ab 3. Fehlversuch) + Magic-Link-Alternative
- [x] **TOTP-2FA** (RFC 6238, QR-Setup + Trust-Device)
- [x] **Sessions Postgres-SoT + Redis-Cache** (AD-4): Geräte-Liste, Revoke einzeln, „überall abmelden"
- [x] Multi-Tenant-Membership + Tenant-Auswahl-Screen _(Backend + Routen fertig; finale Screen-Optik via `D-P2`)_
- [x] 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)
- [x] **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
- [x] 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.