feat(identity): simple user and role management for admins

[Fluory]

Warum

Fixes #30 · Epic #18 · gestapelt auf #37 (Basis claude/feat-rls-guard-29).

Arbeitsstand

• Ziel: Firmen-Admins verwalten ihre Nutzer in der App: Liste mit Rolle und Status, einladen, Rolle ändern, deaktivieren (und reaktivieren); jede Änderung auditiert; der letzte Admin bleibt; Sachbearbeitung hat serverseitig keinen Zugriff.
• Nicht-Ziele: SSO, SCIM, eigene Rollen, firmenübergreifende Verwaltung, E-Mail-Versand von Einladungen.
• Erledigt: Last-Admin-Regel (Unit), Dienst (Liste, Rolle, Deaktivieren/Reaktivieren, auditierte Einladung), Seite /users mit Server Actions, Better-Auth-Härtung (Creator-Rolle unerreichbar, /organization/* außer set-active abgeschaltet), Tests inkl. Server Actions, Doku inkl. ADR-Nachtrag, Security-Review inkl. Fixes.
• Offen: Merge durch den Orchestrator nach feat(tenancy): guard test – every app table has forced RLS #37.
• Annahmen: siehe Impact Manifest.
• Nächster kleinster Schritt: Review durch den Orchestrator; danach feat(ai-service): full field set including line items #22 auf diesem Branch.

Was ist passiert (Klartext)

Admins haben jetzt eine Seite „Benutzer": Sie sehen alle Personen ihrer Firma mit Rolle und Status (aktiv/deaktiviert) sowie offene Einladungen, ändern Rollen (Administration/Sachbearbeitung), deaktivieren Zugänge (Anmeldung gesperrt, laufende Sitzungen sofort beendet) und aktivieren sie wieder. Jede Änderung – auch jede Einladung – wird protokolliert. Den letzten aktiven Admin kann niemand herabstufen, und sich selbst sperren geht nicht. Sachbearbeiter:innen bekommen die Seite und ihre Aktionen gar nicht zu sehen – das prüft der Server. Sicherheitsfund unterwegs: Die Login-Bibliothek (Better Auth) hat eigene Web-Schnittstellen für Mitglieder; darüber hätten Admins ohne Protokoll Rollen ändern und der letzte Admin die Firma verlassen können, und Sachbearbeiter:innen hätten die Mitgliederliste lesen können. Diese Schnittstellen sind jetzt abgeschaltet; alles läuft über den protokollierten Weg.

Plan-Pflicht (SYSTEM.md §4)

• Kein Auslöser – keine Modulgrenze, öffentliche API, Migration, Auth/Rechte, kein Zahlungs-/Daten-/Infrapfad, höchstens zwei Module, keine Architekturvarianten, umkehrbar
• Auslöser zutreffend – Impact Manifest ausgefüllt (Plan vor Code)

Impact Manifest

• Betroffene Module: identity (Nutzerverwaltung, Last-Admin-Regel, inviteUser auditiert, getActor lehnt gesperrte Nutzer ab, Better-Auth-Konfiguration), audit (Ereignisse user.*, neuer Entity-Typ invitation), tenancy (Audit in withTenant), app (Seite /users, Server Actions, Link auf der Startseite).
• Schnittstellen / Datenänderungen: keine Migration. Deaktivieren nutzt auth.user.banned/ban_reason (Admin-Plugin) und löscht die Sitzungen; Rollen auf auth.member.role. /api/auth/organization/* außer set-active → 404 (disabledPaths); creatorRole = owner (von niemandem erreichbar).
• Akzeptanzkriterien: alle aus feat(identity): simple user and role management for admins #30 – siehe Nachweis.
• Testplan: Unit – Last-Admin-Regel; Integration – Liste nur eigene Firma, Rollenwechsel + Audit, Einladung auditiert (ohne E-Mail), Deaktivieren sperrt Login/Sitzung + Reaktivieren, letzter Admin, keine Selbstsperre, parallele Änderungen, fremde Firma, Clerk über die Server Actions selbst (nur next/headers gefälscht), abgeschaltete Plugin-Endpunkte.
• Verifizierte Fakten: Better Auth 1.7.5: hasPermission gibt der creatorRole alle Rechte; /organization/leave ohne Rechteprüfung; Admin-Plugin blockiert gesperrte Nutzer beim Session-Erstellen; keine Cookie-Cache-Konfiguration → gelöschte Sitzungen sofort ungültig; member.user_id eindeutig (eine Firma pro Nutzer).
• Offene Annahmen: Deaktivieren sperrt den Nutzer global (wegen „eine Firma pro Nutzer" gleichbedeutend).
• Nicht-Ziele: siehe oben.
• Risiken und Rollback: Autorisierung in jeder Action und im Modul; keine personenbezogenen Daten in Logs; keine Migration; Rollback per Revert.

Geändert

• src/features/identity/{users,last-admin,companies,actor,access,auth,index}.ts (+ last-admin.test.ts)
• src/features/audit/audit.ts (Entity-Typ invitation)
• src/app/users/{page.tsx,actions.ts}, src/app/page.tsx
• Tests: tests/integration/{users,identity}.test.ts, tests/integration/helpers/stack.ts (Text-404 lesbar)
• Doku: docs/decisions/ADR-0001-pilot-architecture.md (D6-Nachtrag), docs/technical/{operations,data-model,architecture}.md, CHANGELOG.md

Nachweis (SYSTEM.md §11)

• verify:changed: typecheck + lint + Unit Last-Admin 4/4 + Integration users/identity 25/25 grün
• verify: lokal grün (Exit 0, Node 24) gegen echtes PostgreSQL 17 + SeaweedFS – Unit 131/131, Integration 96/96, depcruise ohne Verstöße, Build, Audit (1 moderate, Schwelle high); CI check: siehe Checks dieses PRs
• verify:full / E2E-Spec: Smoke lokal grün (Login/Session-Pfad nach Auth-Änderung unverändert)
• Akzeptanzkriterien feat(identity): simple user and role management for admins #30: Admins sehen Nutzer der eigenen Firma mit Rolle/Status → „lists the users of the own company only…"; einladen/Rolle/deaktivieren, jede Änderung auditiert → „changes a role and audits it…", „deactivating ends the sessions…"; letzter Admin nicht entfernbar → Unit Last-Admin + „keeps the last active admin…" + „serialises concurrent changes…" + Plugin-leave/remove-member abgeschaltet; Clerks ohne Zugriff serverseitig → „server actions: a clerk gets 404…" + „refuses … clerks (module)" + list-members abgeschaltet
• Manueller Prüfnachweis: –
• Frischer Review (P1 vor Ready-for-review; Architektur/API/DB immer): unabhängiger Security-Review – 1 Blocker, 4 should-fix, 2 nits, alle behoben (PR-Kommentar); Mutationsprobe für den Blocker dokumentiert
• Hinweis: Für den Review wurden Better-Auth-Quellen in node_modules gelesen (FLUORY_ALLOW_ARTIFACTS=1, Read-Guard) – nötig, um die Rechteprüfung der Plugin-Endpunkte zu belegen.

Doku-Entscheidung (genau eine)

• Keine langlebige Doku betroffen – Begründung: –
• Doku betroffen und im selben PR aktualisiert:
  • Produktdoku (P0: README): –
  • Technische Doku: docs/technical/operations.md, docs/technical/data-model.md
  • Architekturkarte: docs/technical/architecture.md (Identity-Status, Registereintrag Admin-Plugin entschieden)
  • ADR: docs/decisions/ADR-0001-pilot-architecture.md – Nachtrag D6 (Rollen-Admin-UI im Pilot, Plugin-Härtung)
  • CHANGELOG [Unreleased] (sichtbares Feature oder Verhalten – im selben PR, nie „später")

Entferntes oder Umbenanntes: nichts entfernt (Plugin-Endpunkte abgeschaltet, nicht entfernt)

Dateigrößen und neue Bausteine (SYSTEM.md §7)

Dateien über 500 Zeilen im Diff (Ausnahmen: generierter Code, Lockfiles, Fixtures, Migrationen, Schemas, Ressourcen, Doku, Konfiguration):

• keine
• bewusst belassen – Begründung: –
• im selben PR nach fachlicher Verantwortung geteilt
• Folge-Issue –

Über 800 Zeilen mit neuer Fachlogik oder über 1000 Zeilen (P1/P2): nicht betroffen

Neue Shared-Komponente, Utility-Datei, Adapter oder fachlicher Service:

• nein
• ja – gesucht nach: vorhandener Nutzer-/Einladungslogik; gefunden: identity/companies.ts (inviteUser), authorize() mit users.manage – erweitert, nicht dupliziert

Subagent-Einsätze

• Frischer Security-Review (read-only): Ergebnis und Auflösung als PR-Kommentar.

Risiken / offene Punkte

• Better-Auth-Upgrades können neue /organization/*-Endpunkte bringen – die Abschaltliste ist explizit; bei Upgrades die Endpunktliste prüfen (Test deckt die bekannten ab).

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01DJ5vaKvTYiMvdngT4d3xo1

[Fluory]

Frischer Security-Review (unabhängiger Subagent, read-only, review-pr + Security-Regel, Better-Auth-Quellen gelesen)

Ergebnis: 1 Blocker · 4 should-fix · 2 nits – alle behoben. Bestätigt: kein IDOR (Ziel nur unter den gesperrten Mitgliedern der eigenen Firma), Firma nur aus der Session, UUID/Rollen validiert, Clerk → 404 in Seite und allen Actions, Sperren blockiert Login (Admin-Plugin-Hook) und getActor prüft zusätzlich, kein Deadlock (gleiche Sperrreihenfolge), Rolle owner unerreichbar, Audit in derselben Transaktion.

#	Schwere	Befund	Auflösung
B1	blocker	/organization/leave hat keine Rechteprüfung; mit creatorRole: "owner" griff auch der Schutz „letzter Owner" nicht mehr → der letzte Admin konnte die Firma unauditiert verlassen	Alle /organization/*-Endpunkte außer set-active per disabledPaths abgeschaltet (404). Test „…the plugin endpoints are disabled" prüft u. a. leave; Mutationsprobe ohne disabledPaths: leave = 200, list-members (Clerk) = 200 → Test rot
S1	should-fix	remove-member-Tests nutzten User-ID statt Member-ID (scheiterten aus falschem Grund)	Member-ID + exakter Status 404
S2	should-fix	E-Mail im append-only Audit (user.invited) nicht löschbar	nur { role }, entityType: "invitation" (Invitation-ID verweist auf die E-Mail)
S3	should-fix	Clerks konnten per /organization/list-members / get-full-organization alle Kolleg:innen lesen	durch B1 abgeschaltet, getestet
S4	should-fix	PR-Body veraltet; ADR-0001 D6 sagte „kein Rollen-Admin-UI"	Body aktualisiert; datierter Nachtrag in D6
N1	nit	Admin konnte sich selbst deaktivieren	abgelehnt (SelfDeactivation, Code self), Test; ein anderer Admin darf
N2	nit	Admins konnten die Firma per Plugin umbenennen (ohne Audit)	durch B1 abgeschaltet, getestet

Danach: pnpm verify lokal grün (Unit 131/131, Integration 96/96), E2E-Smoke grün.

---

Generated by Claude Code