Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/VR-P28a-RBAC.md
T

235 lines
15 KiB
Markdown

# VR-P28a-RBAC · Rollenbasierter Admin-Bereich für Authentik-Mitarbeiter
| | |
|---|---|
| **Plane** | `HIVEGRID-205` · Parent `HIVEGRID-111` |
| **Typ** | Dev (Code) |
| **Owner** | Raffael |
| **Phase** | Phase 28 (v2-P8) — Plattform-Admin-Tiefe |
| **Cycle/Fenster** | v2-W3 · 2026-07-26 bis 2026-07-31 |
| **Status** | Ready for Review · **10/10 DoD = 100 % done** · Design-Nachzug offen |
🎨 **design-nachzug: offen** · Die rollenbasierte Mitarbeiterverwaltung und das persönliche
Dashboard werden als geprüfte AD-28-Interim-UI aus `~/ui` geliefert. Davids finales
Subframe-Delta bleibt ein getrackter Nachzug und blockiert die Dev-DoD nicht.
## Abhängigkeiten & Parallelität
- **Blocked by:** `VR-P28a` (AdminUser/AdminSession/RBAC), `VA-P28b` (CRM Core),
`VA-P28c` (persönliche Admin-Mailboxen), `VA-P28d` (Telefonie) und `VA-P28f`
(Buchungen).
- **Blocks:** `VA-P28h`; Reporting-Aggregate und konfigurierbare Kacheln müssen den hier
festgelegten Rollen-, Own-/All-Scope- und Widget-Allowlist-Vertrag konsumieren.
- **Läuft parallel zu:** keinem weiteren Schema-Umbau. Das Delta erweitert die bestehenden
typisierten P28-Verträge und zieht ihre RLS-/Repository-Konsumenten gemeinsam nach.
- **Hardgrenze:** ausschließlich der tenant-lose HiveGrid-Admin-Space. Authentik entscheidet
nur über Identität, MFA und grundsätzlichen Zugang; fachliche Rollen und Datensichtbarkeit
bleiben vollständig in HiveGrid.
- **Auswirkung auf Abhängige:** `VA-P28b/c/d/f` behalten Datenmodell und Fachlogik. Ihre
Zugriffe werden zusätzlich durch denselben Own-/All-Permission-Vertrag in Repository und
RLS begrenzt. `VA-P28h` darf sensible KPI-Quellen erst nach serverseitiger Widget-Freigabe
laden.
## Was wir bauen
Vorbereitete Authentik-Mitarbeiterkonten, sechs administrierbare feste Rollenpakete plus
unveränderlichem Super Admin, additive Mehrfachrollen und eine fachlich gruppierte
Rollenverwaltung. Vertrieb sieht gemeinsame Firmen-, Kontakt-, Tag- und Notizdaten, aber nur
eigene Leads, Deals, Aufgaben, Mails, Calls und Buchungen. Vertriebsleitung sieht den gesamten
Sales-Bereich einschließlich Team-Kommunikation. Support, Engineering, Geschäftsführung und
Viewer erhalten ausschließlich ihre festgelegten Admin-Bereiche.
Alle Rollen landen auf `/dashboard`. Der Server bildet aus der Vereinigungsmenge der Permissions
eine deduplizierte Widget-Allowlist und lädt nur freigegebene Daten. Sidebar, Command Palette,
Suche, Breadcrumbs und Direkt-Routen verwenden denselben Permission-Vertrag.
## Rollen- und Scope-Vertrag
| Rolle | Standardzugriff |
|---|---|
| Super Admin | Alle aktuellen und zukünftigen Admin-Permissions; unveränderlich |
| Vertrieb | Gemeinsame Firmen/Kontakte; eigene Leads, Deals, Aufgaben, Mails, Calls und Buchungen |
| Vertriebsleitung | Gesamter Sales-Bereich, Teamdaten und vollständige Team-Kommunikation |
| Support | Kunden-/Nutzerverwaltung, Support-Inbox und auditierte Impersonation; keine Deploys |
| Engineering | Health, Jobs, Deploys, Events, Feature-Flags und Integrationen |
| Geschäftsführung | Business-Dashboard, Forecast, Pipeline, MRR/ARR und Churn; read-only |
| Viewer | Read-only Dashboard, Reports und freigegebene Übersichten |
- Mehrere Rollen wirken additiv; Einzelpermissions am AdminUser sind nicht vorgesehen.
- Die sechs Rollenpakete außer Super Admin sind administrierbar. Frei erstellbare Rollen
entstehen nicht.
- Rollenänderung und Deaktivierung erfordern einen Grund, werden auditiert und widerrufen
aktive Sessions.
- Der letzte aktive Super Admin kann nicht entfernt, deaktiviert oder entrechtet werden.
- `authentikSubject = null` bedeutet **Aktivierung ausstehend**. Erst der Authentik-Callback
bindet den verifizierten Subject exakt einmal an die vorbereitete E-Mail.
## Benötigte Screens
| Screen [Admin-Host-Route] | Kern-Inhalt |
|---|---|
| Mitarbeiter [`/admin-users`] | Status, Rollen, letzte Aktivität, Aktivierungszustand; Anlage mit Rollen-Multiselect |
| Mitarbeiter-Detail [`/admin-users/:id`] | Effektive Rollen/Bereiche, Sessions, Audit-Trail, Rollenänderung mit Grund |
| Rollen-Editor [`/admin-users/roles`] | Verständliche Permission-Gruppen und Sichtbarkeitszusammenfassung |
| Persönliches Dashboard [`/dashboard`] | Rollenbasierte, serverseitig erlaubte und deduplizierte Widgets |
## Definition of Done
- [x] Vorbereitete aktive AdminUser werden per verifizierter E-Mail exakt einmal an einen
zulässigen Authentik-Subject gebunden; Authentik-Gruppen gate-en nur den Zugang, vergeben
keine Rollen, und unbekannte Nutzer werden fail-closed mit Klartext abgewiesen.
- [x] Die sieben festen Rollenpakete, additive Mehrfachrollen, das Verbot direkter
Nutzer-Permissions und die unveränderliche Super-Admin-Invariante sind im Katalog und in
Backfill-/Contract-Tests bewiesen; neue Permissions erreichen Super Admin automatisch.
- [x] `admin_sales.crm.read_all`, `admin_sales.crm.write_all`,
`admin_sales.communication.read_all` und `admin_sales.reporting.read_all` sind eingeführt;
Repository-Filter und SECURITY-DEFINER-gestützte RLS erzwingen dieselben Own-/All-Regeln.
- [x] Vertriebsleitung kann Team-Mails, Anhänge, Calls, Aufzeichnungen und Buchungen lesen;
Fremdzugriffe und Downloads auditieren Actor, Dateneigentümer und Zielobjekt.
- [x] Mitarbeiterliste und Anlage unterstützen Status, Rollen-Multiselect, letzte Aktivität
und „Aktivierung ausstehend“; die Detailseite zeigt effektive Rollen/Bereiche, Sessions und Audit.
- [x] Der Rollen-Editor gruppiert verständliche fachliche Bereiche, zeigt die tatsächliche
Sichtbarkeit vor dem Speichern und lässt ausschließlich die sechs festen Pakete bearbeiten.
- [x] Rollenänderung und Deaktivierung verlangen einen Grund, schreiben Audit und widerrufen
aktive Sessions; der letzte aktive Super Admin bleibt gegen Entfernen, Deaktivieren und
Entzug geschützt.
- [x] Dashboard-Widgets werden serverseitig aus der additiven Permission-Menge dedupliziert;
sensible Loader laufen nur bei Freigabe, und alle sieben Personas erhalten ihre festgelegte Sicht.
- [x] Sidebar, Command Palette, Suche, Breadcrumbs und Direkt-Routen nutzen denselben
Permission-Vertrag; unberechtigte Direktzugriffe liefern 404.
- [x] Persona-, echte `hivegrid_app`-RLS-, Unit-, Route-, i18n-, A11y-, Visual-, Hot-Swap-,
Reachability- und Leer-DB-Migrations-Proofs sind grün; die forward-only Migration enthält
dokumentiertes Inverse-SQL.
**Fortschritt:** **10/10 DoD = 100 % done · 0 Punkte offen**.
## Technische Bausteine
- `AdminUser.authentikSubject` bleibt nullable und unique; kein JIT-Anlegen im Callback.
- Feste Rollen und Permission-Bundles in `packages/db/src/admin-permissions.ts`; kein neues
generisches Rollen-/Entity-System.
- SECURITY-DEFINER-Permission-Funktion für den gebundenen `app.user_id`; Runtime-Grant nur
für `hivegrid_app`, kein `BYPASSRLS`.
- Modulbezogene RLS-Policies in den generierten Plattform-Policy-Verträgen; Ownership-Felder
bleiben die bestehenden `AdminUser`-Relationen.
- Reine Dashboard-Widget-Registry und View-Models; geschützte Loader werden erst nach
serverseitiger Freigabe aufgerufen.
- Interim-UI aus bestehenden `~/ui`-Komponenten mit VM als Prop und Action-Callbacks.
## Rollback
Der Code kann auf den letzten stabilen P28-Stand zurückgerollt werden. Die Migration ist
forward-only: Permission-Zeilen und die neuen Funktionen bleiben bei einem reinen
Applikations-Rollback liegen. Da die alte v2-JIT-Funktion bewusst entfernt wird, schlägt ein
zurückgerollter alter Authentik-Callback fail-closed fehl; ein vollständiger struktureller
Rollback muss deshalb das kommentierte Inverse-SQL und den vorherigen Policy-Vertrag
koordiniert wiederherstellen. Bereits gebundene Authentik-Subjects und Audit-Historie werden
nicht automatisch gelöscht.
## Quellen
- `.planning/ticket-docs/VR-P28a.md`
- `.planning/ticket-docs/VA-P28b.md`, `VA-P28c.md`, `VA-P28d.md`, `VA-P28f.md`, `VA-P28h.md`
- `.planning/ENTITY-MODEL.md`
- `docs/ARCHITECTURE-DECISIONS.md` — AD-21, AD-28
- `docs/security/RLS-HARDENING-2026-07-13.md`
- AGENTS.md — Admin-SSO, RLS, Ticket-Treue, Interim-UI und Definition of Done
## Dev-Nachzug
- [ ] Davids finales Mitarbeiter-/Rollen-/Dashboard-Delta integrieren.
- [ ] Interim-Visual-Baselines beim Design-Nachzug bewusst rebaselinen.
## Umsetzungs-Notiz
**2026-07-26 · 10/10 DoD = 100 % done · 0 Punkte offen**
- Plane-Folgeticket `HIVEGRID-205` wurde unter `VR-P28a` angelegt und Raffael zugewiesen.
- Abhängigkeiten zu CRM, E-Mail, Telefonie, Buchung und Reporting wurden in beiden Richtungen
dokumentiert.
- Authentik-Gruppen sind nur noch das grobe Login-Gate. Der Callback bindet ausschließlich
einen aktiven vorbereiteten AdminUser mit verifizierter passender E-Mail, verändert keine
HiveGrid-Rollen und weist unbekannte Nutzer mit Klartext fail-closed ab.
- Die sieben festen Rollenpakete sind als additive HiveGrid-Bundles definiert. Nur die sechs
Fachrollen sind editierbar; Super Admin bleibt unveränderlich und erhält bei jedem
Katalog-Sync automatisch alle aktuellen und zukünftigen Permissions.
- Die neuen Own-/All-Permissions sind im typisierten Admin- und Seed-Katalog gespiegelt.
- Repository-Filter und die generierten RLS-Policies erzwingen Own-/All-Zugriffe für Leads,
Deals, Aufgaben und ihre abhängigen Aktivitäten, Relationen und Custom Values. Die
SECURITY-DEFINER-Funktion löst Permissions ausschließlich für den aktiven, gebundenen
AdminUser unter `hivegrid_app` auf.
- Team-Mails, Anhänge, Calls, Aufzeichnungen und Buchungen sind für die Vertriebsleitung
read-only sichtbar. Listen-, Detail- und Download-Zugriffe auf fremde Datensätze schreiben
Actor, Dateneigentümer und exakte Ziel-IDs ins Audit.
- Die Mitarbeiteranlage vergibt additive Rollen direkt beim Vorbereiten. Liste und Detail
unterscheiden den fachlichen Status vom Authentik-Aktivierungszustand und zeigen letzte
Aktivität, effektive Rollen/Bereiche, Sessions und Audit.
- Mitarbeiter-Rollenänderungen, Paketänderungen und Deaktivierungen verlangen eine
Begründung, schreiben Audit und widerrufen alle betroffenen aktiven Sessions. Die
Last-Super-Admin-Sperre greift bei Entzug und Deaktivierung.
- Der Rollen-Editor zeigt acht verständliche fachliche Bereiche mit lokalisierten
Ressourcen/Aktionen und einer live abgeleiteten Sichtbarkeitszusammenfassung. Nur die
sechs festen Fachrollen sind editierbar; freie Legacy-Rollen und Super Admin werden
serverseitig abgewiesen.
- Das persönliche Dashboard bildet kombinierte Rollen in eine deduplizierte Widget-Allowlist
ab. Jeder Widget-Bereich besitzt zusätzlich eine effektive Permission-Schranke; nicht
freigegebene Datenquellen werden weder aufgerufen noch im Hintergrund vorab geladen.
- Sidebar, Command Palette, Suche, Breadcrumbs sowie sensible Dashboard-, Support-,
Health-, Job-, System- und Deploy-Direktrouten konsumieren denselben zentralen
Permission-Vertrag. Abgewiesene Direktrouten bleiben beim bestehenden 404-Verhalten.
- Proof: Callback-/Claims-/DB-Grenz-/Generator-Tests sowie `verify:tenant-policy-contract`
grün; Rollenmatrix-, Additivitäts-, Seed-Paritäts- und Super-Admin-Backfill-Tests grün.
`pnpm typecheck`, `pnpm lint`, `pnpm test` (7.737 bestanden, 60 umgebungsabhängig
übersprungen), Hot-Swap, i18n, A11y, Source-Health und 375/375 Policy-Definitionen sind
grün.
- Mitarbeiter-/Rollen-VM-, Route-, Katalog-i18n- und Session-Widerruf-Tests sind grün.
Die aktualisierte Mitarbeiter-Baseline und die neue gruppierte Rollen-Editor-Baseline
bestehen jeweils Chromium-Visual- und WCAG-2-A/AA-Prüfung.
- Die neue kombinierte Sales-/Engineering-Dashboard-Baseline besteht Chromium-Visual- und
WCAG-2-A/AA-Prüfung. Service-Tests belegen zusätzlich, dass nur die tatsächlich
freigegebenen Sales-, Support-, Engineering- und Plattform-Loader ausgeführt werden.
- Ein gemeinsamer 17-teiliger Persona-Integrationslauf deckt Super Admin, Vertrieb,
Vertriebsleitung, Support, Engineering, Geschäftsführung und Viewer exakt einmal ab.
Er prüft Widget-Sicht, Navigations-/Suchziele, additive Sales-/Engineering-Rollen sowie
alle erlaubten und verweigerten Direkt-Routen; verweigerte Zugriffe antworten 404.
- Commit `aa78bcb4e` liefert die forward-only Migration
`20260726220000_admin_rbac_access_scope` mit ausführbarem Inverse-SQL-Hinweis, den vier
Permission-Katalogzeilen, Prepared-Identity-v3, SECURITY-DEFINER-Permission-Prüfung und
exakt den 62 geänderten Own-/All-Policy-Blöcken. Der zugehörige Migrationstest vergleicht
diese Blöcke bytegenau mit dem generierten 375/375-Vertrag.
- Der strikte Leer-DB-Lauf
`HIVEGRID_RLS_REQUIRE_MIGRATION_CHAIN_PARITY=1 pnpm run verify:rls-live` ist grün:
Migration als `hivegrid_migrator` ohne Superuser, 46/46 Kern-RLS-Tests, 11/11
Chat-Isolationstests, 38/38 Portal-RLS-Tests und 7/7 Tenant-Bootstrap-Tests. Ein separater
frischer PostgreSQL-Lauf meldet für alle 11 Migrationen `Database schema is up to date`.
`verify:migrations-parity` meldet keine Differenz zwischen Leer-DB-Kette und Prisma-Schema.
- Rollout: Migration vor den neuen Web-Containern anwenden; danach müssen Readiness und
Admin-Login den neuen Funktionskatalog sehen. Bei einem App-Rollback bleibt Authentik
bewusst fail-closed, bis v3 wieder ausgerollt oder der koordinierte Inverse-Pfad
durchgeführt wird. Eine Production-Promotion ist nicht Teil dieses Tickets.
- Der globale Coverage-Lauf bleibt unabhängig von diesem Delta an den bereits bestehenden
Targets `session.server` (97,9 % Statements/95,7 % Branches bei 99/98) und
`packages/queue` (94,9 % Branches bei 95) rot; keines der geänderten Admin-Sales-Module
ist ein Coverage-Target.
- Der erste Staging-Deploy in Gitea-Run `11294` war technisch grün und hatte
`20260726220000_admin_rbac_access_scope` angewandt. Die anschließende transaktionale
Persona-/RLS-Probe unter dem echten `hivegrid_app`-Login deckte jedoch auf, dass bestehende
Installationen nur die vier neuen Own-/All-Grants erhalten hatten: die unveränderten alten
Engineering- und Viewer-Standardpakete waren noch nicht auf die neue Rollenmatrix überführt.
Das Ticket bleibt deshalb trotz 10/10 fachlicher DoD operativ offen, bis der Korrektur-Deploy
auf Staging nachgewiesen ist.
- Die forward-only Korrekturmigration
`20260726233000_admin_rbac_role_bundle_transition` bootstrapt auf einer leeren
Migrationskette alle 112 Permissions und sieben festen Rollen. Auf bestehenden Installationen
überführt sie ausschließlich ein bytegenau erkanntes, unverändertes Legacy-Permission-Bundle;
jede abweichende administrativ angepasste Rollenbelegung bleibt erhalten. Super Admin wird
abschließend gegen den vollständigen Permission-Katalog geprüft. Das kommentierte Inverse-SQL
beschreibt den manuellen, auditgestützten Rückweg.
- Korrektur-Proof: 18/18 fokussierte Migration-/Katalogtests, `pnpm typecheck`, `pnpm lint`,
`pnpm test` (7.746 bestanden, 60 umgebungsabhängig übersprungen),
`verify:ci-baseline`, `verify:source-health`, `verify:tenant-policy-contract` (375/375),
`verify:migrations-parity` und `prisma validate` sind grün. Der strikte Leer-DB-Lauf mit
vollständiger Migration-Chain ist ebenfalls grün: 47/47 Kern-RLS-Tests einschließlich
Rollenpaket-Konvergenz, 11/11 Chat-Isolationstests, 38/38 Portal-RLS-Tests und 7/7
Tenant-Bootstrap-Tests.