15 KiB
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) undVA-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/fbehalten Datenmodell und Fachlogik. Ihre Zugriffe werden zusätzlich durch denselben Own-/All-Permission-Vertrag in Repository und RLS begrenzt.VA-P28hdarf 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 = nullbedeutet 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
- 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.
- 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.
admin_sales.crm.read_all,admin_sales.crm.write_all,admin_sales.communication.read_allundadmin_sales.reporting.read_allsind eingeführt; Repository-Filter und SECURITY-DEFINER-gestützte RLS erzwingen dieselben Own-/All-Regeln.- Vertriebsleitung kann Team-Mails, Anhänge, Calls, Aufzeichnungen und Buchungen lesen; Fremdzugriffe und Downloads auditieren Actor, Dateneigentümer und Zielobjekt.
- Mitarbeiterliste und Anlage unterstützen Status, Rollen-Multiselect, letzte Aktivität und „Aktivierung ausstehend“; die Detailseite zeigt effektive Rollen/Bereiche, Sessions und Audit.
- 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.
- 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.
- Dashboard-Widgets werden serverseitig aus der additiven Permission-Menge dedupliziert; sensible Loader laufen nur bei Freigabe, und alle sieben Personas erhalten ihre festgelegte Sicht.
- Sidebar, Command Palette, Suche, Breadcrumbs und Direkt-Routen nutzen denselben Permission-Vertrag; unberechtigte Direktzugriffe liefern 404.
- 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.authentikSubjectbleibt 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ürhivegrid_app, keinBYPASSRLS. - 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.mddocs/ARCHITECTURE-DECISIONS.md— AD-21, AD-28docs/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-205wurde unterVR-P28aangelegt 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_appauf. - 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-contractgrü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
aa78bcb4eliefert die forward-only Migration20260726220000_admin_rbac_access_scopemit 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-liveist grün: Migration alshivegrid_migratorohne 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 MigrationenDatabase schema is up to date.verify:migrations-paritymeldet 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) undpackages/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
11294war technisch grün und hatte20260726220000_admin_rbac_access_scopeangewandt. Die anschließende transaktionale Persona-/RLS-Probe unter dem echtenhivegrid_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_transitionbootstrapt 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-parityundprisma validatesind 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.