Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/_bmad-output/specs/M27-auth-multi-tenancy.md
T
2026-07-08 16:15:37 +02:00

502 lines
23 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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 → Legacy-Provider-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`: Legacy-Provider-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 Legacy-Provider-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, Legacy-Provider-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)