502 lines
23 KiB
Markdown
502 lines
23 KiB
Markdown
---
|
||
module: 27
|
||
title: Auth / Multi-Tenancy / Rollen / Permissions
|
||
phase: 1
|
||
status: detail-spec-draft
|
||
last_updated: 2026-05-08
|
||
session_source: brainstorming-session-2026-05-07-2206.md
|
||
related_lps: [LP-1, LP-2, LP-3, LP-6, LP-8, LP-9, LP-10]
|
||
spec_style: requirements-pur
|
||
---
|
||
|
||
# Modul 27 — Auth / Multi-Tenancy / Rollen / Permissions
|
||
|
||
> **Detail-Spec gemäß LP-9.** Plattform-Fundament. Alles andere baut darauf auf.
|
||
|
||
## Themenblöcke
|
||
|
||
```
|
||
A. Multi-Tenancy-Modell + URL-Struktur
|
||
B. Auth-Methoden
|
||
C. Rollen & Permissions
|
||
D. User-Lifecycle
|
||
E. API-Keys & technische Auth
|
||
F. Feature-Gating
|
||
```
|
||
|
||
---
|
||
|
||
## Block A — Multi-Tenancy + URL-Struktur
|
||
|
||
### A.1 — Tenant-Anlage
|
||
|
||
Zwei Pfade:
|
||
|
||
**Pfad 1: Self-Service** (`hivegrid.de` → Marketing-Site, externe Next.js-App, NICHT Teil der SaaS-Codebase). Signup-Form auf `hivegrid.de/signup` leitet zu `app.hivegrid.de/signup` zur Account-Erstellung.
|
||
|
||
**Pfad 2: Enterprise** (Demo-Buchung über externes Tool auf Marketing-Site, manuelle Tenant-Anlage durch Plattform-Admin nach Vertrag).
|
||
|
||
**Self-Service-Signup-Formular:**
|
||
|
||
| Feld | Pflicht | Anmerkung |
|
||
|---|---|---|
|
||
| Email | ✓ | wird zum User-Account-Identifier |
|
||
| Passwort | ✓ | NIST-konform (siehe B.1) |
|
||
| Firmenname | ✓ | wird zum Default-Tenant-Slug |
|
||
| Vor-/Nachname | ✓ | |
|
||
| Branche | ✓ | SHK pre-selected, andere als „Coming soon" sichtbar |
|
||
| Größe | ✓ | Dropdown 1-10 / 11-25 / 26-50 / 51-100 / 100+ MA |
|
||
| AGB-Akzeptanz | ✓ | Checkbox |
|
||
| DSGVO-Akzeptanz | ✓ | Checkbox |
|
||
| AVV-Akzeptanz | ✓ | Checkbox (PDF wird elektronisch unterschrieben) |
|
||
| Telefonnummer | optional | für Support |
|
||
| USt-Id | optional | für Rechnungen |
|
||
|
||
### A.2 — Tenant-Slug
|
||
|
||
- **Auto-Generierung** aus Firmenname → `geerkens-gmbh` (lowercase, Bindestrich-getrennt, Umlaute → ae/oe/ue, Sonderzeichen weg, Suffix wie GmbH/AG/UG bleibt drin)
|
||
- **User darf editieren** im Signup-Formular
|
||
- **Live-Validierung** beim Tippen:
|
||
- Nur `[a-z0-9-]`, mind. 3, max. 40 Zeichen
|
||
- Reserved Words: `admin`, `app`, `api`, `www`, `help`, `support`, `marketing`, `dev`, `test`, `signup`, `login`, `auth`, `static`, `assets`, `public`, `settings`, `portal`, `buch`, `f`
|
||
- Eindeutigkeit live geprüft (debounced 500ms), bei Konflikt Vorschlag mit Nummer (`geerkens-gmbh-2`)
|
||
- **Slug ist nach Anlage NICHT änderbar** (Bookmark-Stabilität, Auth-URL-Stabilität). Migration-Tool ggf. später als Plattform-Admin-Funktion.
|
||
|
||
### A.3 — URL-Struktur
|
||
|
||
```
|
||
hivegrid.de → Marketing-Page (Next.js, extern)
|
||
app.hivegrid.de → SaaS-Anwendung (Tenant-Welt)
|
||
admin.hivegrid.de → Plattform-Admin (wir, Software-Betreiber)
|
||
```
|
||
|
||
**Routen auf `app.hivegrid.de`:**
|
||
|
||
```
|
||
/ → Login (oder Tenant-Switcher wenn schon eingeloggt)
|
||
/signup → Self-Service-Signup
|
||
/login → Email/Passwort-Login
|
||
/forgot-password → Passwort-Reset
|
||
/verify-email → Email-Verification
|
||
/accept-invitation/{token} → MA-Einladung annehmen
|
||
|
||
/{tenant}/ → Tenant-Dashboard (Default nach Login)
|
||
/{tenant}/contacts → CRM
|
||
/{tenant}/deals → Sales-Pipeline
|
||
/{tenant}/projects → Auftragspipeline
|
||
/{tenant}/... → Modul-Routen
|
||
|
||
/{tenant}/settings/ → Persönliche Settings (jeder User)
|
||
/{tenant}/admin/ → Workspace-Verwaltung (nur tenant.admin)
|
||
|
||
/portal/{tenant}/ → Customer-Portal (eigene User-Klasse)
|
||
/help/{lang}/{slug} → Öffentliches Help-Center
|
||
/buch/{tenant}/{slug} → Öffentliche Booking-Page
|
||
/f/{tenant}/{form-slug} → Embedded-Form
|
||
|
||
/api/v1/... → Public REST-API
|
||
```
|
||
|
||
**Trennung Tenant-Admin vs. Settings:**
|
||
- `/settings/` = persönlich (Profil, Sprache, Theme, Notifications, 2FA, OAuth-Connects, Account löschen)
|
||
- `/admin/` = Workspace-Verwaltung (Mitarbeiter, Rollen, Groups, Billing, Integrationen, API-Keys, Branding (P2), Audit-Log, Export, Lösch-Workflow). Permission-gegated mit `tenant.admin`.
|
||
|
||
**Multi-Tenant-Membership (Anforderungen):**
|
||
- Default nach Login: letzter genutzter Tenant
|
||
- Benötigt: Tenant-Switcher-Komponente (überall in der App verfügbar) mit Liste aller Tenants des Users + Suchfeld-Funktion bei 5+ Tenants
|
||
- Erst-Login mit 2+ Tenants: separater Tenant-Auswahl-Screen
|
||
- `last_accessed_at` pro Tenant für Default-Sortierung
|
||
|
||
**Custom-Domain:** Phase 2, nur Enterprise (`crm.geerkens.de` als CNAME-Alternative zu `app.hivegrid.de/geerkens`).
|
||
|
||
### A.4 — Datenisolation / RLS-Pattern (bauliche Vorgabe)
|
||
|
||
- Jede tenant-scoped Tabelle hat `tenant_id UUID NOT NULL`
|
||
- Policy SELECT/UPDATE/DELETE: `USING (tenant_id = current_setting('app.tenant_id')::uuid)`
|
||
- Policy INSERT: `WITH CHECK (tenant_id = current_setting('app.tenant_id')::uuid)`
|
||
- App-Role hat **kein** `BYPASSRLS`-Privileg
|
||
- Superuser-Role ausschließlich für Migrations
|
||
- Middleware setzt: `SET LOCAL app.tenant_id = '...'` pro Request
|
||
- Sonderfälle (kein RLS, App-Code permission-gegated): `users`, `subscription_plans`, `feature_flags`, `branchen_templates`
|
||
- Hintergrund-Jobs (Worker, Scheduler) setzen Tenant-Context explizit pro Job
|
||
- **Storage-Isolation:** Scaleway-Bucket-Pfad `tenants/{tenantId}/...`
|
||
- **Cache-Isolation:** Redis-Keys mit Präfix `tenant:{tenantId}:...`
|
||
|
||
### A.5 — Tenant-Lifecycle
|
||
|
||
Status-Werte:
|
||
|
||
```
|
||
trial → Self-Service-Tenant in Trial-Phase (5-7 Tage)
|
||
active → Bezahlend
|
||
past_due → Stripe-Zahlung gescheitert, Read-Only-Modus
|
||
frozen → Tenant zahlt reduzierte Gebühr, Workspace read-only, jederzeit reaktivierbar
|
||
suspended → Manuell gesperrt von Plattform-Admin (z.B. AGB-Verstoß)
|
||
deletion_pending → Kündigung läuft, 30-Tage-Grace
|
||
deleted → Hard-Delete erfolgt
|
||
```
|
||
|
||
**Übergänge:**
|
||
- `trial → active`: nach Zahlungs-Setup
|
||
- `active → past_due`: Stripe-Webhook bei Fehlversuch
|
||
- `past_due → active`: nach Nachzahlung
|
||
- `past_due → deletion_pending`: nach 30 Tagen Read-Only
|
||
- `active → frozen`: User klickt „Workspace pausieren" + reduzierten Plan bestätigen
|
||
- `frozen → active`: User klickt „Reaktivieren" + Standard-Plan
|
||
- `frozen → past_due`: bei Zahlungsausfall der reduzierten Gebühr
|
||
- `* → deletion_pending`: User klickt „Tenant kündigen"
|
||
- `deletion_pending → active`: User klickt „Kündigung zurückziehen" innerhalb 30 Tagen
|
||
- `deletion_pending → deleted`: nach 30 Tagen (Cron)
|
||
- `* → suspended`: Plattform-Admin
|
||
- `suspended → active`: Plattform-Admin
|
||
|
||
**Frozen-Modus Rechte:**
|
||
|
||
| Aktion | Erlaubt |
|
||
|---|---|
|
||
| Login (alle Rollen) | ✓ |
|
||
| Daten lesen | ✓ |
|
||
| Schreibende Aktionen | ✗ |
|
||
| Email/WhatsApp/Push senden | ✗ |
|
||
| Automationen ausführen | ✗ |
|
||
| Eingehende Webhooks | ✗ (verworfen, nicht gequeued) |
|
||
| Customer-Portal-Zugang (read-only) | ✓ |
|
||
| API (Read) | ✓ |
|
||
| API (Write) | ✗ |
|
||
|
||
**UI-Banner pro Status:**
|
||
- `past_due`: *„Zahlung fehlgeschlagen, Konto in 14 Tagen gesperrt — [Klick hier]"*
|
||
- `frozen`: *„Workspace pausiert. Reaktivieren um wieder zu schreiben."*
|
||
- `deletion_pending`: *„Konto wird in X Tagen gelöscht — [Kündigung zurückziehen]"*
|
||
- `suspended`: Login-Page Klartext *„Konto temporär gesperrt — Support kontaktieren"*
|
||
|
||
---
|
||
|
||
## Block B — Auth-Methoden
|
||
|
||
### B.1 — Email + Passwort
|
||
|
||
**Passwort-Anforderungen (NIST-konform):**
|
||
- Mind. 12 Zeichen
|
||
- Keine erzwungenen Sonderzeichen-Regeln
|
||
- Check gegen **Have-I-Been-Pwned**-API (Top-1M-Liste lokal): Block bei Treffer mit Klartext: *„Dieses Passwort wurde in einem bekannten Datenleck gefunden — bitte ein anderes wählen."*
|
||
- Bcrypt mit Cost-Faktor 12
|
||
|
||
**Login-Schutz:**
|
||
- Rate-Limit pro Email: 5 Fehlversuche in 15 Min → 15 Min Lockout
|
||
- Rate-Limit pro IP: 50 Versuche/h
|
||
- Captcha (hCaptcha, DSGVO-konform) ab 3. Fehlversuch
|
||
|
||
**Passwort-Reset:**
|
||
- Magic-Link-Email mit 1h-Token, einmalig nutzbar
|
||
- Bei Reset: alle aktiven Sessions invalidiert
|
||
|
||
### B.2 — Magic-Link (Login-Alternative)
|
||
|
||
- Token: 64 Zeichen, kryptographisch sicher, URL-safe
|
||
- Lebenszeit: 15 Minuten, einmalig nutzbar
|
||
- Rate-Limit: max. 3 Anfragen/Email/15min
|
||
- 2FA wird trotzdem abgefragt (Magic-Link ersetzt nur Passwort)
|
||
- Klartext-Hinweise für Token-abgelaufen / bereits-genutzt / Email-Verzögerung
|
||
|
||
### B.3 — Microsoft-OAuth
|
||
|
||
**→ Backlog (Phase 2 oder später).** Nicht in Phase 1.
|
||
|
||
### B.4 — 2FA (TOTP)
|
||
|
||
- **TOTP only** (Google Authenticator, Authy, 1Password, Bitwarden, etc.)
|
||
- **Keine SMS**
|
||
- Backup-Codes: 10 einmalige Recovery-Codes beim Aktivieren
|
||
- Setup-Flow: QR-Code + Secret in Klartext → Authenticator-App scannt → Test-Code → Backup-Codes-Download
|
||
|
||
**Login-Flow mit 2FA:**
|
||
- Nach Pwd/Magic-Link: 6-stelliger-Code-Eingabe
|
||
- Rate-Limit: max. 5 Versuche/5min
|
||
|
||
**Trust-Device-Option:**
|
||
- Checkbox: *„Auf diesem Gerät 30 Tage merken"*
|
||
- Signed Cookie umgeht 2FA für 30 Tage
|
||
- Trust-Device-Liste in `/settings/security/` mit individuellem Revoke
|
||
|
||
**Recovery:**
|
||
- Backup-Code → einmal-Login + Aufforderung neue 2FA einzurichten
|
||
- Backup-Codes weg → Tenant-Admin kann 2FA für User zurücksetzen (mit Audit-Log)
|
||
- User selbst Tenant-Admin und alleine → Plattform-Admin-Reset über Support
|
||
|
||
**Pflicht-2FA:**
|
||
- Default: Pflicht für `tenant.admin`-Permission, optional für Rest
|
||
- Tenant-Admin kann Toggle setzen: *„2FA für alle User dieses Tenants verpflichtend"* → User ohne 2FA werden beim nächsten Login zur Einrichtung gezwungen
|
||
|
||
### B.5 — Session-Management
|
||
|
||
- **Server-Side-Sessions** in Postgres (nicht JWT — Logout/Revoke wäre mit JWT problematisch)
|
||
- HTTP-only, Secure, SameSite=Lax Cookie
|
||
- Default-Lebenszeit: 30 Tage Sliding-Window
|
||
- Tenant-Admin-konfigurierbar pro Tenant (max. Lebenszeit)
|
||
- Inaktivitäts-Timeout: 4h ohne Aktivität → Soft-Refresh + 2FA-Re-Verify falls aktiv
|
||
- Browser-Fingerprint (UA + IP-Range): bei deutlicher Abweichung → Re-Login
|
||
|
||
**Session-Übersicht in `/settings/security/`:**
|
||
- Liste aller aktiven Sessions: Gerät, Browser, IP, Letzte Aktivität, Standort (IP-Geolocation)
|
||
- Pro Session: Abmelden-Button
|
||
- Globaler „Von allen Geräten abmelden"-Button
|
||
|
||
**Auto-Logout-Trigger:**
|
||
- Passwort/2FA/Email geändert → alle Sessions weg
|
||
- User-Deaktivierung → alle Sessions weg
|
||
- Tenant-Suspended/Deleted → alle Sessions weg
|
||
|
||
---
|
||
|
||
## Block C — Rollen & Permissions
|
||
|
||
### C.1 — Permission-Modell: Variante 2 + Advanced
|
||
|
||
**Default-View** für Tenant-Admin im Rollen-Editor: Bundle-Stufen pro Modul.
|
||
|
||
```
|
||
crm.none → kein Zugriff
|
||
crm.read_own → eigene Kontakte/Deals sehen
|
||
crm.read_all → alle sehen
|
||
crm.write → eigene anlegen/bearbeiten
|
||
crm.admin → Modul-Settings, Custom-Felder, alle löschen
|
||
```
|
||
|
||
**Advanced-Mode:** Toggle „Erweiterte Berechtigungen anzeigen" → klappt atomare Permissions auf. Bundle-Header zeigt *„Benutzerdefiniert"*, falls atomare Auswahl nicht zu Standard-Bundle passt.
|
||
|
||
**Code-Internal:** Permissions sind atomar gespeichert. Bundles sind Pre-Sets aus atomaren Permissions.
|
||
|
||
### C.2 — 7 SHK-Template-Rollen (Seeding bei Tenant-Anlage mit Branche=SHK)
|
||
|
||
| Rolle | Kern-Rechte | Tenant-Admin | UI-Modus Default |
|
||
|---|---|---|---|
|
||
| **GF / Geschäftsführer** | Alles, Tenant-Admin | ✓ | Büro |
|
||
| **Vertriebsleiter** | CRM admin, Sales-Pipeline admin, Lead-Inbox admin, Email-Marketing admin, Reports lesen. Projekte read_all. | ✗ | Büro |
|
||
| **Vertriebler** | CRM read_all + write_own, Pipeline read_all + write_own, Lead write, Booking write_own. | ✗ | Büro (mobil-fähig) |
|
||
| **Projektleiter / Bauleiter** | Projektpipeline admin (eigene), Plantafel write_own, Tasks write + assign, Files read_all + write, HR-Genehmigungen für eigene Monteure. | ✗ | Büro (mobil-fähig auf Baustelle) |
|
||
| **Büro / Backoffice** | CRM read_all, Pipeline read_all, Projektpipeline write, HR-Hub admin, Booking admin, Email-Inbox read_all, Files write. | ✗ | Büro |
|
||
| **Marketing** | CRM read_all + Segmente, Email-Marketing admin, Form-Builder admin, Lead-Inbox write, Booking read. Kein HR/Projekt-Edit. | ✗ | Büro |
|
||
| **Monteur** | Projektpipeline read_own + nur aktive, Tasks own + edit, Acceptance write, Foto-Forms write, Files read in Projekt + write Fotos, Chat in eigenen Projekt-Channels, HR-Hub read_own. Kein Sales/Marketing/Admin. | ✗ | **Baustelle** |
|
||
|
||
**Sonderpunkte:**
|
||
- **UI-Modus** (LP-2): Default je nach Rolle, **vom User pro Gerät überschreibbar** (Vertriebler kann auf iPhone auf „Baustelle" umschalten)
|
||
- **Tenant-Admin** in Phase 1 nur GF (Custom-Rollen können das später erweitern)
|
||
- **Endkunde** ist *keine* Tenant-Rolle (eigene `PortalUser`-Klasse, Modul 15)
|
||
|
||
**Wichtige Architektur-Vorschrift:** Diese 7 Rollen sind **nicht hartkodiert**, sondern **deklaratives SHK-Branchen-Template**. Beim Tenant-Anlegen mit Branche=SHK wird das Template geseeded. Andere Branchen haben eigene Default-Rollen-Templates. Tenant-Admin kann nach Anlage **alle** Rollen vollständig editieren/umbenennen/löschen/neue anlegen.
|
||
|
||
### C.3 — Custom-Rollen + Edit-Logik
|
||
|
||
**Editor unter `/{tenant}/admin/roles/`:**
|
||
|
||
- Liste aller Rollen mit User-Anzahl pro Rolle
|
||
- **Neue Rolle anlegen** (komplett von Null möglich, oder „Basieren auf"-Dropdown als Ausgangspunkt — kopiert Permissions als Snapshot)
|
||
- Editieren: Name, Beschreibung, Permissions, Default-UI-Modus
|
||
- Duplizieren mit Suffix „(Kopie)"
|
||
- Löschen: Block falls noch User zugewiesen → Ersatz-Rolle wählen oder Bulk-Reassign
|
||
|
||
**Standard- vs. Custom-Rollen:** Alle Rollen nach Anlage **vollständig editierbar**. Internes Flag `is_template_origin: true/false` nur als Hinweis, keine Funktions-Einschränkung.
|
||
|
||
**Inheritance:** Keine Live-Inheritance. Permissions werden beim Anlegen kopiert (Snapshot).
|
||
|
||
**Multi-Rolle pro User:** möglich. Permissions additiv kombiniert. Bei UI-Modus-Konflikt → umfangreichere UI als Default.
|
||
|
||
**Default-Rolle bei neuen Usern:** Tenant-Admin wählt beim Einladen explizit, kein globales Default.
|
||
|
||
**Klartext-Fehler:**
|
||
- Permission-Konflikte: *„Diese Permission-Kombination ist inkonsistent (z.B. ‚Deals löschen' aber kein ‚Deals lesen'). Wir aktivieren ‚Deals lesen' automatisch dazu."*
|
||
- Last-Tenant-Admin-Rolle löschen: Block + Klartext
|
||
|
||
### C.4 — Groups
|
||
|
||
Orthogonal zu Rollen — keine Permission-Wirkung.
|
||
|
||
**Use-Cases (Geerkens):** „Team Süd"/„Team Nord", „Außendienst"/„Innendienst", „Praktikanten"/„Festangestellte".
|
||
|
||
**Spec:**
|
||
- User in mehreren Groups möglich
|
||
- Genutzt für: Filter in Listen, Mass-Assign (Files/Projekte), Notifications, Automation-Bedingungen
|
||
- Editor unter `/{tenant}/admin/groups/`: Liste mit Mitgliederzahl, anlegen/umbenennen/löschen, Bulk-Add/Remove, Description
|
||
- Keine Hierarchien in Phase 1
|
||
- Klartext bei Lösch mit Mitgliedern: *„Diese Group hat 8 Mitglieder. Bei Löschen verlieren sie die Zuordnung."*
|
||
|
||
### C.5 — Permission-Audit & Edge-Cases
|
||
|
||
- **Audit-Trail:** jede Rollen-/Permission-Änderung mit Diff geloggt
|
||
- **Permission-Preview-Tool** in `/admin/users/{id}/`: zeigt aufgelöste effektive Permissions mit Quellen-Hinweis
|
||
- **Self-Permission-Schutz:** Tenant-Admin kann sich nicht selbst die Permission entziehen, wenn er einziger ist
|
||
- **Group-Mitgliedschaft:** vergibt KEINE Permissions in Phase 1
|
||
- **Concurrent-Update:** Last-Write-Wins mit Klartext-Konflikt-Hinweis bei Mehrfach-Edit
|
||
|
||
---
|
||
|
||
## Block D — User-Lifecycle
|
||
|
||
### D.1 — User-Einladung
|
||
|
||
**Flow:** Tenant-Admin in `/admin/users/` → „Mitarbeiter einladen" → Modal (Email Pflicht, Name optional, Rolle Pflicht, Groups optional, Persönliche Nachricht optional) → System legt `TenantUserInvitation` an mit 7-Tage-Token → Email mit Magic-Link.
|
||
|
||
**Drei Pfade beim Klick:**
|
||
- **(a) Email noch nicht im System:** Account-Erstellung (Pwd, ggf. 2FA-Setup) → Tenant-Onboarding-Wizard
|
||
- **(b) Email im System (anderer Tenant):** Login → automatisch Mitglied → Welcome-Hinweis im Switcher
|
||
- **(c) Email bereits Mitglied dieses Tenants:** Klartext-Fehler beim Einladen schon: *„Max Mustermann ist bereits Mitglied — Rolle: Vertriebler"*
|
||
|
||
**Edge-Cases:**
|
||
- Token-Lebensdauer 7 Tage; bei Ablauf „Erneut senden"
|
||
- Max. 3 aktive Einladungen pro Email pro Tenant
|
||
- Bulk-CSV-Invite: **Phase 2**
|
||
|
||
### D.2 — Deaktivierung & Entfernen
|
||
|
||
**Modus 1 — Deaktivieren** (vorübergehend):
|
||
- TenantUser bleibt, Status=`disabled`
|
||
- Sessions invalidiert, kein Login mehr möglich
|
||
- Re-Aktivierung jederzeit ohne neue Einladung
|
||
|
||
**Modus 2 — Aus Workspace entfernen** (permanent):
|
||
- TenantUser-Beziehung gelöscht
|
||
- 2FA-Trust-Devices invalidiert
|
||
- Audit-Trail bleibt, User wird als „ehemaliger Mitarbeiter" angezeigt
|
||
- Re-Aufnahme nur durch neue Einladung
|
||
|
||
**Vor beiden Modi: Reassign-Workflow**
|
||
|
||
Wenn der zu deaktivierende User noch zugewiesene Entitäten hat, wird ein Bestätigungs-Workflow erzwungen, bevor die Deaktivierung greift. Folgende UI-Elemente werden benötigt:
|
||
|
||
- Anzeige aller offenen Verknüpfungen pro Typ (Deals, Projekte, Tasks, Termine, ...) mit Anzahl
|
||
- Bulk-Reassign-Funktion (alle Verknüpfungen an eine Person/Group)
|
||
- Einzel-Reassign-Funktion (pro Entität individuell)
|
||
- Override-Bestätigungs-Funktion *„Ohne Zuweisung lassen — Daten bleiben verwaist"* (nicht empfohlen, mit explizitem Bestätigungs-Schritt)
|
||
|
||
**Klartext-Fehler:**
|
||
- Last-Tenant-Admin entfernen: Block
|
||
- Sich selbst entfernen: Block, Klartext: *„Du kannst dich nicht selbst entfernen. Bitte einen anderen Tenant-Admin oder kündige deinen Account in den Settings."*
|
||
|
||
### D.3 — Account-Löschung (Apple-Pflicht + DSGVO)
|
||
|
||
**Multi-Step-Bestätigung in `/{tenant}/settings/account/`:**
|
||
|
||
- **Step 1 — Erklärung:** Klartext was gelöscht / was anonymisiert / was bleibt
|
||
- **Step 2 — Identität:** Pwd oder Magic-Link + 2FA falls aktiv
|
||
- **Step 3 — Edge-Cases:** falls einziger Tenant-Admin in mind. 1 Tenant → Block mit Klartext + Direkt-Link zum Lösen
|
||
- **Step 4 — Final-Klick** mit 3-Sek-Countdown auf Button
|
||
|
||
**Was technisch passiert:**
|
||
- TenantUser-Beziehungen gelöscht
|
||
- PII-Felder mit `[deleted-{userId}]` überschrieben (FKs intakt)
|
||
- Audit-Spuren behalten User-ID, zeigen „ehemaliger Mitarbeiter"
|
||
- 2FA-Geräte/Sessions/Push-Tokens entfernt
|
||
- Verbundene OAuth-Konten getrennt
|
||
- Avatar-Datei aus Storage gelöscht
|
||
|
||
**Bestätigungs-Email + 24h-Reverse-Window:**
|
||
- Email an Lösch-Adresse: *„Dein Account wurde gelöscht am [Datum]. Falls nicht von dir, kontaktiere uns innerhalb 24h: [Support-Link]"*
|
||
- Support kann innerhalb 24h wiederherstellen (mit Audit-Eintrag)
|
||
|
||
### D.4 — Multi-Tenant-Membership & Tenant-Wechsel
|
||
|
||
- **Erst-Login mit 1 Tenant:** automatisch ins Dashboard
|
||
- **Erst-Login mit 2+ Tenants:** separater Tenant-Auswahl-Screen
|
||
- **Folge-Logins:** letzter genutzter Tenant (siehe `last_accessed_at`)
|
||
- **Tenant-Switcher-Komponente** muss überall in der App verfügbar sein, mit Liste aller Tenants des Users + Suchfeld bei 5+ Tenants
|
||
- **Tenant verlassen** in `/settings/account/`: Multi-Step + Reassign-Workflow + Last-Tenant-Admin-Schutz
|
||
- **User landet ohne Tenant:** Klartext-Screen mit Funktionen *„Neuen Workspace anlegen"* und *„Auf Einladung warten"*
|
||
- **`last_accessed_at`** pro Tenant für Default-Sortierung
|
||
|
||
---
|
||
|
||
## Block E — API-Keys
|
||
|
||
**Verwaltung in `/{tenant}/admin/api-keys/`:**
|
||
|
||
- Liste: Name, Scopes, Erstellt-Datum, Letzte Nutzung, Status
|
||
- Anlage: Name + Scopes → Key einmalig sichtbar (Copy-to-Clipboard mit Klartext-Warnung)
|
||
- Widerrufen mit einem Klick
|
||
- Detail-View: Logs der letzten 100 Anfragen (Endpoint, Status, Antwort-Zeit, IP)
|
||
|
||
**Authentifizierung:**
|
||
- `Authorization: Bearer <key>` Header
|
||
- Query-Param `?api_key=...` nur für GET-Webhook-Inbound mit Klartext-Warnung im UI
|
||
|
||
**Scopes (Variante-2-Bundles):**
|
||
- `read_only` — alle GET-Endpoints (Default)
|
||
- `webhook_inbound` — nur eingehende Lead/Form-Webhooks
|
||
- `read_full` — alle GET inkl. sensible Daten (Mails, HR)
|
||
- `automation_trigger` — kann Trigger in Engine auslösen
|
||
|
||
**Rate-Limiting:** 1.000 Req/h Default, Tenant-Admin kann erhöhen, 429 mit Klartext-Body.
|
||
|
||
**Sicherheits-Defaults:**
|
||
- 365-Tage-Ablauf (erzwingt Rotation)
|
||
- Keys gehören dem Tenant, nicht dem User (überleben User-Deaktivierung)
|
||
- Audit-Log pro Anlage / Widerruf / Fehlernutzung
|
||
|
||
**Phase 2:** OAuth2-Provider-Modus, granulare Scopes, API-Versioning.
|
||
|
||
---
|
||
|
||
## Block F — Feature-Gating
|
||
|
||
### F.1 — Subscription-Feature-Gates
|
||
|
||
**Datenmodell** (Modul 28):
|
||
```
|
||
SubscriptionProduct (z.B. "Cloud", "Cloud+", "Enterprise")
|
||
├── enthält viele SubscriptionFeatures (z.B. "crm", "automation", "kwp_integration")
|
||
└── verknüpft mit Stripe-Price
|
||
TenantSubscription
|
||
└── verweist auf SubscriptionProduct + Status
|
||
```
|
||
|
||
**Code-Convention** (Loader-First-Call):
|
||
```
|
||
await requireTenantFeatureAccess(tenantId, 'kwp_integration')
|
||
```
|
||
|
||
Bei kein Zugang → Loader wirft → React-Boundary zeigt Klartext: *„Die KWP-Integration ist im Cloud-Plus-Plan verfügbar. Mehr erfahren auf hivegrid.de/pricing"* → Link führt **außerhalb der App** zur Marketing-Site (Apple-Compliance).
|
||
|
||
**Gate-Granularität:**
|
||
- Pro Modul auf Tenant-Ebene
|
||
- Pro Feature innerhalb Modul wenn nötig (z.B. `automation.advanced_branches`)
|
||
|
||
**Pricing-Definitionen geparkt** — Engine baut bereits, konkrete Plans später definiert.
|
||
|
||
### F.2 — Feature-Flags (Modul 32)
|
||
|
||
- Boolean pro Tenant von uns Admin-side aktivierbar (`admin.hivegrid.de/feature-flags`)
|
||
- Code: `if (await tenantHasFlag(tenantId, 'beta_new_dashboard')) { ... }`
|
||
- Default-Wert pro Flag
|
||
- Filter (z.B. „Tenants > 50 MA")
|
||
- Audit-Log bei Flag-Änderung
|
||
|
||
**Flag-Lifecycle:**
|
||
- `beta` → einzeln aktiviert für Test-Tenants
|
||
- `rollout` → breit aktiviert über Filter
|
||
- `GA` → Flag aus Code entfernt (always-on)
|
||
- `deprecated` → Default false, Code wird entfernt
|
||
|
||
**Klartext:** Tenants sehen kein UI für Flags — Features einfach sichtbar/nicht. Phase 2: Tenant-self-service-Flags.
|
||
|
||
---
|
||
|
||
## Architektur-Vorschriften (Querschnitt)
|
||
|
||
Bezug aus Master-Session-Datei (Architektur-Vorschriften):
|
||
- LP-3, AV #3 — **Branchen-Templates deklarativ:** SHK-Rollen sind Seeding, nicht Hardcode
|
||
- LP-10, AV #1 — **Klartext-Diagnostik:** alle Auth/Permission-Fehler mit menschenlesbarem Text + Lösungs-Hinweis
|
||
- AV #5 — **Permissions-aware-Default:** alle Listen/Suchen filtern automatisch nach User-Permissions
|
||
- AV #6 — **Audit-Trail-Default:** alle schreibenden Aktionen geloggt
|
||
- AV #20 — **Action-Boundary für KI:** KI darf keine Permissions-Änderungen direkt durchführen, nur User-Bestätigt
|
||
|
||
---
|
||
|
||
## Detail-Spec-Status: DRAFT
|
||
|
||
Erste vollständige Detail-Spec für Modul 27. **Vor Bau:** Verifizierung mit Noah (zusammen mit Pflichtenheft-Sweep). Bei Implementierung dann konkrete Permission-IDs, RLS-Policy-SQL, Stripe-Price-IDs ergänzen.
|
||
|
||
**Offene Detail-Punkte (nicht-blockierend, beim Bau zu klären):**
|
||
- Konkrete Permission-IDs pro Modul (entstehen modulweise mit den jeweiligen Detail-Specs)
|
||
- Konkrete UI-Layouts (Subframe-Designs kommen separat)
|
||
- Migrations-Skripte / Seeding-SQL (Implementierungs-Detail)
|