# 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.