Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -1,42 +1,54 @@
# R-P2b · P2 RLS-Härtung (Gate-Beweis) + RBAC + User-Lifecycle
| | |
|---|---|
| **Typ** | Dev (Code) |
| **Owner** | Raffael |
| **Phase** | P2 — Identität & Mandantentrennung |
> **Nachzug 2026-07-15 (R-CR1/R-P20b, AD-29):** Die unten dokumentierte Sechs-Rollen-
> Implementierung bleibt historischer Proof für R-P2b, ist aber kein aktueller Provisionierungsvertrag
> mehr. Der Staging-/Dev-Seed und `shkRoles.server.ts` sind entfernt. Für neue Workspaces gelten fünf
> editierbare Tenant-Rollen (Vertrieb, Marketing, Innendienst, Buchhaltung/Verwaltung, Monteur) und
> ausschließlich die globale `Admin`-Rolle für den Owner; Bestands-Tenants bleiben unverändert.
| | |
| ----------------- | ------------------------------------------------------------------------------ |
| **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 |
| **Status** | Done (Plane, seit 2026-07-07) |
**🎨 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.)*
| 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)
- [x] **DSGVO-Ausführung zur Laufzeit** _(im Stand-Audit 2026-07-17 als fehlender DoD-Punkt nachgetragen — war bis dahin offen)_: `dsgvoGraceCronService` im Worker-Bootstrap verdrahtet, Lösch-Kaskade läuft RLS-kontext-gebunden im Modus Pseudonymisierung → s. Umsetzungs-Notiz 2026-07-17
## 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).
@@ -44,16 +56,17 @@ Die **RLS-Härtung als Gate-Beweis** (AD-1): Postgres-Row-Level-Security mit `US
- `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)
- `ROADMAP.md` → Phase 2 · Milestones: (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
- [ ] REQUIREMENTS/ROADMAP nachgezogen
- [ ] Plane-Ticket `R-P2b` aktualisiert
## Nachtrag 2026-06-22 (Claude) — Rollen-Liste übernommen, Relevanz-/Flag-Klärung
@@ -79,6 +92,7 @@ Die **RLS-Härtung als Gate-Beweis** (AD-1): Postgres-Row-Level-Security mit `US
> 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
@@ -93,13 +107,15 @@ Die **RLS-Härtung als Gate-Beweis** (AD-1): Postgres-Row-Level-Security mit `US
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**.
- DSGVO-Löschung: `packages/db/dsgvo/pseudonymize` + Worker `dsgvo-deletion`/`dsgvo-grace-cron` + Audit-Hash-Kette — **komplett**. _(Korrektur Stand-Audit 2026-07-17: das galt nur für die Job-Kerne — das Laufzeit-Wiring des Grace-Cron-Service fehlte bis dahin vollständig, s. Umsetzungs-Notiz 2026-07-17.)_
- 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.
@@ -114,6 +130,7 @@ P6); bei P2 differenzieren nur die bestehenden App-/Settings-Rechte. DoD-Scope d
(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.
@@ -122,6 +139,7 @@ gegen Docker-Postgres **bewiesen** wurden, in der CI/ohne DB sauber skippen) ·
`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
@@ -136,6 +154,7 @@ Advanced-Einzelrechte, Gruppen, Mitarbeiter, Lösch-Wizard) + screen-abhängige
> (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`).
@@ -170,6 +189,7 @@ Advanced-Einzelrechte, Gruppen, Mitarbeiter, Lösch-Wizard) + screen-abhängige
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).
@@ -185,3 +205,67 @@ KEIN Prisma-Schema-Change (Abteilung/Kategorie/Rollen-Status bewusst weggelassen
**%-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.
## Dependency-Nachzug 2026-07-15 · R-P20b
- User-Identitäten sind global über `lower(trim(email))` eindeutig; Resolver brechen bei Alt-Dubletten fail-closed ab.
- Pro Tenant und normalisierter E-Mail existiert höchstens eine lebende Einladung. Accept/Revoke/Owner-Claim sind bedingte, race-sichere Zustandswechsel.
- Der neue ownerlose Reservierungs-Claim gilt nur für `OWNER` und `pending_owner`. Normale Member-Einladungen behalten ihren bisherigen Lifecycle unverändert.
- Öffentliche Invite-Lookups sind rate-limitiert, indexgestützt und geben finalisierte/abgelaufene Capability-Daten nicht an fremde oder anonyme Sessions aus.
## Umsetzungs-Notiz 2026-07-17 (Akeshan) — Stand-Audit + DSGVO-Grace-Cron-Restarbeit
> Drei-Quellen-Audit (Doc vs. Plane vs. Code) via `/audit-ticket`. DoD 1–4 und die Screen-DoD
> waren im Code belegt (Proofs unverändert gültig). **Realer Befund an DoD 5:** Die DSGVO-Löschung
> war nur als Job-Kern + Self-Service-Antrag fertig — **kein Laufzeit-Ausführungspfad existierte**:
> `dsgvoGraceCronService` wurde nirgends konstruiert, der tägliche Cron ackte jeden Tick mit
> `"dsgvoGraceCronService not configured"`, und auch die Operator-CLI plant nur ein (Kommentar dort:
> „the grace-period cron picks it up later"). Ein bestätigter Löschantrag wurde nach Ablauf der
> 30 Tage **nie ausgeführt**. Zusätzlich hätte die Kaskade seit dem RLS-Cutover (13.07.) ohne
> Kontextbindung still 0 Zeilen getroffen (gleiche Klasse wie die notify()-Regression, PR #146).
**Fix (Branch `fix/r-p2b-dsgvo-grace-wiring`):**
- **`apps/worker/src/jobs/dsgvo-grace-bootstrap.ts` (neu):** `createWorkerDsgvoGraceCronService` —
`listOverdueUsers` als Per-Tenant-Sweep (`runActiveTenantSweep`) unter `runWithRlsContext({tenantId})`
(die `User`-Select-Policy zeigt dem Worker einen User nur über den gebundenen Membership-Tenant;
ein globaler Scan liefert unter FORCE RLS still 0 Zeilen), Kandidaten über Tenants dedupliziert.
Die Kaskade läuft inline (Muster AK-P21, serialisiert): jede `USER_FK_MAP`-Operation einmal pro
Membership-Tenant unter `{userId, tenantId}` plus einmal unter `{userId}` (idempotent, Summen korrekt).
- **Modus verbindlich `pseudonymize`** (Ticket-Design: PII-Anonymisierung, kein Hard-Delete, Audit-Kette
intakt; Entscheidung 2026-07-17): Grace-Cron-Kern + Handler-Vertrag von `mode:"delete"` auf
`"pseudonymize"` gezogen; `hardDeleteUser` wirft im Worker bewusst (Grant-Set kann Hard-Delete nicht erfüllen).
- **Bewusste Skips (geloggt + im Audit-Event-Metadata):** `AdminTenantNote`/`AdminUser`/`Feedback`/
`ImpersonationAudit`/`SupportTicket`/`SupportTicketMessage` haben im RLS-Vertrag keine Worker-Write-Grants,
`UserRole` nur SELECT. Die Zeilen behalten die Referenz auf das pseudonymisierte User-Skelett (Identitäts-Link
anonymisiert). **Grant-Erweiterung am generierten RLS-Vertrag = getrackter Folge-Punkt (Raffael, RLS-Territorium).**
- **Wiring** in `apps/worker/src/index.ts` (general-Group, neben AK-P21-Tenant-Delete).
**Proof:** `@hivegrid/worker`-Typecheck grün · ESLint grün · 12 DSGVO-Job-Tests grün (davon 4 neue
Bootstrap-Tests mit RLS-Policy-nachbildendem Fake-Client: unbound ⇒ 0 Zeilen/Reject, gebunden ⇒ trifft;
FK-Map-Vollklassifikations-Guard) · `handlers.test.ts` 110 grün · `index.test.ts` 58 grün ·
`verify:i18n`/`verify:sidebar-routes`/`verify:cross-cutting-models` Exit 0 · kein Schema-Change, keine Migration.
**Korrektur eines Audit-Zwischenbefunds:** `packages/db/src/shk-template-roles-seed.server.ts` ist
**kein** Dead-Code — `shk-v2.config.test.ts` (R-P20b) nutzt `shkTemplateRoleSeeds` als validierte
Provenance-Baseline der fünf AD-29-Rollen. Nur `seedShkTemplateRolesForTenant` ist ungenutzt; Datei bewusst belassen.
**%-Stand: 6/6 DoD (inkl. nachgetragenem Laufzeit-Punkt) = 100 %.** Offen bleibt nur der markierte
`design-nachzug` (Header-Tag) sowie der Folge-Punkt Grant-Erweiterung (außerhalb R-P2b, Owner Raffael).
## Dependency-Hinweis 2026-07-16 · Cutover-Regression bei worker-seitigem notify()
Der app-weite RLS-Cutover (`20260713190000_appwide_rls_cutover`) hat `NotificationDelivery` auf
FORCE RLS gestellt; worker-seitige `notify()`-Aufrufe ohne gebundenen Tenant-Kontext scheitern
seither still (beobachtet: Task-Reminder-Sweep stellt auf Staging nicht mehr zu, 16.07.).
Befund + To-do dokumentiert in `R-P1b.md` §Regressions-Befund (Owner notify()-Kern) und
`AK-P4b.md` (Notiz 16.07. Abend).
## Dependency-Nachzug 2026-07-29 · R-P2a Pflichtfeldvertrag
Der vorgelagerte Signup validiert konfigurierte Pflichtfelder jetzt unabhängig
vom Passwortzweig und lehnt leere Firma sowie leeren Vor- oder Nachnamen vor
der Tenant-Provisionierung ab. Rollen-, Gruppen-, Einladungs- und
DSGVO-Verträge dieses Tickets ändern sich nicht.
**Fortschritt:** R-P2b bleibt bei 6/6 DoD = 100 % done.