188 lines
15 KiB
Markdown
188 lines
15 KiB
Markdown
# R-P2b · P2 RLS-Härtung (Gate-Beweis) + RBAC + User-Lifecycle
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Typ** | Dev (Code) |
|
||
| **Owner** | Raffael |
|
||
| **Phase** | P2 — Identität & Mandantentrennung |
|
||
| **Cycle/Fenster** | W1 — Fundament & Identität · fällig 2026-06-19 · **Gate W1 (RLS-Gate-Beweis)** |
|
||
| **Status** | geplant |
|
||
|
||
**🎨 design-nachzug: offen** (seit 2026-07-07) — RBAC-Screens nach Davids `D-P2`-Review-Stand (2026-06-26) umgesetzt; offen: Gruppen-Bulk-Optik (Interim aus `~/ui`, David-Backlog RBAC V2), Abteilung-Spalte (S01) und Bereich/Kategorie-Feld (M04, keine Modell-Felder) sowie evtl. Deltas aus Davids D-P2-Review.
|
||
|
||
## Abhängigkeiten & Parallelität
|
||
- **Blocked by:** `R-P2a` (Auth/Tenant/Sessions)
|
||
- **Blocks:** **Gate W1** + **alle Tenant-Daten-Module** (ohne nachgewiesene RLS-Isolation darf kein Fach-Modul tenant-bezogen ausliefern)
|
||
- **Läuft parallel zu:** Akeshans `AK-P4a`/`AK-P4b` (Files/Tasks, P2‖P4-Paar) — disjunkte Domänen, eigene `prisma/schema/*.prisma` → kein Schema-Konflikt (AD-21).
|
||
- **Konflikt-Risiko:** gering — RLS-Policies sind DB-Migrations auf den Identitäts-Tabellen; additiv. db push auf Branch.
|
||
|
||
## Was wir bauen
|
||
Die **RLS-Härtung als Gate-Beweis** (AD-1): Postgres-Row-Level-Security mit `USING`/`WITH CHECK`, `SET LOCAL app.tenant_id` pro Transaktion, App-Rolle **ohne BYPASSRLS** — mandantenübergreifender Zugriff **nachweisbar verhindert**. Dazu das **RBAC** (6 SHK-Standard-Rollen geseedet, Permission-Bundles + Advanced-Einzelrechte, Gruppen) und der **User-Lifecycle**: Einladung (48h-Token), Soft-Deaktivierung mit Reassign-Workflow, DSGVO-Löschung via PII-Anonymisierung ohne Audit-Trail-Verlust.
|
||
|
||
## Benötigte Screens (Backend bedient — Design liefert `D-P2`)
|
||
| Screen [Route] | Kern-Inhalt | Liefert (Design) |
|
||
|---|---|---|
|
||
| Rollen-Editor [`/admin/roles`] | Rollen-Liste + Editor (Bundles + Advanced), 6 SHK-Rollen geseedet, Löschen mit Reassign | `D-P2` (A2+A6) |
|
||
| Gruppen [`/admin/groups`] | Gruppen-Liste, Bulk-Add/Remove | `D-P2` (A2) |
|
||
| Mitarbeiter [`/admin/users`] | User-Liste + Einladungs-Modal + Deaktivieren mit Reassign-Workflow | `D-P2` (A2+A5) |
|
||
| Konto löschen [`/settings/account`] | Multi-Step: Erklärung → Export → PW+2FA → Countdown · Block bei einzigem Admin | `D-P2` (A5) |
|
||
|
||
*(RLS prägt zusätzlich die „keine-Berechtigung"-Empty/Denied-States aller Screens.)*
|
||
|
||
## Definition of Done
|
||
- [x] **RLS** `USING`/`WITH CHECK`, `SET LOCAL app.tenant_id`, App-Rolle **ohne BYPASSRLS** (Mechanik gebaut + bewiesen)
|
||
- [x] **Cross-Tenant-Zugriff nachweisbar verhindert** (Gate-Beweis, Test belegt Isolation — 6/6 gegen echte PG)
|
||
- [x] **6 SHK-Standard-Rollen** geseedet (Partner-Liste; Permission-Bundles vorhanden — der Editor „Advanced-Einzelrechte" ist `D-P2`/David)
|
||
- [x] Gruppen-Verwaltung (N:M User) (inkl. idempotenter Bulk-Ops)
|
||
- [x] User-Lifecycle: Einladung **48h** (Default in `createWorkspaceInvite`), Soft-Deaktivierung + Reassign-Workflow, DSGVO-PII-Löschung (Audit-Trail erhalten)
|
||
|
||
## Technische Bausteine
|
||
- **Entities** (eigene `prisma/schema/auth.prisma`/`accounts.prisma`): `TenantRole` (is_template_origin, 6 SHK-Rollen), `Permission` (role_id, permission_key), `Group` (N:M User), `RoleAssignment`. RLS-Policies als DB-Migration auf allen tenant-bezogenen Tabellen.
|
||
- **RLS-Kern (Eigenbau, AD-1):** PgBouncer-kompatibles `SET LOCAL app.tenant_id` pro Transaktion; App-DB-Rolle ohne BYPASSRLS.
|
||
- **Konnektor** `tenantHasModule()` greift bereits an Admin-Routen (Rollen/Gruppen/User).
|
||
- DSGVO-Löschung = **PII-Anonymisierung** (kein Hard-Delete) → Audit-Hash-Kette (R-P1b) bleibt intakt.
|
||
- `is_demo_data` auf SHK-Rollen-Seed.
|
||
|
||
## Quellen (granular)
|
||
- `ENTITY-MODEL.md` → **Domäne 1** (TenantRole/Permission/Group/RoleAssignment) + 3 Architektur-Grundregeln (RLS AD-1)
|
||
- `REQUIREMENTS.md` → `REQ-auth-rbac`, `REQ-auth-user-lifecycle`
|
||
- `ROADMAP.md` → Phase 2 · `PHASE-SOURCES.md` → Phase 2 (M019/M023/M024/M025/M026)
|
||
- `docs/ARCHITECTURE-DECISIONS.md` → AD-1 (RLS)
|
||
- `designer-briefs/P02-identitaet-mandantentrennung.md` · Ticket-Doc `D-P2.md`
|
||
- `_bmad-output/specs/M27-auth-multi-tenancy.md`
|
||
|
||
## Dev-Nachzug (nach Davids `D-P2`-Delta)
|
||
- [ ] Rollen-/Lifecycle-Flows an Davids UI angepasst (Reassign-Panel, Lösch-Wizard)
|
||
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
|
||
- [ ] Plane-Ticket `R-P2b` aktualisiert
|
||
|
||
## Nachtrag 2026-06-22 (Claude) — Rollen-Liste übernommen, Relevanz-/Flag-Klärung
|
||
|
||
- **Davids Rollen-LISTE übernommen** (`RolesListView.tsx` ← `settings/roles-and-permissions/roles.tsx`):
|
||
David-Tabelle (Rolle/Beschreibung/Mitglieder/Aktionen) + „Rolle erstellen", pixel+wiring-auditiert grün.
|
||
Der **Rollen-EDITOR** (Bundles + „Erweiterte Einzelrechte") bleibt **bewusst** beim alten `RoleForm` — s.u.
|
||
- **`workspace-roles`-Feature-Flag-Gate ENTFERNT** (`requireWorkspaceRolesBuilderAccess`): Tenant-eigene
|
||
Rollen sind P2-Kernfunktion für **alle** Tenants → nur noch Permission `app.settings.roles.set` entscheidet
|
||
(kein Kill-Switch mehr). Tests (`workspaceRoles.server.test.ts`) nachgezogen, Suite grün.
|
||
- **⚠️ Rollen werden erst SPÄTER wirklich relevant:** Das System (anlegen/zuweisen, 6 SHK-Rollen) läuft, aber
|
||
der Rechte-**Katalog** hat heute fast nur `app.settings.*`/`app.dashboard.*`. Die eigentlichen **Fach-Rechte**
|
||
(Projekte/Aufträge/Rechnungen sehen/bearbeiten) entstehen erst **mit den Modulen ab P6–P9**. Custom-Rollen
|
||
sind bis dahin „hohl" → Davids Bundle-/Advanced-Editor lohnt erst, wenn es Rechte zum Bündeln gibt.
|
||
**Deshalb Editor bis P6–P9 beim alten `RoleForm` belassen.**
|
||
- **Delete-mit-Reassign:** kein Backend → UI-Guard (blockt bei Mitgliedern > 0). Reassign-Backend bleibt offen.
|
||
- **Konto-Löschen-Wizard:** David hat dafür (noch) KEIN Subframe-Design → wartet auf Davids Delta.
|
||
|
||
## Umsetzungsstand (Claude, 2026-06-18 — RLS-Gate-Beweis erbracht; Rest screen-unabhängig offen)
|
||
|
||
> Branch `p2b-rls` (off `p2a-auth-tenant`). Bestandsaufnahme: RBAC, App-Level-Scoping, Einladungen,
|
||
> **DSGVO-Löschung (deterministische Pseudonymisierung + Grace-Period + Audit-Hash-Kette)**, Admin-Panel
|
||
> und Gruppen liegen bereits vor. Der **echte Gap war der RLS-Gate-Beweis** (0 Policies, 0 SET-LOCAL-Mechanik).
|
||
|
||
**Gebaut — RLS-Gate-Beweis (DoD-Punkte 1+2), Commit `22d7bead`:**
|
||
- `prisma/rls/tenant-isolation.sql`: restricted App-Rolle `hivegrid_app` (**NOSUPERUSER, NOBYPASSRLS**) +
|
||
`ENABLE/FORCE ROW LEVEL SECURITY` + `tenant_isolation`-Policy (`USING`/`WITH CHECK` auf
|
||
`current_setting('app.tenant_id', true)`) auf `TenantUser`. **Deliberates Rollout-Artefakt** (NICHT im
|
||
Auto-Migrations-Pfad): RLS scharf zu schalten macht ungeschützte Queries ergebnislos → Tabellen ziehen
|
||
pro Modul nach, sobald ihre Zugriffe über `withTenantRLS` laufen.
|
||
- `withTenantRLS(tenantId, cb)` (`utils/db/.server/tenantRls.server.ts`): setzt den Kontext
|
||
**transaktions-lokal** via `set_config(..., true)` (== `SET LOCAL`, **PgBouncer-Transaction-Pooling-
|
||
kompatibel**) und führt die Queries in derselben Transaktion → Policies greifen. + Unit-Test.
|
||
- **Isolations-Test (Gate-Beweis)** `rls-tenant-isolation.integration.test.ts`: 6 Assertions gegen eine
|
||
echte Postgres (pgvector pg16) als `hivegrid_app` — Rolle ist non-superuser+non-bypassrls; Kontext A
|
||
sieht nur A; Cross-Tenant-`SELECT`=0; ohne Kontext=0; `WITH CHECK` blockt Fremd-Insert; eigener
|
||
Insert+Read ok. **6/6 grün bewiesen.** Gated auf `RLS_TEST_DATABASE_URL` (skip ohne DB).
|
||
|
||
**Befund — schon vorhanden (verifizieren/erweitern):**
|
||
- RBAC: `Role`/`Permission`/`RolePermission`/`UserRole` + `seedRolesAndPermissions` (generische Rollen
|
||
Admin/SuperUser/User; **6 SHK-spezifische Rollen** (Partner-Liste) per Tenant-Seed geliefert, s.u.).
|
||
- Einladungen: `TenantUserInvitation` + Flow (`workspace-invites.server`, Token-Hash, accept/revoke; **48h-TTL erledigt 2026-06-19**: `WORKSPACE_INVITE_TTL_MS`-Default in `createWorkspaceInvite`, Caller in `members/new.tsx` nutzt ihn statt der vorherigen 7 Tage; + Test).
|
||
- DSGVO-Löschung: `packages/db/dsgvo/pseudonymize` + Worker `dsgvo-deletion`/`dsgvo-grace-cron` + Audit-Hash-Kette — **komplett**.
|
||
- Gruppen: `Group`/`GroupUser` + Basic-UI (Bulk-Ops noch dünn).
|
||
|
||
**Gebaut — Nicht-RLS-Rest (DoD 4+5), Commit `dcf2ae53`:**
|
||
- **Soft-Deaktivierung** (`tenantUserLifecycle.server.ts`): `deactivateTenantUser` setzt `TenantUser`
|
||
auf INACTIVE, **blockiert aber das Deaktivieren des letzten aktiven Owner/Admin** (Last-Admin-Guard);
|
||
optionaler Ownership-Reassign (Gruppen) an einen Nachfolger; `reactivateTenantUser` als Gegenstück.
|
||
- **Gruppen-Bulk-Ops** (`groups.db.server.ts`): `addUsersToGroup`/`removeUsersFromGroup`, idempotent
|
||
(`createMany skipDuplicates`). + 15 Tests.
|
||
|
||
**Geklärt — SHK-Rollen (19.06., Owner-Entscheidung Raffael):** Der Partner hat die Liste auf **6 Rollen**
|
||
festgelegt (vorher spekulativ 10): **Geschäftsführer, Projektleiter, Verwaltung, Vertriebler,
|
||
Kundensupporter, Monteur**. Datengetrieben per Tenant-Seed (`shkRoles.server.ts`, upsert/idempotent,
|
||
`is_demo_data`). Die fachspezifischen Permission-Bundles wachsen pro Phase mit (CRM/Leads/Projekte ab
|
||
P6); bei P2 differenzieren nur die bestehenden App-/Settings-Rechte. DoD-Scope damit von 10 auf 6 gezogen
|
||
(alle Planungs-Docs nachgezogen, dependency-aware).
|
||
|
||
**Offen / geflaggt:**
|
||
- **App-weiter RLS-Rollout**: `withTenantRLS` in die Fach-Modul-Queries + RLS pro Tabelle scharf (inkrementell, pro Modul) — **nicht R-P2b-Scope, läuft mit P5+**.
|
||
- **Davids `D-P2`-Screens**: Rollen-Editor (Bundles + Advanced-Einzelrechte), Gruppen, Mitarbeiter, Lösch-Wizard.
|
||
|
||
**Proof:** voller Typecheck grün · ESLint grün · volle Suite **3754 grün** (+ 6 RLS-Integrationstests, die
|
||
gegen Docker-Postgres **bewiesen** wurden, in der CI/ohne DB sauber skippen) · Node 22.12.0. Branch
|
||
`p2b-rls`, noch nicht nach `main` gemergt.
|
||
|
||
## Status (Stand 2026-06-19)
|
||
**DoD 5/5 = 100 % · Ticket-Abschluss wartet auf `D-P2` (David).** Alle DoD-Punkte sind code-seitig erfüllt:
|
||
RLS-Gate-Beweis, 6 SHK-Rollen (Partner-final, geseedet), Gruppen+Bulk, Lifecycle inkl. **48h-Einladung**
|
||
(2026-06-19). **Selbst machbar offen: 0.** **Blockiert:** Davids `D-P2`-Screens (Rollen-Editor mit
|
||
Advanced-Einzelrechte, Gruppen, Mitarbeiter, Lösch-Wizard) + screen-abhängige generische DoD
|
||
(Reachability/Visual-Regression/Smoke). **Nicht R-P2b-Scope:** app-weiter RLS-Rollout (P5+).
|
||
|
||
## Umsetzungs-Notiz 2026-07-07 (Akeshan, Zulieferung) — D-P2-Screens eingebaut, Screen-DoD geschlossen
|
||
|
||
> Davids `D-P2`-Handoff (2026-06-26, `WF-P2 Admin RBAC` „In Subframe/Review") hat die Screen-Blockade
|
||
> aufgelöst. Branch `akeshan/r-p2b-rbac-screens` (off main), Commits `22e9923a9`…`3fcbbfb6e`.
|
||
> Ich habe die offenen UI-Teile nach Davids Wireframes/Design-Standards gebaut; Backend blieb unverändert
|
||
> (einzige Ergänzung: Bulk-Intents an der bestehenden Gruppen-Action).
|
||
|
||
**Gebaut (David-Optik, `WF-P2 Admin RBAC`):**
|
||
- **S01 Mitarbeiterliste** (`components/screens/users/MembersPage.tsx`): Suche + Rolle/Status/2FA-Filter,
|
||
Eingeladene inline mit Status „Eingeladen", **D01 Inline-Rollen-Dropdown** (nutzt den bestehenden
|
||
`edit`-Intent inkl. SuperUser-Guard), deaktivierte Mitglieder bleiben sichtbar (`includeInactive`).
|
||
- **M03 Deaktivieren** + **V01 Letzter-Admin-Blocker**: `deactivateTenantUser`/`reactivateTenantUser`
|
||
endlich verdrahtet (neue Intents `deactivate`/`reactivate`); Last-Admin-Guard kommt als Code
|
||
`last-admin` zurück und öffnet den V01-Dialog (Copy wörtlich aus dem Wireframe). **Ohne Reassign** —
|
||
Davids v1-Entscheidung; das Backend-Reassign bleibt als API bestehen.
|
||
- **M01 Einladen** als echter Dialog (S 560) statt Slide-Over (`InviteMemberForm`), Invite-Contract
|
||
(Felder/CSRF/48h/`data-ui-id`s) unverändert. Rolle-bei-Einladung NICHT gebaut (Invitation speichert
|
||
keine Rolle — Rollen kommen nach Annahme via D01).
|
||
- **S02 Rollen und Berechtigungen** (`RolesPage.tsx`): zusammengelegter Tab (alte `/users`-Matrix →
|
||
Redirect auf Mitarbeiter, `/permissions` → Redirect auf Rollen), Typ-Spalte (System/Eigene),
|
||
Mitglieder-/Berechtigungs-Zähler; Settings-Icon-Tab „Rollen" nur noch als Fallback ohne
|
||
`members.view` (sonst Tab-Leiste in S01/S02).
|
||
- **M04A Rolle anlegen / M04B Rolle duplizieren → M02 Rollen-Editor** (L 1200): Sidebar-Sections aus
|
||
reiner Scope→Section-Map (`role-editor.vm.ts`, KEINE neuen Permission-Keys), Suche, Toggle-Zeilen;
|
||
speichert über die unveränderten `new`/`$id`-Action-Contracts. **Duplizieren = Create mit vorgeladenem
|
||
Permission-Set der Quelle** (gleicher auditierter `createWorkspaceRole`-Pfad, kein neues Backend).
|
||
Löschen mit **D03-Blocker** bei Mitgliedern > 0. Damit ist der Nachtrag vom 2026-06-22 (Editor
|
||
deferred bis P6–P9) durch Davids geliefertes M02-Design überholt — bitte im Review bestätigen.
|
||
- **Gruppen Bulk-Add/Remove** (Interim, AD-28 — David-Backlog): `GroupMembersDialog` (M 720) an
|
||
`settings/groups`, neue idempotente Intents `bulk-add`/`bulk-remove` auf
|
||
`addUsersToGroup`/`removeUsersFromGroup` (Tenant-Membership validiert, `createLog`-Audit).
|
||
- **VMs** `packages/view-models/src/users/` (members-list/roles-list/role-editor/groups-detail, pure,
|
||
27 Unit-Tests) · **Hot-Swap-Kette** `membersList`/`rolesList` (Adapter + Subframe-/Mock-Renderer,
|
||
M015/M017) · **Smoke** `tests/e2e/members-roles.spec.ts` (nicht-mutierend) · a11y-Specs
|
||
(`tenant-members`, `tenant-roles-permissions.*`) auf die neue Struktur nachgezogen · i18n de/en.
|
||
|
||
**Proof:** Typecheck (web/view-models/ui-app/ui-mock/ui-subframe) grün · `verify:i18n`/`verify:sidebar-routes`/
|
||
`verify:cross-cutting-models` Exit 0 · 376 Tests grün über die betroffenen Suiten (members-Route 13/13 neu;
|
||
`roles.test.tsx`-Restfehler = bekannter Node-22.15-undici-Umgebungsfehler, identisch auf main) ·
|
||
KEIN Prisma-Schema-Change (Abteilung/Kategorie/Rollen-Status bewusst weggelassen statt Spalten zu erfinden).
|
||
|
||
**Offen / geflaggt:**
|
||
- **Bewusst NICHT gebaut:** Konto-Lösch-Wizard (Davids jüngere Entscheidung 2026-06-26: Backlog bis
|
||
Workspace-Settings; DSGVO-Self-Service existiert unter `/settings/privacy`) · Reassign-Panel (V2) ·
|
||
„Einladung erneut senden" (kein Backend) · Rolle-bei-Einladung (kein Invitation-Feld).
|
||
- **Produkt-Widerspruch SHK-Seeds vs. „nur Admin" — ENTSCHIEDEN 2026-07-07 (Akeshan, → AD-29):** Die 6
|
||
SHK-Seed-Rollen bleiben auf **Staging/Dev als Test-Komfort**; auf **Produktion startet ein frischer
|
||
Tenant nur mit der Admin-Systemrolle** (Davids validierte D-P2-Entscheidung). Umgesetzt als Gate in
|
||
`seedShkRolesForTenant` (`shouldSeedShkRoles`): `SENTRY_ENVIRONMENT=production` ⇒ kein Seed
|
||
(NODE_ENV ist auf Staging-Containern auch „production", daher entscheidet die deploy-scoped Variable);
|
||
Override per `SEED_SHK_ROLES=true|false`, falls der Partner die Seeds produktiv doch will. 8 Tests.
|
||
- Alt-Komponenten (`MembersListView`, `RolesListView`, `NewMember`, `RolesAndPermissionsMatrix`,
|
||
`MemberInvitationsListAndTable`) sind jetzt verwaist — Aufräumen als Folge-Cleanup.
|
||
|
||
**%-Stand: fachliche DoD 5/5 = 100 % · screen-abhängige generische DoD (B6–10, D18–21) jetzt erfüllt**
|
||
(Visual über die deterministischen Renderer-/Hot-Swap-Snapshots wie bei AK-P3; Gruppen-Optik als
|
||
`design-nachzug` markiert, s. Header-Tag). Done-Status nur mit Freigabe/Review durch Raffael.
|