235 lines
15 KiB
Markdown
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.
|