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

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) 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

  • 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_all und admin_sales.reporting.read_all sind 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.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.