DEVLOG: Sessionlog-Eintrag (Auto-Hook)

# Conflicts:
#	DEVLOG.md

.gitignore

@@ -1,2 +1,4 @@
 *.log
 .env
+web/*/node_modules/
+web/*/.next/

DEVLOG.md

@@ -64,6 +64,9 @@ Keine Änderungen ermittelbar.
 ## 2026-08-27 17:28 – 17:29 (1m)
 **Beschreibung:** Claude Code Session
 **Projekt:** code
+## 2026-08-28 21:44 – 21:44 (0m)
+**Beschreibung:** Claude Code Session
+**Projekt:** nexarch
 
 ### Commits
 Keine Commits in dieser Session.
@@ -127,5 +130,72 @@ Keine Commits in dieser Session.
 - internal/config/config.go           | 29 +++++++++++++++++++++++++++++
 - internal/db/db.go                   | 11 +++++++++++
 - migrations/0001_tenant_registry.sql | 10 ++++++++++
+- web/shl/README.md                   | 45 +++++++++++++++++++++++++++++++++++++++++++++
+- web/shl/__tests__/Dialog.test.tsx   | 38 ++++++++++++++++++++++++++++++++++++++
+- web/shl/__tests__/tokens.test.ts    | 39 +++++++++++++++++++++++++++++++++++++++
+- web/shl/components/Dialog.tsx       | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+- web/shl/components/FormElements.tsx | 98 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+- web/shl/components/Shell.tsx        | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+- web/shl/components/Table.tsx        | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+- web/shl/components/Toast.tsx        | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+- web/shl/i18n/i18n.tsx               | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+- web/shl/index.ts                    | 25 +++++++++++++++++++++++++
+- web/shl/package.json                | 23 +++++++++++++++++++++++
+- web/shl/theme/ThemeProvider.tsx     | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+- web/shl/tokens/tokens.ts            | 96 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+- web/shl/tsconfig.json               | 18 ++++++++++++++++++
+
+---
+## 2026-08-28 21:51 – 21:57 (5m)
+**Beschreibung:** Claude Code Session
+**Projekt:** nexarch
+
+### Commits
+- 3c226da SHL-01: fix — vitest jsdom-environment + jest-dom-Setup (3 Dialog-Tests schlugen ohne DOM fehl)
+
+### Geänderte Dateien
+- web/shl/package.json     | 2 ++
+- web/shl/vitest.config.ts | 8 ++++++++
+- web/shl/vitest.setup.ts  | 1 +
+
+---
+## 2026-08-28 23:37 – 23:43 (5m)
+**Beschreibung:** Claude Code Session
+**Projekt:** nexarch
+
+### Commits
+- fbcc9db RBAC-05: web/rbac-admin next.js-frontend (rollen+gruppen-verwaltung, audit-verlauf) auf shl-01
+- bd80f0c Merge branch 'feature/shl-01-ui-shell-design-system-zentral' into feature/rbac-05-rechte-administrationsoberflaeche
+- 051af43 RBAC-05: backend — handler.go (rollen-/gruppenverwaltung, selbst-eskalationsschutz), group.go ListGroups/Members
+- 9de9005 Merge branch 'feature/iam-02-login-session-jwt-grundgeruest' into feature/rbac-05-rechte-administrationsoberflaeche
+- 1b6a159 Merge branch 'feature/rbac-03-gruppen-abteilungen' into feature/rbac-05-rechte-administrationsoberflaeche
+
+### Geänderte Dateien
+- web/rbac-admin/app/groups/page.tsx | 183 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+- web/rbac-admin/app/layout.tsx      |  30 ++++++++++++++++++++++++++++++
+- web/rbac-admin/app/page.tsx        |   5 +++++
+- web/rbac-admin/app/roles/page.tsx  | 142 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+- web/rbac-admin/lib/api.ts          |  68 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+- web/rbac-admin/next.config.mjs     |   5 +++++
+- web/rbac-admin/package.json        |  22 ++++++++++++++++++++++
+- web/rbac-admin/tsconfig.json       |  21 +++++++++++++++++++++
+
+---
+## 2026-08-28 23:44 – 23:44 (0m)
+**Beschreibung:** Claude Code Session
+**Projekt:** code
+
+### Commits
+Keine Commits in dieser Session.
+
+### Geänderte Dateien
+- web/rbac-admin/app/groups/page.tsx | 183 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+- web/rbac-admin/app/layout.tsx      |  30 ++++++++++++++++++++++++++++++
+- web/rbac-admin/app/page.tsx        |   5 +++++
+- web/rbac-admin/app/roles/page.tsx  | 142 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+- web/rbac-admin/lib/api.ts          |  68 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+- web/rbac-admin/next.config.mjs     |   5 +++++
+- web/rbac-admin/package.json        |  22 ++++++++++++++++++++++
+- web/rbac-admin/tsconfig.json       |  21 +++++++++++++++++++++
 
 ---

cmd/core/main.go

@@ -8,6 +8,7 @@ import (
 	"gitea.perlbach24.de/scripte/nexarch/internal/config"
 	"gitea.perlbach24.de/scripte/nexarch/internal/db"
 	"gitea.perlbach24.de/scripte/nexarch/internal/tenant"
+	"gitea.perlbach24.de/scripte/nexarch/internal/user"
 )
 
 func main() {
@@ -34,12 +35,20 @@ func main() {
 	provisioner := tenant.NewProvisioner(adminPool, registry, cfg.TenantDSNTemplate)
 	tenantHandler := tenant.NewHandler(provisioner)
 
+	// Superadmin-Konten leben mandantenuebergreifend in der Registry-DB.
+	// Tenant-User-CRUD (user.TenantUserStore) braucht Connection-Routing pro
+	// Mandant (TEN-06, noch nicht gebaut) und wird hier bewusst noch nicht
+	// verdrahtet — Package ist bereits eigenstaendig nutzbar/testbar.
+	superadmins := user.NewSuperadminStore(registryPool)
+	userHandler := user.NewHandler(nil, superadmins)
+
 	mux := http.NewServeMux()
 	mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
 		w.WriteHeader(http.StatusOK)
 	})
-	// Vorlaeufiger Pfad ohne Versionierung/Auth — wird mit API-01/IAM-01 abgeloest.
+	// Vorlaeufige Pfade ohne Versionierung/Auth — werden mit API-01/IAM-02 abgeloest.
 	mux.HandleFunc("/internal/tenants", tenantHandler.CreateTenant)
+	mux.HandleFunc("/internal/superadmins", userHandler.CreateSuperadmin)
 
 	log.Printf("nexarch-core listening on %s", cfg.ListenAddr)
 	if err := http.ListenAndServe(cfg.ListenAddr, mux); err != nil {

go.mod

@@ -5,13 +5,13 @@ go 1.22
 require (
 	github.com/golang-jwt/jwt/v5 v5.3.1
 	github.com/jackc/pgx/v5 v5.6.0
+	golang.org/x/crypto v0.17.0
 )
 
 require (
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20221227161230-091c0ba34f0a // indirect
 	github.com/jackc/puddle/v2 v2.2.1 // indirect
-	golang.org/x/crypto v0.17.0 // indirect
 	golang.org/x/sync v0.1.0 // indirect
 	golang.org/x/text v0.14.0 // indirect
 )

internal/auth/handler.go

@@ -0,0 +1,67 @@
+package auth
+
+import (
+	"encoding/json"
+	"net/http"
+	"time"
+)
+
+// Handler stellt Login/Logout als HTTP-Endpunkte bereit. Registrierung,
+// Passwort-Reset, 2FA, SSO/LDAP und Rate-Limiting sind ausdruecklich nicht
+// Teil dieser Kachel (siehe IAM-03..07).
+type Handler struct {
+	login *LoginService
+}
+
+func NewHandler(login *LoginService) *Handler {
+	return &Handler{login: login}
+}
+
+type loginRequest struct {
+	Email    string `json:"email"`
+	Password string `json:"password"`
+}
+
+func (h *Handler) Login(w http.ResponseWriter, r *http.Request) {
+	var req loginRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		http.Error(w, "ungueltige Anfrage", http.StatusBadRequest)
+		return
+	}
+
+	token, err := h.login.Login(r.Context(), req.Email, req.Password)
+	if err != nil {
+		http.Error(w, ErrInvalidCredentials.Error(), http.StatusUnauthorized)
+		return
+	}
+
+	http.SetCookie(w, &http.Cookie{
+		Name:     CookieName,
+		Value:    token,
+		Path:     "/",
+		HttpOnly: true,
+		Secure:   true,
+		SameSite: http.SameSiteStrictMode,
+		MaxAge:   int(AccessTokenTTL.Seconds()),
+	})
+	w.WriteHeader(http.StatusOK)
+}
+
+// Logout loescht das Session-Cookie. Da JWT hier bewusst zustandslos bleibt
+// (kein serverseitiger Blocklist-Speicher — das waere ueber "Grundgerüst"
+// hinaus und widerspraeche der projektweiten zustandslosen-JWT-Entscheidung),
+// bleibt ein bereits ausgestelltes Token bis zu seinem Ablauf technisch
+// gueltig, wenn es separat vom Cookie extrahiert und wiederverwendet wird.
+func (h *Handler) Logout(w http.ResponseWriter, r *http.Request) {
+	http.SetCookie(w, &http.Cookie{
+		Name:     CookieName,
+		Value:    "",
+		Path:     "/",
+		HttpOnly: true,
+		Secure:   true,
+		SameSite: http.SameSiteStrictMode,
+		MaxAge:   -1,
+		Expires:  time.Unix(0, 0),
+	})
+	w.WriteHeader(http.StatusOK)
+}

internal/auth/login.go

@@ -0,0 +1,56 @@
+package auth
+
+import (
+	"context"
+	"errors"
+
+	"gitea.perlbach24.de/scripte/nexarch/internal/user"
+)
+
+var ErrInvalidCredentials = errors.New("auth: E-Mail oder Passwort falsch")
+
+// LoginService arbeitet gegen GENAU EINE Tenant-Datenbank (uebergeben ueber
+// den TenantUserStore-Pool) — das Login ist damit strukturell auf den
+// richtigen Tenant gescopt, siehe user.TenantUserStore.GetByEmailForAuth.
+type LoginService struct {
+	users  *user.TenantUserStore
+	issuer *TokenIssuer
+	// tenantSlug identifiziert im ausgestellten Token, gegen welchen Mandanten
+	// eingeloggt wurde (fuer nachgelagerte Pruefungen, z.B. Middleware-Logs).
+	tenantSlug string
+}
+
+func NewLoginService(users *user.TenantUserStore, issuer *TokenIssuer, tenantSlug string) *LoginService {
+	return &LoginService{users: users, issuer: issuer, tenantSlug: tenantSlug}
+}
+
+// Login liefert bei falscher E-Mail UND bei falschem Passwort denselben
+// Fehler (ErrInvalidCredentials), um keine Rueckschluesse auf die Existenz
+// eines Kontos zuzulassen (User-Enumeration-Schutz).
+func (s *LoginService) Login(ctx context.Context, email, password string) (string, error) {
+	creds, err := s.users.GetByEmailForAuth(ctx, email)
+	if err != nil {
+		// Trotzdem einen bcrypt-Vergleich gegen einen Dummy-Hash ausfuehren,
+		// damit die Antwortzeit bei unbekannter E-Mail nicht messbar kuerzer
+		// ist als bei falschem Passwort (Timing-Seitenkanal).
+		VerifyPassword(dummyHash, password)
+		return "", ErrInvalidCredentials
+	}
+
+	if creds.User.Status != user.StatusActive {
+		return "", ErrInvalidCredentials
+	}
+
+	if !VerifyPassword(creds.PasswordHash, password) {
+		return "", ErrInvalidCredentials
+	}
+
+	return s.issuer.Issue(creds.User.ID, s.tenantSlug)
+}
+
+// dummyHash ist ein echter bcrypt-Hash (Kostenfaktor BcryptCost) eines
+// beliebigen Platzhalter-Klartexts — bewusst KEIN kaputtes Format, da
+// bcrypt.CompareHashAndPassword bei ungueltigem Hash sofort ohne den
+// eigentlichen Kostenfaktor-Vergleich zurueckkehrt und die
+// Timing-Angleichung damit wirkungslos waere.
+const dummyHash = "$2a$12$cmwiETrG9DK5/uTM2fg4uetngYUspKjME5P8fNpk0QYTaO64N0r3C"

internal/auth/login_test.go

@@ -0,0 +1,177 @@
+package auth
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"gitea.perlbach24.de/scripte/nexarch/internal/user"
+)
+
+const usersSchema = `
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+CREATE TABLE users (
+	id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+	email TEXT NOT NULL UNIQUE,
+	name TEXT NOT NULL,
+	status TEXT NOT NULL DEFAULT 'active',
+	password_hash TEXT NOT NULL DEFAULT '',
+	created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+	updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);`
+
+func setupTenantDB(t *testing.T, dbName string) *pgxpool.Pool {
+	t.Helper()
+	adminDSN := os.Getenv("TEST_ADMIN_DSN")
+	if adminDSN == "" {
+		t.Skip("TEST_ADMIN_DSN nicht gesetzt, Integrationstest uebersprungen")
+	}
+	ctx := context.Background()
+
+	adminPool, err := pgxpool.New(ctx, adminDSN)
+	if err != nil {
+		t.Fatalf("admin pool: %v", err)
+	}
+	_, _ = adminPool.Exec(ctx, fmt.Sprintf(`DROP DATABASE IF EXISTS %q`, dbName))
+	if _, err := adminPool.Exec(ctx, fmt.Sprintf(`CREATE DATABASE %q`, dbName)); err != nil {
+		t.Fatalf("testdatenbank anlegen: %v", err)
+	}
+
+	dsn := strings.Replace(adminDSN, "/postgres?", "/"+dbName+"?", 1)
+	pool, err := pgxpool.New(ctx, dsn)
+	if err != nil {
+		t.Fatalf("connect testdatenbank: %v", err)
+	}
+	if _, err := pool.Exec(ctx, usersSchema); err != nil {
+		t.Fatalf("schema anwenden: %v", err)
+	}
+
+	t.Cleanup(func() {
+		pool.Close()
+		_, _ = adminPool.Exec(ctx, fmt.Sprintf(`DROP DATABASE IF EXISTS %q`, dbName))
+		adminPool.Close()
+	})
+	return pool
+}
+
+func createUserWithPassword(t *testing.T, store *user.TenantUserStore, email, password string) user.User {
+	t.Helper()
+	ctx := context.Background()
+	u, err := store.Create(ctx, email, "Test User")
+	if err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+	hash, err := HashPassword(password)
+	if err != nil {
+		t.Fatalf("hash password: %v", err)
+	}
+	if err := store.SetPasswordHash(ctx, u.ID, hash); err != nil {
+		t.Fatalf("set password: %v", err)
+	}
+	return u
+}
+
+func TestLoginService_SuccessAndWrongPassword(t *testing.T) {
+	pool := setupTenantDB(t, "test_iam02_login")
+	store := user.NewTenantUserStore(pool)
+	createUserWithPassword(t, store, "alice@example.com", "korrektes-passwort")
+
+	issuer := NewTokenIssuer("test-secret-nur-fuer-tests")
+	login := NewLoginService(store, issuer, "acme")
+
+	token, err := login.Login(context.Background(), "alice@example.com", "korrektes-passwort")
+	if err != nil {
+		t.Fatalf("login: %v", err)
+	}
+	if token == "" {
+		t.Fatal("erwartet nicht-leeres token")
+	}
+
+	if _, err := login.Login(context.Background(), "alice@example.com", "falsches-passwort"); !errors.Is(err, ErrInvalidCredentials) {
+		t.Fatalf("erwartet ErrInvalidCredentials, habe %v", err)
+	}
+
+	if _, err := login.Login(context.Background(), "unbekannt@example.com", "irgendwas"); !errors.Is(err, ErrInvalidCredentials) {
+		t.Fatalf("erwartet ErrInvalidCredentials bei unbekannter email, habe %v", err)
+	}
+}
+
+// Pruefung 1: kein Cross-Tenant-Login moeglich, obwohl dieselbe E-Mail in
+// zwei unterschiedlichen Tenant-Datenbanken mit unterschiedlichen Passwoertern
+// existiert.
+func TestLoginService_NoCrossTenantLogin(t *testing.T) {
+	poolA := setupTenantDB(t, "test_iam02_tenant_a")
+	poolB := setupTenantDB(t, "test_iam02_tenant_b")
+
+	storeA := user.NewTenantUserStore(poolA)
+	storeB := user.NewTenantUserStore(poolB)
+	createUserWithPassword(t, storeA, "shared@example.com", "passwort-tenant-a")
+	createUserWithPassword(t, storeB, "shared@example.com", "passwort-tenant-b")
+
+	issuer := NewTokenIssuer("test-secret-nur-fuer-tests")
+	loginA := NewLoginService(storeA, issuer, "tenant-a")
+
+	// Login gegen Tenant A mit dem Passwort von Tenant B darf nicht klappen,
+	// obwohl die E-Mail-Adresse identisch ist — die Store-Instanz kennt
+	// strukturell nur die Zeilen ihrer eigenen Datenbank.
+	if _, err := loginA.Login(context.Background(), "shared@example.com", "passwort-tenant-b"); !errors.Is(err, ErrInvalidCredentials) {
+		t.Fatalf("erwartet ErrInvalidCredentials fuer fremdes tenant-passwort, habe %v", err)
+	}
+
+	token, err := loginA.Login(context.Background(), "shared@example.com", "passwort-tenant-a")
+	if err != nil {
+		t.Fatalf("login gegen eigenen tenant sollte klappen: %v", err)
+	}
+	claims, err := issuer.Verify(token)
+	if err != nil {
+		t.Fatalf("verify: %v", err)
+	}
+	if claims.TenantSlug != "tenant-a" {
+		t.Fatalf("token tenant = %q, want tenant-a", claims.TenantSlug)
+	}
+}
+
+// Akzeptanzkriterium 3: geschuetzte Route ohne gueltige Session nicht erreichbar.
+func TestRequireAuth_BlocksWithoutValidCookie(t *testing.T) {
+	issuer := NewTokenIssuer("test-secret-nur-fuer-tests")
+	protected := RequireAuth(issuer, func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	})
+
+	// Kein Cookie.
+	req := httptest.NewRequest(http.MethodGet, "/geschuetzt", nil)
+	rec := httptest.NewRecorder()
+	protected(rec, req)
+	if rec.Code != http.StatusUnauthorized {
+		t.Fatalf("ohne cookie: status = %d, want 401", rec.Code)
+	}
+
+	// Manipuliertes Cookie.
+	req = httptest.NewRequest(http.MethodGet, "/geschuetzt", nil)
+	req.AddCookie(&http.Cookie{Name: CookieName, Value: "kaputt.token.hier"})
+	rec = httptest.NewRecorder()
+	protected(rec, req)
+	if rec.Code != http.StatusUnauthorized {
+		t.Fatalf("mit kaputtem cookie: status = %d, want 401", rec.Code)
+	}
+
+	// Gueltiges Token.
+	token, err := issuer.Issue("user-1", "acme")
+	if err != nil {
+		t.Fatalf("issue: %v", err)
+	}
+	req = httptest.NewRequest(http.MethodGet, "/geschuetzt", nil)
+	req.AddCookie(&http.Cookie{Name: CookieName, Value: token})
+	rec = httptest.NewRecorder()
+	protected(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("mit gueltigem cookie: status = %d, want 200", rec.Code)
+	}
+}

internal/auth/middleware.go

@@ -0,0 +1,41 @@
+package auth
+
+import (
+	"context"
+	"net/http"
+)
+
+const CookieName = "nexarch_session"
+
+type contextKey int
+
+const claimsContextKey contextKey = iota
+
+// RequireAuth schuetzt eine Route: ohne gueltiges, nicht abgelaufenes Token
+// im Session-Cookie wird 401 zurueckgegeben und der Handler nicht aufgerufen
+// (IAM-02 Akzeptanzkriterium 3).
+func RequireAuth(issuer *TokenIssuer, next http.HandlerFunc) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		cookie, err := r.Cookie(CookieName)
+		if err != nil {
+			http.Error(w, "nicht angemeldet", http.StatusUnauthorized)
+			return
+		}
+
+		claims, err := issuer.Verify(cookie.Value)
+		if err != nil {
+			http.Error(w, "nicht angemeldet", http.StatusUnauthorized)
+			return
+		}
+
+		ctx := context.WithValue(r.Context(), claimsContextKey, claims)
+		next(w, r.WithContext(ctx))
+	}
+}
+
+// ClaimsFromContext liest die Claims, die RequireAuth in den Request-Context
+// gelegt hat.
+func ClaimsFromContext(ctx context.Context) (*Claims, bool) {
+	c, ok := ctx.Value(claimsContextKey).(*Claims)
+	return c, ok
+}

internal/auth/password.go

@@ -0,0 +1,28 @@
+// Package auth implementiert Core IAM-02: Login/Logout, Passwort-Hashing und
+// die Middleware zum Schutz von Routen. Autorisierung (was ein Benutzer darf)
+// ist ausdruecklich NICHT Teil dieses Pakets, siehe RBAC-01 — auth prueft nur
+// "wer bin ich" (Casbin-Architekturprinzip, siehe IAM-02-Ticket).
+package auth
+
+import "golang.org/x/crypto/bcrypt"
+
+// BcryptCost ist bewusst explizit festgelegt statt bcrypt.DefaultCost (10)
+// unreflektiert zu uebernehmen (IAM-02 Akzeptanzkriterium 4). Kostenfaktor 12
+// wurde gegen die Ziel-Login-Latenz benchmarkt, siehe password_bench_test.go
+// und den Pruefungs-Eintrag in der Commit-Nachricht.
+const BcryptCost = 12
+
+func HashPassword(plain string) (string, error) {
+	hash, err := bcrypt.GenerateFromPassword([]byte(plain), BcryptCost)
+	if err != nil {
+		return "", err
+	}
+	return string(hash), nil
+}
+
+// VerifyPassword ist timing-safe: bcrypt.CompareHashAndPassword vergleicht
+// konstant in der Zeit bzgl. des Hash-Inhalts (Referenzimplementierung fuer
+// die projektweite Timing-safe-Vergleich-Konvention aus IAM-02).
+func VerifyPassword(hash, plain string) bool {
+	return bcrypt.CompareHashAndPassword([]byte(hash), []byte(plain)) == nil
+}

internal/auth/password_bench_test.go

@@ -0,0 +1,42 @@
+package auth
+
+import (
+	"testing"
+	"time"
+)
+
+// TargetLoginLatency ist der Zielwert aus IAM-02 Akzeptanzkriterium 4: der
+// bcrypt-Vergleich allein darf die Login-Latenz nicht dominieren. 400ms ist
+// grosszuegig genug, um auf unterschiedlicher Hardware stabil zu sein, aber
+// eng genug, um eine versehentliche Kostenfaktor-Explosion (z.B. 16 statt 12)
+// zuverlaessig aufzudecken.
+const TargetLoginLatency = 400 * time.Millisecond
+
+// TestBcryptCostAgainstLatencyTarget misst die tatsaechliche Dauer eines
+// Passwort-Vergleichs mit dem festgelegten BcryptCost und dokumentiert das
+// Ergebnis (IAM-02 Pruefung 4).
+func TestBcryptCostAgainstLatencyTarget(t *testing.T) {
+	hash, err := HashPassword("benchmark-passwort")
+	if err != nil {
+		t.Fatalf("hash: %v", err)
+	}
+
+	start := time.Now()
+	if !VerifyPassword(hash, "benchmark-passwort") {
+		t.Fatal("verifikation haette erfolgreich sein muessen")
+	}
+	elapsed := time.Since(start)
+
+	t.Logf("bcrypt-vergleich mit cost=%d dauerte %s (ziel: unter %s)", BcryptCost, elapsed, TargetLoginLatency)
+	if elapsed > TargetLoginLatency {
+		t.Fatalf("bcrypt-vergleich zu langsam: %s > ziel %s", elapsed, TargetLoginLatency)
+	}
+}
+
+func BenchmarkVerifyPassword(b *testing.B) {
+	hash, _ := HashPassword("benchmark-passwort")
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		VerifyPassword(hash, "benchmark-passwort")
+	}
+}

internal/auth/password_test.go

@@ -0,0 +1,28 @@
+package auth
+
+import "testing"
+
+func TestHashAndVerifyPassword(t *testing.T) {
+	hash, err := HashPassword("s3hr-geheim!")
+	if err != nil {
+		t.Fatalf("hash: %v", err)
+	}
+	if hash == "s3hr-geheim!" {
+		t.Fatal("passwort wurde nicht gehasht")
+	}
+	if !VerifyPassword(hash, "s3hr-geheim!") {
+		t.Fatal("erwartet erfolgreiche verifikation")
+	}
+	if VerifyPassword(hash, "falsches-passwort") {
+		t.Fatal("erwartet fehlgeschlagene verifikation")
+	}
+}
+
+func TestDummyHashIsValidBcryptHash(t *testing.T) {
+	// Stellt sicher, dass der Timing-Angleichs-Hash in login.go tatsaechlich
+	// ein gueltiges bcrypt-Format hat und den vollen Kostenfaktor durchlaeuft
+	// (siehe Kommentar dort) statt sofort mit einem Format-Fehler abzubrechen.
+	if VerifyPassword(dummyHash, "irgendein-text") {
+		t.Fatal("dummyHash sollte fuer beliebigen text nicht passen")
+	}
+}

internal/auth/token.go

@@ -0,0 +1,63 @@
+package auth
+
+import (
+	"errors"
+	"time"
+
+	"github.com/golang-jwt/jwt/v5"
+)
+
+// AccessTokenTTL ist bewusst kurz gehalten (Session-Ablauf statt langlebiger
+// Tokens), passend zur "so vertrauenswuerdig wie noetig"-Produkt-DNA.
+const AccessTokenTTL = 30 * time.Minute
+
+var ErrInvalidToken = errors.New("auth: ungueltiges oder abgelaufenes token")
+
+type Claims struct {
+	UserID     string `json:"uid"`
+	TenantSlug string `json:"tenant"`
+	jwt.RegisteredClaims
+}
+
+// TokenIssuer signiert/verifiziert JWTs mit einem HMAC-Secret. Das
+// asymmetrische Core-weite Signaturschema (API-05, kid-Rotation) ist
+// ausdruecklich nicht Teil dieser Kachel — hier geht es nur um das
+// Login-Grundgerüst innerhalb eines einzelnen Core-Prozesses.
+type TokenIssuer struct {
+	secret []byte
+}
+
+func NewTokenIssuer(secret string) *TokenIssuer {
+	return &TokenIssuer{secret: []byte(secret)}
+}
+
+func (i *TokenIssuer) Issue(userID, tenantSlug string) (string, error) {
+	now := time.Now()
+	claims := Claims{
+		UserID:     userID,
+		TenantSlug: tenantSlug,
+		RegisteredClaims: jwt.RegisteredClaims{
+			IssuedAt:  jwt.NewNumericDate(now),
+			ExpiresAt: jwt.NewNumericDate(now.Add(AccessTokenTTL)),
+		},
+	}
+	token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
+	return token.SignedString(i.secret)
+}
+
+// Verify prueft Signatur UND Ablauf (jwt.ParseWithClaims lehnt abgelaufene
+// Tokens automatisch ab) — der Signaturvergleich in golang-jwt ist
+// timing-safe (hmac.Equal).
+func (i *TokenIssuer) Verify(tokenString string) (*Claims, error) {
+	claims := &Claims{}
+	token, err := jwt.ParseWithClaims(tokenString, claims, func(t *jwt.Token) (interface{}, error) {
+		if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok {
+			return nil, ErrInvalidToken
+		}
+		return i.secret, nil
+	})
+	if err != nil || !token.Valid {
+		return nil, ErrInvalidToken
+	}
+	return claims, nil
+}

internal/auth/token_test.go

@@ -0,0 +1,82 @@
+package auth
+
+import (
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/golang-jwt/jwt/v5"
+)
+
+func TestTokenIssueAndVerify(t *testing.T) {
+	issuer := NewTokenIssuer("test-secret-nur-fuer-tests")
+
+	token, err := issuer.Issue("user-1", "acme")
+	if err != nil {
+		t.Fatalf("issue: %v", err)
+	}
+
+	claims, err := issuer.Verify(token)
+	if err != nil {
+		t.Fatalf("verify: %v", err)
+	}
+	if claims.UserID != "user-1" || claims.TenantSlug != "acme" {
+		t.Fatalf("claims unerwartet: %+v", claims)
+	}
+}
+
+// Pruefung 2: Token-Manipulationstest.
+func TestTokenVerify_RejectsManipulatedPayload(t *testing.T) {
+	issuer := NewTokenIssuer("test-secret-nur-fuer-tests")
+	token, err := issuer.Issue("user-1", "acme")
+	if err != nil {
+		t.Fatalf("issue: %v", err)
+	}
+
+	parts := strings.Split(token, ".")
+	if len(parts) != 3 {
+		t.Fatalf("unerwartetes token-format: %d teile", len(parts))
+	}
+	// Payload-Segment leicht veraendern (Signatur passt danach nicht mehr).
+	tampered := parts[0] + "." + parts[1] + "x" + "." + parts[2]
+
+	if _, err := issuer.Verify(tampered); err == nil {
+		t.Fatal("erwartet fehler bei manipuliertem token, habe nil")
+	}
+}
+
+func TestTokenVerify_RejectsWrongSecret(t *testing.T) {
+	issuer := NewTokenIssuer("secret-a")
+	other := NewTokenIssuer("secret-b")
+
+	token, err := issuer.Issue("user-1", "acme")
+	if err != nil {
+		t.Fatalf("issue: %v", err)
+	}
+	if _, err := other.Verify(token); err == nil {
+		t.Fatal("erwartet fehler bei falschem secret, habe nil")
+	}
+}
+
+// Pruefung 3: abgelaufenes Token erzwingt Neuanmeldung.
+func TestTokenVerify_RejectsExpiredToken(t *testing.T) {
+	issuer := NewTokenIssuer("test-secret-nur-fuer-tests")
+
+	claims := Claims{
+		UserID:     "user-1",
+		TenantSlug: "acme",
+		RegisteredClaims: jwt.RegisteredClaims{
+			IssuedAt:  jwt.NewNumericDate(time.Now().Add(-2 * AccessTokenTTL)),
+			ExpiresAt: jwt.NewNumericDate(time.Now().Add(-time.Minute)),
+		},
+	}
+	tok := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
+	expired, err := tok.SignedString([]byte("test-secret-nur-fuer-tests"))
+	if err != nil {
+		t.Fatalf("signieren: %v", err)
+	}
+
+	if _, err := issuer.Verify(expired); err == nil {
+		t.Fatal("erwartet fehler bei abgelaufenem token, habe nil")
+	}
+}

internal/flag/flag.go

@@ -1,87 +0,0 @@
-// Package flag implementiert Core LIC-02: einen Feature-Flag-Dienst mit
-// Strategien (global an/aus, Prozentsatz, Tenant-Zielgruppe) als Kernfunktion
-// des Core-Dienstes selbst — keine zusaetzliche Infrastruktur (Unleash-Server
-// + eigene DB), siehe "bewusst vermeiden" im LIC-02-Ticket.
-package flag
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"hash/fnv"
-
-	"github.com/jackc/pgx/v5"
-	"github.com/jackc/pgx/v5/pgxpool"
-)
-
-var ErrNotFound = errors.New("flag: nicht gefunden")
-
-// Flag ist die zentrale Definition — Auswertung (Evaluate) ist bewusst davon
-// getrennt (Unleash-Prinzip: Flag-Verwaltung vs. Flag-Auswertung).
-type Flag struct {
-	Key               string
-	Enabled           bool
-	RolloutPercentage int
-	TargetTenantSlugs []string
-}
-
-// Store ist die Verwaltungsseite (Admin): Flags definieren/lesen.
-type Store struct {
-	pool *pgxpool.Pool
-}
-
-func NewStore(pool *pgxpool.Pool) *Store {
-	return &Store{pool: pool}
-}
-
-func (s *Store) Set(ctx context.Context, f Flag) error {
-	if f.TargetTenantSlugs == nil {
-		f.TargetTenantSlugs = []string{} // pgx uebertraegt ein nil-Slice sonst als SQL NULL statt leerem Array.
-	}
-	_, err := s.pool.Exec(ctx, `
-		INSERT INTO feature_flags (key, enabled, rollout_percentage, target_tenant_slugs, updated_at)
-		VALUES ($1, $2, $3, $4, now())
-		ON CONFLICT (key) DO UPDATE SET
-			enabled = $2, rollout_percentage = $3, target_tenant_slugs = $4, updated_at = now()
-	`, f.Key, f.Enabled, f.RolloutPercentage, f.TargetTenantSlugs)
-	if err != nil {
-		return fmt.Errorf("flag speichern: %w", err)
-	}
-	return nil
-}
-
-func (s *Store) Get(ctx context.Context, key string) (Flag, error) {
-	var f Flag
-	row := s.pool.QueryRow(ctx, `
-		SELECT key, enabled, rollout_percentage, target_tenant_slugs
-		FROM feature_flags WHERE key = $1
-	`, key)
-	if err := row.Scan(&f.Key, &f.Enabled, &f.RolloutPercentage, &f.TargetTenantSlugs); err != nil {
-		if errors.Is(err, pgx.ErrNoRows) {
-			return Flag{}, ErrNotFound
-		}
-		return Flag{}, fmt.Errorf("flag lesen: %w", err)
-	}
-	return f, nil
-}
-
-// evaluate wendet die Strategien in fester Reihenfolge an: globaler
-// An/Aus-Schalter zuerst, dann Tenant-Zielgruppe, dann Prozentsatz-Rollout.
-// Ein unbekannter/nicht getroffener Fall ergibt false — Fail-Safe-Default,
-// kein Feature wird versehentlich aktiv.
-func evaluate(f Flag, tenantSlug string) bool {
-	if f.Enabled {
-		return true
-	}
-	for _, target := range f.TargetTenantSlugs {
-		if target == tenantSlug {
-			return true
-		}
-	}
-	if f.RolloutPercentage > 0 {
-		h := fnv.New32a()
-		_, _ = h.Write([]byte(f.Key + "|" + tenantSlug))
-		return int(h.Sum32()%100) < f.RolloutPercentage
-	}
-	return false
-}

internal/flag/flag_test.go

@@ -1,43 +0,0 @@
-package flag
-
-import "testing"
-
-func TestEvaluate_GlobalEnabled(t *testing.T) {
-	f := Flag{Key: "k", Enabled: true}
-	if !evaluate(f, "irgendein-tenant") {
-		t.Fatal("global aktiviertes flag sollte fuer jeden tenant true liefern")
-	}
-}
-
-// Akzeptanzkriterium 1 + Pruefung 2: Zielgruppen-Strategie.
-func TestEvaluate_TargetTenantStrategy(t *testing.T) {
-	f := Flag{Key: "k", Enabled: false, TargetTenantSlugs: []string{"acme"}}
-	if !evaluate(f, "acme") {
-		t.Fatal("erwartet true fuer tenant in zielgruppe")
-	}
-	if evaluate(f, "globex") {
-		t.Fatal("erwartet false fuer tenant ausserhalb der zielgruppe")
-	}
-}
-
-func TestEvaluate_RolloutPercentageBoundaries(t *testing.T) {
-	full := Flag{Key: "k", RolloutPercentage: 100}
-	if !evaluate(full, "beliebiger-tenant-1") || !evaluate(full, "beliebiger-tenant-2") {
-		t.Fatal("100% rollout sollte immer true liefern")
-	}
-
-	none := Flag{Key: "k", RolloutPercentage: 0}
-	if evaluate(none, "beliebiger-tenant") {
-		t.Fatal("0% rollout ohne enabled/zielgruppe sollte false liefern")
-	}
-}
-
-func TestEvaluate_RolloutIsDeterministicPerTenant(t *testing.T) {
-	f := Flag{Key: "k", RolloutPercentage: 50}
-	first := evaluate(f, "stabiler-tenant")
-	for i := 0; i < 5; i++ {
-		if evaluate(f, "stabiler-tenant") != first {
-			t.Fatal("rollout-auswertung sollte fuer denselben tenant/key stabil sein")
-		}
-	}
-}

internal/flag/service.go

@@ -1,87 +0,0 @@
-package flag
-
-import (
-	"context"
-	"log/slog"
-	"sync"
-	"time"
-)
-
-// DefaultCacheTTL ist die dokumentierte Cache-Invalidierungszeit
-// (Akzeptanzkriterium 2/3): eine Aenderung wirkt spaetestens nach dieser
-// Zeit auf allen Core-Instanzen, ohne dass ein Dienst neu gestartet werden
-// muss (Akzeptanzkriterium 3).
-const DefaultCacheTTL = 5 * time.Second
-
-type cacheEntry struct {
-	flag      Flag
-	expiresAt time.Time
-}
-
-// Service ist die Auswertungsseite (SDK/Client-Analogon zu Unleash) mit
-// lokalem TTL-Cache. Bewusst getrennt von Store (Verwaltung).
-type Service struct {
-	store *Store
-	ttl   time.Duration
-
-	mu    sync.RWMutex
-	cache map[string]cacheEntry
-}
-
-func NewService(store *Store, ttl time.Duration) *Service {
-	if ttl <= 0 {
-		ttl = DefaultCacheTTL
-	}
-	return &Service{store: store, ttl: ttl, cache: make(map[string]cacheEntry)}
-}
-
-// IsEnabled wertet ein Flag fuer einen Tenant aus. Liefert IMMER einen
-// bool ohne Fehlerwert — ein nicht erreichbarer Flag-Dienst darf abhaengige
-// Aufrufer nicht zum Absturz bringen oder zu Fehlerbehandlungscode zwingen,
-// der leicht vergessen wird (Akzeptanzkriterium 3 / Pruefung 3: dokumentiertes
-// Fallback-Verhalten = false, ggf. aus dem zuletzt bekannten Zwischenspeicher).
-func (s *Service) IsEnabled(ctx context.Context, tenantSlug, key string) bool {
-	f, ok := s.resolve(ctx, key)
-	if !ok {
-		return false
-	}
-	return evaluate(f, tenantSlug)
-}
-
-func (s *Service) resolve(ctx context.Context, key string) (Flag, bool) {
-	s.mu.RLock()
-	entry, exists := s.cache[key]
-	fresh := exists && time.Now().Before(entry.expiresAt)
-	s.mu.RUnlock()
-	if fresh {
-		return entry.flag, true
-	}
-
-	f, err := s.store.Get(ctx, key)
-	if err != nil {
-		if exists {
-			slog.Warn("feature-flag-dienst nicht erreichbar, nutze zwischengespeicherten stand",
-				"flag_key", key, "error", err)
-			return entry.flag, true
-		}
-		slog.Warn("feature-flag-dienst nicht erreichbar, kein zwischengespeicherter stand vorhanden, fallback: deaktiviert",
-			"flag_key", key, "error", err)
-		return Flag{}, false
-	}
-
-	s.mu.Lock()
-	s.cache[key] = cacheEntry{flag: f, expiresAt: time.Now().Add(s.ttl)}
-	s.mu.Unlock()
-	return f, true
-}
-
-// Invalidate erzwingt beim naechsten IsEnabled-Aufruf ein sofortiges Neuladen
-// aus der Datenbank statt auf den TTL-Ablauf zu warten — wird nach Store.Set
-// auf derselben Instanz aufgerufen, damit der Schreiber die eigene Aenderung
-// ohne Wartezeit sieht. Andere Core-Instanzen sehen sie spaetestens nach
-// DefaultCacheTTL (siehe Akzeptanzkriterium 3).
-func (s *Service) Invalidate(key string) {
-	s.mu.Lock()
-	delete(s.cache, key)
-	s.mu.Unlock()
-}

internal/flag/service_test.go

@@ -1,179 +0,0 @@
-package flag
-
-import (
-	"context"
-	"os"
-	"testing"
-	"time"
-
-	"github.com/jackc/pgx/v5/pgxpool"
-)
-
-func setupFlagStoreTest(t *testing.T) (*Store, func()) {
-	t.Helper()
-	adminDSN := os.Getenv("TEST_ADMIN_DSN")
-	if adminDSN == "" {
-		t.Skip("TEST_ADMIN_DSN nicht gesetzt, Integrationstest uebersprungen")
-	}
-	ctx := context.Background()
-
-	pool, err := pgxpool.New(ctx, adminDSN)
-	if err != nil {
-		t.Fatalf("pool: %v", err)
-	}
-	if _, err := pool.Exec(ctx, `
-		CREATE TABLE IF NOT EXISTS feature_flags (
-			key TEXT PRIMARY KEY,
-			enabled BOOLEAN NOT NULL DEFAULT false,
-			rollout_percentage INT NOT NULL DEFAULT 0,
-			target_tenant_slugs TEXT[] NOT NULL DEFAULT '{}',
-			updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
-		)`); err != nil {
-		t.Fatalf("schema: %v", err)
-	}
-
-	cleanup := func() {
-		_, _ = pool.Exec(ctx, `DELETE FROM feature_flags WHERE key LIKE 'test\_%' ESCAPE '\'`)
-		pool.Close()
-	}
-	return NewStore(pool), cleanup
-}
-
-// Akzeptanzkriterium 1 + Pruefung 2: Zielgruppen-Strategie liefert im Test
-// die erwartete Auswertung.
-func TestService_TargetTenantStrategy(t *testing.T) {
-	store, cleanup := setupFlagStoreTest(t)
-	defer cleanup()
-	ctx := context.Background()
-
-	if err := store.Set(ctx, Flag{Key: "test_target_flag", TargetTenantSlugs: []string{"acme"}}); err != nil {
-		t.Fatalf("set: %v", err)
-	}
-	svc := NewService(store, time.Hour)
-
-	if !svc.IsEnabled(ctx, "acme", "test_target_flag") {
-		t.Fatal("erwartet true fuer tenant in zielgruppe")
-	}
-	if svc.IsEnabled(ctx, "globex", "test_target_flag") {
-		t.Fatal("erwartet false fuer tenant ausserhalb der zielgruppe")
-	}
-}
-
-// Akzeptanzkriterium 2 + 3 + Pruefung 1: Flag-Aenderung wirkt innerhalb der
-// dokumentierten Cache-Invalidierungszeit, automatisiert gemessen.
-func TestService_CacheInvalidationTiming(t *testing.T) {
-	store, cleanup := setupFlagStoreTest(t)
-	defer cleanup()
-	ctx := context.Background()
-
-	const ttl = 150 * time.Millisecond
-	if err := store.Set(ctx, Flag{Key: "test_ttl_flag", Enabled: false}); err != nil {
-		t.Fatalf("set: %v", err)
-	}
-	svc := NewService(store, ttl)
-
-	if svc.IsEnabled(ctx, "acme", "test_ttl_flag") {
-		t.Fatal("erwartet false vor der aenderung")
-	}
-
-	// Aenderung "auf einer anderen instanz" simulieren: direkt ueber den
-	// Store, ohne svc.Invalidate aufzurufen.
-	changedAt := time.Now()
-	if err := store.Set(ctx, Flag{Key: "test_ttl_flag", Enabled: true}); err != nil {
-		t.Fatalf("set: %v", err)
-	}
-
-	// Sofort danach sollte der Cache noch den alten Stand liefern.
-	if svc.IsEnabled(ctx, "acme", "test_ttl_flag") {
-		t.Fatal("cache haette den alten (false) stand liefern sollen, direkt nach der aenderung")
-	}
-
-	deadline := changedAt.Add(ttl + 100*time.Millisecond)
-	for time.Now().Before(deadline) {
-		if svc.IsEnabled(ctx, "acme", "test_ttl_flag") {
-			elapsed := time.Since(changedAt)
-			t.Logf("aenderung wurde nach %s wirksam (ziel: innerhalb %s + toleranz)", elapsed, ttl)
-			return
-		}
-		time.Sleep(10 * time.Millisecond)
-	}
-	t.Fatalf("aenderung wurde nicht innerhalb von %s wirksam", deadline.Sub(changedAt))
-}
-
-func TestService_InvalidateForcesImmediateRefresh(t *testing.T) {
-	store, cleanup := setupFlagStoreTest(t)
-	defer cleanup()
-	ctx := context.Background()
-
-	if err := store.Set(ctx, Flag{Key: "test_invalidate_flag", Enabled: false}); err != nil {
-		t.Fatalf("set: %v", err)
-	}
-	svc := NewService(store, time.Hour) // lange TTL, damit Invalidate den unterschied macht
-	_ = svc.IsEnabled(ctx, "acme", "test_invalidate_flag")
-
-	if err := store.Set(ctx, Flag{Key: "test_invalidate_flag", Enabled: true}); err != nil {
-		t.Fatalf("set: %v", err)
-	}
-	svc.Invalidate("test_invalidate_flag")
-
-	if !svc.IsEnabled(ctx, "acme", "test_invalidate_flag") {
-		t.Fatal("erwartet sofort sichtbaren neuen stand nach Invalidate")
-	}
-}
-
-// Akzeptanzkriterium 3 + Pruefung 3: Ausfall des Flag-Dienstes fuehrt zu
-// dokumentiertem Fallback-Verhalten, nicht zum Absturz.
-func TestService_FallsBackOnStoreFailure(t *testing.T) {
-	store, cleanup := setupFlagStoreTest(t)
-	defer cleanup()
-	ctx := context.Background()
-
-	if err := store.Set(ctx, Flag{Key: "test_fallback_flag", Enabled: true}); err != nil {
-		t.Fatalf("set: %v", err)
-	}
-	svc := NewService(store, time.Hour)
-
-	// Cache vorwaermen, waehrend die DB noch erreichbar ist.
-	if !svc.IsEnabled(ctx, "acme", "test_fallback_flag") {
-		t.Fatal("erwartet true bei funktionierender db")
-	}
-
-	brokenPool, err := pgxpool.New(ctx, "postgresql://nonexistent-host-fuer-test:5432/x?connect_timeout=1")
-	if err != nil {
-		t.Fatalf("broken pool erstellen (sollte nicht sofort verbinden): %v", err)
-	}
-	brokenStore := NewStore(brokenPool)
-
-	svcWithCache := NewService(brokenStore, time.Nanosecond) // TTL sofort abgelaufen, erzwingt reload-versuch
-	svcWithCache.mu.Lock()
-	svcWithCache.cache["test_fallback_flag"] = cacheEntry{
-		flag:      Flag{Key: "test_fallback_flag", Enabled: true},
-		expiresAt: time.Now().Add(-time.Hour), // bereits abgelaufen
-	}
-	svcWithCache.mu.Unlock()
-
-	func() {
-		defer func() {
-			if r := recover(); r != nil {
-				t.Fatalf("IsEnabled hat gepanict statt einen fallback zu liefern: %v", r)
-			}
-		}()
-		if !svcWithCache.IsEnabled(ctx, "acme", "test_fallback_flag") {
-			t.Fatal("erwartet fallback auf zwischengespeicherten (true) stand bei db-ausfall")
-		}
-	}()
-
-	// Voellig frischer Dienst ohne jeglichen cache + kaputte db -> sicherer
-	// default false, kein absturz.
-	freshSvc := NewService(brokenStore, time.Hour)
-	func() {
-		defer func() {
-			if r := recover(); r != nil {
-				t.Fatalf("IsEnabled hat gepanict: %v", r)
-			}
-		}()
-		if freshSvc.IsEnabled(ctx, "acme", "test_fallback_flag") {
-			t.Fatal("erwartet fail-safe false ohne cache und mit kaputter db")
-		}
-	}()
-}

internal/moduleregistry/credentials.go

@@ -1,99 +0,0 @@
-package moduleregistry
-
-import (
-	"context"
-	"crypto/rand"
-	"crypto/sha256"
-	"crypto/subtle"
-	"encoding/hex"
-	"errors"
-	"fmt"
-
-	"github.com/jackc/pgx/v5"
-)
-
-var (
-	ErrModuleNotRegistered = errors.New("moduleregistry: modul muss vor provisionierung registriert sein")
-	ErrInvalidCredential   = errors.New("moduleregistry: ungueltiges oder fehlendes service-credential")
-)
-
-// Provision stellt ein Service-Credential (Client-ID + Secret) fuer eine
-// Modul-Instanz aus (Akzeptanzkriterium 4). Das Secret wird NUR beim
-// Ausstellen im Klartext zurueckgegeben, gespeichert wird ausschliesslich
-// dessen SHA-256-Hash.
-func (r *Registry) Provision(ctx context.Context, moduleName string) (clientID, secret string, err error) {
-	if _, err := r.Get(ctx, moduleName); err != nil {
-		if errors.Is(err, ErrModuleNotFound) {
-			return "", "", ErrModuleNotRegistered
-		}
-		return "", "", err
-	}
-
-	clientID, err = randomToken(16)
-	if err != nil {
-		return "", "", fmt.Errorf("client-id erzeugen: %w", err)
-	}
-	secret, err = randomToken(32)
-	if err != nil {
-		return "", "", fmt.Errorf("secret erzeugen: %w", err)
-	}
-	hash := hashSecret(secret)
-
-	_, err = r.pool.Exec(ctx, `
-		INSERT INTO module_credentials (module_name, client_id, secret_hash, issued_at)
-		VALUES ($1, $2, $3, now())
-		ON CONFLICT (module_name) DO UPDATE SET client_id = $2, secret_hash = $3, issued_at = now()
-	`, moduleName, clientID, hash)
-	if err != nil {
-		return "", "", fmt.Errorf("credential speichern: %w", err)
-	}
-	return clientID, secret, nil
-}
-
-// Authenticate prueft ein Service-Credential timing-safe (Referenzmuster
-// siehe AUD-02) — Aufrufe ohne gueltiges Credential werden abgelehnt
-// (Akzeptanzkriterium 4 / Pruefung 4).
-func (r *Registry) Authenticate(ctx context.Context, clientID, secret string) (moduleName string, ok bool, err error) {
-	if clientID == "" || secret == "" {
-		return "", false, nil
-	}
-
-	var storedHash []byte
-	err = r.pool.QueryRow(ctx, `
-		SELECT module_name, secret_hash FROM module_credentials WHERE client_id = $1
-	`, clientID).Scan(&moduleName, &storedHash)
-	if err != nil {
-		if errors.Is(err, pgx.ErrNoRows) {
-			return "", false, nil
-		}
-		return "", false, fmt.Errorf("credential lesen: %w", err)
-	}
-
-	if !timingSafeEqual(hashSecret(secret), storedHash) {
-		return "", false, nil
-	}
-	return moduleName, true, nil
-}
-
-func randomToken(n int) (string, error) {
-	buf := make([]byte, n)
-	if _, err := rand.Read(buf); err != nil {
-		return "", err
-	}
-	return hex.EncodeToString(buf), nil
-}
-
-func hashSecret(secret string) []byte {
-	sum := sha256.Sum256([]byte(secret))
-	return sum[:]
-}
-
-// timingSafeEqual folgt derselben Referenzimplementierung wie AUD-02
-// (subtle.ConstantTimeCompare) — projektweite Konvention fuer jeden
-// sicherheitsrelevanten Vergleich.
-func timingSafeEqual(a, b []byte) bool {
-	if len(a) != len(b) {
-		return false
-	}
-	return subtle.ConstantTimeCompare(a, b) == 1
-}

internal/moduleregistry/middleware.go

@@ -1,46 +0,0 @@
-package moduleregistry
-
-import "net/http"
-
-// RequireActiveModule weist Anfragen an ein nicht aktiviertes Modul ZENTRAL
-// ab, bevor der eigentliche Modul-Handler erreicht wird (Akzeptanzkriterium 2 /
-// Pruefung 1) — Casbin-Prinzip: Durchsetzung als Middleware statt verstreuter
-// Pruefungen in jedem Handler. tenantSlug/moduleName werden hier ueber
-// Query-Parameter gelesen (echte Extraktion aus JWT/Tenant-Kontext ist
-// API-05/TEN-06, nicht Teil dieser Kachel).
-func (r *Registry) RequireActiveModule(moduleName string, next http.HandlerFunc) http.HandlerFunc {
-	return func(w http.ResponseWriter, req *http.Request) {
-		tenantSlug := req.URL.Query().Get("tenant")
-		active, err := r.IsActive(req.Context(), tenantSlug, moduleName)
-		if err != nil {
-			http.Error(w, "aktivierungspruefung fehlgeschlagen", http.StatusInternalServerError)
-			return
-		}
-		if !active {
-			http.Error(w, "modul nicht aktiviert", http.StatusForbidden)
-			return
-		}
-		next(w, req)
-	}
-}
-
-// RequireServiceCredential authentifiziert eine Modul-Instanz ueber ihr
-// Service-Credential (X-Client-Id/X-Client-Secret-Header) BEVOR der
-// eigentliche Handler erreicht wird (Akzeptanzkriterium 4 / Pruefung 4).
-func (r *Registry) RequireServiceCredential(next http.HandlerFunc) http.HandlerFunc {
-	return func(w http.ResponseWriter, req *http.Request) {
-		clientID := req.Header.Get("X-Client-Id")
-		secret := req.Header.Get("X-Client-Secret")
-
-		_, ok, err := r.Authenticate(req.Context(), clientID, secret)
-		if err != nil {
-			http.Error(w, "authentifizierung fehlgeschlagen", http.StatusInternalServerError)
-			return
-		}
-		if !ok {
-			http.Error(w, ErrInvalidCredential.Error(), http.StatusUnauthorized)
-			return
-		}
-		next(w, req)
-	}
-}

internal/moduleregistry/registry.go

@@ -1,120 +0,0 @@
-// Package moduleregistry implementiert Core API-02: die Registry, in der
-// sich Fachmodule (DMS, Mail, weitere) mit Metadaten eintragen, gekoppelt an
-// die Aktivierungspruefung aus LIC-02 (Feature-Flags). Zusaetzlich
-// authentifiziert die Registry Modul-Instanzen selbst ueber ein bei
-// Provisionierung ausgestelltes Service-Credential.
-package moduleregistry
-
-import (
-	"context"
-	"errors"
-	"fmt"
-
-	"github.com/jackc/pgx/v5"
-	"github.com/jackc/pgx/v5/pgxpool"
-
-	"gitea.perlbach24.de/scripte/nexarch/internal/flag"
-)
-
-var (
-	ErrMissingName    = errors.New("moduleregistry: name darf nicht leer sein")
-	ErrMissingVersion = errors.New("moduleregistry: version darf nicht leer sein")
-	ErrModuleNotFound = errors.New("moduleregistry: modul nicht registriert")
-)
-
-type Module struct {
-	Name          string
-	Version       string
-	RequiredFlags []string
-}
-
-type Registry struct {
-	pool  *pgxpool.Pool
-	flags *flag.Service
-}
-
-func NewRegistry(pool *pgxpool.Pool, flags *flag.Service) *Registry {
-	return &Registry{pool: pool, flags: flags}
-}
-
-// Register traegt ein Modul mit Name, Version und benoetigten Feature-Flags
-// ein (Akzeptanzkriterium 1). Fehlende Pflichtangaben werden abgewiesen
-// (Akzeptanzkriterium 1 / Pruefung 2). Erneutes Register desselben Namens
-// aktualisiert Version/Flags (Redeploy-Fall).
-func (r *Registry) Register(ctx context.Context, name, version string, requiredFlags []string) (Module, error) {
-	if name == "" {
-		return Module{}, ErrMissingName
-	}
-	if version == "" {
-		return Module{}, ErrMissingVersion
-	}
-	if requiredFlags == nil {
-		requiredFlags = []string{}
-	}
-
-	_, err := r.pool.Exec(ctx, `
-		INSERT INTO modules (name, version, required_flags, registered_at)
-		VALUES ($1, $2, $3, now())
-		ON CONFLICT (name) DO UPDATE SET version = $2, required_flags = $3, registered_at = now()
-	`, name, version, requiredFlags)
-	if err != nil {
-		return Module{}, fmt.Errorf("modul registrieren: %w", err)
-	}
-	return Module{Name: name, Version: version, RequiredFlags: requiredFlags}, nil
-}
-
-func (r *Registry) Get(ctx context.Context, name string) (Module, error) {
-	var m Module
-	m.Name = name
-	err := r.pool.QueryRow(ctx, `
-		SELECT version, required_flags FROM modules WHERE name = $1
-	`, name).Scan(&m.Version, &m.RequiredFlags)
-	if err != nil {
-		if errors.Is(err, pgx.ErrNoRows) {
-			return Module{}, ErrModuleNotFound
-		}
-		return Module{}, fmt.Errorf("modul lesen: %w", err)
-	}
-	return m, nil
-}
-
-// List liefert alle registrierten Module (Akzeptanzkriterium 3: ueber API
-// abfragbar, z.B. fuer Statusseite/Lizenzoberflaeche).
-func (r *Registry) List(ctx context.Context) ([]Module, error) {
-	rows, err := r.pool.Query(ctx, `SELECT name, version, required_flags FROM modules ORDER BY name`)
-	if err != nil {
-		return nil, fmt.Errorf("module auflisten: %w", err)
-	}
-	defer rows.Close()
-
-	var out []Module
-	for rows.Next() {
-		var m Module
-		if err := rows.Scan(&m.Name, &m.Version, &m.RequiredFlags); err != nil {
-			return nil, fmt.Errorf("modul lesen: %w", err)
-		}
-		out = append(out, m)
-	}
-	return out, rows.Err()
-}
-
-// IsActive prueft, ob ein registriertes Modul fuer einen Tenant aktiviert
-// ist: registriert UND alle benoetigten Feature-Flags sind fuer diesen
-// Tenant aktiv (Akzeptanzkriterium 2). Ein nicht registriertes Modul gilt
-// immer als nicht aktiv.
-func (r *Registry) IsActive(ctx context.Context, tenantSlug, moduleName string) (bool, error) {
-	m, err := r.Get(ctx, moduleName)
-	if err != nil {
-		if errors.Is(err, ErrModuleNotFound) {
-			return false, nil
-		}
-		return false, err
-	}
-
-	for _, flagKey := range m.RequiredFlags {
-		if !r.flags.IsEnabled(ctx, tenantSlug, flagKey) {
-			return false, nil
-		}
-	}
-	return true, nil
-}

internal/moduleregistry/registry_test.go

@@ -1,304 +0,0 @@
-package moduleregistry
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"net/http"
-	"net/http/httptest"
-	"os"
-	"testing"
-	"time"
-
-	"github.com/jackc/pgx/v5/pgxpool"
-
-	"gitea.perlbach24.de/scripte/nexarch/internal/flag"
-)
-
-func setupTest(t *testing.T) (*Registry, *flag.Store, func()) {
-	t.Helper()
-	adminDSN := os.Getenv("TEST_ADMIN_DSN")
-	if adminDSN == "" {
-		t.Skip("TEST_ADMIN_DSN nicht gesetzt, Integrationstest uebersprungen")
-	}
-	ctx := context.Background()
-
-	pool, err := pgxpool.New(ctx, adminDSN)
-	if err != nil {
-		t.Fatalf("pool: %v", err)
-	}
-	if _, err := pool.Exec(ctx, `
-		CREATE TABLE IF NOT EXISTS feature_flags (
-			key TEXT PRIMARY KEY, enabled BOOLEAN NOT NULL DEFAULT false,
-			rollout_percentage INT NOT NULL DEFAULT 0, target_tenant_slugs TEXT[] NOT NULL DEFAULT '{}',
-			updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
-		);
-		CREATE TABLE IF NOT EXISTS modules (
-			name TEXT PRIMARY KEY, version TEXT NOT NULL CHECK (version <> ''),
-			required_flags TEXT[] NOT NULL DEFAULT '{}', registered_at TIMESTAMPTZ NOT NULL DEFAULT now()
-		);
-		CREATE TABLE IF NOT EXISTS module_credentials (
-			module_name TEXT PRIMARY KEY REFERENCES modules(name),
-			client_id TEXT NOT NULL UNIQUE, secret_hash BYTEA NOT NULL,
-			issued_at TIMESTAMPTZ NOT NULL DEFAULT now()
-		);
-	`); err != nil {
-		t.Fatalf("schema: %v", err)
-	}
-
-	flagStore := flag.NewStore(pool)
-	// Kurze TTL, damit Tests, die den Flag-Store direkt aendern (an
-	// Registry.IsActive vorbei), den neuen Stand ohne manuelles Invalidate
-	// zuverlaessig sehen.
-	flagService := flag.NewService(flagStore, 10*time.Millisecond)
-	registry := NewRegistry(pool, flagService)
-
-	cleanup := func() { pool.Close() }
-	return registry, flagStore, cleanup
-}
-
-func uniqueModuleName(t *testing.T) string {
-	return fmt.Sprintf("dms_%d", time.Now().UnixNano())
-}
-
-// Akzeptanzkriterium 1 + Pruefung 2: fehlende Pflichtangaben abgewiesen.
-func TestRegister_RejectsMissingFields(t *testing.T) {
-	registry, _, cleanup := setupTest(t)
-	defer cleanup()
-	ctx := context.Background()
-
-	if _, err := registry.Register(ctx, "", "1.0", nil); !errors.Is(err, ErrMissingName) {
-		t.Fatalf("erwartet ErrMissingName, habe %v", err)
-	}
-	if _, err := registry.Register(ctx, "dms", "", nil); !errors.Is(err, ErrMissingVersion) {
-		t.Fatalf("erwartet ErrMissingVersion, habe %v", err)
-	}
-}
-
-func TestRegister_AndGet(t *testing.T) {
-	registry, _, cleanup := setupTest(t)
-	defer cleanup()
-	ctx := context.Background()
-	name := uniqueModuleName(t)
-
-	m, err := registry.Register(ctx, name, "1.2.0", []string{"dms_enabled"})
-	if err != nil {
-		t.Fatalf("register: %v", err)
-	}
-	if m.Version != "1.2.0" || len(m.RequiredFlags) != 1 {
-		t.Fatalf("unerwartet: %+v", m)
-	}
-
-	got, err := registry.Get(ctx, name)
-	if err != nil {
-		t.Fatalf("get: %v", err)
-	}
-	if got.Version != "1.2.0" {
-		t.Fatalf("get version = %q", got.Version)
-	}
-}
-
-// Akzeptanzkriterium 2 + 3 + Pruefung 3: konsistente Daten nach
-// Aktivierung/Deaktivierung eines Moduls.
-func TestIsActive_ReflectsFlagStateConsistently(t *testing.T) {
-	registry, flagStore, cleanup := setupTest(t)
-	defer cleanup()
-	ctx := context.Background()
-	name := uniqueModuleName(t)
-	flagKey := name + "_enabled"
-
-	if _, err := registry.Register(ctx, name, "1.0", []string{flagKey}); err != nil {
-		t.Fatalf("register: %v", err)
-	}
-
-	active, err := registry.IsActive(ctx, "acme", name)
-	if err != nil {
-		t.Fatalf("is active (vor flag): %v", err)
-	}
-	if active {
-		t.Fatal("erwartet nicht aktiv, solange flag nicht gesetzt ist")
-	}
-
-	if err := flagStore.Set(ctx, flag.Flag{Key: flagKey, Enabled: true}); err != nil {
-		t.Fatalf("flag setzen: %v", err)
-	}
-	time.Sleep(20 * time.Millisecond) // TTL abwarten
-
-	active, err = registry.IsActive(ctx, "acme", name)
-	if err != nil {
-		t.Fatalf("is active (nach flag an): %v", err)
-	}
-	if !active {
-		t.Fatal("erwartet aktiv, nachdem flag aktiviert wurde")
-	}
-
-	if err := flagStore.Set(ctx, flag.Flag{Key: flagKey, Enabled: false}); err != nil {
-		t.Fatalf("flag zuruecksetzen: %v", err)
-	}
-	time.Sleep(20 * time.Millisecond) // TTL abwarten
-	active, err = registry.IsActive(ctx, "acme", name)
-	if err != nil {
-		t.Fatalf("is active (nach flag aus): %v", err)
-	}
-	if active {
-		t.Fatal("erwartet wieder nicht aktiv, nachdem flag deaktiviert wurde")
-	}
-}
-
-func TestIsActive_UnregisteredModuleIsNeverActive(t *testing.T) {
-	registry, _, cleanup := setupTest(t)
-	defer cleanup()
-	ctx := context.Background()
-
-	active, err := registry.IsActive(ctx, "acme", "nie-registriert")
-	if err != nil {
-		t.Fatalf("is active: %v", err)
-	}
-	if active {
-		t.Fatal("unregistriertes modul darf nie aktiv sein")
-	}
-}
-
-// Akzeptanzkriterium 2 + Pruefung 1: Anfrage an deaktiviertes Modul wird
-// zentral abgewiesen, BEVOR die Modul-Logik erreicht wird.
-func TestRequireActiveModule_BlocksBeforeHandler(t *testing.T) {
-	registry, flagStore, cleanup := setupTest(t)
-	defer cleanup()
-	ctx := context.Background()
-	name := uniqueModuleName(t)
-	flagKey := name + "_enabled"
-
-	if _, err := registry.Register(ctx, name, "1.0", []string{flagKey}); err != nil {
-		t.Fatalf("register: %v", err)
-	}
-
-	handlerReached := false
-	handler := registry.RequireActiveModule(name, func(w http.ResponseWriter, r *http.Request) {
-		handlerReached = true
-		w.WriteHeader(http.StatusOK)
-	})
-
-	req := httptest.NewRequest(http.MethodGet, "/modul?tenant=acme", nil)
-	rec := httptest.NewRecorder()
-	handler(rec, req)
-	if rec.Code != http.StatusForbidden {
-		t.Fatalf("status = %d, want 403", rec.Code)
-	}
-	if handlerReached {
-		t.Fatal("handler haette bei deaktiviertem modul NICHT erreicht werden duerfen")
-	}
-
-	if err := flagStore.Set(ctx, flag.Flag{Key: flagKey, Enabled: true}); err != nil {
-		t.Fatalf("flag setzen: %v", err)
-	}
-	req2 := httptest.NewRequest(http.MethodGet, "/modul?tenant=acme", nil)
-	rec2 := httptest.NewRecorder()
-	handler(rec2, req2)
-	if rec2.Code != http.StatusOK {
-		t.Fatalf("status nach aktivierung = %d, want 200", rec2.Code)
-	}
-	if !handlerReached {
-		t.Fatal("handler haette bei aktiviertem modul erreicht werden muessen")
-	}
-}
-
-// Akzeptanzkriterium 4 + Pruefung 4: gueltiges/ungueltiges Service-Credential.
-func TestProvisionAndAuthenticate(t *testing.T) {
-	registry, _, cleanup := setupTest(t)
-	defer cleanup()
-	ctx := context.Background()
-	name := uniqueModuleName(t)
-
-	if _, err := registry.Register(ctx, name, "1.0", nil); err != nil {
-		t.Fatalf("register: %v", err)
-	}
-
-	clientID, secret, err := registry.Provision(ctx, name)
-	if err != nil {
-		t.Fatalf("provision: %v", err)
-	}
-	if clientID == "" || secret == "" {
-		t.Fatal("erwartet nicht-leere client-id/secret")
-	}
-
-	moduleName, ok, err := registry.Authenticate(ctx, clientID, secret)
-	if err != nil {
-		t.Fatalf("authenticate (korrekt): %v", err)
-	}
-	if !ok || moduleName != name {
-		t.Fatalf("erwartet erfolgreiche authentifizierung fuer %q, habe ok=%v moduleName=%q", name, ok, moduleName)
-	}
-
-	_, ok, err = registry.Authenticate(ctx, clientID, "falsches-secret")
-	if err != nil {
-		t.Fatalf("authenticate (falsch): %v", err)
-	}
-	if ok {
-		t.Fatal("erwartet fehlschlag bei falschem secret")
-	}
-
-	_, ok, err = registry.Authenticate(ctx, "unbekannte-client-id", secret)
-	if err != nil {
-		t.Fatalf("authenticate (unbekannt): %v", err)
-	}
-	if ok {
-		t.Fatal("erwartet fehlschlag bei unbekannter client-id")
-	}
-}
-
-func TestProvision_RequiresRegisteredModule(t *testing.T) {
-	registry, _, cleanup := setupTest(t)
-	defer cleanup()
-	ctx := context.Background()
-
-	if _, _, err := registry.Provision(ctx, "nie-registriert"); !errors.Is(err, ErrModuleNotRegistered) {
-		t.Fatalf("erwartet ErrModuleNotRegistered, habe %v", err)
-	}
-}
-
-func TestRequireServiceCredential_RejectsInvalidAcceptsValid(t *testing.T) {
-	registry, _, cleanup := setupTest(t)
-	defer cleanup()
-	ctx := context.Background()
-	name := uniqueModuleName(t)
-
-	if _, err := registry.Register(ctx, name, "1.0", nil); err != nil {
-		t.Fatalf("register: %v", err)
-	}
-	clientID, secret, err := registry.Provision(ctx, name)
-	if err != nil {
-		t.Fatalf("provision: %v", err)
-	}
-
-	handler := registry.RequireServiceCredential(func(w http.ResponseWriter, r *http.Request) {
-		w.WriteHeader(http.StatusOK)
-	})
-
-	// Fehlendes Credential.
-	req := httptest.NewRequest(http.MethodPost, "/service-aufruf", nil)
-	rec := httptest.NewRecorder()
-	handler(rec, req)
-	if rec.Code != http.StatusUnauthorized {
-		t.Fatalf("ohne credential: status = %d, want 401", rec.Code)
-	}
-
-	// Falsches Secret.
-	req2 := httptest.NewRequest(http.MethodPost, "/service-aufruf", nil)
-	req2.Header.Set("X-Client-Id", clientID)
-	req2.Header.Set("X-Client-Secret", "falsch")
-	rec2 := httptest.NewRecorder()
-	handler(rec2, req2)
-	if rec2.Code != http.StatusUnauthorized {
-		t.Fatalf("falsches secret: status = %d, want 401", rec2.Code)
-	}
-
-	// Gueltiges Credential.
-	req3 := httptest.NewRequest(http.MethodPost, "/service-aufruf", nil)
-	req3.Header.Set("X-Client-Id", clientID)
-	req3.Header.Set("X-Client-Secret", secret)
-	rec3 := httptest.NewRecorder()
-	handler(rec3, req3)
-	if rec3.Code != http.StatusOK {
-		t.Fatalf("gueltiges credential: status = %d, want 200", rec3.Code)
-	}
-}

internal/moduletrust/cache.go

@@ -1,97 +0,0 @@
-package moduletrust
-
-import (
-	"context"
-	"fmt"
-	"sync"
-	"time"
-)
-
-// StaleCache ist der generische Rechte-/Feature-Flag-Cache-Kontrakt
-// (Akzeptanzkriterium 2): TTL-basiert, mit explizitem, benanntem Verhalten
-// bei abgelaufenem Cache waehrend Core nicht erreichbar ist.
-//
-//   - Get: FAIL-OPEN fuer Lesevorgaenge. Schlaegt der Refresh fehl, aber es
-//     gibt bereits einen (wenn auch abgelaufenen) Stand, wird dieser mit
-//     stale=true zurueckgegeben — Begruendung: ein bereits authentifiziertes
-//     Modul soll mit dem letztbekannten Stand weiterarbeiten koennen statt
-//     hart zu blockieren (siehe "Bekannte Fehler vermeiden" im Ticket).
-//     Existiert noch nie ein Stand, gibt es keinen sinnvollen Fallback —
-//     dann liefert auch Get einen Fehler.
-//   - RequireFresh: FAIL-CLOSED fuer sicherheitskritische Aktionen (z.B.
-//     ein komplett NEUER Login). Nutzt NIEMALS einen zwischengespeicherten
-//     Stand, ruft immer frisch ab — Begruendung: eine neue Vertrauens-
-//     entscheidung darf nicht auf veralteten Daten beruhen, auch wenn das
-//     bedeutet, dass die Aktion bei Core-Ausfall sichtbar fehlschlaegt statt
-//     unsicher "irgendwie" durchgelassen zu werden.
-//
-// LIC-02 (internal/flag.Service) implementiert bereits denselben Kontrakt
-// fuer Feature-Flags — StaleCache verallgemeinert dasselbe Muster fuer
-// JWT-Signaturschluessel, damit beide Faelle derselben dokumentierten
-// Policy folgen.
-type StaleCache[T any] struct {
-	mu        sync.RWMutex
-	value     T
-	hasValue  bool
-	fetchedAt time.Time
-	ttl       time.Duration
-	fetch     func(ctx context.Context) (T, error)
-}
-
-func NewStaleCache[T any](ttl time.Duration, fetch func(ctx context.Context) (T, error)) *StaleCache[T] {
-	return &StaleCache[T]{ttl: ttl, fetch: fetch}
-}
-
-// Get liefert den Cache-Wert. FAIL-OPEN: bei Refresh-Fehler wird ein
-// vorhandener, ggf. abgelaufener Stand zurueckgegeben (stale=true).
-func (c *StaleCache[T]) Get(ctx context.Context) (value T, stale bool, err error) {
-	c.mu.RLock()
-	fresh := c.hasValue && time.Since(c.fetchedAt) < c.ttl
-	if fresh {
-		v := c.value
-		c.mu.RUnlock()
-		return v, false, nil
-	}
-	c.mu.RUnlock()
-
-	newVal, fetchErr := c.fetch(ctx)
-	if fetchErr == nil {
-		c.mu.Lock()
-		c.value, c.hasValue, c.fetchedAt = newVal, true, time.Now()
-		c.mu.Unlock()
-		return newVal, false, nil
-	}
-
-	c.mu.RLock()
-	defer c.mu.RUnlock()
-	if c.hasValue {
-		return c.value, true, nil
-	}
-	var zero T
-	return zero, false, fmt.Errorf("cache leer und refresh fehlgeschlagen: %w", fetchErr)
-}
-
-// Invalidate erzwingt beim naechsten Get-Aufruf einen sofortigen Refresh
-// statt auf den TTL-Ablauf zu warten (API-06, Akzeptanzkriterium 1: ein
-// Health-Check-getriggerter Wiederanlauf soll den Cache SOFORT aktualisieren,
-// nicht die reguläre TTL abwarten) — rein additiv, aendert nichts an
-// Get/RequireFresh (dasselbe Muster wie internal/flag.Service.Invalidate).
-func (c *StaleCache[T]) Invalidate() {
-	c.mu.Lock()
-	c.hasValue = false
-	c.mu.Unlock()
-}
-
-// RequireFresh ruft IMMER frisch ab (FAIL-CLOSED) — fuer sicherheitskritische
-// Aktionen, die niemals auf einem zwischengespeicherten Stand basieren duerfen.
-func (c *StaleCache[T]) RequireFresh(ctx context.Context) (T, error) {
-	v, err := c.fetch(ctx)
-	if err != nil {
-		var zero T
-		return zero, fmt.Errorf("core nicht erreichbar, sicherheitskritische aktion abgelehnt: %w", err)
-	}
-	c.mu.Lock()
-	c.value, c.hasValue, c.fetchedAt = v, true, time.Now()
-	c.mu.Unlock()
-	return v, nil
-}

internal/moduletrust/issuer.go

@@ -1,79 +0,0 @@
-package moduletrust
-
-import (
-	"encoding/base64"
-	"encoding/json"
-	"fmt"
-	"net/http"
-	"time"
-
-	"github.com/golang-jwt/jwt/v5"
-)
-
-type Claims struct {
-	Subject    string `json:"sub"`
-	TenantSlug string `json:"tenant"`
-	jwt.RegisteredClaims
-}
-
-// Issue signiert ein Token mit dem aktuellen Signierschluessel und traegt
-// dessen KID im JWT-Header ein — der Verifier auf Modulseite waehlt darueber
-// den passenden oeffentlichen Schluessel aus PublicKeySet() aus.
-func (m *KeyManager) Issue(subject, tenantSlug string, ttl time.Duration) (string, error) {
-	key, err := m.SigningKey()
-	if err != nil {
-		return "", err
-	}
-
-	now := time.Now()
-	claims := Claims{
-		Subject:    subject,
-		TenantSlug: tenantSlug,
-		RegisteredClaims: jwt.RegisteredClaims{
-			IssuedAt:  jwt.NewNumericDate(now),
-			ExpiresAt: jwt.NewNumericDate(now.Add(ttl)),
-		},
-	}
-	token := jwt.NewWithClaims(jwt.SigningMethodEdDSA, claims)
-	token.Header["kid"] = key.KID
-	return token.SignedString(key.Private)
-}
-
-type jwksResponse struct {
-	Keys []jwksKey `json:"keys"`
-}
-
-type jwksKey struct {
-	Kid       string `json:"kid"`
-	PublicKey string `json:"public_key"` // base64 (raw Ed25519, 32 Byte)
-}
-
-// ServeJWKS liefert alle bekannten oeffentlichen Schluessel als JSON —
-// Module fragen dies periodisch ab (nicht pro Request), siehe Verifier.
-func (m *KeyManager) ServeJWKS(w http.ResponseWriter, r *http.Request) {
-	set := m.PublicKeySet()
-	resp := jwksResponse{Keys: make([]jwksKey, 0, len(set))}
-	for kid, pub := range set {
-		resp.Keys = append(resp.Keys, jwksKey{Kid: kid, PublicKey: base64.StdEncoding.EncodeToString(pub)})
-	}
-	w.Header().Set("Content-Type", "application/json")
-	_ = json.NewEncoder(w).Encode(resp)
-}
-
-// ParseJWKS dekodiert die JSON-Antwort von ServeJWKS zurueck in kid->PublicKey
-// — Hilfsfunktion fuer Module, die JWKS per HTTP abrufen.
-func ParseJWKS(data []byte) (map[string][]byte, error) {
-	var resp jwksResponse
-	if err := json.Unmarshal(data, &resp); err != nil {
-		return nil, fmt.Errorf("jwks parsen: %w", err)
-	}
-	out := make(map[string][]byte, len(resp.Keys))
-	for _, k := range resp.Keys {
-		raw, err := base64.StdEncoding.DecodeString(k.PublicKey)
-		if err != nil {
-			return nil, fmt.Errorf("oeffentlichen schluessel %q dekodieren: %w", k.Kid, err)
-		}
-		out[k.Kid] = raw
-	}
-	return out, nil
-}

internal/moduletrust/keys.go

@@ -1,83 +0,0 @@
-// Package moduletrust implementiert Core API-05: asymmetrische JWT-Signatur
-// mit Schluesselverteilung (JWKS), damit DMS/Mail/Archive/Workflow JWTs
-// LOKAL verifizieren koennen, ohne pro Aufruf einen synchronen Request an
-// Core zu stellen — Core darf Fundament sein, ohne zum Flaschenhals zu
-// werden (siehe Entscheidungsverlauf "Vertrauensstellung Core<->Module" in
-// nexarch-state.json). IAM-02s HS256-Session-Cookie (Browser-Login) bleibt
-// unangetastet — dies ist ein zusaetzlicher, getrennter Vertrauensmechanismus
-// fuer Modul-zu-Modul/Modul-zu-Core-Aufrufe.
-package moduletrust
-
-import (
-	"crypto/ed25519"
-	"crypto/rand"
-	"encoding/hex"
-	"fmt"
-	"sync"
-)
-
-type KeyPair struct {
-	KID     string
-	Private ed25519.PrivateKey
-	Public  ed25519.PublicKey
-}
-
-// KeyManager haelt ALLE noch gueltigen Schluesselpaare — nicht nur das
-// aktuell signierende. Rotate erzeugt ein neues Paar und behaelt die alten
-// fuer die Verifikation bereits ausgestellter Tokens (Akzeptanzkriterium 3:
-// Rotation ohne Ausfallzeit fuer andere Module).
-type KeyManager struct {
-	mu   sync.RWMutex
-	keys []KeyPair // aeltestes zuerst, neuestes zuletzt
-}
-
-func NewKeyManager() (*KeyManager, error) {
-	m := &KeyManager{}
-	if _, err := m.Rotate(); err != nil {
-		return nil, err
-	}
-	return m, nil
-}
-
-// Rotate erzeugt ein neues Ed25519-Schluesselpaar mit eigener KID und macht
-// es zum aktuellen Signierschluessel. Aeltere Schluessel bleiben in
-// PublicKeySet() erhalten, damit bereits ausgestellte Tokens weiterhin
-// verifizierbar sind.
-func (m *KeyManager) Rotate() (KeyPair, error) {
-	pub, priv, err := ed25519.GenerateKey(nil)
-	if err != nil {
-		return KeyPair{}, fmt.Errorf("schluesselpaar erzeugen: %w", err)
-	}
-	kidBytes := make([]byte, 8)
-	if _, err := rand.Read(kidBytes); err != nil {
-		return KeyPair{}, fmt.Errorf("kid erzeugen: %w", err)
-	}
-	kp := KeyPair{KID: hex.EncodeToString(kidBytes), Private: priv, Public: pub}
-
-	m.mu.Lock()
-	m.keys = append(m.keys, kp)
-	m.mu.Unlock()
-	return kp, nil
-}
-
-// SigningKey liefert den aktuellen (neuesten) Schluessel zum Signieren neuer Tokens.
-func (m *KeyManager) SigningKey() (KeyPair, error) {
-	m.mu.RLock()
-	defer m.mu.RUnlock()
-	if len(m.keys) == 0 {
-		return KeyPair{}, fmt.Errorf("moduletrust: kein schluessel vorhanden")
-	}
-	return m.keys[len(m.keys)-1], nil
-}
-
-// PublicKeySet liefert ALLE bekannten oeffentlichen Schluessel (kid ->
-// public key) — die Grundlage fuer den JWKS-Endpunkt.
-func (m *KeyManager) PublicKeySet() map[string]ed25519.PublicKey {
-	m.mu.RLock()
-	defer m.mu.RUnlock()
-	out := make(map[string]ed25519.PublicKey, len(m.keys))
-	for _, k := range m.keys {
-		out[k.KID] = k.Public
-	}
-	return out
-}

internal/moduletrust/moduletrust_test.go

@@ -1,214 +0,0 @@
-package moduletrust
-
-import (
-	"context"
-	"crypto/ed25519"
-	"errors"
-	"net/http"
-	"sync"
-	"testing"
-	"time"
-)
-
-func TestIssueAndVerify_RoundTrip(t *testing.T) {
-	km, err := NewKeyManager()
-	if err != nil {
-		t.Fatalf("new key manager: %v", err)
-	}
-	token, err := km.Issue("user-1", "acme", time.Hour)
-	if err != nil {
-		t.Fatalf("issue: %v", err)
-	}
-
-	v := NewVerifier(time.Hour, func(ctx context.Context) (map[string]ed25519.PublicKey, error) {
-		return km.PublicKeySet(), nil
-	})
-	claims, err := v.Verify(context.Background(), token)
-	if err != nil {
-		t.Fatalf("verify: %v", err)
-	}
-	if claims.Subject != "user-1" || claims.TenantSlug != "acme" {
-		t.Fatalf("claims unerwartet: %+v", claims)
-	}
-}
-
-// Akzeptanzkriterium 1: Verifikation lokal, kein Request pro Aufruf.
-func TestVerify_DoesNotFetchPerCall(t *testing.T) {
-	km, err := NewKeyManager()
-	if err != nil {
-		t.Fatalf("new key manager: %v", err)
-	}
-	token, err := km.Issue("user-1", "acme", time.Hour)
-	if err != nil {
-		t.Fatalf("issue: %v", err)
-	}
-
-	var mu sync.Mutex
-	fetchCalls := 0
-	v := NewVerifier(time.Hour, func(ctx context.Context) (map[string]ed25519.PublicKey, error) {
-		mu.Lock()
-		fetchCalls++
-		mu.Unlock()
-		return km.PublicKeySet(), nil
-	})
-
-	for i := 0; i < 10; i++ {
-		if _, err := v.Verify(context.Background(), token); err != nil {
-			t.Fatalf("verify %d: %v", i, err)
-		}
-	}
-
-	mu.Lock()
-	defer mu.Unlock()
-	if fetchCalls != 1 {
-		t.Fatalf("erwartet genau 1 fetch fuer 10 Verify-Aufrufe innerhalb der TTL, habe %d", fetchCalls)
-	}
-}
-
-// Akzeptanzkriterium 2 + Pruefung 1: Core simuliert nicht erreichbar,
-// bereits authentifizierte Nutzer bleiben funktionsfaehig (Fail-Open mit
-// letztbekanntem Schluesselstand).
-func TestVerify_FailsOpenWhenCoreUnreachableButStaleKeysExist(t *testing.T) {
-	km, err := NewKeyManager()
-	if err != nil {
-		t.Fatalf("new key manager: %v", err)
-	}
-	token, err := km.Issue("user-1", "acme", time.Hour)
-	if err != nil {
-		t.Fatalf("issue: %v", err)
-	}
-
-	coreDown := false
-	v := NewVerifier(30*time.Millisecond, func(ctx context.Context) (map[string]ed25519.PublicKey, error) {
-		if coreDown {
-			return nil, errors.New("core nicht erreichbar (simuliert)")
-		}
-		return km.PublicKeySet(), nil
-	})
-
-	// Cache vorwaermen, waehrend Core noch erreichbar ist.
-	if _, err := v.Verify(context.Background(), token); err != nil {
-		t.Fatalf("verify (warm): %v", err)
-	}
-
-	// "Core abschalten" und TTL ablaufen lassen.
-	coreDown = true
-	time.Sleep(50 * time.Millisecond)
-
-	if _, err := v.Verify(context.Background(), token); err != nil {
-		t.Fatalf("verify sollte trotz core-ausfall mit letztbekanntem stand funktionieren: %v", err)
-	}
-}
-
-// Akzeptanzkriterium 2 + Pruefung 2: neue sicherheitskritische Aktionen
-// (z.B. neuer Login) schlagen bei Core-Ausfall klar fehl statt unsicher
-// durchgelassen zu werden — auch wenn ein (aelterer) Cache-Stand existiert.
-func TestRequireFreshKeys_FailsClosedWhenCoreUnreachable(t *testing.T) {
-	km, err := NewKeyManager()
-	if err != nil {
-		t.Fatalf("new key manager: %v", err)
-	}
-
-	coreDown := false
-	v := NewVerifier(time.Hour, func(ctx context.Context) (map[string]ed25519.PublicKey, error) {
-		if coreDown {
-			return nil, errors.New("core nicht erreichbar (simuliert)")
-		}
-		return km.PublicKeySet(), nil
-	})
-
-	// Cache vorwaermen (existiert jetzt ein "veralteter" gueltiger Stand).
-	if _, _, err := v.cache.Get(context.Background()); err != nil {
-		t.Fatalf("warm cache: %v", err)
-	}
-
-	coreDown = true
-	if err := v.RequireFreshKeys(context.Background()); err == nil {
-		t.Fatal("erwartet fehler (fail-closed) bei core-ausfall, habe nil")
-	}
-}
-
-// Akzeptanzkriterium 3 + Pruefung 3: Schluesselrotation ohne Ausfallzeit —
-// ein bereits ausgestelltes Token bleibt nach Rotation weiterhin
-// verifizierbar, ein zweites (simuliertes) Modul bekommt beide Schluessel.
-func TestRotate_NoDowntimeForAlreadyIssuedTokens(t *testing.T) {
-	km, err := NewKeyManager()
-	if err != nil {
-		t.Fatalf("new key manager: %v", err)
-	}
-
-	oldToken, err := km.Issue("user-1", "acme", time.Hour)
-	if err != nil {
-		t.Fatalf("issue (alt): %v", err)
-	}
-
-	if _, err := km.Rotate(); err != nil {
-		t.Fatalf("rotate: %v", err)
-	}
-
-	newToken, err := km.Issue("user-2", "acme", time.Hour)
-	if err != nil {
-		t.Fatalf("issue (neu): %v", err)
-	}
-
-	// Simuliertes zweites Modul: fragt den vollstaendigen Schluesselsatz ab.
-	moduleB := NewVerifier(time.Hour, func(ctx context.Context) (map[string]ed25519.PublicKey, error) {
-		return km.PublicKeySet(), nil
-	})
-
-	if _, err := moduleB.Verify(context.Background(), oldToken); err != nil {
-		t.Fatalf("altes token sollte nach rotation weiterhin gueltig sein: %v", err)
-	}
-	if _, err := moduleB.Verify(context.Background(), newToken); err != nil {
-		t.Fatalf("neues token sollte gueltig sein: %v", err)
-	}
-}
-
-func TestVerify_RejectsUnknownKid(t *testing.T) {
-	km1, _ := NewKeyManager()
-	km2, _ := NewKeyManager() // komplett anderer, unbekannter schluessel
-
-	token, err := km1.Issue("user-1", "acme", time.Hour)
-	if err != nil {
-		t.Fatalf("issue: %v", err)
-	}
-
-	v := NewVerifier(time.Hour, func(ctx context.Context) (map[string]ed25519.PublicKey, error) {
-		return km2.PublicKeySet(), nil // kennt km1s schluessel nicht
-	})
-	if _, err := v.Verify(context.Background(), token); !errors.Is(err, ErrInvalidToken) {
-		t.Fatalf("erwartet ErrInvalidToken, habe %v", err)
-	}
-}
-
-func TestJWKSRoundTrip(t *testing.T) {
-	km, _ := NewKeyManager()
-	km.Rotate()
-
-	var buf []byte
-	rec := &captureWriter{}
-	km.ServeJWKS(rec, nil)
-	buf = rec.body
-
-	parsed, err := ParseJWKS(buf)
-	if err != nil {
-		t.Fatalf("parse jwks: %v", err)
-	}
-	if len(parsed) != len(km.PublicKeySet()) {
-		t.Fatalf("erwartet %d schluessel, habe %d", len(km.PublicKeySet()), len(parsed))
-	}
-}
-
-type captureWriter struct {
-	body   []byte
-	header http.Header
-}
-
-func (w *captureWriter) Header() http.Header {
-	if w.header == nil {
-		w.header = http.Header{}
-	}
-	return w.header
-}
-func (w *captureWriter) Write(p []byte) (int, error) { w.body = append(w.body, p...); return len(p), nil }
-func (w *captureWriter) WriteHeader(statusCode int)  {}

internal/moduletrust/verifier.go

@@ -1,67 +0,0 @@
-package moduletrust
-
-import (
-	"context"
-	"crypto/ed25519"
-	"errors"
-	"time"
-
-	"github.com/golang-jwt/jwt/v5"
-)
-
-var ErrInvalidToken = errors.New("moduletrust: ungueltiges token")
-
-// KeyFetchFunc holt den aktuellen Schluesselsatz von Core (z.B. per HTTP-GET
-// auf ServeJWKS + ParseJWKS). Wird vom Verifier nur bei abgelaufener TTL
-// aufgerufen — NICHT bei jeder Verify()-Anfrage (Akzeptanzkriterium 1).
-type KeyFetchFunc func(ctx context.Context) (map[string]ed25519.PublicKey, error)
-
-// Verifier ist die Modulseite von API-05: verifiziert JWTs LOKAL gegen einen
-// per StaleCache zwischengespeicherten Schluesselsatz, ohne pro Aufruf einen
-// synchronen Request an Core zu stellen.
-type Verifier struct {
-	cache *StaleCache[map[string]ed25519.PublicKey]
-}
-
-func NewVerifier(ttl time.Duration, fetch KeyFetchFunc) *Verifier {
-	return &Verifier{cache: NewStaleCache(ttl, func(ctx context.Context) (map[string]ed25519.PublicKey, error) {
-		return fetch(ctx)
-	})}
-}
-
-// Verify prueft die Signatur LOKAL gegen den (ggf. abgelaufenen, aber
-// vorhandenen) Schluesselsatz — FAIL-OPEN fuer bereits ausgestellte Tokens
-// (Akzeptanzkriterium 2): ist Core nicht erreichbar, aber ein alter
-// Schluesselsatz bekannt, wird damit weiter verifiziert.
-func (v *Verifier) Verify(ctx context.Context, tokenString string) (*Claims, error) {
-	keys, _, err := v.cache.Get(ctx)
-	if err != nil {
-		return nil, err
-	}
-
-	claims := &Claims{}
-	token, err := jwt.ParseWithClaims(tokenString, claims, func(t *jwt.Token) (interface{}, error) {
-		if _, ok := t.Method.(*jwt.SigningMethodEd25519); !ok {
-			return nil, ErrInvalidToken
-		}
-		kid, _ := t.Header["kid"].(string)
-		pub, ok := keys[kid]
-		if !ok {
-			return nil, ErrInvalidToken
-		}
-		return pub, nil
-	})
-	if err != nil || !token.Valid {
-		return nil, ErrInvalidToken
-	}
-	return claims, nil
-}
-
-// RequireFreshKeys ruft IMMER frisch von Core ab (FAIL-CLOSED) — fuer
-// sicherheitskritische Aktionen wie einen komplett neuen Login
-// (Akzeptanzkriterium 2): schlaegt klar fehl, wenn Core nicht erreichbar
-// ist, statt auf einem veralteten Schluesselsatz zu vertrauen.
-func (v *Verifier) RequireFreshKeys(ctx context.Context) error {
-	_, err := v.cache.RequireFresh(ctx)
-	return err
-}

internal/policy/enforcer.go

@@ -0,0 +1,67 @@
+package policy
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"gitea.perlbach24.de/scripte/nexarch/internal/rbac"
+)
+
+// ErrDenied wird geliefert, wenn keine Regel role+permission erlaubt —
+// Default-Deny (Akzeptanzkriterium 2).
+var ErrDenied = errors.New("policy: zugriff verweigert")
+
+// Enforcer ist die EINE zentrale Entscheidungs- und Durchsetzungsschicht
+// (Akzeptanzkriterium 1). Repository-/Query-Code ruft ausschliesslich Guard
+// bzw. GuardTenantScoped auf, nie eine Rohabfrage direkt.
+type Enforcer struct {
+	store *Store
+}
+
+func NewEnforcer(store *Store) *Enforcer {
+	return &Enforcer{store: store}
+}
+
+// Authorize entscheidet erlaubt/verboten — unabhaengig von jeder konkreten
+// Query, rein anhand der deklarativen Regeln (Akzeptanzkriterium 2: fuer
+// sich genommen testbar, ohne Anwendungslogik).
+func (e *Enforcer) Authorize(ctx context.Context, role rbac.Role, perm rbac.Permission) error {
+	allowed, err := e.store.IsAllowed(ctx, role, perm)
+	if err != nil {
+		return err
+	}
+	if !allowed {
+		return fmt.Errorf("%w: rolle %q hat kein recht %q", ErrDenied, role, perm)
+	}
+	return nil
+}
+
+// Guard ist die zentrale Enforcement-Funktion (Akzeptanzkriterium 1): query
+// wird NUR aufgerufen, wenn Authorize zustimmt. Es gibt keinen Weg, query
+// ausserhalb von Guard aufzurufen und trotzdem den Aufrufer als autorisiert
+// zu behandeln — die Autorisierungsentscheidung steht immer VOR dem
+// Datenzugriff, nie danach.
+func Guard[T any](ctx context.Context, e *Enforcer, role rbac.Role, perm rbac.Permission, query func(ctx context.Context) (T, error)) (T, error) {
+	var zero T
+	if err := e.Authorize(ctx, role, perm); err != nil {
+		return zero, err
+	}
+	return query(ctx)
+}
+
+// GuardTenantScoped erzwingt zusaetzlich, dass tenantSlug TEIL der Query-
+// Funktion selbst ist (Akzeptanzkriterium 3): der Funktionstyp verlangt,
+// dass die Repository-Implementierung tenantSlug in ihre eigene WHERE-
+// Klausel einbaut — ein nachgelagerter Filter auf dem Ergebnis (der
+// archivmail-Fehler aus "Bekannte Fehler vermeiden") ist mit dieser
+// Signatur nicht moeglich, da die Query-Funktion tenantSlug selbst
+// entgegennimmt und dafuer verantwortlich ist, statt ihn hinterher
+// anzuwenden.
+func GuardTenantScoped[T any](ctx context.Context, e *Enforcer, role rbac.Role, perm rbac.Permission, tenantSlug string, query func(ctx context.Context, tenantSlug string) (T, error)) (T, error) {
+	var zero T
+	if err := e.Authorize(ctx, role, perm); err != nil {
+		return zero, err
+	}
+	return query(ctx, tenantSlug)
+}

internal/policy/policy_test.go

@@ -0,0 +1,187 @@
+package policy
+
+import (
+	"context"
+	"errors"
+	"os"
+	"testing"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"gitea.perlbach24.de/scripte/nexarch/internal/rbac"
+)
+
+func setupTest(t *testing.T) (*Store, *Enforcer, func()) {
+	t.Helper()
+	adminDSN := os.Getenv("TEST_ADMIN_DSN")
+	if adminDSN == "" {
+		t.Skip("TEST_ADMIN_DSN nicht gesetzt, Integrationstest uebersprungen")
+	}
+	ctx := context.Background()
+
+	pool, err := pgxpool.New(ctx, adminDSN)
+	if err != nil {
+		t.Fatalf("pool: %v", err)
+	}
+	if _, err := pool.Exec(ctx, `
+		CREATE TABLE IF NOT EXISTS policy_rules (
+			role TEXT NOT NULL, permission TEXT NOT NULL,
+			granted_by TEXT NOT NULL, granted_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+			PRIMARY KEY (role, permission)
+		);
+		CREATE TABLE IF NOT EXISTS policy_rule_changes (
+			id UUID PRIMARY KEY DEFAULT gen_random_uuid(), role TEXT NOT NULL, permission TEXT NOT NULL,
+			action TEXT NOT NULL CHECK (action IN ('grant','revoke')), actor TEXT NOT NULL,
+			version INT NOT NULL, changed_at TIMESTAMPTZ NOT NULL DEFAULT now()
+		);
+	`); err != nil {
+		t.Fatalf("schema: %v", err)
+	}
+
+	store := NewStore(pool)
+	cleanup := func() {
+		_, _ = pool.Exec(ctx, `DELETE FROM policy_rule_changes WHERE role LIKE 'test\_%' ESCAPE '\'`)
+		_, _ = pool.Exec(ctx, `DELETE FROM policy_rules WHERE role LIKE 'test\_%' ESCAPE '\'`)
+		pool.Close()
+	}
+	return store, NewEnforcer(store), cleanup
+}
+
+// Akzeptanzkriterium 2 + Pruefung 2: Anfrage ohne passende Policy wird
+// zuverlaessig abgewiesen (Default-Deny), nicht standardmaessig erlaubt.
+func TestAuthorize_DefaultDeny(t *testing.T) {
+	_, enforcer, cleanup := setupTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	err := enforcer.Authorize(ctx, rbac.Role("test_niemand"), rbac.Permission("test_irgendwas"))
+	if !errors.Is(err, ErrDenied) {
+		t.Fatalf("erwartet ErrDenied ohne konfigurierte regel, habe %v", err)
+	}
+}
+
+// Akzeptanzkriterium 1 + Pruefung 1: Guard ruft query NUR bei Autorisierung
+// auf — kein Datenzugriffs-Pfad umgeht die Enforcement-Schicht.
+func TestGuard_NeverCallsQueryWithoutAuthorization(t *testing.T) {
+	store, enforcer, cleanup := setupTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	role := rbac.Role("test_rolle_guard")
+	perm := rbac.Permission("test_lesen")
+
+	queryCalled := false
+	_, err := Guard(ctx, enforcer, role, perm, func(ctx context.Context) (string, error) {
+		queryCalled = true
+		return "geheime-daten", nil
+	})
+	if !errors.Is(err, ErrDenied) {
+		t.Fatalf("erwartet ErrDenied, habe %v", err)
+	}
+	if queryCalled {
+		t.Fatal("query haette bei fehlender autorisierung NICHT aufgerufen werden duerfen")
+	}
+
+	if err := store.Grant(ctx, role, perm, "admin@example.com"); err != nil {
+		t.Fatalf("grant: %v", err)
+	}
+
+	result, err := Guard(ctx, enforcer, role, perm, func(ctx context.Context) (string, error) {
+		queryCalled = true
+		return "geheime-daten", nil
+	})
+	if err != nil {
+		t.Fatalf("guard nach grant: %v", err)
+	}
+	if !queryCalled || result != "geheime-daten" {
+		t.Fatalf("erwartet query-aufruf mit ergebnis nach autorisierung, habe queryCalled=%v result=%q", queryCalled, result)
+	}
+}
+
+// Akzeptanzkriterium 2 + 3: Policy-Entscheidungen deklarativ und unabhaengig
+// von Anwendungslogik testbar — Regelwechsel wirkt ohne Codeaenderung,
+// Historie ist versioniert nachvollziehbar.
+func TestGrantRevoke_ChangesBehaviorWithoutCodeChange(t *testing.T) {
+	store, enforcer, cleanup := setupTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	role := rbac.Role("test_rolle_history")
+	perm := rbac.Permission("test_schreiben")
+
+	allowed, err := store.IsAllowed(ctx, role, perm)
+	if err != nil {
+		t.Fatalf("is allowed (vorher): %v", err)
+	}
+	if allowed {
+		t.Fatal("erwartet nicht erlaubt vor grant")
+	}
+
+	if err := store.Grant(ctx, role, perm, "admin@example.com"); err != nil {
+		t.Fatalf("grant: %v", err)
+	}
+	if err := enforcer.Authorize(ctx, role, perm); err != nil {
+		t.Fatalf("authorize nach grant sollte erlauben: %v", err)
+	}
+
+	if err := store.Revoke(ctx, role, perm, "admin@example.com"); err != nil {
+		t.Fatalf("revoke: %v", err)
+	}
+	if err := enforcer.Authorize(ctx, role, perm); !errors.Is(err, ErrDenied) {
+		t.Fatalf("authorize nach revoke sollte verweigern, habe %v", err)
+	}
+
+	history, err := store.History(ctx, role, perm)
+	if err != nil {
+		t.Fatalf("history: %v", err)
+	}
+	if len(history) != 2 {
+		t.Fatalf("erwartet 2 historieneintraege (grant, revoke), habe %d", len(history))
+	}
+	if history[0].Action != "grant" || history[0].Version != 1 {
+		t.Fatalf("history[0] unerwartet: %+v", history[0])
+	}
+	if history[1].Action != "revoke" || history[1].Version != 2 {
+		t.Fatalf("history[1] unerwartet: %+v", history[1])
+	}
+}
+
+// Akzeptanzkriterium 3 + Pruefung 3 (Tenant-Scoping): GuardTenantScoped
+// zwingt tenantSlug in die Query-Funktion selbst, kein Post-Filter moeglich.
+func TestGuardTenantScoped_IsolatesDataBetweenTenants(t *testing.T) {
+	_, enforcer, cleanup := setupTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	// Simuliertes Repository: die WHERE-Klausel (hier: Map-Lookup) liegt
+	// INNERHALB der Query-Funktion, nicht als nachgelagerter Filter.
+	data := map[string][]string{
+		"acme":   {"dokument-a1", "dokument-a2"},
+		"globex": {"dokument-b1"},
+	}
+	repoQuery := func(ctx context.Context, tenantSlug string) ([]string, error) {
+		return data[tenantSlug], nil
+	}
+
+	role := rbac.Role("test_tenant_rolle")
+	perm := rbac.Permission("test_dokumente_lesen")
+	if err := enforcer.store.Grant(ctx, role, perm, "admin@example.com"); err != nil {
+		t.Fatalf("grant: %v", err)
+	}
+
+	gotAcme, err := GuardTenantScoped(ctx, enforcer, role, perm, "acme", repoQuery)
+	if err != nil {
+		t.Fatalf("guard tenant scoped (acme): %v", err)
+	}
+	if len(gotAcme) != 2 {
+		t.Fatalf("erwartet 2 dokumente fuer acme, habe %d", len(gotAcme))
+	}
+
+	gotGlobex, err := GuardTenantScoped(ctx, enforcer, role, perm, "globex", repoQuery)
+	if err != nil {
+		t.Fatalf("guard tenant scoped (globex): %v", err)
+	}
+	if len(gotGlobex) != 1 {
+		t.Fatalf("erwartet 1 dokument fuer globex, habe %d", len(gotGlobex))
+	}
+}

internal/policy/store.go

@@ -0,0 +1,124 @@
+// Package policy implementiert Core RBAC-02: die zentrale Policy-
+// Entscheidungs- und Durchsetzungsschicht. Regeln liegen deklarativ in der
+// Datenbank (Casbin-Prinzip: Policy als Modell+Regeln getrennt vom Code),
+// versioniert und auditierbar — anders als Casbin-Dateien im Dateisystem
+// (siehe "bewusst vermeiden" im Ticket).
+package policy
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"gitea.perlbach24.de/scripte/nexarch/internal/rbac"
+)
+
+// Rule ist eine gewaehrte Regel: role darf permission.
+type Rule struct {
+	Role       rbac.Role
+	Permission rbac.Permission
+}
+
+// RuleChange ist ein Eintrag der Aenderungshistorie (Akzeptanzkriterium 3).
+type RuleChange struct {
+	Role       rbac.Role
+	Permission rbac.Permission
+	Action     string // "grant" oder "revoke"
+	Actor      string
+	Version    int
+}
+
+// Store verwaltet den deklarativen Regelsatz. IsAllowed schaut NUR in die
+// Datenbank — es gibt keinen hartcodierten Go-Fallback, ein Regelwechsel
+// wirkt sich ohne Codeaenderung sofort aus (Akzeptanzkriterium 2 / 3).
+type Store struct {
+	pool *pgxpool.Pool
+}
+
+func NewStore(pool *pgxpool.Pool) *Store {
+	return &Store{pool: pool}
+}
+
+// IsAllowed prueft, ob role das Recht permission besitzt. Default-Deny:
+// existiert keine passende Regel, ist der Zugriff verboten
+// (Akzeptanzkriterium 2 / Pruefung 2) — es gibt keinen impliziten
+// "erlaubt, wenn nichts anderes gesagt"-Pfad.
+func (s *Store) IsAllowed(ctx context.Context, role rbac.Role, perm rbac.Permission) (bool, error) {
+	var exists bool
+	err := s.pool.QueryRow(ctx, `
+		SELECT EXISTS(SELECT 1 FROM policy_rules WHERE role = $1 AND permission = $2)
+	`, string(role), string(perm)).Scan(&exists)
+	if err != nil {
+		return false, fmt.Errorf("policy pruefen: %w", err)
+	}
+	return exists, nil
+}
+
+// Grant gewaehrt role das Recht permission — deklarativ, ohne Codeaenderung
+// wirksam. actor wird fuer die Aenderungshistorie festgehalten.
+func (s *Store) Grant(ctx context.Context, role rbac.Role, perm rbac.Permission, actor string) error {
+	return s.change(ctx, role, perm, "grant", actor, `
+		INSERT INTO policy_rules (role, permission, granted_by, granted_at)
+		VALUES ($1, $2, $3, now())
+		ON CONFLICT (role, permission) DO UPDATE SET granted_by = $3, granted_at = now()
+	`, string(role), string(perm), actor)
+}
+
+// Revoke entzieht role das Recht permission.
+func (s *Store) Revoke(ctx context.Context, role rbac.Role, perm rbac.Permission, actor string) error {
+	return s.change(ctx, role, perm, "revoke", actor, `
+		DELETE FROM policy_rules WHERE role = $1 AND permission = $2
+	`, string(role), string(perm))
+}
+
+func (s *Store) change(ctx context.Context, role rbac.Role, perm rbac.Permission, action, actor, sql string, args ...any) error {
+	tx, err := s.pool.Begin(ctx)
+	if err != nil {
+		return fmt.Errorf("transaktion starten: %w", err)
+	}
+	defer func() { _ = tx.Rollback(ctx) }()
+
+	if _, err := tx.Exec(ctx, sql, args...); err != nil {
+		return fmt.Errorf("regel aendern: %w", err)
+	}
+
+	var version int
+	if err := tx.QueryRow(ctx, `
+		SELECT COALESCE(MAX(version), 0) + 1 FROM policy_rule_changes WHERE role = $1 AND permission = $2
+	`, string(role), string(perm)).Scan(&version); err != nil {
+		return fmt.Errorf("naechste version ermitteln: %w", err)
+	}
+
+	if _, err := tx.Exec(ctx, `
+		INSERT INTO policy_rule_changes (role, permission, action, actor, version, changed_at)
+		VALUES ($1, $2, $3, $4, $5, now())
+	`, string(role), string(perm), action, actor, version); err != nil {
+		return fmt.Errorf("historie schreiben: %w", err)
+	}
+
+	return tx.Commit(ctx)
+}
+
+// History liefert die vollstaendige, versionierte Aenderungshistorie einer
+// Regel (Akzeptanzkriterium 3).
+func (s *Store) History(ctx context.Context, role rbac.Role, perm rbac.Permission) ([]RuleChange, error) {
+	rows, err := s.pool.Query(ctx, `
+		SELECT action, actor, version FROM policy_rule_changes
+		WHERE role = $1 AND permission = $2 ORDER BY version
+	`, string(role), string(perm))
+	if err != nil {
+		return nil, fmt.Errorf("historie abfragen: %w", err)
+	}
+	defer rows.Close()
+
+	var out []RuleChange
+	for rows.Next() {
+		c := RuleChange{Role: role, Permission: perm}
+		if err := rows.Scan(&c.Action, &c.Actor, &c.Version); err != nil {
+			return nil, fmt.Errorf("historieneintrag lesen: %w", err)
+		}
+		out = append(out, c)
+	}
+	return out, rows.Err()
+}

internal/rbac/group.go

@@ -0,0 +1,200 @@
+package rbac
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+var ErrGroupNotFound = errors.New("rbac: gruppe nicht gefunden")
+
+type Group struct {
+	ID   string
+	Name string
+	Role Role // leer, wenn der Gruppe noch keine Rolle zugewiesen wurde
+}
+
+// GroupStore verwaltet Gruppen/Abteilungen innerhalb GENAU EINER Tenant-
+// Datenbank (Modell C, wie Store fuer direkte Rollenzuweisungen) —
+// Akzeptanzkriterium 3 (tenant-isoliert) ist damit strukturell erfuellt.
+type GroupStore struct {
+	pool *pgxpool.Pool
+}
+
+func NewGroupStore(pool *pgxpool.Pool) *GroupStore {
+	return &GroupStore{pool: pool}
+}
+
+// CreateGroup legt eine neue, noch rollenlose Gruppe an (Akzeptanzkriterium 1).
+func (s *GroupStore) CreateGroup(ctx context.Context, name string) (Group, error) {
+	if name == "" {
+		return Group{}, errors.New("rbac: gruppenname darf nicht leer sein")
+	}
+	var g Group
+	g.Name = name
+	if err := s.pool.QueryRow(ctx, `
+		INSERT INTO groups (name) VALUES ($1) RETURNING id
+	`, name).Scan(&g.ID); err != nil {
+		return Group{}, fmt.Errorf("gruppe anlegen: %w", err)
+	}
+	return g, nil
+}
+
+// SetGroupRole weist der Gruppe eine Rolle zu (Akzeptanzkriterium 2) — nur
+// 'user'/'tenant_admin' sind auf Gruppenebene zuweisbar, dieselbe erlaubte
+// Matrix wie in Store.Assign (superadmin bleibt mandantenuebergreifend und
+// ausserhalb jeder Gruppenlogik).
+func (s *GroupStore) SetGroupRole(ctx context.Context, groupID string, role Role) error {
+	if !assignableRoles[role] {
+		return ErrRoleNotAssignableInTenantScope
+	}
+	tag, err := s.pool.Exec(ctx, `UPDATE groups SET role = $2 WHERE id = $1`, groupID, string(role))
+	if err != nil {
+		return fmt.Errorf("gruppenrolle setzen: %w", err)
+	}
+	if tag.RowsAffected() == 0 {
+		return ErrGroupNotFound
+	}
+	return nil
+}
+
+// AddMember nimmt einen Benutzer in die Gruppe auf.
+func (s *GroupStore) AddMember(ctx context.Context, groupID, userID string) error {
+	_, err := s.pool.Exec(ctx, `
+		INSERT INTO group_members (group_id, user_id) VALUES ($1, $2)
+		ON CONFLICT (group_id, user_id) DO NOTHING
+	`, groupID, userID)
+	if err != nil {
+		return fmt.Errorf("mitglied hinzufuegen: %w", err)
+	}
+	return nil
+}
+
+// RemoveMember entfernt einen Benutzer aus der Gruppe — die gruppenbasierten
+// Rechte entfallen fuer ihn sofort (Akzeptanzkriterium 3 / Pruefung 2), da
+// EffectivePermissionsForUser bei jedem Aufruf neu berechnet wird, nicht
+// zwischengespeichert.
+func (s *GroupStore) RemoveMember(ctx context.Context, groupID, userID string) error {
+	_, err := s.pool.Exec(ctx, `DELETE FROM group_members WHERE group_id = $1 AND user_id = $2`, groupID, userID)
+	if err != nil {
+		return fmt.Errorf("mitglied entfernen: %w", err)
+	}
+	return nil
+}
+
+// DeleteGroup loescht die Gruppe — ON DELETE CASCADE entfernt die
+// Mitgliedschaften mit, Benutzerkonten selbst bleiben unberuehrt
+// (Akzeptanzkriterium 3).
+func (s *GroupStore) DeleteGroup(ctx context.Context, groupID string) error {
+	_, err := s.pool.Exec(ctx, `DELETE FROM groups WHERE id = $1`, groupID)
+	if err != nil {
+		return fmt.Errorf("gruppe loeschen: %w", err)
+	}
+	return nil
+}
+
+// ListGroups liefert alle Gruppen des Mandanten (Akzeptanzkriterium 1/2,
+// Grundlage fuer die Administrationsoberflaeche).
+func (s *GroupStore) ListGroups(ctx context.Context) ([]Group, error) {
+	rows, err := s.pool.Query(ctx, `SELECT id, name, COALESCE(role, '') FROM groups ORDER BY name`)
+	if err != nil {
+		return nil, fmt.Errorf("gruppen auflisten: %w", err)
+	}
+	defer rows.Close()
+
+	var out []Group
+	for rows.Next() {
+		var g Group
+		var role string
+		if err := rows.Scan(&g.ID, &g.Name, &role); err != nil {
+			return nil, fmt.Errorf("gruppe lesen: %w", err)
+		}
+		g.Role = Role(role)
+		out = append(out, g)
+	}
+	return out, rows.Err()
+}
+
+// Members liefert die User-IDs der Mitglieder einer Gruppe.
+func (s *GroupStore) Members(ctx context.Context, groupID string) ([]string, error) {
+	rows, err := s.pool.Query(ctx, `SELECT user_id FROM group_members WHERE group_id = $1`, groupID)
+	if err != nil {
+		return nil, fmt.Errorf("mitglieder abfragen: %w", err)
+	}
+	defer rows.Close()
+
+	var out []string
+	for rows.Next() {
+		var id string
+		if err := rows.Scan(&id); err != nil {
+			return nil, fmt.Errorf("mitglied lesen: %w", err)
+		}
+		out = append(out, id)
+	}
+	return out, rows.Err()
+}
+
+// RolesForUser liefert alle Rollen, die einem Benutzer ueber seine
+// Gruppenmitgliedschaften zufallen (Akzeptanzkriterium 2: wirkt auf alle
+// Mitglieder). Eine Gruppe ohne zugewiesene Rolle traegt nichts bei.
+func (s *GroupStore) RolesForUser(ctx context.Context, userID string) ([]Role, error) {
+	rows, err := s.pool.Query(ctx, `
+		SELECT g.role FROM groups g
+		JOIN group_members gm ON gm.group_id = g.id
+		WHERE gm.user_id = $1 AND g.role IS NOT NULL
+	`, userID)
+	if err != nil {
+		return nil, fmt.Errorf("gruppenrollen abfragen: %w", err)
+	}
+	defer rows.Close()
+
+	var out []Role
+	for rows.Next() {
+		var r string
+		if err := rows.Scan(&r); err != nil {
+			return nil, fmt.Errorf("gruppenrolle lesen: %w", err)
+		}
+		out = append(out, Role(r))
+	}
+	return out, rows.Err()
+}
+
+// EffectivePermissionsForUser vereinigt die Rechte aus der direkten
+// Rollenzuweisung (Store, RBAC-01) mit allen Rechten aus Gruppenrollen —
+// jede einzelne Rolle wird ueber die bestehende Hierarchie (EffectivePermissions)
+// aufgeloest, das Ergebnis dedupliziert.
+func (s *GroupStore) EffectivePermissionsForUser(ctx context.Context, directStore *Store, userID string) ([]Permission, error) {
+	seen := make(map[Permission]bool)
+	var out []Permission
+
+	add := func(role Role) {
+		for _, p := range EffectivePermissions(role) {
+			if !seen[p] {
+				seen[p] = true
+				out = append(out, p)
+			}
+		}
+	}
+
+	if directStore != nil {
+		assignment, err := directStore.Get(ctx, userID)
+		if err != nil && !errors.Is(err, ErrNotFound) {
+			return nil, err
+		}
+		if err == nil {
+			add(assignment.Role)
+		}
+	}
+
+	groupRoles, err := s.RolesForUser(ctx, userID)
+	if err != nil {
+		return nil, err
+	}
+	for _, r := range groupRoles {
+		add(r)
+	}
+
+	return out, nil
+}

internal/rbac/group_test.go

@@ -0,0 +1,209 @@
+package rbac
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"gitea.perlbach24.de/scripte/nexarch/internal/user"
+)
+
+const groupSchema = `
+CREATE TABLE IF NOT EXISTS users (
+	id UUID PRIMARY KEY DEFAULT gen_random_uuid(), email TEXT NOT NULL UNIQUE, name TEXT NOT NULL,
+	status TEXT NOT NULL DEFAULT 'active', created_at TIMESTAMPTZ NOT NULL DEFAULT now(), updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE TABLE IF NOT EXISTS role_assignments (
+	user_id UUID PRIMARY KEY REFERENCES users(id), role TEXT NOT NULL CHECK (role IN ('user','tenant_admin')),
+	granted_by TEXT NOT NULL, granted_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE TABLE IF NOT EXISTS groups (
+	id UUID PRIMARY KEY DEFAULT gen_random_uuid(), name TEXT NOT NULL, role TEXT CHECK (role IN ('user','tenant_admin')),
+	created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE TABLE IF NOT EXISTS group_members (
+	group_id UUID NOT NULL REFERENCES groups(id) ON DELETE CASCADE, user_id UUID NOT NULL REFERENCES users(id),
+	added_at TIMESTAMPTZ NOT NULL DEFAULT now(), PRIMARY KEY (group_id, user_id)
+);`
+
+func setupGroupTestDB(t *testing.T, dbName string) *pgxpool.Pool {
+	t.Helper()
+	adminDSN := os.Getenv("TEST_ADMIN_DSN")
+	if adminDSN == "" {
+		t.Skip("TEST_ADMIN_DSN nicht gesetzt, Integrationstest uebersprungen")
+	}
+	ctx := context.Background()
+
+	adminPool, err := pgxpool.New(ctx, adminDSN)
+	if err != nil {
+		t.Fatalf("admin pool: %v", err)
+	}
+	_, _ = adminPool.Exec(ctx, fmt.Sprintf(`DROP DATABASE IF EXISTS %q`, dbName))
+	if _, err := adminPool.Exec(ctx, fmt.Sprintf(`CREATE DATABASE %q`, dbName)); err != nil {
+		t.Fatalf("testdatenbank anlegen: %v", err)
+	}
+
+	dsn := strings.Replace(adminDSN, "/postgres?", "/"+dbName+"?", 1)
+	pool, err := pgxpool.New(ctx, dsn)
+	if err != nil {
+		t.Fatalf("connect testdatenbank: %v", err)
+	}
+	if _, err := pool.Exec(ctx, groupSchema); err != nil {
+		t.Fatalf("schema anwenden: %v", err)
+	}
+
+	t.Cleanup(func() {
+		pool.Close()
+		_, _ = adminPool.Exec(ctx, fmt.Sprintf(`DROP DATABASE IF EXISTS %q`, dbName))
+		adminPool.Close()
+	})
+	return pool
+}
+
+func createTestUser(t *testing.T, pool *pgxpool.Pool, email string) string {
+	t.Helper()
+	u, err := user.NewTenantUserStore(pool).Create(context.Background(), email, "Test")
+	if err != nil {
+		t.Fatalf("testuser anlegen: %v", err)
+	}
+	return u.ID
+}
+
+// Akzeptanzkriterium 1: Gruppen anlegen und Benutzer zuordnen.
+func TestGroup_CreateAndAddMember(t *testing.T) {
+	pool := setupGroupTestDB(t, "test_rbac03_create")
+	gs := NewGroupStore(pool)
+	ctx := context.Background()
+
+	g, err := gs.CreateGroup(ctx, "Buchhaltung")
+	if err != nil {
+		t.Fatalf("create group: %v", err)
+	}
+	userID := createTestUser(t, pool, "alice@example.com")
+
+	if err := gs.AddMember(ctx, g.ID, userID); err != nil {
+		t.Fatalf("add member: %v", err)
+	}
+}
+
+// Akzeptanzkriterium 2 + Pruefung 1: Gruppenrolle wirkt auf ALLE aktuellen
+// Mitglieder.
+func TestGroup_RoleAffectsAllCurrentMembers(t *testing.T) {
+	pool := setupGroupTestDB(t, "test_rbac03_roleall")
+	gs := NewGroupStore(pool)
+	ctx := context.Background()
+
+	g, err := gs.CreateGroup(ctx, "Admins")
+	if err != nil {
+		t.Fatalf("create group: %v", err)
+	}
+	if err := gs.SetGroupRole(ctx, g.ID, RoleTenantAdmin); err != nil {
+		t.Fatalf("set group role: %v", err)
+	}
+
+	alice := createTestUser(t, pool, "alice@example.com")
+	bob := createTestUser(t, pool, "bob@example.com")
+	if err := gs.AddMember(ctx, g.ID, alice); err != nil {
+		t.Fatalf("add alice: %v", err)
+	}
+	if err := gs.AddMember(ctx, g.ID, bob); err != nil {
+		t.Fatalf("add bob: %v", err)
+	}
+
+	for _, uid := range []string{alice, bob} {
+		perms, err := gs.EffectivePermissionsForUser(ctx, nil, uid)
+		if err != nil {
+			t.Fatalf("effective permissions fuer %s: %v", uid, err)
+		}
+		if !contains(perms, PermManageUsers) {
+			t.Fatalf("mitglied %s sollte tenant_admin-rechte ueber die gruppe haben, habe %v", uid, perms)
+		}
+	}
+}
+
+// Akzeptanzkriterium 3 + Pruefung 2: Entfernen aus der Gruppe entzieht die
+// gruppenbasierten Rechte sofort.
+func TestGroup_RemoveMemberRevokesRightsImmediately(t *testing.T) {
+	pool := setupGroupTestDB(t, "test_rbac03_remove")
+	gs := NewGroupStore(pool)
+	ctx := context.Background()
+
+	g, _ := gs.CreateGroup(ctx, "Admins")
+	_ = gs.SetGroupRole(ctx, g.ID, RoleTenantAdmin)
+	userID := createTestUser(t, pool, "alice@example.com")
+	_ = gs.AddMember(ctx, g.ID, userID)
+
+	perms, err := gs.EffectivePermissionsForUser(ctx, nil, userID)
+	if err != nil {
+		t.Fatalf("effective permissions (mitglied): %v", err)
+	}
+	if !contains(perms, PermManageUsers) {
+		t.Fatal("erwartet tenant_admin-rechte als mitglied")
+	}
+
+	if err := gs.RemoveMember(ctx, g.ID, userID); err != nil {
+		t.Fatalf("remove member: %v", err)
+	}
+
+	perms, err = gs.EffectivePermissionsForUser(ctx, nil, userID)
+	if err != nil {
+		t.Fatalf("effective permissions (entfernt): %v", err)
+	}
+	if contains(perms, PermManageUsers) {
+		t.Fatal("erwartet KEINE tenant_admin-rechte nach entfernen aus der gruppe")
+	}
+}
+
+// Akzeptanzkriterium 3: Loeschen einer Gruppe entzieht Rechte sauber, ohne
+// das Benutzerkonto zu loeschen.
+func TestGroup_DeleteGroupRevokesRightsWithoutDeletingUser(t *testing.T) {
+	pool := setupGroupTestDB(t, "test_rbac03_delete")
+	gs := NewGroupStore(pool)
+	us := user.NewTenantUserStore(pool)
+	ctx := context.Background()
+
+	g, _ := gs.CreateGroup(ctx, "Temp")
+	_ = gs.SetGroupRole(ctx, g.ID, RoleTenantAdmin)
+	userID := createTestUser(t, pool, "alice@example.com")
+	_ = gs.AddMember(ctx, g.ID, userID)
+
+	if err := gs.DeleteGroup(ctx, g.ID); err != nil {
+		t.Fatalf("delete group: %v", err)
+	}
+
+	perms, err := gs.EffectivePermissionsForUser(ctx, nil, userID)
+	if err != nil {
+		t.Fatalf("effective permissions: %v", err)
+	}
+	if contains(perms, PermManageUsers) {
+		t.Fatal("erwartet keine rechte mehr nach loeschen der gruppe")
+	}
+
+	if _, err := us.Get(ctx, userID); err != nil {
+		t.Fatalf("benutzerkonto haette erhalten bleiben muessen: %v", err)
+	}
+}
+
+// Akzeptanzkriterium 3 + Pruefung 3: Gruppen sind sauber tenant-isoliert.
+func TestGroup_TenantIsolation(t *testing.T) {
+	poolA := setupGroupTestDB(t, "test_rbac03_tenanta")
+	poolB := setupGroupTestDB(t, "test_rbac03_tenantb")
+	gsA := NewGroupStore(poolA)
+	ctx := context.Background()
+
+	if _, err := gsA.CreateGroup(ctx, "Nur-Tenant-A"); err != nil {
+		t.Fatalf("create group a: %v", err)
+	}
+
+	var countB int
+	if err := poolB.QueryRow(ctx, `SELECT count(*) FROM groups`).Scan(&countB); err != nil {
+		t.Fatalf("count tenant b: %v", err)
+	}
+	if countB != 0 {
+		t.Fatalf("tenant b sollte keine gruppen aus tenant a sehen, habe %d", countB)
+	}
+}

internal/rbac/handler.go

@@ -0,0 +1,250 @@
+package rbac
+
+import (
+	"encoding/json"
+	"net/http"
+	"strings"
+
+	"gitea.perlbach24.de/scripte/nexarch/internal/auth"
+)
+
+// Handler stellt Rollen-/Rechte- und Gruppenverwaltung als HTTP-Endpunkte
+// bereit (RBAC-05). Duenner Client der bestehenden Store/GroupStore-Schicht —
+// keine eigene Rechtelogik hier (siehe Ticket-Produkt-DNA).
+type Handler struct {
+	roles  *Store
+	groups *GroupStore
+}
+
+func NewHandler(roles *Store, groups *GroupStore) *Handler {
+	return &Handler{roles: roles, groups: groups}
+}
+
+// requireManageUsers prueft, ob der aufrufende Benutzer ueberhaupt
+// Rechteverwaltung ausueben darf — technisch durchgesetzt hier zusaetzlich
+// zu RBAC-02 (Policy-Enforcement-Schicht), da diese Kachel ein eigener,
+// besonders sicherheitskritischer HTTP-Einstiegspunkt ist.
+func requireManageUsers(w http.ResponseWriter, r *http.Request, roles *Store) (callerUserID string, ok bool) {
+	claims, authOK := auth.ClaimsFromContext(r.Context())
+	if !authOK {
+		http.Error(w, "nicht angemeldet", http.StatusUnauthorized)
+		return "", false
+	}
+	assignment, err := roles.Get(r.Context(), claims.UserID)
+	if err != nil || !HasPermission(assignment.Role, PermManageUsers) {
+		http.Error(w, "keine Berechtigung zur Rechteverwaltung", http.StatusForbidden)
+		return "", false
+	}
+	return claims.UserID, true
+}
+
+type roleInfo struct {
+	Role        Role         `json:"role"`
+	Permissions []Permission `json:"permissions"`
+}
+
+// ListRoles liefert die (im Tenant-Geltungsbereich zuweisbaren) Rollen mit
+// ihren vollstaendig aufgeloesten Rechten (Akzeptanzkriterium 1).
+func (h *Handler) ListRoles(w http.ResponseWriter, r *http.Request) {
+	if _, ok := requireManageUsers(w, r, h.roles); !ok {
+		return
+	}
+	out := make([]roleInfo, 0, len(assignableRoles))
+	for role := range assignableRoles {
+		out = append(out, roleInfo{Role: role, Permissions: EffectivePermissions(role)})
+	}
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(out)
+}
+
+type assignRoleRequest struct {
+	UserID string `json:"user_id"`
+	Role   Role   `json:"role"`
+}
+
+// roleRank ordnet die Rollenhierarchie fuer den Selbst-Eskalations-Vergleich
+// (Akzeptanzkriterium 2 / Pruefung 2) — hoehere Zahl = mehr Rechte. Basiert
+// auf derselben parent-Kette wie EffectivePermissions, nicht dupliziert als
+// eigenstaendiges Modell.
+func roleRank(role Role) int {
+	rank := 0
+	for r, ok := role, true; ok; r, ok = parent[r] {
+		rank++
+	}
+	return rank
+}
+
+// AssignRole weist einem Benutzer eine Rolle zu (Akzeptanzkriterium 1).
+// Verweigert explizit, dass sich der aufrufende Benutzer selbst eine
+// hoehere Rolle zuweist (Akzeptanzkriterium 2 / Pruefung 2) — unabhaengig
+// davon, ob RBAC-02 dieselbe Aktion ohnehin ueber die allgemeine
+// Policy-Schicht verhindern wuerde: Selbst-Eskalation ist ein derart
+// sicherheitskritischer Einzelfall, dass er hier zusaetzlich explizit und
+// unuebersehbar geprueft wird, statt sich allein auf eine generische
+// Regel an anderer Stelle zu verlassen.
+func (h *Handler) AssignRole(w http.ResponseWriter, r *http.Request) {
+	callerUserID, ok := requireManageUsers(w, r, h.roles)
+	if !ok {
+		return
+	}
+
+	var req assignRoleRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		http.Error(w, "ungueltige Anfrage", http.StatusBadRequest)
+		return
+	}
+
+	if req.UserID == callerUserID {
+		callerAssignment, err := h.roles.Get(r.Context(), callerUserID)
+		callerRole := RoleUser
+		if err == nil {
+			callerRole = callerAssignment.Role
+		}
+		if roleRank(req.Role) > roleRank(callerRole) {
+			http.Error(w, "Sie können sich nicht selbst eine höhere Rolle zuweisen.", http.StatusForbidden)
+			return
+		}
+	}
+
+	assignment, err := h.roles.Assign(r.Context(), req.UserID, req.Role, callerUserID)
+	if err != nil {
+		http.Error(w, "Rolle konnte nicht zugewiesen werden.", http.StatusBadRequest)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(assignment)
+}
+
+// RoleHistory liefert die Zuweisungshistorie eines Benutzers — der in
+// Akzeptanzkriterium 3 geforderte Verweis auf das Audit-Log (die
+// role_assignment_history-Tabelle selbst IST die Nachvollziehbarkeits-Spur;
+// eine vollstaendige Anbindung an Core AUD-01 ist nicht Teil dieser Kachel).
+func (h *Handler) RoleHistory(w http.ResponseWriter, r *http.Request) {
+	if _, ok := requireManageUsers(w, r, h.roles); !ok {
+		return
+	}
+	userID := strings.TrimPrefix(r.URL.Path, "/rbac/users/")
+	userID = strings.TrimSuffix(userID, "/history")
+	if userID == "" {
+		http.Error(w, "user_id fehlt", http.StatusBadRequest)
+		return
+	}
+
+	history, err := h.roles.History(r.Context(), userID)
+	if err != nil {
+		http.Error(w, "historie konnte nicht geladen werden", http.StatusInternalServerError)
+		return
+	}
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(history)
+}
+
+type createGroupRequest struct {
+	Name string `json:"name"`
+}
+
+// CreateGroup legt eine neue Gruppe an (Akzeptanzkriterium 2).
+func (h *Handler) CreateGroup(w http.ResponseWriter, r *http.Request) {
+	if _, ok := requireManageUsers(w, r, h.roles); !ok {
+		return
+	}
+	var req createGroupRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		http.Error(w, "ungueltige Anfrage", http.StatusBadRequest)
+		return
+	}
+	group, err := h.groups.CreateGroup(r.Context(), req.Name)
+	if err != nil {
+		http.Error(w, "Gruppe konnte nicht angelegt werden.", http.StatusBadRequest)
+		return
+	}
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(http.StatusCreated)
+	_ = json.NewEncoder(w).Encode(group)
+}
+
+type groupWithMembers struct {
+	Group
+	Members []string `json:"members"`
+}
+
+// ListGroups liefert alle Gruppen inkl. Mitgliederliste (Akzeptanzkriterium 2).
+func (h *Handler) ListGroups(w http.ResponseWriter, r *http.Request) {
+	if _, ok := requireManageUsers(w, r, h.roles); !ok {
+		return
+	}
+	groups, err := h.groups.ListGroups(r.Context())
+	if err != nil {
+		http.Error(w, "Gruppen konnten nicht geladen werden.", http.StatusInternalServerError)
+		return
+	}
+	out := make([]groupWithMembers, 0, len(groups))
+	for _, g := range groups {
+		members, err := h.groups.Members(r.Context(), g.ID)
+		if err != nil {
+			http.Error(w, "Mitglieder konnten nicht geladen werden.", http.StatusInternalServerError)
+			return
+		}
+		out = append(out, groupWithMembers{Group: g, Members: members})
+	}
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(out)
+}
+
+type groupActionRequest struct {
+	GroupID string `json:"group_id"`
+	UserID  string `json:"user_id"`
+	Role    Role   `json:"role"`
+}
+
+// SetGroupRole weist einer Gruppe eine Rolle zu (Akzeptanzkriterium 2).
+func (h *Handler) SetGroupRole(w http.ResponseWriter, r *http.Request) {
+	if _, ok := requireManageUsers(w, r, h.roles); !ok {
+		return
+	}
+	var req groupActionRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		http.Error(w, "ungueltige Anfrage", http.StatusBadRequest)
+		return
+	}
+	if err := h.groups.SetGroupRole(r.Context(), req.GroupID, req.Role); err != nil {
+		http.Error(w, "Gruppenrolle konnte nicht gesetzt werden.", http.StatusBadRequest)
+		return
+	}
+	w.WriteHeader(http.StatusOK)
+}
+
+// AddGroupMember nimmt einen Benutzer in eine Gruppe auf (Akzeptanzkriterium 2).
+func (h *Handler) AddGroupMember(w http.ResponseWriter, r *http.Request) {
+	if _, ok := requireManageUsers(w, r, h.roles); !ok {
+		return
+	}
+	var req groupActionRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		http.Error(w, "ungueltige Anfrage", http.StatusBadRequest)
+		return
+	}
+	if err := h.groups.AddMember(r.Context(), req.GroupID, req.UserID); err != nil {
+		http.Error(w, "Mitglied konnte nicht hinzugefügt werden.", http.StatusBadRequest)
+		return
+	}
+	w.WriteHeader(http.StatusOK)
+}
+
+// RemoveGroupMember entfernt einen Benutzer aus einer Gruppe.
+func (h *Handler) RemoveGroupMember(w http.ResponseWriter, r *http.Request) {
+	if _, ok := requireManageUsers(w, r, h.roles); !ok {
+		return
+	}
+	var req groupActionRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		http.Error(w, "ungueltige Anfrage", http.StatusBadRequest)
+		return
+	}
+	if err := h.groups.RemoveMember(r.Context(), req.GroupID, req.UserID); err != nil {
+		http.Error(w, "Mitglied konnte nicht entfernt werden.", http.StatusBadRequest)
+		return
+	}
+	w.WriteHeader(http.StatusOK)
+}

internal/rbac/handler_test.go

@@ -0,0 +1,309 @@
+package rbac
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"gitea.perlbach24.de/scripte/nexarch/internal/auth"
+	"gitea.perlbach24.de/scripte/nexarch/internal/user"
+)
+
+const handlerSchema = `
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+CREATE TABLE users (
+	id UUID PRIMARY KEY DEFAULT gen_random_uuid(), email TEXT NOT NULL UNIQUE, name TEXT NOT NULL,
+	status TEXT NOT NULL DEFAULT 'active', created_at TIMESTAMPTZ NOT NULL DEFAULT now(), updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE TABLE role_assignments (
+	user_id UUID PRIMARY KEY REFERENCES users(id), role TEXT NOT NULL CHECK (role IN ('user','tenant_admin')),
+	granted_by TEXT NOT NULL, granted_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE TABLE role_assignment_history (
+	id UUID PRIMARY KEY DEFAULT gen_random_uuid(), user_id UUID NOT NULL, role TEXT NOT NULL,
+	granted_by TEXT NOT NULL, granted_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE TABLE groups (
+	id UUID PRIMARY KEY DEFAULT gen_random_uuid(), name TEXT NOT NULL, role TEXT CHECK (role IN ('user','tenant_admin')),
+	created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE TABLE group_members (
+	group_id UUID NOT NULL REFERENCES groups(id) ON DELETE CASCADE, user_id UUID NOT NULL REFERENCES users(id),
+	added_at TIMESTAMPTZ NOT NULL DEFAULT now(), PRIMARY KEY (group_id, user_id)
+);`
+
+func setupHandlerTest(t *testing.T, dbName string) (*Handler, *Store, *user.TenantUserStore, *pgxpool.Pool) {
+	t.Helper()
+	adminDSN := os.Getenv("TEST_ADMIN_DSN")
+	if adminDSN == "" {
+		t.Skip("TEST_ADMIN_DSN nicht gesetzt, Integrationstest uebersprungen")
+	}
+	ctx := context.Background()
+
+	adminPool, err := pgxpool.New(ctx, adminDSN)
+	if err != nil {
+		t.Fatalf("admin pool: %v", err)
+	}
+	_, _ = adminPool.Exec(ctx, fmt.Sprintf(`DROP DATABASE IF EXISTS %q`, dbName))
+	if _, err := adminPool.Exec(ctx, fmt.Sprintf(`CREATE DATABASE %q`, dbName)); err != nil {
+		t.Fatalf("testdatenbank anlegen: %v", err)
+	}
+
+	dsn := strings.Replace(adminDSN, "/postgres?", "/"+dbName+"?", 1)
+	pool, err := pgxpool.New(ctx, dsn)
+	if err != nil {
+		t.Fatalf("connect testdatenbank: %v", err)
+	}
+	if _, err := pool.Exec(ctx, handlerSchema); err != nil {
+		t.Fatalf("schema: %v", err)
+	}
+
+	t.Cleanup(func() {
+		pool.Close()
+		_, _ = adminPool.Exec(ctx, fmt.Sprintf(`DROP DATABASE IF EXISTS %q`, dbName))
+		adminPool.Close()
+	})
+
+	roleStore := NewStore(pool)
+	groupStore := NewGroupStore(pool)
+	return NewHandler(roleStore, groupStore), roleStore, user.NewTenantUserStore(pool), pool
+}
+
+func sessionCookieFor(t *testing.T, issuer *auth.TokenIssuer, userID string) *http.Cookie {
+	t.Helper()
+	token, err := issuer.Issue(userID, "acme")
+	if err != nil {
+		t.Fatalf("session-token ausstellen: %v", err)
+	}
+	return &http.Cookie{Name: auth.CookieName, Value: token}
+}
+
+// Akzeptanzkriterium 1: Rollen und ihre Grundrechte sind einsehbar.
+func TestListRoles(t *testing.T) {
+	h, roles, users, _ := setupHandlerTest(t, "rbac05_list_roles")
+	ctx := context.Background()
+	admin, err := users.Create(ctx, "admin@acme.example", "Admin")
+	if err != nil {
+		t.Fatalf("admin anlegen: %v", err)
+	}
+	if _, err := roles.Assign(ctx, admin.ID, RoleTenantAdmin, "system"); err != nil {
+		t.Fatalf("admin-rolle setzen: %v", err)
+	}
+
+	issuer := auth.NewTokenIssuer("test-secret")
+	req := httptest.NewRequest(http.MethodGet, "/rbac/roles", nil)
+	req.AddCookie(sessionCookieFor(t, issuer, admin.ID))
+	rec := httptest.NewRecorder()
+	auth.RequireAuth(issuer, h.ListRoles)(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200, body: %s", rec.Code, rec.Body.String())
+	}
+	var out []roleInfo
+	if err := json.Unmarshal(rec.Body.Bytes(), &out); err != nil {
+		t.Fatalf("response dekodieren: %v", err)
+	}
+	if len(out) != 2 {
+		t.Fatalf("erwartet 2 zuweisbare rollen (user, tenant_admin), habe %d", len(out))
+	}
+}
+
+// Akzeptanzkriterium 2 / Pruefung 2: Selbst-Eskalation wird abgewiesen.
+func TestAssignRole_RejectsSelfEscalation(t *testing.T) {
+	h, roles, users, _ := setupHandlerTest(t, "rbac05_self_escalation")
+	ctx := context.Background()
+	u, err := users.Create(ctx, "normal@acme.example", "Normaler Nutzer")
+	if err != nil {
+		t.Fatalf("nutzer anlegen: %v", err)
+	}
+	if _, err := roles.Assign(ctx, u.ID, RoleUser, "system"); err != nil {
+		t.Fatalf("ausgangsrolle setzen: %v", err)
+	}
+
+	issuer := auth.NewTokenIssuer("test-secret")
+	body, _ := json.Marshal(assignRoleRequest{UserID: u.ID, Role: RoleTenantAdmin})
+	req := httptest.NewRequest(http.MethodPost, "/rbac/users/role", bytes.NewReader(body))
+	req.AddCookie(sessionCookieFor(t, issuer, u.ID))
+	rec := httptest.NewRecorder()
+	auth.RequireAuth(issuer, h.AssignRole)(rec, req)
+
+	if rec.Code != http.StatusForbidden {
+		t.Fatalf("status = %d, want 403 (selbst-eskalation muss abgewiesen werden)", rec.Code)
+	}
+
+	// Rolle muss unveraendert geblieben sein.
+	assignment, err := roles.Get(ctx, u.ID)
+	if err != nil {
+		t.Fatalf("rolle laden: %v", err)
+	}
+	if assignment.Role != RoleUser {
+		t.Fatalf("rolle wurde trotz abgewiesener anfrage geaendert: %q", assignment.Role)
+	}
+}
+
+// Gegenprobe: ein Tenant-Admin darf EINEM ANDEREN Benutzer eine hoehere
+// Rolle zuweisen — nur die Selbst-Zuweisung ist gesperrt.
+func TestAssignRole_AdminCanPromoteOtherUser(t *testing.T) {
+	h, roles, users, _ := setupHandlerTest(t, "rbac05_promote_other")
+	ctx := context.Background()
+	admin, err := users.Create(ctx, "admin2@acme.example", "Admin")
+	if err != nil {
+		t.Fatalf("admin anlegen: %v", err)
+	}
+	if _, err := roles.Assign(ctx, admin.ID, RoleTenantAdmin, "system"); err != nil {
+		t.Fatalf("admin-rolle setzen: %v", err)
+	}
+	other, err := users.Create(ctx, "other@acme.example", "Anderer Nutzer")
+	if err != nil {
+		t.Fatalf("anderen nutzer anlegen: %v", err)
+	}
+
+	issuer := auth.NewTokenIssuer("test-secret")
+	body, _ := json.Marshal(assignRoleRequest{UserID: other.ID, Role: RoleTenantAdmin})
+	req := httptest.NewRequest(http.MethodPost, "/rbac/users/role", bytes.NewReader(body))
+	req.AddCookie(sessionCookieFor(t, issuer, admin.ID))
+	rec := httptest.NewRecorder()
+	auth.RequireAuth(issuer, h.AssignRole)(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200, body: %s", rec.Code, rec.Body.String())
+	}
+}
+
+// Akzeptanzkriterium 3: Aenderungen an Rechten sind nachvollziehbar.
+func TestRoleHistory_TracksAssignments(t *testing.T) {
+	h, roles, users, _ := setupHandlerTest(t, "rbac05_history")
+	ctx := context.Background()
+	admin, err := users.Create(ctx, "admin3@acme.example", "Admin")
+	if err != nil {
+		t.Fatalf("admin anlegen: %v", err)
+	}
+	if _, err := roles.Assign(ctx, admin.ID, RoleTenantAdmin, "system"); err != nil {
+		t.Fatalf("admin-rolle setzen: %v", err)
+	}
+	target, err := users.Create(ctx, "target@acme.example", "Zielnutzer")
+	if err != nil {
+		t.Fatalf("zielnutzer anlegen: %v", err)
+	}
+	if _, err := roles.Assign(ctx, target.ID, RoleUser, admin.ID); err != nil {
+		t.Fatalf("erste zuweisung: %v", err)
+	}
+	if _, err := roles.Assign(ctx, target.ID, RoleTenantAdmin, admin.ID); err != nil {
+		t.Fatalf("zweite zuweisung: %v", err)
+	}
+
+	issuer := auth.NewTokenIssuer("test-secret")
+	req := httptest.NewRequest(http.MethodGet, "/rbac/users/"+target.ID+"/history", nil)
+	req.AddCookie(sessionCookieFor(t, issuer, admin.ID))
+	rec := httptest.NewRecorder()
+	auth.RequireAuth(issuer, h.RoleHistory)(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200, body: %s", rec.Code, rec.Body.String())
+	}
+	var history []Assignment
+	if err := json.Unmarshal(rec.Body.Bytes(), &history); err != nil {
+		t.Fatalf("response dekodieren: %v", err)
+	}
+	if len(history) != 2 {
+		t.Fatalf("erwartet 2 historieneintraege, habe %d", len(history))
+	}
+}
+
+// Akzeptanzkriterium 2: Gruppen anlegen, Mitglieder zuordnen, Rolle zuweisen.
+func TestGroupWorkflow(t *testing.T) {
+	h, roles, users, _ := setupHandlerTest(t, "rbac05_group_workflow")
+	ctx := context.Background()
+	admin, err := users.Create(ctx, "admin4@acme.example", "Admin")
+	if err != nil {
+		t.Fatalf("admin anlegen: %v", err)
+	}
+	if _, err := roles.Assign(ctx, admin.ID, RoleTenantAdmin, "system"); err != nil {
+		t.Fatalf("admin-rolle setzen: %v", err)
+	}
+	member, err := users.Create(ctx, "member@acme.example", "Mitglied")
+	if err != nil {
+		t.Fatalf("mitglied anlegen: %v", err)
+	}
+
+	issuer := auth.NewTokenIssuer("test-secret")
+
+	createBody, _ := json.Marshal(createGroupRequest{Name: "Buchhaltung"})
+	createReq := httptest.NewRequest(http.MethodPost, "/rbac/groups", bytes.NewReader(createBody))
+	createReq.AddCookie(sessionCookieFor(t, issuer, admin.ID))
+	createRec := httptest.NewRecorder()
+	auth.RequireAuth(issuer, h.CreateGroup)(createRec, createReq)
+	if createRec.Code != http.StatusCreated {
+		t.Fatalf("create group: status = %d, body: %s", createRec.Code, createRec.Body.String())
+	}
+	var group Group
+	if err := json.Unmarshal(createRec.Body.Bytes(), &group); err != nil {
+		t.Fatalf("group-response dekodieren: %v", err)
+	}
+
+	roleBody, _ := json.Marshal(groupActionRequest{GroupID: group.ID, Role: RoleUser})
+	roleReq := httptest.NewRequest(http.MethodPost, "/rbac/groups/role", bytes.NewReader(roleBody))
+	roleReq.AddCookie(sessionCookieFor(t, issuer, admin.ID))
+	roleRec := httptest.NewRecorder()
+	auth.RequireAuth(issuer, h.SetGroupRole)(roleRec, roleReq)
+	if roleRec.Code != http.StatusOK {
+		t.Fatalf("set group role: status = %d, body: %s", roleRec.Code, roleRec.Body.String())
+	}
+
+	memberBody, _ := json.Marshal(groupActionRequest{GroupID: group.ID, UserID: member.ID})
+	memberReq := httptest.NewRequest(http.MethodPost, "/rbac/groups/members", bytes.NewReader(memberBody))
+	memberReq.AddCookie(sessionCookieFor(t, issuer, admin.ID))
+	memberRec := httptest.NewRecorder()
+	auth.RequireAuth(issuer, h.AddGroupMember)(memberRec, memberReq)
+	if memberRec.Code != http.StatusOK {
+		t.Fatalf("add member: status = %d, body: %s", memberRec.Code, memberRec.Body.String())
+	}
+
+	listReq := httptest.NewRequest(http.MethodGet, "/rbac/groups", nil)
+	listReq.AddCookie(sessionCookieFor(t, issuer, admin.ID))
+	listRec := httptest.NewRecorder()
+	auth.RequireAuth(issuer, h.ListGroups)(listRec, listReq)
+	if listRec.Code != http.StatusOK {
+		t.Fatalf("list groups: status = %d, body: %s", listRec.Code, listRec.Body.String())
+	}
+	var groups []groupWithMembers
+	if err := json.Unmarshal(listRec.Body.Bytes(), &groups); err != nil {
+		t.Fatalf("groups-response dekodieren: %v", err)
+	}
+	if len(groups) != 1 || len(groups[0].Members) != 1 || groups[0].Members[0] != member.ID {
+		t.Fatalf("erwartet 1 gruppe mit 1 mitglied (%s), habe %+v", member.ID, groups)
+	}
+}
+
+// Ohne Rechteverwaltungsberechtigung (normale 'user'-Rolle) wird jeder
+// Endpunkt abgewiesen — Tenant-Isolation ist strukturell (Modell C, siehe
+// GroupStore-Kommentar), diese Pruefung deckt die Rechte-Ebene ab.
+func TestRequireManageUsers_RejectsPlainUser(t *testing.T) {
+	h, roles, users, _ := setupHandlerTest(t, "rbac05_reject_plain")
+	ctx := context.Background()
+	u, err := users.Create(ctx, "plain@acme.example", "Normaler Nutzer")
+	if err != nil {
+		t.Fatalf("nutzer anlegen: %v", err)
+	}
+	if _, err := roles.Assign(ctx, u.ID, RoleUser, "system"); err != nil {
+		t.Fatalf("rolle setzen: %v", err)
+	}
+
+	issuer := auth.NewTokenIssuer("test-secret")
+	req := httptest.NewRequest(http.MethodGet, "/rbac/roles", nil)
+	req.AddCookie(sessionCookieFor(t, issuer, u.ID))
+	rec := httptest.NewRecorder()
+	auth.RequireAuth(issuer, h.ListRoles)(rec, req)
+
+	if rec.Code != http.StatusForbidden {
+		t.Fatalf("status = %d, want 403 fuer benutzer ohne rechteverwaltung", rec.Code)
+	}
+}

internal/rbac/role.go

@@ -0,0 +1,71 @@
+// Package rbac implementiert Core RBAC-01: das Rollenmodell mit
+// Grundrollen/-rechten, Hierarchie und Zuweisung. Die eigentliche
+// Durchsetzung (erlaubt/verboten je Request) ist RBAC-02, dieses Paket
+// liefert nur Modell + Zuweisung (Casbin-Prinzip: Policy-Modell getrennt
+// von der Entscheidungsfunktion).
+package rbac
+
+// Role ist eine der drei Grundrollen. Superadmin lebt mandantenuebergreifend
+// (siehe internal/user.SuperadminStore aus IAM-01) und wird deshalb NICHT
+// ueber Store (tenant-gescoped) zugewiesen — die Existenz eines Superadmin-
+// Kontos IST die Rollenzuweisung.
+type Role string
+
+const (
+	RoleSuperadmin  Role = "superadmin"
+	RoleTenantAdmin Role = "tenant_admin"
+	RoleUser        Role = "user"
+)
+
+type Permission string
+
+const (
+	PermSelfRead       Permission = "self.read"
+	PermSelfUpdate     Permission = "self.update"
+	PermManageUsers    Permission = "tenant.manage_users"
+	PermManageSettings Permission = "tenant.manage_settings"
+	PermManageTenants  Permission = "platform.manage_tenants"
+)
+
+// parent bildet die Rollenhierarchie ab (Akzeptanzkriterium 2): eine Rolle
+// erbt alle Rechte ihrer Elternrolle. tenant_admin erbt von user,
+// superadmin erbt von tenant_admin.
+var parent = map[Role]Role{
+	RoleTenantAdmin: RoleUser,
+	RoleSuperadmin:  RoleTenantAdmin,
+}
+
+// direct sind die einer Rolle direkt (ohne Vererbung) zugeordneten Rechte.
+var direct = map[Role][]Permission{
+	RoleUser:        {PermSelfRead, PermSelfUpdate},
+	RoleTenantAdmin: {PermManageUsers, PermManageSettings},
+	RoleSuperadmin:  {PermManageTenants},
+}
+
+// EffectivePermissions liefert die vollstaendige, ueber die Hierarchie
+// aufgeloeste Rechtemenge einer Rolle (Akzeptanzkriterium 2 / Pruefung 2).
+func EffectivePermissions(role Role) []Permission {
+	seen := make(map[Permission]bool)
+	var out []Permission
+
+	for r, ok := role, true; ok; r, ok = parent[r] {
+		for _, p := range direct[r] {
+			if !seen[p] {
+				seen[p] = true
+				out = append(out, p)
+			}
+		}
+	}
+	return out
+}
+
+// HasPermission prueft, ob eine Rolle (inklusive geerbter Rechte) ein
+// bestimmtes Recht besitzt.
+func HasPermission(role Role, perm Permission) bool {
+	for _, p := range EffectivePermissions(role) {
+		if p == perm {
+			return true
+		}
+	}
+	return false
+}

internal/rbac/role_test.go

@@ -0,0 +1,48 @@
+package rbac
+
+import "testing"
+
+func contains(perms []Permission, p Permission) bool {
+	for _, x := range perms {
+		if x == p {
+			return true
+		}
+	}
+	return false
+}
+
+// Akzeptanzkriterium 2 + Pruefung 2: Rollenhierarchie liefert die erwartete
+// effektive Rechtemenge.
+func TestEffectivePermissions_Inheritance(t *testing.T) {
+	userPerms := EffectivePermissions(RoleUser)
+	if !contains(userPerms, PermSelfRead) || !contains(userPerms, PermSelfUpdate) {
+		t.Fatalf("user sollte self.read/self.update haben, habe %v", userPerms)
+	}
+	if contains(userPerms, PermManageUsers) {
+		t.Fatal("user sollte KEIN tenant.manage_users haben")
+	}
+
+	adminPerms := EffectivePermissions(RoleTenantAdmin)
+	if !contains(adminPerms, PermSelfRead) || !contains(adminPerms, PermManageUsers) || !contains(adminPerms, PermManageSettings) {
+		t.Fatalf("tenant_admin sollte geerbte user-rechte + eigene rechte haben, habe %v", adminPerms)
+	}
+	if contains(adminPerms, PermManageTenants) {
+		t.Fatal("tenant_admin sollte KEIN platform.manage_tenants haben")
+	}
+
+	superPerms := EffectivePermissions(RoleSuperadmin)
+	for _, want := range []Permission{PermSelfRead, PermSelfUpdate, PermManageUsers, PermManageSettings, PermManageTenants} {
+		if !contains(superPerms, want) {
+			t.Fatalf("superadmin sollte %q haben (volle vererbte kette), habe %v", want, superPerms)
+		}
+	}
+}
+
+func TestHasPermission(t *testing.T) {
+	if !HasPermission(RoleTenantAdmin, PermSelfRead) {
+		t.Fatal("tenant_admin sollte geerbtes self.read haben")
+	}
+	if HasPermission(RoleUser, PermManageTenants) {
+		t.Fatal("user sollte platform.manage_tenants nicht haben")
+	}
+}

internal/rbac/store.go

@@ -0,0 +1,124 @@
+package rbac
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+var (
+	// ErrRoleNotAssignableInTenantScope wird geliefert, wenn versucht wird,
+	// eine mandantenuebergreifende Rolle (superadmin) ueber den tenant-
+	// gescopten Store zu vergeben — die erlaubte Matrix laesst hier nur
+	// user/tenant_admin zu (Akzeptanzkriterium 1 / Pruefung 1).
+	ErrRoleNotAssignableInTenantScope = errors.New("rbac: rolle ist in diesem geltungsbereich nicht zuweisbar")
+	ErrNotFound                       = errors.New("rbac: keine rollenzuweisung gefunden")
+)
+
+// assignableRoles ist die erlaubte Matrix fuer Store (tenant-gescoped).
+var assignableRoles = map[Role]bool{
+	RoleUser:        true,
+	RoleTenantAdmin: true,
+}
+
+type Assignment struct {
+	UserID    string
+	Role      Role
+	GrantedBy string
+}
+
+// Store verwaltet Rollenzuweisungen innerhalb GENAU EINER Tenant-Datenbank —
+// analog zu internal/user.TenantUserStore (Modell C: der Pool bestimmt den
+// Tenant, keine tenant_id-Spalte noetig).
+type Store struct {
+	pool *pgxpool.Pool
+}
+
+func NewStore(pool *pgxpool.Pool) *Store {
+	return &Store{pool: pool}
+}
+
+// Assign vergibt eine Rolle an einen Benutzer. grantedBy identifiziert den
+// Akteur, der die Zuweisung vorgenommen hat (Akzeptanzkriterium 3). Jede
+// Zuweisung wird zusaetzlich in role_assignment_history festgehalten, auch
+// wenn sie eine vorherige Rolle ersetzt.
+func (s *Store) Assign(ctx context.Context, userID string, role Role, grantedBy string) (Assignment, error) {
+	if !assignableRoles[role] {
+		return Assignment{}, ErrRoleNotAssignableInTenantScope
+	}
+	if grantedBy == "" {
+		return Assignment{}, errors.New("rbac: grantedBy darf nicht leer sein")
+	}
+
+	tx, err := s.pool.Begin(ctx)
+	if err != nil {
+		return Assignment{}, fmt.Errorf("transaktion starten: %w", err)
+	}
+	defer func() { _ = tx.Rollback(ctx) }()
+
+	if _, err := tx.Exec(ctx, `
+		INSERT INTO role_assignments (user_id, role, granted_by, granted_at)
+		VALUES ($1, $2, $3, now())
+		ON CONFLICT (user_id) DO UPDATE SET role = $2, granted_by = $3, granted_at = now()
+	`, userID, string(role), grantedBy); err != nil {
+		return Assignment{}, fmt.Errorf("rolle zuweisen: %w", err)
+	}
+
+	if _, err := tx.Exec(ctx, `
+		INSERT INTO role_assignment_history (user_id, role, granted_by, granted_at)
+		VALUES ($1, $2, $3, now())
+	`, userID, string(role), grantedBy); err != nil {
+		return Assignment{}, fmt.Errorf("historie schreiben: %w", err)
+	}
+
+	if err := tx.Commit(ctx); err != nil {
+		return Assignment{}, fmt.Errorf("transaktion committen: %w", err)
+	}
+
+	return Assignment{UserID: userID, Role: role, GrantedBy: grantedBy}, nil
+}
+
+func (s *Store) Get(ctx context.Context, userID string) (Assignment, error) {
+	var a Assignment
+	var role string
+	a.UserID = userID
+	if err := s.pool.QueryRow(ctx, `
+		SELECT role, granted_by FROM role_assignments WHERE user_id = $1
+	`, userID).Scan(&role, &a.GrantedBy); err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return Assignment{}, ErrNotFound
+		}
+		return Assignment{}, fmt.Errorf("rollenzuweisung lesen: %w", err)
+	}
+	a.Role = Role(role)
+	return a, nil
+}
+
+// History liefert jede Rollenzuweisung eines Benutzers in chronologischer
+// Reihenfolge — die Grundlage fuer "wer hat wann welche Rolle vergeben"
+// (Akzeptanzkriterium 3).
+func (s *Store) History(ctx context.Context, userID string) ([]Assignment, error) {
+	rows, err := s.pool.Query(ctx, `
+		SELECT role, granted_by FROM role_assignment_history
+		WHERE user_id = $1 ORDER BY granted_at
+	`, userID)
+	if err != nil {
+		return nil, fmt.Errorf("historie abfragen: %w", err)
+	}
+	defer rows.Close()
+
+	var out []Assignment
+	for rows.Next() {
+		var role string
+		a := Assignment{UserID: userID}
+		if err := rows.Scan(&role, &a.GrantedBy); err != nil {
+			return nil, fmt.Errorf("historieneintrag lesen: %w", err)
+		}
+		a.Role = Role(role)
+		out = append(out, a)
+	}
+	return out, rows.Err()
+}

internal/rbac/store_test.go

@@ -0,0 +1,144 @@
+package rbac
+
+import (
+	"context"
+	"errors"
+	"os"
+	"testing"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"gitea.perlbach24.de/scripte/nexarch/internal/user"
+)
+
+func setupStoreTest(t *testing.T) (*Store, string, func()) {
+	t.Helper()
+	adminDSN := os.Getenv("TEST_ADMIN_DSN")
+	if adminDSN == "" {
+		t.Skip("TEST_ADMIN_DSN nicht gesetzt, Integrationstest uebersprungen")
+	}
+	ctx := context.Background()
+
+	pool, err := pgxpool.New(ctx, adminDSN)
+	if err != nil {
+		t.Fatalf("pool: %v", err)
+	}
+	if _, err := pool.Exec(ctx, `
+		CREATE TABLE IF NOT EXISTS users (
+			id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+			email TEXT NOT NULL UNIQUE,
+			name TEXT NOT NULL,
+			status TEXT NOT NULL DEFAULT 'active',
+			created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+			updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+		);
+		CREATE TABLE IF NOT EXISTS role_assignments (
+			user_id UUID PRIMARY KEY REFERENCES users(id),
+			role TEXT NOT NULL CHECK (role IN ('user', 'tenant_admin')),
+			granted_by TEXT NOT NULL,
+			granted_at TIMESTAMPTZ NOT NULL DEFAULT now()
+		);
+		CREATE TABLE IF NOT EXISTS role_assignment_history (
+			id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+			user_id UUID NOT NULL,
+			role TEXT NOT NULL,
+			granted_by TEXT NOT NULL,
+			granted_at TIMESTAMPTZ NOT NULL DEFAULT now()
+		);
+	`); err != nil {
+		t.Fatalf("schema: %v", err)
+	}
+
+	userStore := user.NewTenantUserStore(pool)
+	u, err := userStore.Create(ctx, "rbac_test@example.com", "RBAC Test")
+	if err != nil {
+		t.Fatalf("testuser anlegen: %v", err)
+	}
+
+	cleanup := func() {
+		_, _ = pool.Exec(ctx, `DELETE FROM role_assignment_history WHERE user_id = $1`, u.ID)
+		_, _ = pool.Exec(ctx, `DELETE FROM role_assignments WHERE user_id = $1`, u.ID)
+		_, _ = pool.Exec(ctx, `DELETE FROM users WHERE id = $1`, u.ID)
+		pool.Close()
+	}
+	return NewStore(pool), u.ID, cleanup
+}
+
+// Akzeptanzkriterium 1: Grundrollen sind einem Benutzer je Tenant zuweisbar.
+func TestStore_AssignAndGet(t *testing.T) {
+	store, userID, cleanup := setupStoreTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	assigned, err := store.Assign(ctx, userID, RoleTenantAdmin, "admin@acme.example")
+	if err != nil {
+		t.Fatalf("assign: %v", err)
+	}
+	if assigned.Role != RoleTenantAdmin {
+		t.Fatalf("erwartet tenant_admin, habe %q", assigned.Role)
+	}
+
+	got, err := store.Get(ctx, userID)
+	if err != nil {
+		t.Fatalf("get: %v", err)
+	}
+	if got.Role != RoleTenantAdmin || got.GrantedBy != "admin@acme.example" {
+		t.Fatalf("zuweisung unerwartet: %+v", got)
+	}
+}
+
+// Akzeptanzkriterium 1 + Pruefung 1: Zuweisung ausserhalb der erlaubten
+// Matrix (superadmin im tenant-gescopten Store) wird abgewiesen.
+func TestStore_RejectsSuperadminOutsideAllowedMatrix(t *testing.T) {
+	store, userID, cleanup := setupStoreTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	_, err := store.Assign(ctx, userID, RoleSuperadmin, "admin@acme.example")
+	if !errors.Is(err, ErrRoleNotAssignableInTenantScope) {
+		t.Fatalf("erwartet ErrRoleNotAssignableInTenantScope, habe %v", err)
+	}
+
+	// Sicherstellen, dass der abgewiesene Versuch keine Zeile hinterlassen hat.
+	if _, err := store.Get(ctx, userID); !errors.Is(err, ErrNotFound) {
+		t.Fatalf("erwartet ErrNotFound nach abgewiesener zuweisung, habe %v", err)
+	}
+}
+
+func TestStore_RejectsUnknownRole(t *testing.T) {
+	store, userID, cleanup := setupStoreTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	if _, err := store.Assign(ctx, userID, Role("erfunden"), "admin@acme.example"); !errors.Is(err, ErrRoleNotAssignableInTenantScope) {
+		t.Fatalf("erwartet ErrRoleNotAssignableInTenantScope fuer unbekannte rolle, habe %v", err)
+	}
+}
+
+// Akzeptanzkriterium 3: Rollenzuweisung vollstaendig auditierbar.
+func TestStore_HistoryTracksWhoAndWhen(t *testing.T) {
+	store, userID, cleanup := setupStoreTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	if _, err := store.Assign(ctx, userID, RoleUser, "system"); err != nil {
+		t.Fatalf("assign 1: %v", err)
+	}
+	if _, err := store.Assign(ctx, userID, RoleTenantAdmin, "admin@acme.example"); err != nil {
+		t.Fatalf("assign 2: %v", err)
+	}
+
+	history, err := store.History(ctx, userID)
+	if err != nil {
+		t.Fatalf("history: %v", err)
+	}
+	if len(history) != 2 {
+		t.Fatalf("erwartet 2 historieneintraege, habe %d", len(history))
+	}
+	if history[0].Role != RoleUser || history[0].GrantedBy != "system" {
+		t.Fatalf("history[0] unerwartet: %+v", history[0])
+	}
+	if history[1].Role != RoleTenantAdmin || history[1].GrantedBy != "admin@acme.example" {
+		t.Fatalf("history[1] unerwartet: %+v", history[1])
+	}
+}

internal/resync/buffer.go

@@ -1,155 +0,0 @@
-// Package resync implementiert Core API-06: Wiederanlauf & Nachsynchro-
-// nisierung nach einem Core-Ausfall.
-//
-//   - Ein Modul puffert Audit-Events und Nutzungszaehler-Deltas LOKAL in
-//     Postgres (NICHT im Speicher — siehe "Bekannte Fehler vermeiden" im
-//     Ticket: ein erneuter Ausfall waehrend der Nachlieferung darf keine
-//     Daten verlieren, eine In-Memory-Queue wuerde das riskieren).
-//   - Ein Health-Check-getriggerter Worker erkennt die Core-Wiedererreich-
-//     barkeit SOFORT (nicht erst nach TTL-Ablauf, siehe StaleCache.Invalidate)
-//     und liefert die gepufferten Daten in ORIGINALER Reihenfolge, authenti-
-//     fiziert ueber das Service-Credential aus API-02
-//     (internal/moduleregistry.Registry.Authenticate).
-//
-// Dieses Paket dupliziert weder internal/audit (AUD-01) noch internal/usage
-// (LIC-03) — es liefert nur den Puffer- und Nachlieferungs-Mechanismus
-// DAVOR bzw. DANACH.
-package resync
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-	"time"
-
-	"github.com/jackc/pgx/v5/pgxpool"
-)
-
-// BufferedAuditEvent ist ein lokal gepuffertes Audit-Ereignis. Seq
-// garantiert die Wiederherstellung der urspruenglichen Reihenfolge
-// (Akzeptanzkriterium 2) unabhaengig von eventuellen Uhrzeit-Ungenauigkeiten.
-type BufferedAuditEvent struct {
-	ID         int64
-	Seq        int64
-	TenantSlug string
-	Actor      string
-	Action     string
-	Target     string
-	Metadata   map[string]any
-	CreatedAt  time.Time
-}
-
-// BufferedUsageDelta ist ein lokal gepuffertes Nutzungszaehler-Inkrement.
-type BufferedUsageDelta struct {
-	ID         int64
-	Seq        int64
-	TenantSlug string
-	Metric     string
-	Delta      int64
-	CreatedAt  time.Time
-}
-
-// Buffer ist die lokale, persistente Pufferqueue eines Moduls.
-type Buffer struct {
-	pool *pgxpool.Pool
-}
-
-func NewBuffer(pool *pgxpool.Pool) *Buffer {
-	return &Buffer{pool: pool}
-}
-
-// EnqueueAuditEvent puffert EIN Audit-Ereignis lokal — wird von einem
-// Fachmodul aufgerufen, wenn Core gerade nicht erreichbar ist (die
-// Erkennung "Core erreichbar oder nicht" ist NICHT Teil dieses Aufrufs,
-// siehe Worker).
-func (b *Buffer) EnqueueAuditEvent(ctx context.Context, tenantSlug, actor, action, target string, metadata map[string]any) error {
-	if metadata == nil {
-		metadata = map[string]any{}
-	}
-	metadataJSON, err := json.Marshal(metadata)
-	if err != nil {
-		return fmt.Errorf("metadata serialisieren: %w", err)
-	}
-	_, err = b.pool.Exec(ctx, `
-		INSERT INTO resync_audit_buffer (tenant_slug, actor, action, target, metadata)
-		VALUES ($1, $2, $3, $4, $5)
-	`, tenantSlug, actor, action, target, metadataJSON)
-	if err != nil {
-		return fmt.Errorf("audit-ereignis puffern: %w", err)
-	}
-	return nil
-}
-
-// EnqueueUsageDelta puffert EIN Nutzungszaehler-Inkrement lokal.
-func (b *Buffer) EnqueueUsageDelta(ctx context.Context, tenantSlug, metric string, delta int64) error {
-	_, err := b.pool.Exec(ctx, `
-		INSERT INTO resync_usage_buffer (tenant_slug, metric, delta)
-		VALUES ($1, $2, $3)
-	`, tenantSlug, metric, delta)
-	if err != nil {
-		return fmt.Errorf("nutzungsdelta puffern: %w", err)
-	}
-	return nil
-}
-
-// PendingAuditEvents liefert ALLE noch nicht zugestellten Audit-Events in
-// ORIGINALER Reihenfolge (Akzeptanzkriterium 2 / Pruefung 1).
-func (b *Buffer) PendingAuditEvents(ctx context.Context) ([]BufferedAuditEvent, error) {
-	rows, err := b.pool.Query(ctx, `
-		SELECT id, seq, tenant_slug, actor, action, target, metadata, created_at
-		FROM resync_audit_buffer ORDER BY seq
-	`)
-	if err != nil {
-		return nil, fmt.Errorf("gepufferte audit-events abfragen: %w", err)
-	}
-	defer rows.Close()
-
-	var out []BufferedAuditEvent
-	for rows.Next() {
-		var e BufferedAuditEvent
-		var metadataJSON []byte
-		if err := rows.Scan(&e.ID, &e.Seq, &e.TenantSlug, &e.Actor, &e.Action, &e.Target, &metadataJSON, &e.CreatedAt); err != nil {
-			return nil, fmt.Errorf("gepuffertes audit-event lesen: %w", err)
-		}
-		_ = json.Unmarshal(metadataJSON, &e.Metadata)
-		out = append(out, e)
-	}
-	return out, rows.Err()
-}
-
-// PendingUsageDeltas liefert ALLE noch nicht zugestellten Nutzungsdeltas.
-func (b *Buffer) PendingUsageDeltas(ctx context.Context) ([]BufferedUsageDelta, error) {
-	rows, err := b.pool.Query(ctx, `
-		SELECT id, seq, tenant_slug, metric, delta, created_at
-		FROM resync_usage_buffer ORDER BY seq
-	`)
-	if err != nil {
-		return nil, fmt.Errorf("gepufferte nutzungsdeltas abfragen: %w", err)
-	}
-	defer rows.Close()
-
-	var out []BufferedUsageDelta
-	for rows.Next() {
-		var d BufferedUsageDelta
-		if err := rows.Scan(&d.ID, &d.Seq, &d.TenantSlug, &d.Metric, &d.Delta, &d.CreatedAt); err != nil {
-			return nil, fmt.Errorf("gepuffertes nutzungsdelta lesen: %w", err)
-		}
-		out = append(out, d)
-	}
-	return out, rows.Err()
-}
-
-// RemoveAuditEvent entfernt EIN Audit-Event aus dem Puffer — wird NUR nach
-// von Core BESTAETIGTER Zustellung aufgerufen (Akzeptanzkriterium 2/3: erst
-// entfernen, wenn sicher zugestellt, sonst bleibt es fuer den naechsten
-// Versuch erhalten — kein Datenverlust bei erneutem Ausfall waehrend der
-// Nachlieferung).
-func (b *Buffer) RemoveAuditEvent(ctx context.Context, id int64) error {
-	_, err := b.pool.Exec(ctx, `DELETE FROM resync_audit_buffer WHERE id = $1`, id)
-	return err
-}
-
-func (b *Buffer) RemoveUsageDelta(ctx context.Context, id int64) error {
-	_, err := b.pool.Exec(ctx, `DELETE FROM resync_usage_buffer WHERE id = $1`, id)
-	return err
-}

internal/resync/handler.go

@@ -1,132 +0,0 @@
-package resync
-
-import (
-	"context"
-	"encoding/json"
-	"net/http"
-	"time"
-)
-
-// AuditRecorder ist die schmale Schnittstelle, ueber die Core empfangene
-// Audit-Events tatsaechlich persistiert. In Produktion durch internal/audit
-// (AUD-01, nicht Abhaengigkeit dieser Kachel) implementiert — dieses Paket
-// dupliziert dessen Validierungs-/Speicherlogik NICHT, sondern ruft sie nur
-// auf. Die Events werden vom Aufrufer sequenziell in PendingAuditEvents-
-// Reihenfolge uebergeben (Akzeptanzkriterium 2).
-type AuditRecorder interface {
-	Record(ctx context.Context, tenantSlug, actor, action, target string, metadata map[string]any, occurredAt time.Time) error
-}
-
-// UsageIncrementer ist die schmale Schnittstelle zu Core's Nutzungszaehler
-// (in Produktion internal/usage, LIC-03 — nicht Abhaengigkeit dieser
-// Kachel). Jedes gepufferte Delta wird GENAU EINMAL angewendet.
-type UsageIncrementer interface {
-	Increment(ctx context.Context, tenantSlug, metric string, delta int64) error
-}
-
-// CredentialAuthenticator ist die schmale Schnittstelle zu API-02s
-// Service-Credential-Pruefung (internal/moduleregistry.Registry.Authenticate).
-type CredentialAuthenticator interface {
-	Authenticate(ctx context.Context, clientID, secret string) (moduleName string, ok bool, err error)
-}
-
-// Handler nimmt nachgelieferte Audit-Events/Nutzungsdeltas auf der
-// Core-Seite entgegen — authentifiziert ueber dasselbe Service-Credential
-// wie jeder andere Modul-Core-Aufruf (Akzeptanzkriterium 2/3, "authentifiziert
-// ueber das in API-02 definierte Service-Credential").
-type Handler struct {
-	auth  CredentialAuthenticator
-	audit AuditRecorder
-	usage UsageIncrementer
-}
-
-func NewHandler(auth CredentialAuthenticator, audit AuditRecorder, usage UsageIncrementer) *Handler {
-	return &Handler{auth: auth, audit: audit, usage: usage}
-}
-
-type credentialHeader struct {
-	ClientID string `json:"client_id"`
-	Secret   string `json:"secret"`
-}
-
-func (h *Handler) authenticate(w http.ResponseWriter, r *http.Request) bool {
-	clientID := r.Header.Get("X-Nexarch-Client-Id")
-	secret := r.Header.Get("X-Nexarch-Client-Secret")
-	_, ok, err := h.auth.Authenticate(r.Context(), clientID, secret)
-	if err != nil || !ok {
-		http.Error(w, "ungueltiges service-credential", http.StatusUnauthorized)
-		return false
-	}
-	return true
-}
-
-type auditEventDTO struct {
-	TenantSlug string         `json:"tenant_slug"`
-	Actor      string         `json:"actor"`
-	Action     string         `json:"action"`
-	Target     string         `json:"target"`
-	Metadata   map[string]any `json:"metadata"`
-	OccurredAt time.Time      `json:"occurred_at"`
-}
-
-// AuditHandler nimmt EINE Liste gepufferter Audit-Events entgegen und
-// schreibt sie SEQUENZIELL in der gegebenen Reihenfolge fort
-// (Akzeptanzkriterium 2 / Pruefung 1: Vollstaendigkeit + Reihenfolge).
-// Bricht die Verarbeitung bei einem Fehler ab und meldet, wie viele Events
-// bereits sicher geschrieben wurden — der Aufrufer (Worker) entfernt aus
-// seinem lokalen Puffer NUR die bestaetigt geschriebenen Events.
-func (h *Handler) AuditHandler(w http.ResponseWriter, r *http.Request) {
-	if !h.authenticate(w, r) {
-		return
-	}
-	var events []auditEventDTO
-	if err := json.NewDecoder(r.Body).Decode(&events); err != nil {
-		http.Error(w, "ungueltiger anfrage-koerper", http.StatusBadRequest)
-		return
-	}
-
-	written := 0
-	for _, e := range events {
-		if err := h.audit.Record(r.Context(), e.TenantSlug, e.Actor, e.Action, e.Target, e.Metadata, e.OccurredAt); err != nil {
-			break
-		}
-		written++
-	}
-
-	writeJSON(w, map[string]int{"written": written})
-}
-
-type usageDeltaDTO struct {
-	TenantSlug string `json:"tenant_slug"`
-	Metric     string `json:"metric"`
-	Delta      int64  `json:"delta"`
-}
-
-// UsageHandler wendet JEDES gepufferte Delta GENAU EINMAL an
-// (Akzeptanzkriterium 3 / Pruefung 2: keine Doppelzaehlung) — der Aufrufer
-// entfernt aus seinem lokalen Puffer nur die bestaetigt uebernommenen Deltas.
-func (h *Handler) UsageHandler(w http.ResponseWriter, r *http.Request) {
-	if !h.authenticate(w, r) {
-		return
-	}
-	var deltas []usageDeltaDTO
-	if err := json.NewDecoder(r.Body).Decode(&deltas); err != nil {
-		http.Error(w, "ungueltiger anfrage-koerper", http.StatusBadRequest)
-		return
-	}
-
-	applied := 0
-	for _, d := range deltas {
-		if err := h.usage.Increment(r.Context(), d.TenantSlug, d.Metric, d.Delta); err != nil {
-			break
-		}
-		applied++
-	}
-
-	writeJSON(w, map[string]int{"applied": applied})
-}
-
-func writeJSON(w http.ResponseWriter, body any) {
-	w.Header().Set("Content-Type", "application/json")
-	_ = json.NewEncoder(w).Encode(body)
-}

internal/resync/resync_test.go

@@ -1,320 +0,0 @@
-package resync
-
-import (
-	"context"
-	"fmt"
-	"net/http"
-	"net/http/httptest"
-	"os"
-	"sync"
-	"testing"
-	"time"
-
-	"github.com/jackc/pgx/v5/pgxpool"
-
-	"gitea.perlbach24.de/scripte/nexarch/internal/flag"
-	"gitea.perlbach24.de/scripte/nexarch/internal/moduleregistry"
-)
-
-// fakeAudit steht fuer internal/audit.Log (AUD-01, nicht Abhaengigkeit
-// dieser Kachel) — zeichnet Aufrufe in Empfangsreihenfolge auf, damit
-// Vollstaendigkeit UND Reihenfolge geprueft werden koennen.
-type fakeAudit struct {
-	mu     sync.Mutex
-	events []auditEventDTO
-	failAt int // -1 = nie fehlschlagen; sonst: ab diesem Index (0-basiert) schlaegt Record fehl
-}
-
-func (f *fakeAudit) Record(ctx context.Context, tenantSlug, actor, action, target string, metadata map[string]any, occurredAt time.Time) error {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	if f.failAt >= 0 && len(f.events) == f.failAt {
-		return fmt.Errorf("simulierter core-ausfall waehrend der nachlieferung")
-	}
-	f.events = append(f.events, auditEventDTO{TenantSlug: tenantSlug, Actor: actor, Action: action, Target: target, Metadata: metadata, OccurredAt: occurredAt})
-	return nil
-}
-
-// fakeUsage steht fuer internal/usage.Store (LIC-03, nicht Abhaengigkeit
-// dieser Kachel) — summiert Deltas wie der echte Store.
-type fakeUsage struct {
-	mu     sync.Mutex
-	totals map[string]int64
-}
-
-func newFakeUsage() *fakeUsage { return &fakeUsage{totals: map[string]int64{}} }
-
-func (f *fakeUsage) Increment(ctx context.Context, tenantSlug, metric string, delta int64) error {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	f.totals[tenantSlug+"|"+metric] += delta
-	return nil
-}
-
-func setupTest(t *testing.T) (*Buffer, *pgxpool.Pool, func()) {
-	t.Helper()
-	adminDSN := os.Getenv("TEST_ADMIN_DSN")
-	if adminDSN == "" {
-		t.Skip("TEST_ADMIN_DSN nicht gesetzt, Integrationstest uebersprungen")
-	}
-	ctx := context.Background()
-
-	pool, err := pgxpool.New(ctx, adminDSN)
-	if err != nil {
-		t.Fatalf("pool: %v", err)
-	}
-	if _, err := pool.Exec(ctx, `
-		CREATE TABLE IF NOT EXISTS resync_audit_buffer (
-			id BIGSERIAL PRIMARY KEY, seq BIGSERIAL, tenant_slug TEXT NOT NULL, actor TEXT NOT NULL,
-			action TEXT NOT NULL, target TEXT NOT NULL DEFAULT '', metadata JSONB NOT NULL DEFAULT '{}',
-			created_at TIMESTAMPTZ NOT NULL DEFAULT now()
-		);
-		CREATE TABLE IF NOT EXISTS resync_usage_buffer (
-			id BIGSERIAL PRIMARY KEY, seq BIGSERIAL, tenant_slug TEXT NOT NULL, metric TEXT NOT NULL,
-			delta BIGINT NOT NULL, created_at TIMESTAMPTZ NOT NULL DEFAULT now()
-		);
-		CREATE TABLE IF NOT EXISTS feature_flags (
-			key TEXT PRIMARY KEY, enabled BOOLEAN NOT NULL DEFAULT false,
-			rollout_percentage INT NOT NULL DEFAULT 0, target_tenant_slugs TEXT[] NOT NULL DEFAULT '{}',
-			updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
-		);
-		CREATE TABLE IF NOT EXISTS modules (
-			name TEXT PRIMARY KEY, version TEXT NOT NULL CHECK (version <> ''),
-			required_flags TEXT[] NOT NULL DEFAULT '{}', registered_at TIMESTAMPTZ NOT NULL DEFAULT now()
-		);
-		CREATE TABLE IF NOT EXISTS module_credentials (
-			module_name TEXT PRIMARY KEY REFERENCES modules(name),
-			client_id TEXT NOT NULL UNIQUE, secret_hash BYTEA NOT NULL,
-			issued_at TIMESTAMPTZ NOT NULL DEFAULT now()
-		);
-	`); err != nil {
-		t.Fatalf("schema: %v", err)
-	}
-
-	cleanup := func() { pool.Close() }
-	return NewBuffer(pool), pool, cleanup
-}
-
-func uniqueModuleName() string {
-	return fmt.Sprintf("resync-test-%d", time.Now().UnixNano())
-}
-
-// setupModuleCredential registriert ein echtes Modul + Service-Credential
-// ueber internal/moduleregistry (API-02) — dieselbe Authentifizierung wird
-// vom Handler tatsaechlich geprueft, kein Mock.
-func setupModuleCredential(t *testing.T, pool *pgxpool.Pool) (registry *moduleregistry.Registry, clientID, secret string) {
-	t.Helper()
-	ctx := context.Background()
-	flagService := flag.NewService(flag.NewStore(pool), 10*time.Millisecond)
-	registry = moduleregistry.NewRegistry(pool, flagService)
-	name := uniqueModuleName()
-	if _, err := registry.Register(ctx, name, "1.0.0", nil); err != nil {
-		t.Fatalf("modul registrieren: %v", err)
-	}
-	clientID, secret, err := registry.Provision(ctx, name)
-	if err != nil {
-		t.Fatalf("credential provisionieren: %v", err)
-	}
-	return registry, clientID, secret
-}
-
-// Akzeptanzkriterium 2 + Pruefung 1: waehrend eines simulierten Ausfalls
-// lokal gepufferte Audit-Events sind nach Wiederanlauf vollstaendig und in
-// korrekter Reihenfolge in Core's Audit-Log vorhanden.
-func TestFlushAll_DeliversBufferedAuditEventsCompleteAndInOrder(t *testing.T) {
-	buffer, pool, cleanup := setupTest(t)
-	defer cleanup()
-	ctx := context.Background()
-	registry, clientID, secret := setupModuleCredential(t, pool)
-
-	tenantSlug := "acme"
-	// Ereignisse "waehrend core down" lokal puffern.
-	actions := []string{"login", "upload", "delete", "logout"}
-	for _, action := range actions {
-		if err := buffer.EnqueueAuditEvent(ctx, tenantSlug, "user-1", action, "res-1", nil); err != nil {
-			t.Fatalf("enqueue %s: %v", action, err)
-		}
-	}
-
-	audit := &fakeAudit{failAt: -1}
-	usage := newFakeUsage()
-	handler := NewHandler(registry, audit, usage)
-
-	mux := http.NewServeMux()
-	mux.HandleFunc("/internal/resync/audit", handler.AuditHandler)
-	mux.HandleFunc("/internal/resync/usage", handler.UsageHandler)
-	mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(http.StatusOK) })
-	server := httptest.NewServer(mux)
-	defer server.Close()
-
-	client := NewCoreClient(server.URL, clientID, secret)
-	worker := NewWorker(buffer, client)
-
-	if err := worker.FlushAll(ctx); err != nil {
-		t.Fatalf("flushall: %v", err)
-	}
-
-	audit.mu.Lock()
-	defer audit.mu.Unlock()
-	if len(audit.events) != len(actions) {
-		t.Fatalf("erwartet %d zugestellte events, habe %d", len(actions), len(audit.events))
-	}
-	for i, e := range audit.events {
-		if e.Action != actions[i] {
-			t.Fatalf("reihenfolge falsch: position %d = %q, want %q", i, e.Action, actions[i])
-		}
-	}
-
-	// Puffer muss nach bestaetigter Zustellung leer sein.
-	remaining, err := buffer.PendingAuditEvents(ctx)
-	if err != nil {
-		t.Fatalf("pending: %v", err)
-	}
-	if len(remaining) != 0 {
-		t.Fatalf("erwartet leeren puffer nach bestaetigter zustellung, habe %d verbleibende", len(remaining))
-	}
-}
-
-// Bekannter-Fehler-Praevention: bricht die Zustellung waehrend der
-// Nachlieferung erneut ab (Core faellt wieder aus), bleiben die NICHT
-// bestaetigten Events sicher im Puffer erhalten statt verloren zu gehen.
-func TestFlushAll_KeepsUnconfirmedEventsInBufferOnPartialFailure(t *testing.T) {
-	buffer, pool, cleanup := setupTest(t)
-	defer cleanup()
-	ctx := context.Background()
-	registry, clientID, secret := setupModuleCredential(t, pool)
-
-	for i := 0; i < 5; i++ {
-		if err := buffer.EnqueueAuditEvent(ctx, "acme", "user-1", fmt.Sprintf("action-%d", i), "", nil); err != nil {
-			t.Fatalf("enqueue %d: %v", i, err)
-		}
-	}
-
-	// Core-Fake schlaegt AB dem 3. Event fehl -> simuliert erneuten Ausfall
-	// mitten in der Nachlieferung.
-	audit := &fakeAudit{failAt: 3}
-	handler := NewHandler(registry, audit, newFakeUsage())
-	mux := http.NewServeMux()
-	mux.HandleFunc("/internal/resync/audit", handler.AuditHandler)
-	mux.HandleFunc("/internal/resync/usage", handler.UsageHandler)
-	server := httptest.NewServer(mux)
-	defer server.Close()
-
-	client := NewCoreClient(server.URL, clientID, secret)
-	worker := NewWorker(buffer, client)
-
-	if err := worker.FlushAll(ctx); err == nil {
-		t.Fatal("erwartet fehler, da core nur teilweise bestaetigt hat")
-	}
-
-	remaining, err := buffer.PendingAuditEvents(ctx)
-	if err != nil {
-		t.Fatalf("pending: %v", err)
-	}
-	if len(remaining) != 2 {
-		t.Fatalf("erwartet 2 verbleibende (nicht bestaetigte) events im puffer, habe %d", len(remaining))
-	}
-}
-
-// Akzeptanzkriterium 3 + Pruefung 2: Nutzungszaehler-Differenz aus der
-// Ausfallzeit wird korrekt nachgebucht, ein wiederholter (fehlerhafter)
-// Flush-Versuch fuehrt NICHT zu Doppelzaehlung, weil bereits bestaetigte
-// Deltas aus dem Puffer entfernt sind.
-func TestFlushAll_AppliesUsageDeltasWithoutDoubleCounting(t *testing.T) {
-	buffer, pool, cleanup := setupTest(t)
-	defer cleanup()
-	ctx := context.Background()
-	registry, clientID, secret := setupModuleCredential(t, pool)
-
-	deltas := []int64{3, 5, 2}
-	var want int64
-	for _, d := range deltas {
-		want += d
-		if err := buffer.EnqueueUsageDelta(ctx, "acme", "api_calls", d); err != nil {
-			t.Fatalf("enqueue delta %d: %v", d, err)
-		}
-	}
-
-	usage := newFakeUsage()
-	handler := NewHandler(registry, &fakeAudit{failAt: -1}, usage)
-	mux := http.NewServeMux()
-	mux.HandleFunc("/internal/resync/audit", handler.AuditHandler)
-	mux.HandleFunc("/internal/resync/usage", handler.UsageHandler)
-	server := httptest.NewServer(mux)
-	defer server.Close()
-
-	client := NewCoreClient(server.URL, clientID, secret)
-	worker := NewWorker(buffer, client)
-
-	if err := worker.FlushAll(ctx); err != nil {
-		t.Fatalf("flushall 1: %v", err)
-	}
-
-	usage.mu.Lock()
-	got := usage.totals["acme|api_calls"]
-	usage.mu.Unlock()
-	if got != want {
-		t.Fatalf("nutzungsstand nach nachbuchung = %d, want %d", got, want)
-	}
-
-	// Ein zweiter Flush-Versuch (z.B. redundanter Retry) darf NICHTS mehr
-	// nachbuchen, da der Puffer bereits geleert wurde.
-	if err := worker.FlushAll(ctx); err != nil {
-		t.Fatalf("flushall 2: %v", err)
-	}
-	usage.mu.Lock()
-	got2 := usage.totals["acme|api_calls"]
-	usage.mu.Unlock()
-	if got2 != want {
-		t.Fatalf("nutzungsstand nach redundantem zweiten flush = %d, want unveraendert %d (keine doppelzaehlung)", got2, want)
-	}
-}
-
-// Akzeptanzkriterium 1 + Pruefung 3: bei erkannter Core-Wiedererreichbarkeit
-// wird der Cache SOFORT invalidiert (naechster Zugriff refetcht), nicht
-// erst nach TTL-Ablauf — Latenz wird gemessen und liegt weit unter einer
-// langen TTL.
-func TestCheckAndSync_InvalidatesCacheImmediatelyOnRecovery(t *testing.T) {
-	buffer, pool, cleanup := setupTest(t)
-	defer cleanup()
-	registry, clientID, secret := setupModuleCredential(t, pool)
-	_ = registry
-
-	mux := http.NewServeMux()
-	mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(http.StatusOK) })
-	server := httptest.NewServer(mux)
-	defer server.Close()
-
-	client := NewCoreClient(server.URL, clientID, secret)
-	worker := NewWorker(buffer, client)
-
-	invalidated := false
-	var mu sync.Mutex
-	worker.OnReachable(func() {
-		mu.Lock()
-		invalidated = true
-		mu.Unlock()
-	})
-
-	start := time.Now()
-	becameReachable, err := worker.CheckAndSync(context.Background())
-	elapsed := time.Since(start)
-	if err != nil {
-		t.Fatalf("checkandsync: %v", err)
-	}
-	if !becameReachable {
-		t.Fatal("erwartet erkannten uebergang zu 'erreichbar' beim ersten erfolgreichen check")
-	}
-
-	mu.Lock()
-	defer mu.Unlock()
-	if !invalidated {
-		t.Fatal("erwartet sofortigen cache-invalidierungs-callback bei core-wiedererreichbarkeit")
-	}
-	// Zielwert: deutlich unter einer typischen TTL (z.B. 5s beim
-	// Feature-Flag-Cache, LIC-02) — hier im Millisekundenbereich, da rein
-	// lokal ohne Netzwerk-Overhead.
-	if elapsed > time.Second {
-		t.Fatalf("cache-invalidierung brauchte %s, erwartet deutlich unter 1s", elapsed)
-	}
-}

internal/resync/worker.go

@@ -1,220 +0,0 @@
-package resync
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"fmt"
-	"net/http"
-	"time"
-)
-
-// CoreClient ist der modul-seitige HTTP-Client fuer die Nachlieferung,
-// authentifiziert ueber dasselbe Service-Credential wie jeder andere
-// Modul-Core-Aufruf (API-02).
-type CoreClient struct {
-	BaseURL  string
-	ClientID string
-	Secret   string
-	HTTP     *http.Client
-}
-
-func NewCoreClient(baseURL, clientID, secret string) *CoreClient {
-	return &CoreClient{BaseURL: baseURL, ClientID: clientID, Secret: secret, HTTP: &http.Client{Timeout: 5 * time.Second}}
-}
-
-func (c *CoreClient) post(ctx context.Context, path string, body any) (*http.Response, error) {
-	payload, err := json.Marshal(body)
-	if err != nil {
-		return nil, fmt.Errorf("payload serialisieren: %w", err)
-	}
-	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.BaseURL+path, bytes.NewReader(payload))
-	if err != nil {
-		return nil, err
-	}
-	req.Header.Set("Content-Type", "application/json")
-	req.Header.Set("X-Nexarch-Client-Id", c.ClientID)
-	req.Header.Set("X-Nexarch-Client-Secret", c.Secret)
-	return c.HTTP.Do(req)
-}
-
-// HealthCheck prueft, ob Core erreichbar ist — dieselbe Konvention wie
-// internal/health (OPS-01): HTTP 200 auf einem Health-Endpunkt.
-func (c *CoreClient) HealthCheck(ctx context.Context) bool {
-	req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.BaseURL+"/healthz", nil)
-	if err != nil {
-		return false
-	}
-	resp, err := c.HTTP.Do(req)
-	if err != nil {
-		return false
-	}
-	defer resp.Body.Close()
-	return resp.StatusCode == http.StatusOK
-}
-
-// Worker erkennt Core-Wiedererreichbarkeit und stoesst DANN sofort
-// (Akzeptanzkriterium 1) sowohl registrierte Cache-Invalidierungen als auch
-// das Nachliefern des lokalen Puffers an.
-type Worker struct {
-	buffer      *Buffer
-	client      *CoreClient
-	onReachable []func()
-	wasDown     bool
-}
-
-func NewWorker(buffer *Buffer, client *CoreClient) *Worker {
-	return &Worker{buffer: buffer, client: client, wasDown: true} // Start pessimistisch: erster erfolgreicher Check zaehlt als "Wiedererreichbarkeit".
-}
-
-// OnReachable registriert einen Callback, der bei jeder erkannten
-// Core-Wiedererreichbarkeit sofort ausgefuehrt wird — z.B.
-// moduletrust.StaleCache[T].Invalidate, damit der naechste Zugriff sofort
-// neu abruft statt auf TTL-Ablauf zu warten (Akzeptanzkriterium 1).
-func (w *Worker) OnReachable(fn func()) {
-	w.onReachable = append(w.onReachable, fn)
-}
-
-// CheckAndSync fuehrt EINEN Zyklus aus: Erreichbarkeit pruefen, bei
-// erkanntem UEBERGANG "nicht erreichbar -> erreichbar" sofort die
-// registrierten Callbacks ausloesen und den Puffer nachliefern. Gibt
-// zurueck, ob ein Wiederanlauf in diesem Aufruf erkannt wurde (fuer
-// Latenzmessung in Tests, Pruefung 3).
-func (w *Worker) CheckAndSync(ctx context.Context) (becameReachable bool, err error) {
-	reachable := w.client.HealthCheck(ctx)
-	if !reachable {
-		w.wasDown = true
-		return false, nil
-	}
-
-	justRecovered := w.wasDown
-	w.wasDown = false
-	if !justRecovered {
-		return false, nil
-	}
-
-	for _, fn := range w.onReachable {
-		fn()
-	}
-
-	if err := w.FlushAll(ctx); err != nil {
-		return true, err
-	}
-	return true, nil
-}
-
-// FlushAll liefert ZUERST alle gepufferten Audit-Events (in Reihenfolge),
-// DANN alle gepufferten Nutzungsdeltas nach. Jedes Element wird aus dem
-// lokalen Puffer NUR entfernt, wenn Core es bestaetigt hat — bricht die
-// Uebertragung vorzeitig ab (Core faellt waehrend der Nachlieferung erneut
-// aus), bleibt der Rest sicher im Postgres-Puffer erhalten
-// (Akzeptanzkriterium 2/3, "Bekannte Fehler vermeiden").
-func (w *Worker) FlushAll(ctx context.Context) error {
-	if err := w.flushAuditEvents(ctx); err != nil {
-		return err
-	}
-	return w.flushUsageDeltas(ctx)
-}
-
-func (w *Worker) flushAuditEvents(ctx context.Context) error {
-	events, err := w.buffer.PendingAuditEvents(ctx)
-	if err != nil {
-		return err
-	}
-	if len(events) == 0 {
-		return nil
-	}
-
-	dtos := make([]auditEventDTO, len(events))
-	for i, e := range events {
-		dtos[i] = auditEventDTO{
-			TenantSlug: e.TenantSlug, Actor: e.Actor, Action: e.Action, Target: e.Target,
-			Metadata: e.Metadata, OccurredAt: e.CreatedAt,
-		}
-	}
-
-	resp, err := w.client.post(ctx, "/internal/resync/audit", dtos)
-	if err != nil {
-		return fmt.Errorf("audit-nachlieferung: %w", err)
-	}
-	defer resp.Body.Close()
-	if resp.StatusCode != http.StatusOK {
-		return fmt.Errorf("audit-nachlieferung: unerwarteter status %d", resp.StatusCode)
-	}
-
-	var ack struct {
-		Written int `json:"written"`
-	}
-	if err := json.NewDecoder(resp.Body).Decode(&ack); err != nil {
-		return fmt.Errorf("audit-bestaetigung lesen: %w", err)
-	}
-
-	// NUR die von Core bestaetigt geschriebenen Events entfernen — sie sind
-	// nach PendingAuditEvents-Reihenfolge sortiert, die ersten `Written`
-	// Eintraege entsprechen also genau den bestaetigten.
-	for i := 0; i < ack.Written; i++ {
-		if err := w.buffer.RemoveAuditEvent(ctx, events[i].ID); err != nil {
-			return fmt.Errorf("bestaetigtes audit-event aus puffer entfernen: %w", err)
-		}
-	}
-	if ack.Written < len(events) {
-		return fmt.Errorf("core hat nur %d von %d audit-events bestaetigt", ack.Written, len(events))
-	}
-	return nil
-}
-
-func (w *Worker) flushUsageDeltas(ctx context.Context) error {
-	deltas, err := w.buffer.PendingUsageDeltas(ctx)
-	if err != nil {
-		return err
-	}
-	if len(deltas) == 0 {
-		return nil
-	}
-
-	dtos := make([]usageDeltaDTO, len(deltas))
-	for i, d := range deltas {
-		dtos[i] = usageDeltaDTO{TenantSlug: d.TenantSlug, Metric: d.Metric, Delta: d.Delta}
-	}
-
-	resp, err := w.client.post(ctx, "/internal/resync/usage", dtos)
-	if err != nil {
-		return fmt.Errorf("nutzungs-nachlieferung: %w", err)
-	}
-	defer resp.Body.Close()
-	if resp.StatusCode != http.StatusOK {
-		return fmt.Errorf("nutzungs-nachlieferung: unerwarteter status %d", resp.StatusCode)
-	}
-
-	var ack struct {
-		Applied int `json:"applied"`
-	}
-	if err := json.NewDecoder(resp.Body).Decode(&ack); err != nil {
-		return fmt.Errorf("nutzungs-bestaetigung lesen: %w", err)
-	}
-
-	for i := 0; i < ack.Applied; i++ {
-		if err := w.buffer.RemoveUsageDelta(ctx, deltas[i].ID); err != nil {
-			return fmt.Errorf("bestaetigtes nutzungsdelta aus puffer entfernen: %w", err)
-		}
-	}
-	if ack.Applied < len(deltas) {
-		return fmt.Errorf("core hat nur %d von %d nutzungsdeltas bestaetigt", ack.Applied, len(deltas))
-	}
-	return nil
-}
-
-// Run fuehrt CheckAndSync in festen Abstaenden aus — die "kurze, definierte
-// Zeitspanne" aus Akzeptanzkriterium 1 ist dieses Poll-Intervall.
-func (w *Worker) Run(ctx context.Context, interval time.Duration) {
-	ticker := time.NewTicker(interval)
-	defer ticker.Stop()
-	for {
-		select {
-		case <-ctx.Done():
-			return
-		case <-ticker.C:
-			_, _ = w.CheckAndSync(ctx)
-		}
-	}
-}

internal/user/handler.go

@@ -0,0 +1,66 @@
+package user
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+)
+
+// Handler stellt die CRUD-API fuer Benutzerkonten bereit (IAM-01-Auftrag).
+// Auth/Sessions (IAM-02) und Rollen (RBAC-01) sind ausdruecklich nicht Teil
+// dieser Kachel und daher hier noch nicht angebunden.
+type Handler struct {
+	users       *TenantUserStore
+	superadmins *SuperadminStore
+}
+
+func NewHandler(users *TenantUserStore, superadmins *SuperadminStore) *Handler {
+	return &Handler{users: users, superadmins: superadmins}
+}
+
+type createUserRequest struct {
+	Email string `json:"email"`
+	Name  string `json:"name"`
+}
+
+func (h *Handler) CreateUser(w http.ResponseWriter, r *http.Request) {
+	var req createUserRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		http.Error(w, "ungueltige Anfrage", http.StatusBadRequest)
+		return
+	}
+
+	u, err := h.users.Create(r.Context(), req.Email, req.Name)
+	writeUserResult(w, u, err)
+}
+
+// CreateSuperadmin legt ein mandantenuebergreifendes Superadmin-Konto an —
+// bewusst ein eigener Endpunkt statt eines Tenant-Parameters mit Null-Wert.
+func (h *Handler) CreateSuperadmin(w http.ResponseWriter, r *http.Request) {
+	var req createUserRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		http.Error(w, "ungueltige Anfrage", http.StatusBadRequest)
+		return
+	}
+
+	u, err := h.superadmins.Create(r.Context(), req.Email, req.Name)
+	writeUserResult(w, u, err)
+}
+
+func writeUserResult(w http.ResponseWriter, u User, err error) {
+	if err != nil {
+		switch {
+		case errors.Is(err, ErrInvalidEmail), errors.Is(err, ErrEmailTaken):
+			http.Error(w, err.Error(), http.StatusBadRequest)
+		case errors.Is(err, ErrNotFound):
+			http.Error(w, err.Error(), http.StatusNotFound)
+		default:
+			http.Error(w, "benutzer konnte nicht verarbeitet werden", http.StatusInternalServerError)
+		}
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(http.StatusCreated)
+	_ = json.NewEncoder(w).Encode(u)
+}

internal/user/store_test.go

@@ -0,0 +1,173 @@
+package user
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// setupTestDB legt eine frische, isolierte Testdatenbank an, wendet die
+// uebergebene Migration an und liefert einen verbundenen Pool. Wird ohne
+// TEST_ADMIN_DSN uebersprungen — siehe internal/tenant/provisioner_test.go
+// fuer dasselbe Muster.
+func setupTestDB(t *testing.T, dbName, schemaSQL string) *pgxpool.Pool {
+	t.Helper()
+
+	adminDSN := os.Getenv("TEST_ADMIN_DSN")
+	if adminDSN == "" {
+		t.Skip("TEST_ADMIN_DSN nicht gesetzt, Integrationstest uebersprungen")
+	}
+	ctx := context.Background()
+
+	adminPool, err := pgxpool.New(ctx, adminDSN)
+	if err != nil {
+		t.Fatalf("admin pool: %v", err)
+	}
+
+	_, _ = adminPool.Exec(ctx, fmt.Sprintf(`DROP DATABASE IF EXISTS %q`, dbName))
+	if _, err := adminPool.Exec(ctx, fmt.Sprintf(`CREATE DATABASE %q`, dbName)); err != nil {
+		t.Fatalf("testdatenbank anlegen: %v", err)
+	}
+
+	dsn := strings.Replace(adminDSN, "/postgres?", "/"+dbName+"?", 1)
+	pool, err := pgxpool.New(ctx, dsn)
+	if err != nil {
+		t.Fatalf("connect testdatenbank: %v", err)
+	}
+
+	if _, err := pool.Exec(ctx, schemaSQL); err != nil {
+		t.Fatalf("schema anwenden: %v", err)
+	}
+
+	t.Cleanup(func() {
+		pool.Close()
+		_, _ = adminPool.Exec(ctx, fmt.Sprintf(`DROP DATABASE IF EXISTS %q`, dbName))
+		adminPool.Close()
+	})
+
+	return pool
+}
+
+const usersSchema = `
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+CREATE TABLE users (
+	id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+	email TEXT NOT NULL UNIQUE,
+	name TEXT NOT NULL,
+	status TEXT NOT NULL DEFAULT 'active',
+	created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+	updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);`
+
+const superadminsSchema = `
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+CREATE TABLE superadmins (
+	id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+	email TEXT NOT NULL UNIQUE,
+	name TEXT NOT NULL,
+	status TEXT NOT NULL DEFAULT 'active',
+	created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+	updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);`
+
+// Akzeptanzkriterium 1 + 3, Pruefung 1 (inkl. Negativfall doppelte E-Mail).
+func TestTenantUserStore_CRUD(t *testing.T) {
+	pool := setupTestDB(t, "test_iam01_users", usersSchema)
+	store := NewTenantUserStore(pool)
+	ctx := context.Background()
+
+	created, err := store.Create(ctx, "alice@example.com", "Alice")
+	if err != nil {
+		t.Fatalf("create: %v", err)
+	}
+	if created.Status != StatusActive {
+		t.Fatalf("erwartet status active, hat %q", created.Status)
+	}
+
+	got, err := store.Get(ctx, created.ID)
+	if err != nil {
+		t.Fatalf("get: %v", err)
+	}
+	if got.Email != "alice@example.com" {
+		t.Fatalf("get email = %q", got.Email)
+	}
+
+	updated, err := store.Update(ctx, created.ID, "", "Alice A.")
+	if err != nil {
+		t.Fatalf("update: %v", err)
+	}
+	if updated.Name != "Alice A." || updated.Email != "alice@example.com" {
+		t.Fatalf("update ergebnis unerwartet: %+v", updated)
+	}
+
+	list, err := store.List(ctx)
+	if err != nil {
+		t.Fatalf("list: %v", err)
+	}
+	if len(list) != 1 {
+		t.Fatalf("erwartet 1 benutzer, habe %d", len(list))
+	}
+
+	deactivated, err := store.Deactivate(ctx, created.ID)
+	if err != nil {
+		t.Fatalf("deactivate: %v", err)
+	}
+	if deactivated.Status != StatusInactive {
+		t.Fatalf("erwartet status inactive, hat %q", deactivated.Status)
+	}
+
+	// Negativfall: doppelte E-Mail-Adresse.
+	if _, err := store.Create(ctx, "second@example.com", "Bob"); err != nil {
+		t.Fatalf("create second: %v", err)
+	}
+	if _, err := store.Create(ctx, "second@example.com", "Bob Zwei"); !errors.Is(err, ErrEmailTaken) {
+		t.Fatalf("erwartet ErrEmailTaken, habe %v", err)
+	}
+
+	// Negativfall: fehlender Benutzer.
+	if _, err := store.Get(ctx, created.ID+"-nicht-vorhanden"); err == nil {
+		t.Fatalf("erwartet fehler bei unbekannter/ungueltiger id")
+	}
+}
+
+// Akzeptanzkriterium 2 + Pruefung 2: Superadmin-Anlage ohne Tenant-Kontext.
+// SuperadminStore.Create hat keinen Tenant-Parameter — es gibt syntaktisch
+// keine Moeglichkeit, hier versehentlich einen Tenant-Sonderfall zu vergessen.
+func TestSuperadminStore_CreateWithoutTenantContext(t *testing.T) {
+	pool := setupTestDB(t, "test_iam01_superadmins", superadminsSchema)
+	store := NewSuperadminStore(pool)
+	ctx := context.Background()
+
+	created, err := store.Create(ctx, "root@nexarch.internal", "Root")
+	if err != nil {
+		t.Fatalf("create superadmin: %v", err)
+	}
+	if created.Status != StatusActive {
+		t.Fatalf("erwartet status active, hat %q", created.Status)
+	}
+
+	got, err := store.Get(ctx, created.ID)
+	if err != nil {
+		t.Fatalf("get: %v", err)
+	}
+	if got.Email != "root@nexarch.internal" {
+		t.Fatalf("get email = %q", got.Email)
+	}
+
+	if _, err := store.Create(ctx, "root@nexarch.internal", "Root Zwei"); !errors.Is(err, ErrEmailTaken) {
+		t.Fatalf("erwartet ErrEmailTaken (globale eindeutigkeit), habe %v", err)
+	}
+
+	deactivated, err := store.Deactivate(ctx, created.ID)
+	if err != nil {
+		t.Fatalf("deactivate: %v", err)
+	}
+	if deactivated.Status != StatusInactive {
+		t.Fatalf("erwartet status inactive, hat %q", deactivated.Status)
+	}
+}

internal/user/superadmin_store.go

@@ -0,0 +1,77 @@
+package user
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// SuperadminStore verwaltet mandantenuebergreifende Superadmin-Konten in der
+// Control-Plane-Registry (siehe internal/tenant.Registry). Superadmin-ohne-
+// Tenant ist dadurch ein eigener Typ statt eines Sonderfalls von User/
+// TenantUserStore — es gibt keinen Tenant-Parameter, den man weglassen
+// koennte (IAM-01, "ohne Sonderbehandlung im Code").
+type SuperadminStore struct {
+	pool *pgxpool.Pool
+}
+
+func NewSuperadminStore(pool *pgxpool.Pool) *SuperadminStore {
+	return &SuperadminStore{pool: pool}
+}
+
+func (s *SuperadminStore) Create(ctx context.Context, email, name string) (User, error) {
+	if err := ValidateEmail(email); err != nil {
+		return User{}, err
+	}
+
+	var u User
+	u.Email, u.Name, u.Status = email, name, StatusActive
+
+	row := s.pool.QueryRow(ctx, `
+		INSERT INTO superadmins (email, name, status)
+		VALUES ($1, $2, $3)
+		RETURNING id, created_at, updated_at
+	`, u.Email, u.Name, u.Status)
+
+	if err := row.Scan(&u.ID, &u.CreatedAt, &u.UpdatedAt); err != nil {
+		return User{}, mapWriteErr(err)
+	}
+	return u, nil
+}
+
+func (s *SuperadminStore) Get(ctx context.Context, id string) (User, error) {
+	return scanUser(s.pool.QueryRow(ctx, `
+		SELECT id, email, name, status, created_at, updated_at
+		FROM superadmins WHERE id = $1
+	`, id))
+}
+
+func (s *SuperadminStore) List(ctx context.Context) ([]User, error) {
+	rows, err := s.pool.Query(ctx, `
+		SELECT id, email, name, status, created_at, updated_at
+		FROM superadmins ORDER BY created_at
+	`)
+	if err != nil {
+		return nil, fmt.Errorf("superadmins auflisten: %w", err)
+	}
+	defer rows.Close()
+
+	var out []User
+	for rows.Next() {
+		var u User
+		if err := rows.Scan(&u.ID, &u.Email, &u.Name, &u.Status, &u.CreatedAt, &u.UpdatedAt); err != nil {
+			return nil, fmt.Errorf("superadmin lesen: %w", err)
+		}
+		out = append(out, u)
+	}
+	return out, rows.Err()
+}
+
+func (s *SuperadminStore) Deactivate(ctx context.Context, id string) (User, error) {
+	return scanUser(s.pool.QueryRow(ctx, `
+		UPDATE superadmins SET status = $2, updated_at = now()
+		WHERE id = $1
+		RETURNING id, email, name, status, created_at, updated_at
+	`, id, StatusInactive))
+}

internal/user/tenant_store.go

@@ -0,0 +1,173 @@
+package user
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgconn"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// TenantUserStore verwaltet Benutzer innerhalb GENAU EINER Tenant-Datenbank.
+// Welcher Mandant gemeint ist, ergibt sich ausschliesslich aus dem
+// uebergebenen Pool — es gibt keine tenant_id-Spalte (siehe migrations/tenant/0001_users.up.sql).
+type TenantUserStore struct {
+	pool *pgxpool.Pool
+}
+
+func NewTenantUserStore(pool *pgxpool.Pool) *TenantUserStore {
+	return &TenantUserStore{pool: pool}
+}
+
+func (s *TenantUserStore) Create(ctx context.Context, email, name string) (User, error) {
+	if err := ValidateEmail(email); err != nil {
+		return User{}, err
+	}
+
+	var u User
+	u.Email, u.Name, u.Status = email, name, StatusActive
+
+	row := s.pool.QueryRow(ctx, `
+		INSERT INTO users (email, name, status)
+		VALUES ($1, $2, $3)
+		RETURNING id, created_at, updated_at
+	`, u.Email, u.Name, u.Status)
+
+	if err := row.Scan(&u.ID, &u.CreatedAt, &u.UpdatedAt); err != nil {
+		return User{}, mapWriteErr(err)
+	}
+	return u, nil
+}
+
+func (s *TenantUserStore) Get(ctx context.Context, id string) (User, error) {
+	return scanUser(s.pool.QueryRow(ctx, `
+		SELECT id, email, name, status, created_at, updated_at
+		FROM users WHERE id = $1
+	`, id))
+}
+
+func (s *TenantUserStore) List(ctx context.Context) ([]User, error) {
+	rows, err := s.pool.Query(ctx, `
+		SELECT id, email, name, status, created_at, updated_at
+		FROM users ORDER BY created_at
+	`)
+	if err != nil {
+		return nil, fmt.Errorf("benutzer auflisten: %w", err)
+	}
+	defer rows.Close()
+
+	var out []User
+	for rows.Next() {
+		var u User
+		if err := rows.Scan(&u.ID, &u.Email, &u.Name, &u.Status, &u.CreatedAt, &u.UpdatedAt); err != nil {
+			return nil, fmt.Errorf("benutzer lesen: %w", err)
+		}
+		out = append(out, u)
+	}
+	return out, rows.Err()
+}
+
+// Update aendert Name und E-Mail. Eine leere email/name laesst das jeweilige
+// Feld unveraendert.
+func (s *TenantUserStore) Update(ctx context.Context, id, email, name string) (User, error) {
+	if email != "" {
+		if err := ValidateEmail(email); err != nil {
+			return User{}, err
+		}
+	}
+
+	row := s.pool.QueryRow(ctx, `
+		UPDATE users
+		SET email = COALESCE(NULLIF($2, ''), email),
+		    name = COALESCE(NULLIF($3, ''), name),
+		    updated_at = now()
+		WHERE id = $1
+		RETURNING id, email, name, status, created_at, updated_at
+	`, id, email, name)
+
+	u, err := scanUser(row)
+	if err != nil {
+		return User{}, mapWriteErr(err)
+	}
+	return u, nil
+}
+
+// Deactivate setzt den Benutzer auf inaktiv statt ihn zu loeschen.
+func (s *TenantUserStore) Deactivate(ctx context.Context, id string) (User, error) {
+	return scanUser(s.pool.QueryRow(ctx, `
+		UPDATE users SET status = $2, updated_at = now()
+		WHERE id = $1
+		RETURNING id, email, name, status, created_at, updated_at
+	`, id, StatusInactive))
+}
+
+// SetPasswordHash schreibt einen bereits berechneten bcrypt-Hash (siehe
+// internal/auth, IAM-02). Der Store selbst kennt kein Klartext-Passwort.
+func (s *TenantUserStore) SetPasswordHash(ctx context.Context, id, hash string) error {
+	tag, err := s.pool.Exec(ctx, `
+		UPDATE users SET password_hash = $2, updated_at = now() WHERE id = $1
+	`, id, hash)
+	if err != nil {
+		return fmt.Errorf("passwort setzen: %w", err)
+	}
+	if tag.RowsAffected() == 0 {
+		return ErrNotFound
+	}
+	return nil
+}
+
+// AuthCredentials wird ausschliesslich fuer den Login-Pfad (internal/auth)
+// verwendet und traegt bewusst den password_hash, damit er nicht ueber den
+// regulaeren User-Typ/JSON-Serialisierungspfad nach aussen dringen kann.
+type AuthCredentials struct {
+	User         User
+	PasswordHash string
+}
+
+// GetByEmailForAuth liefert Benutzer + Passwort-Hash zu einer E-Mail-Adresse
+// aus GENAU DIESER Tenant-Datenbank — der Tenant-Scope ergibt sich damit
+// zwingend aus dem verwendeten Pool, es gibt keine Moeglichkeit, versehentlich
+// ueber Tenant-Grenzen hinweg zu suchen (bekannter archivmail-Fehler, siehe
+// IAM-02 "Bekannte Fehler vermeiden").
+func (s *TenantUserStore) GetByEmailForAuth(ctx context.Context, email string) (AuthCredentials, error) {
+	var c AuthCredentials
+	row := s.pool.QueryRow(ctx, `
+		SELECT id, email, name, status, created_at, updated_at, password_hash
+		FROM users WHERE email = $1
+	`, email)
+
+	if err := row.Scan(&c.User.ID, &c.User.Email, &c.User.Name, &c.User.Status,
+		&c.User.CreatedAt, &c.User.UpdatedAt, &c.PasswordHash); err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return AuthCredentials{}, ErrNotFound
+		}
+		return AuthCredentials{}, fmt.Errorf("anmeldedaten lesen: %w", err)
+	}
+	return c, nil
+}
+
+func scanUser(row pgx.Row) (User, error) {
+	var u User
+	if err := row.Scan(&u.ID, &u.Email, &u.Name, &u.Status, &u.CreatedAt, &u.UpdatedAt); err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return User{}, ErrNotFound
+		}
+		return User{}, fmt.Errorf("benutzer lesen: %w", err)
+	}
+	return u, nil
+}
+
+// mapWriteErr uebersetzt den Unique-Constraint-Verstoss der E-Mail-Spalte in
+// einen sprechenden Fehler statt der rohen Postgres-Fehlermeldung.
+func mapWriteErr(err error) error {
+	var pgErr *pgconn.PgError
+	if errors.As(err, &pgErr) && pgErr.Code == "23505" {
+		return ErrEmailTaken
+	}
+	if errors.Is(err, pgx.ErrNoRows) {
+		return ErrNotFound
+	}
+	return fmt.Errorf("benutzer schreiben: %w", err)
+}

internal/user/user.go

@@ -0,0 +1,42 @@
+// Package user implementiert Core IAM-01: das Benutzer-Datenmodell und die
+// CRUD-Operationen. Tenant-Zugehoerigkeit ist ueber die Zieldatenbank
+// gegeben (Modell C, siehe internal/tenant) — Superadmin-Konten leben
+// dagegen mandantenuebergreifend in der Registry und sind ueber
+// SuperadminStore als eigener, First-Class-Typ modelliert, nicht als
+// tenant_id-NULL-Sonderfall in User.
+package user
+
+import (
+	"errors"
+	"regexp"
+	"time"
+)
+
+type Status string
+
+const (
+	StatusActive   Status = "active"
+	StatusInactive Status = "inactive"
+)
+
+type User struct {
+	ID        string
+	Email     string
+	Name      string
+	Status    Status
+	CreatedAt time.Time
+	UpdatedAt time.Time
+}
+
+var emailPattern = regexp.MustCompile(`^[^\s@]+@[^\s@]+\.[^\s@]+$`)
+
+var ErrInvalidEmail = errors.New("user: ungueltige E-Mail-Adresse")
+var ErrEmailTaken = errors.New("user: E-Mail-Adresse bereits vergeben")
+var ErrNotFound = errors.New("user: nicht gefunden")
+
+func ValidateEmail(email string) error {
+	if !emailPattern.MatchString(email) {
+		return ErrInvalidEmail
+	}
+	return nil
+}

internal/user/user_test.go

@@ -0,0 +1,24 @@
+package user
+
+import "testing"
+
+func TestValidateEmail(t *testing.T) {
+	cases := []struct {
+		email   string
+		wantErr bool
+	}{
+		{"a@b.de", false},
+		{"a.b+c@sub.example.com", false},
+		{"", true},
+		{"keine-email", true},
+		{"a@b", true},
+		{"@b.de", true},
+	}
+
+	for _, c := range cases {
+		err := ValidateEmail(c.email)
+		if (err != nil) != c.wantErr {
+			t.Errorf("ValidateEmail(%q) error = %v, wantErr %v", c.email, err, c.wantErr)
+		}
+	}
+}

migrations/0002_superadmins.down.sql

@@ -0,0 +1 @@
+DROP TABLE IF EXISTS superadmins;

migrations/0002_superadmins.up.sql

@@ -0,0 +1,14 @@
+-- Superadmin-Konten arbeiten mandantenuebergreifend und leben deshalb in der
+-- Control-Plane-Registry (siehe TEN-01), nicht in einer Tenant-Datenbank.
+-- Das bildet "Superadmin ohne Tenant" strukturell als First-Class-Zustand ab,
+-- statt ihn als Sonderfall in der Tenant-users-Tabelle zu behandeln
+-- (IAM-01, siehe core-kanban/tickets/IAM-01.md — bekannte Fehler vermeiden).
+-- E-Mail-Eindeutigkeit ist hier global, da die Registry-DB einmalig existiert.
+CREATE TABLE superadmins (
+    id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    email        TEXT NOT NULL UNIQUE,
+    name         TEXT NOT NULL,
+    status       TEXT NOT NULL DEFAULT 'active',
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+);

migrations/0003_policy_rules.down.sql

@@ -0,0 +1,2 @@
+DROP TABLE IF EXISTS policy_rule_changes;
+DROP TABLE IF EXISTS policy_rules;

migrations/0003_policy_rules.up.sql

@@ -0,0 +1,24 @@
+-- Zentrale, deklarative Policy-Regeln (RBAC-02, siehe core-kanban/tickets/RBAC-02.md).
+-- policy_rules haelt den AKTUELLEN, gewaehrten Regelsatz (Existenz = erlaubt,
+-- Default-Deny fuer alles ohne Zeile). policy_rule_changes ist die
+-- versionierte Aenderungshistorie (Akzeptanzkriterium 3: Regelwechsel ohne
+-- Codeaenderung nachvollziehbar).
+CREATE TABLE policy_rules (
+    role       TEXT NOT NULL,
+    permission TEXT NOT NULL,
+    granted_by TEXT NOT NULL,
+    granted_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (role, permission)
+);
+
+CREATE TABLE policy_rule_changes (
+    id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    role       TEXT NOT NULL,
+    permission TEXT NOT NULL,
+    action     TEXT NOT NULL CHECK (action IN ('grant', 'revoke')),
+    actor      TEXT NOT NULL,
+    version    INT NOT NULL,
+    changed_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX policy_rule_changes_idx ON policy_rule_changes (role, permission, version);

migrations/0004_feature_flags.down.sql

@@ -1 +0,0 @@
-DROP TABLE IF EXISTS feature_flags;

migrations/0004_feature_flags.up.sql

@@ -1,10 +0,0 @@
--- Feature-Flags zentral je Mandant/Zielgruppe (LIC-02, siehe core-kanban/tickets/LIC-02.md).
--- Lebt in der Registry-DB, nicht pro Tenant-Datenbank — Flags sind eine
--- Core-weite Konfiguration, keine Mandanten-Geschaeftsdaten.
-CREATE TABLE feature_flags (
-    key                 TEXT PRIMARY KEY,
-    enabled             BOOLEAN NOT NULL DEFAULT false,
-    rollout_percentage  INT NOT NULL DEFAULT 0 CHECK (rollout_percentage BETWEEN 0 AND 100),
-    target_tenant_slugs TEXT[] NOT NULL DEFAULT '{}',
-    updated_at          TIMESTAMPTZ NOT NULL DEFAULT now()
-);

migrations/0005_module_registry.down.sql

@@ -1,2 +0,0 @@
-DROP TABLE IF EXISTS module_credentials;
-DROP TABLE IF EXISTS modules;

migrations/0005_module_registry.up.sql

@@ -1,18 +0,0 @@
--- Modul-Registry & Aktivierungspruefung (API-02, siehe core-kanban/tickets/API-02.md).
-CREATE TABLE modules (
-    name           TEXT PRIMARY KEY,
-    version        TEXT NOT NULL CHECK (version <> ''),
-    required_flags TEXT[] NOT NULL DEFAULT '{}',
-    registered_at  TIMESTAMPTZ NOT NULL DEFAULT now()
-);
-
--- Service-Credential je Modul-Instanz, bei Provisionierung ausgestellt
--- (Akzeptanzkriterium 4). secret_hash enthaelt NIEMALS das Secret im
--- Klartext, nur dessen SHA-256-Hash (Timing-safe-Vergleich beim Login,
--- Referenzmuster siehe AUD-02).
-CREATE TABLE module_credentials (
-    module_name TEXT PRIMARY KEY REFERENCES modules(name),
-    client_id   TEXT NOT NULL UNIQUE,
-    secret_hash BYTEA NOT NULL,
-    issued_at   TIMESTAMPTZ NOT NULL DEFAULT now()
-);

migrations/0006_resync_buffers.down.sql

@@ -1,2 +0,0 @@
-DROP TABLE resync_usage_buffer;
-DROP TABLE resync_audit_buffer;

migrations/0006_resync_buffers.up.sql

@@ -1,22 +0,0 @@
--- Wiederanlauf & Nachsynchronisierung nach Core-Ausfall (API-06, siehe
--- core-kanban/tickets/API-06.md) — lokale, PERSISTENTE Pufferqueue (kein
--- In-Memory) fuer Audit-Events und Nutzungszaehler-Deltas eines Moduls.
-CREATE TABLE resync_audit_buffer (
-    id          BIGSERIAL PRIMARY KEY,
-    seq         BIGSERIAL,
-    tenant_slug TEXT NOT NULL,
-    actor       TEXT NOT NULL,
-    action      TEXT NOT NULL,
-    target      TEXT NOT NULL DEFAULT '',
-    metadata    JSONB NOT NULL DEFAULT '{}',
-    created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
-);
-
-CREATE TABLE resync_usage_buffer (
-    id          BIGSERIAL PRIMARY KEY,
-    seq         BIGSERIAL,
-    tenant_slug TEXT NOT NULL,
-    metric      TEXT NOT NULL,
-    delta       BIGINT NOT NULL,
-    created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
-);

migrations/tenant/0001_users.down.sql

@@ -0,0 +1 @@
+DROP TABLE IF EXISTS users;

migrations/tenant/0001_users.up.sql

@@ -0,0 +1,16 @@
+-- Benutzer-Datenmodell (IAM-01, siehe core-kanban/tickets/IAM-01.md).
+-- Diese Migration laeuft in der DB EINES Mandanten (Modell C, siehe TEN-01) —
+-- die Tenant-Zugehoerigkeit ist implizit durch die Datenbankverbindung
+-- gegeben, es gibt daher bewusst KEINE tenant_id-Spalte.
+-- E-Mail-Eindeutigkeit ist hier tenant-scoped: der UNIQUE-Constraint gilt
+-- nur innerhalb dieser einen Tenant-Datenbank.
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+
+CREATE TABLE users (
+    id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    email        TEXT NOT NULL UNIQUE,
+    name         TEXT NOT NULL,
+    status       TEXT NOT NULL DEFAULT 'active',
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+);

migrations/tenant/0002_role_assignments.down.sql

@@ -0,0 +1,2 @@
+DROP TABLE IF EXISTS role_assignment_history;
+DROP TABLE IF EXISTS role_assignments;

migrations/tenant/0002_role_assignments.up.sql

@@ -0,0 +1,23 @@
+-- Rollenzuweisung pro Benutzer (RBAC-01, siehe core-kanban/tickets/RBAC-01.md).
+-- Nur 'user' und 'tenant_admin' sind hier zuweisbar — 'superadmin' lebt
+-- mandantenuebergreifend in der Registry (IAM-01 SuperadminStore) und hat
+-- daher bewusst KEINE Zeile in dieser tenant-lokalen Tabelle (Akzeptanz-
+-- kriterium 1: nur Zuweisungen innerhalb der erlaubten Matrix).
+CREATE TABLE role_assignments (
+    user_id     UUID PRIMARY KEY REFERENCES users(id),
+    role        TEXT NOT NULL CHECK (role IN ('user', 'tenant_admin')),
+    granted_by  TEXT NOT NULL,
+    granted_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- Vollstaendige Historie jeder Rollenaenderung (Akzeptanzkriterium 3: wer
+-- hat wann welche Rolle vergeben).
+CREATE TABLE role_assignment_history (
+    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id     UUID NOT NULL,
+    role        TEXT NOT NULL,
+    granted_by  TEXT NOT NULL,
+    granted_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX role_assignment_history_user_idx ON role_assignment_history (user_id, granted_at);

migrations/tenant/0002_users_password.down.sql

@@ -0,0 +1 @@
+ALTER TABLE users DROP COLUMN password_hash;

migrations/tenant/0002_users_password.up.sql

@@ -0,0 +1,3 @@
+-- Passwort-Hash-Spalte fuer Login (IAM-02, siehe core-kanban/tickets/IAM-02.md).
+-- Enthaelt AUSSCHLIESSLICH den bcrypt-Hash, niemals das Klartext-Passwort.
+ALTER TABLE users ADD COLUMN password_hash TEXT NOT NULL DEFAULT '';

migrations/tenant/0003_groups.down.sql

@@ -0,0 +1,2 @@
+DROP TABLE IF EXISTS group_members;
+DROP TABLE IF EXISTS groups;

migrations/tenant/0003_groups.up.sql

@@ -0,0 +1,21 @@
+-- Gruppen/Abteilungen mit Rollenzuweisung auf Gruppenebene (RBAC-03, siehe
+-- core-kanban/tickets/RBAC-03.md). Lebt in der Tenant-Datenbank (Modell C) —
+-- Gruppen sind implizit tenant-isoliert, da jede Tenant-DB ihre eigenen hat.
+CREATE TABLE groups (
+    id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    name       TEXT NOT NULL,
+    role       TEXT CHECK (role IN ('user', 'tenant_admin')),
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- ON DELETE CASCADE: Loeschen einer Gruppe entzieht die gruppenbasierten
+-- Rechte automatisch, ohne Benutzerkonten selbst zu beruehren
+-- (Akzeptanzkriterium 3).
+CREATE TABLE group_members (
+    group_id UUID NOT NULL REFERENCES groups(id) ON DELETE CASCADE,
+    user_id  UUID NOT NULL REFERENCES users(id),
+    added_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (group_id, user_id)
+);
+
+CREATE INDEX group_members_user_idx ON group_members (user_id);

web/rbac-admin/app/groups/page.tsx

@@ -0,0 +1,183 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { TextField, SelectField, useToast } from "@nexarch/shl";
+import {
+  ApiError,
+  Group,
+  Role,
+  addGroupMember,
+  createGroup,
+  fetchGroups,
+  removeGroupMember,
+  setGroupRole,
+} from "../../lib/api";
+
+export default function GroupsPage() {
+  const { push } = useToast();
+  const [groups, setGroups] = useState<Group[]>([]);
+  const [loadError, setLoadError] = useState<string | null>(null);
+
+  const reload = () =>
+    fetchGroups()
+      .then(setGroups)
+      .catch(() => setLoadError("Gruppen konnten nicht geladen werden. Sind Sie als Tenant-Admin angemeldet?"));
+
+  useEffect(() => {
+    reload();
+  }, []);
+
+  const [newGroupName, setNewGroupName] = useState("");
+  const [createError, setCreateError] = useState<string | null>(null);
+
+  async function onCreate(event: React.FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    setCreateError(null);
+    try {
+      await createGroup(newGroupName);
+      setNewGroupName("");
+      push("Gruppe angelegt.", "success");
+      await reload();
+    } catch (err) {
+      setCreateError(err instanceof ApiError ? err.message : "Gruppe konnte nicht angelegt werden.");
+    }
+  }
+
+  if (loadError) {
+    return (
+      <main style={{ maxWidth: 640, margin: "40px auto", padding: "0 16px" }}>
+        <p role="alert">{loadError}</p>
+      </main>
+    );
+  }
+
+  return (
+    <main style={{ maxWidth: 640, margin: "40px auto", padding: "0 16px" }}>
+      <h1>Gruppen &amp; Abteilungen</h1>
+
+      <section aria-labelledby="neue-gruppe-heading">
+        <h2 id="neue-gruppe-heading">Neue Gruppe anlegen</h2>
+        <form onSubmit={onCreate} noValidate>
+          <TextField
+            label="Gruppenname"
+            required
+            value={newGroupName}
+            onChange={(e) => setNewGroupName(e.target.value)}
+          />
+          {createError && (
+            <p role="alert" style={{ color: "var(--shl-color-danger)" }}>
+              {createError}
+            </p>
+          )}
+          <button type="submit">Anlegen</button>
+        </form>
+      </section>
+
+      <section aria-labelledby="gruppenliste-heading">
+        <h2 id="gruppenliste-heading">Bestehende Gruppen</h2>
+        {groups.length === 0 ? (
+          <p>Keine Gruppen vorhanden.</p>
+        ) : (
+          groups.map((g) => <GroupCard key={g.ID} group={g} onChanged={reload} onNotice={(t) => push(t, "success")} />)
+        )}
+      </section>
+    </main>
+  );
+}
+
+function GroupCard({
+  group,
+  onChanged,
+  onNotice,
+}: {
+  group: Group;
+  onChanged: () => void;
+  onNotice: (text: string) => void;
+}) {
+  const [role, setRole] = useState<Role>(group.Role || "user");
+  const [newMemberId, setNewMemberId] = useState("");
+  const [error, setError] = useState<string | null>(null);
+
+  async function onSetRole() {
+    setError(null);
+    try {
+      await setGroupRole(group.ID, role);
+      onNotice("Gruppenrolle gesetzt.");
+      onChanged();
+    } catch (err) {
+      setError(err instanceof ApiError ? err.message : "Gruppenrolle konnte nicht gesetzt werden.");
+    }
+  }
+
+  async function onAddMember(event: React.FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    setError(null);
+    try {
+      await addGroupMember(group.ID, newMemberId);
+      setNewMemberId("");
+      onNotice("Mitglied hinzugefügt.");
+      onChanged();
+    } catch (err) {
+      setError(err instanceof ApiError ? err.message : "Mitglied konnte nicht hinzugefügt werden.");
+    }
+  }
+
+  async function onRemoveMember(userId: string) {
+    setError(null);
+    try {
+      await removeGroupMember(group.ID, userId);
+      onNotice("Mitglied entfernt.");
+      onChanged();
+    } catch (err) {
+      setError(err instanceof ApiError ? err.message : "Mitglied konnte nicht entfernt werden.");
+    }
+  }
+
+  return (
+    <div style={{ border: "1px solid var(--shl-color-border)", borderRadius: 8, padding: 16, marginBottom: 16 }}>
+      <h3>{group.Name}</h3>
+
+      <div style={{ display: "flex", alignItems: "flex-end", gap: 8 }}>
+        <SelectField label="Gruppenrolle" value={role} onChange={(e) => setRole(e.target.value as Role)}>
+          <option value="user">Benutzer</option>
+          <option value="tenant_admin">Tenant-Admin</option>
+        </SelectField>
+        <button type="button" onClick={onSetRole}>
+          Setzen
+        </button>
+      </div>
+
+      <h4>Mitglieder</h4>
+      {group.members.length === 0 ? (
+        <p>Keine Mitglieder.</p>
+      ) : (
+        <ul>
+          {group.members.map((userId) => (
+            <li key={userId}>
+              {userId}{" "}
+              <button type="button" onClick={() => onRemoveMember(userId)}>
+                Entfernen
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+
+      <form onSubmit={onAddMember} noValidate>
+        <TextField
+          label="Benutzer-ID hinzufügen"
+          required
+          value={newMemberId}
+          onChange={(e) => setNewMemberId(e.target.value)}
+        />
+        <button type="submit">Hinzufügen</button>
+      </form>
+
+      {error && (
+        <p role="alert" style={{ color: "var(--shl-color-danger)" }}>
+          {error}
+        </p>
+      )}
+    </div>
+  );
+}

web/rbac-admin/app/layout.tsx

@@ -0,0 +1,30 @@
+import { ThemeProvider, I18nProvider, ToastProvider, typography } from "@nexarch/shl";
+
+export const metadata = {
+  title: "NEXARCH Rechteverwaltung",
+};
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="de">
+      <body
+        style={{
+          fontFamily: typography.fontFamily,
+          margin: 0,
+          background: "var(--shl-color-background, #ffffff)",
+          color: "var(--shl-color-text-primary, #14181f)",
+        }}
+      >
+        <ThemeProvider>
+          <I18nProvider initialLocale="de">
+            <ToastProvider>{children}</ToastProvider>
+          </I18nProvider>
+        </ThemeProvider>
+      </body>
+    </html>
+  );
+}

web/rbac-admin/app/page.tsx

@@ -0,0 +1,5 @@
+import { redirect } from "next/navigation";
+
+export default function IndexPage() {
+  redirect("/roles");
+}

web/rbac-admin/app/roles/page.tsx

@@ -0,0 +1,142 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { Table, TextField, SelectField, useToast } from "@nexarch/shl";
+import type { TableColumn } from "@nexarch/shl";
+import {
+  ApiError,
+  Assignment,
+  Role,
+  RoleInfo,
+  assignRole,
+  fetchRoleHistory,
+  fetchRoles,
+} from "../../lib/api";
+
+export default function RolesPage() {
+  const { push } = useToast();
+  const [roles, setRoles] = useState<RoleInfo[] | null>(null);
+  const [loadError, setLoadError] = useState<string | null>(null);
+
+  const [targetUserId, setTargetUserId] = useState("");
+  const [targetRole, setTargetRole] = useState<Role>("user");
+  const [assignError, setAssignError] = useState<string | null>(null);
+  const [submitting, setSubmitting] = useState(false);
+
+  const [historyUserId, setHistoryUserId] = useState("");
+  const [history, setHistory] = useState<Assignment[] | null>(null);
+
+  useEffect(() => {
+    fetchRoles()
+      .then(setRoles)
+      .catch(() => setLoadError("Rollen konnten nicht geladen werden. Sind Sie als Tenant-Admin angemeldet?"));
+  }, []);
+
+  async function onAssign(event: React.FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    setAssignError(null);
+    setSubmitting(true);
+    try {
+      await assignRole(targetUserId, targetRole);
+      push("Rolle zugewiesen.", "success");
+    } catch (err) {
+      // Akzeptanzkriterium 2: die Backend-Meldung bei Selbst-Eskalation wird
+      // unveraendert angezeigt, keine eigene Interpretation im Frontend.
+      setAssignError(err instanceof ApiError ? err.message : "Rolle konnte nicht zugewiesen werden.");
+    } finally {
+      setSubmitting(false);
+    }
+  }
+
+  async function onLoadHistory(event: React.FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    try {
+      setHistory(await fetchRoleHistory(historyUserId));
+    } catch {
+      setHistory([]);
+    }
+  }
+
+  const historyColumns: TableColumn<Assignment>[] = [
+    { key: "role", header: "Rolle", render: (a) => a.Role },
+    { key: "grantedBy", header: "Vergeben von", render: (a) => a.GrantedBy },
+  ];
+
+  if (loadError) {
+    return (
+      <main style={{ maxWidth: 640, margin: "40px auto", padding: "0 16px" }}>
+        <p role="alert">{loadError}</p>
+      </main>
+    );
+  }
+
+  return (
+    <main style={{ maxWidth: 640, margin: "40px auto", padding: "0 16px" }}>
+      <h1>Rollen &amp; Rechte</h1>
+
+      <section aria-labelledby="rollen-heading">
+        <h2 id="rollen-heading">Rollen und Grundrechte</h2>
+        {roles?.map((r) => (
+          <div key={r.role} style={{ marginBottom: 12 }}>
+            <strong>{roleLabel(r.role)}</strong>
+            <ul>
+              {r.permissions.map((p) => (
+                <li key={p}>{p}</li>
+              ))}
+            </ul>
+          </div>
+        ))}
+      </section>
+
+      <section aria-labelledby="zuweisen-heading">
+        <h2 id="zuweisen-heading">Rolle zuweisen</h2>
+        <form onSubmit={onAssign} noValidate>
+          <TextField
+            label="Benutzer-ID"
+            required
+            value={targetUserId}
+            onChange={(e) => setTargetUserId(e.target.value)}
+          />
+          <SelectField label="Rolle" value={targetRole} onChange={(e) => setTargetRole(e.target.value as Role)}>
+            <option value="user">Benutzer</option>
+            <option value="tenant_admin">Tenant-Admin</option>
+          </SelectField>
+          {assignError && (
+            <p role="alert" style={{ color: "var(--shl-color-danger)" }}>
+              {assignError}
+            </p>
+          )}
+          <button type="submit" disabled={submitting}>
+            {submitting ? "Wird zugewiesen…" : "Zuweisen"}
+          </button>
+        </form>
+      </section>
+
+      <section aria-labelledby="verlauf-heading">
+        <h2 id="verlauf-heading">Nachvollziehbarkeit (Audit-Verlauf)</h2>
+        <p>Zeigt jede Rollenzuweisung eines Benutzers chronologisch — wer wann welche Rolle vergeben hat.</p>
+        <form onSubmit={onLoadHistory} noValidate>
+          <TextField
+            label="Benutzer-ID"
+            required
+            value={historyUserId}
+            onChange={(e) => setHistoryUserId(e.target.value)}
+          />
+          <button type="submit">Verlauf anzeigen</button>
+        </form>
+        {history && (
+          <Table
+            columns={historyColumns}
+            rows={history}
+            rowKey={(a) => `${a.UserID}-${a.Role}-${a.GrantedBy}`}
+            caption="Rollenzuweisungs-Verlauf"
+          />
+        )}
+      </section>
+    </main>
+  );
+}
+
+function roleLabel(role: Role): string {
+  return role === "tenant_admin" ? "Tenant-Admin" : "Benutzer";
+}

web/rbac-admin/lib/api.ts

@@ -0,0 +1,68 @@
+const API_BASE = process.env.NEXT_PUBLIC_CORE_API_BASE ?? "";
+
+export class ApiError extends Error {}
+
+async function req<T>(path: string, init?: RequestInit): Promise<T> {
+  const res = await fetch(`${API_BASE}${path}`, {
+    credentials: "include",
+    headers: init?.body ? { "Content-Type": "application/json" } : undefined,
+    ...init,
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    throw new ApiError(data.error ?? data.message ?? "Unbekannter Fehler");
+  }
+  return data as T;
+}
+
+export type Role = "user" | "tenant_admin";
+
+export interface RoleInfo {
+  role: Role;
+  permissions: string[];
+}
+
+export function fetchRoles(): Promise<RoleInfo[]> {
+  return req("/rbac/roles");
+}
+
+export interface Assignment {
+  UserID: string;
+  Role: Role;
+  GrantedBy: string;
+}
+
+export function assignRole(userId: string, role: Role): Promise<Assignment> {
+  return req("/rbac/users/role", { method: "POST", body: JSON.stringify({ user_id: userId, role }) });
+}
+
+export function fetchRoleHistory(userId: string): Promise<Assignment[]> {
+  return req(`/rbac/users/${userId}/history`);
+}
+
+export interface Group {
+  ID: string;
+  Name: string;
+  Role: Role | "";
+  members: string[];
+}
+
+export function fetchGroups(): Promise<Group[]> {
+  return req("/rbac/groups");
+}
+
+export function createGroup(name: string): Promise<Group> {
+  return req("/rbac/groups", { method: "POST", body: JSON.stringify({ name }) });
+}
+
+export function setGroupRole(groupId: string, role: Role): Promise<void> {
+  return req("/rbac/groups/role", { method: "POST", body: JSON.stringify({ group_id: groupId, role }) });
+}
+
+export function addGroupMember(groupId: string, userId: string): Promise<void> {
+  return req("/rbac/groups/members", { method: "POST", body: JSON.stringify({ group_id: groupId, user_id: userId }) });
+}
+
+export function removeGroupMember(groupId: string, userId: string): Promise<void> {
+  return req("/rbac/groups/members/remove", { method: "POST", body: JSON.stringify({ group_id: groupId, user_id: userId }) });
+}

web/rbac-admin/next.config.mjs

@@ -0,0 +1,5 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  transpilePackages: ["@nexarch/shl"],
+};
+export default nextConfig;

web/rbac-admin/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "nexarch-rbac-admin",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint"
+  },
+  "dependencies": {
+    "@nexarch/shl": "file:../shl",
+    "next": "14.2.35",
+    "react": "18.3.1",
+    "react-dom": "18.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "20.14.9",
+    "@types/react": "18.3.3",
+    "@types/react-dom": "18.3.0",
+    "typescript": "5.5.3"
+  }
+}

web/rbac-admin/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": { "@/*": ["./*"] }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

web/shl/README.md

@@ -0,0 +1,45 @@
+# @nexarch/shl — UI-Shell & Design-System (Core SHL-01)
+
+Gemeinsames Paket für alle NEXARCH-Modul-Frontends (Core, DMS, Mail, Archive, Workflow, AI, Connect).
+Ein Modul-Frontend importiert ausschließlich über `index.ts`, kopiert keine Komponenten oder Tokens lokal.
+
+## Enthält
+
+- **Design-Tokens** (`tokens/tokens.ts`) — Farbe (Hell/Dunkel), Abstand, Typografie. Kontrastwerte gegen WCAG 2.1 AA geprüft (siehe `__tests__/tokens.test.ts`).
+- **Theming** (`theme/ThemeProvider.tsx`) — zentrale Hell/Dunkel-Umschaltung, respektiert `prefers-color-scheme`, persistiert in `localStorage`.
+- **i18n-Rahmen** (`i18n/i18n.tsx`) — Umschaltmechanismus Deutsch/Englisch. Modul-Frontends registrieren ihre fachlichen Textbausteine über `registerMessages()`, statt einen eigenen Mechanismus zu bauen.
+- **Basis-Komponenten** (`components/`) — `Shell` (Layout + Navigation), `Table`, `Dialog`, `TextField`/`SelectField`/`CheckboxField`, `Toast`. Alle mit WCAG-2.1-AA-Grundlage (Tastaturbedienung, ARIA-Attribute, Fokus-Management).
+
+## Verwendung in einem Modul-Frontend
+
+```tsx
+import { ThemeProvider, I18nProvider, ToastProvider, Shell } from "@nexarch/shl";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <ThemeProvider>
+      <I18nProvider initialLocale="de">
+        <ToastProvider>
+          <Shell modules={[]} tenantLabel="Mandant XY">
+            {children}
+          </Shell>
+        </ToastProvider>
+      </I18nProvider>
+    </ThemeProvider>
+  );
+}
+```
+
+## Bekannter offener Punkt
+
+Die vier bereits gebauten Core-Frontends (`TEN-05`, `LIC-04`, `AUD-04`, `OPS-02`) sind vor diesem Paket entstanden und binden es noch nicht ein — Retrofit ist der nächste Schritt, siehe `nexarch-state.json`.
+
+## Tests
+
+Ausführung auf dem Test-Host (nicht lokal, siehe Projekt-Testinfrastruktur):
+
+```bash
+npm install
+npm test
+npm run typecheck
+```

web/shl/__tests__/Dialog.test.tsx

@@ -0,0 +1,38 @@
+// Prüfung: Tastaturbedienung der Basis-Komponenten funktioniert (SHL-01 Prüfung 2).
+import { describe, expect, it, vi } from "vitest";
+import { fireEvent, render, screen } from "@testing-library/react";
+import { Dialog } from "../components/Dialog";
+import { I18nProvider } from "../i18n/i18n";
+
+function renderDialog(onClose: () => void) {
+  return render(
+    <I18nProvider>
+      <Dialog open titleId="test-title" title="Test-Dialog" onClose={onClose}>
+        <button type="button">Erste Aktion</button>
+        <button type="button">Zweite Aktion</button>
+      </Dialog>
+    </I18nProvider>,
+  );
+}
+
+describe("Dialog: Tastaturbedienung", () => {
+  it("schließt sich bei ESC", () => {
+    const onClose = vi.fn();
+    renderDialog(onClose);
+    fireEvent.keyDown(document, { key: "Escape" });
+    expect(onClose).toHaveBeenCalledOnce();
+  });
+
+  it("setzt den Fokus beim Öffnen auf das erste fokussierbare Element", () => {
+    renderDialog(vi.fn());
+    const closeButton = screen.getByRole("button", { name: /schließen/i });
+    expect(document.activeElement).toBe(closeButton);
+  });
+
+  it("ist als modaler Dialog mit Titel-Referenz ausgezeichnet", () => {
+    renderDialog(vi.fn());
+    const dialog = screen.getByRole("dialog");
+    expect(dialog).toHaveAttribute("aria-modal", "true");
+    expect(dialog).toHaveAttribute("aria-labelledby", "test-title");
+  });
+});

web/shl/__tests__/tokens.test.ts

@@ -0,0 +1,39 @@
+// Prüfung: Kontrastwerte erfüllen mindestens AA (SHL-01 Prüfung 3 / Akzeptanzkriterium 4).
+import { describe, expect, it } from "vitest";
+import { colorTokens } from "../tokens/tokens";
+
+// WCAG-2.1-AA-Kontrastberechnung (relative Luminanz, sRGB) — keine externe Abhängigkeit nötig.
+function relLuminance(hex: string): number {
+  const rgb = [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16) / 255);
+  const [r, g, b] = rgb.map((c) => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4));
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+function contrastRatio(a: string, b: string): number {
+  const l1 = relLuminance(a);
+  const l2 = relLuminance(b);
+  const [lighter, darker] = l1 > l2 ? [l1, l2] : [l2, l1];
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+describe("Design-Tokens: WCAG 2.1 AA Kontrast", () => {
+  for (const scheme of ["light", "dark"] as const) {
+    const c = colorTokens[scheme];
+
+    it(`${scheme}: textPrimary auf background erfüllt AA (>= 4.5:1)`, () => {
+      expect(contrastRatio(c.textPrimary, c.background)).toBeGreaterThanOrEqual(4.5);
+    });
+
+    it(`${scheme}: textSecondary auf surface erfüllt AA (>= 4.5:1)`, () => {
+      expect(contrastRatio(c.textSecondary, c.surface)).toBeGreaterThanOrEqual(4.5);
+    });
+
+    it(`${scheme}: accentContrast auf accent erfüllt AA (>= 4.5:1)`, () => {
+      expect(contrastRatio(c.accentContrast, c.accent)).toBeGreaterThanOrEqual(4.5);
+    });
+
+    it(`${scheme}: dangerContrast auf danger erfüllt AA (>= 4.5:1)`, () => {
+      expect(contrastRatio(c.dangerContrast, c.danger)).toBeGreaterThanOrEqual(4.5);
+    });
+  }
+});

web/shl/components/Dialog.tsx

@@ -0,0 +1,88 @@
+"use client";
+
+// Dialog-Basis-Komponente — SHL-01. WCAG 2.1 AA: Fokus-Falle, ESC schließt, Tastaturbedienung vollständig.
+
+import { useEffect, useRef } from "react";
+import type { ReactNode } from "react";
+import { useI18n } from "../i18n/i18n";
+
+const FOCUSABLE_SELECTOR =
+  'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+export interface DialogProps {
+  open: boolean;
+  onClose: () => void;
+  titleId: string;
+  title: string;
+  children: ReactNode;
+}
+
+export function Dialog({ open, onClose, titleId, title, children }: DialogProps) {
+  const { t } = useI18n();
+  const dialogRef = useRef<HTMLDivElement>(null);
+  const previouslyFocused = useRef<HTMLElement | null>(null);
+
+  useEffect(() => {
+    if (!open) return;
+    previouslyFocused.current = document.activeElement as HTMLElement | null;
+
+    const node = dialogRef.current;
+    const focusables = node?.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR);
+    focusables?.[0]?.focus();
+
+    function handleKeyDown(event: KeyboardEvent) {
+      if (event.key === "Escape") {
+        onClose();
+        return;
+      }
+      if (event.key !== "Tab" || !node) return;
+
+      const items = Array.from(node.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR));
+      if (items.length === 0) return;
+      const first = items[0];
+      const last = items[items.length - 1];
+
+      if (event.shiftKey && document.activeElement === first) {
+        event.preventDefault();
+        last.focus();
+      } else if (!event.shiftKey && document.activeElement === last) {
+        event.preventDefault();
+        first.focus();
+      }
+    }
+
+    document.addEventListener("keydown", handleKeyDown);
+    return () => {
+      document.removeEventListener("keydown", handleKeyDown);
+      previouslyFocused.current?.focus();
+    };
+  }, [open, onClose]);
+
+  if (!open) return null;
+
+  return (
+    <div
+      className="shl-dialog-backdrop"
+      role="presentation"
+      onMouseDown={(event) => {
+        if (event.target === event.currentTarget) onClose();
+      }}
+    >
+      <div
+        ref={dialogRef}
+        className="shl-dialog"
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby={titleId}
+      >
+        <div className="shl-dialog-header">
+          <h2 id={titleId}>{title}</h2>
+          <button type="button" onClick={onClose} aria-label={t("shl.dialog.close")}>
+            ×
+          </button>
+        </div>
+        <div className="shl-dialog-body">{children}</div>
+      </div>
+    </div>
+  );
+}

web/shl/components/FormElements.tsx

@@ -0,0 +1,98 @@
+// Formularelemente-Basis-Komponenten — SHL-01. WCAG: jedes Feld hat verknüpftes <label>,
+// Fehler werden per aria-describedby + aria-invalid angebunden, nicht nur farblich markiert.
+
+import { useId } from "react";
+import type { InputHTMLAttributes, ReactNode, SelectHTMLAttributes } from "react";
+
+interface FieldWrapperProps {
+  label: string;
+  error?: string;
+  hint?: string;
+  children: (ids: { inputId: string; describedBy: string | undefined }) => ReactNode;
+}
+
+function FieldWrapper({ label, error, hint, children }: FieldWrapperProps) {
+  const inputId = useId();
+  const hintId = hint ? `${inputId}-hint` : undefined;
+  const errorId = error ? `${inputId}-error` : undefined;
+  const describedBy = [hintId, errorId].filter(Boolean).join(" ") || undefined;
+
+  return (
+    <div className="shl-field">
+      <label htmlFor={inputId}>{label}</label>
+      {children({ inputId, describedBy })}
+      {hint && (
+        <p id={hintId} className="shl-field-hint">
+          {hint}
+        </p>
+      )}
+      {error && (
+        <p id={errorId} className="shl-field-error" role="alert">
+          {error}
+        </p>
+      )}
+    </div>
+  );
+}
+
+export interface TextFieldProps
+  extends Omit<InputHTMLAttributes<HTMLInputElement>, "id" | "aria-describedby"> {
+  label: string;
+  error?: string;
+  hint?: string;
+}
+
+export function TextField({ label, error, hint, ...inputProps }: TextFieldProps) {
+  return (
+    <FieldWrapper label={label} error={error} hint={hint}>
+      {({ inputId, describedBy }) => (
+        <input
+          id={inputId}
+          aria-describedby={describedBy}
+          aria-invalid={error ? true : undefined}
+          {...inputProps}
+        />
+      )}
+    </FieldWrapper>
+  );
+}
+
+export interface SelectFieldProps
+  extends Omit<SelectHTMLAttributes<HTMLSelectElement>, "id" | "aria-describedby"> {
+  label: string;
+  error?: string;
+  hint?: string;
+  children: ReactNode;
+}
+
+export function SelectField({ label, error, hint, children, ...selectProps }: SelectFieldProps) {
+  return (
+    <FieldWrapper label={label} error={error} hint={hint}>
+      {({ inputId, describedBy }) => (
+        <select
+          id={inputId}
+          aria-describedby={describedBy}
+          aria-invalid={error ? true : undefined}
+          {...selectProps}
+        >
+          {children}
+        </select>
+      )}
+    </FieldWrapper>
+  );
+}
+
+export interface CheckboxFieldProps
+  extends Omit<InputHTMLAttributes<HTMLInputElement>, "id" | "type"> {
+  label: string;
+}
+
+export function CheckboxField({ label, ...inputProps }: CheckboxFieldProps) {
+  const inputId = useId();
+  return (
+    <div className="shl-field shl-field-checkbox">
+      <input id={inputId} type="checkbox" {...inputProps} />
+      <label htmlFor={inputId}>{label}</label>
+    </div>
+  );
+}

web/shl/components/Shell.tsx

@@ -0,0 +1,62 @@
+"use client";
+
+// Layout-Shell mit Navigation — SHL-01 Akzeptanzkriterium 1.
+// Globale Navigation zeigt nur Module, die Core für Tenant/Benutzer freigibt (Backend entscheidet, UI blendet nur aus).
+
+import type { ReactNode } from "react";
+import { useI18n } from "../i18n/i18n";
+import { useTheme } from "../theme/ThemeProvider";
+
+export interface ModuleLink {
+  key: string;
+  label: string;
+  href: string;
+  active?: boolean;
+}
+
+export interface ShellProps {
+  modules: ModuleLink[];
+  tenantLabel: string;
+  children: ReactNode;
+}
+
+export function Shell({ modules, tenantLabel, children }: ShellProps) {
+  const { scheme, toggle } = useTheme();
+  const { t } = useI18n();
+
+  return (
+    <div className="shl-shell">
+      <a className="shl-skip-link" href="#shl-main-content">
+        {t("shl.shell.skipToContent", "Zum Inhalt springen")}
+      </a>
+      <header className="shl-shell-header">
+        <nav aria-label={t("shl.shell.moduleNav", "Modul-Navigation")}>
+          <ul>
+            {modules.map((mod) => (
+              <li key={mod.key}>
+                <a href={mod.href} aria-current={mod.active ? "page" : undefined}>
+                  {mod.label}
+                </a>
+              </li>
+            ))}
+          </ul>
+        </nav>
+        <div className="shl-shell-context">
+          <span className="shl-tenant-context">{tenantLabel}</span>
+          <button
+            type="button"
+            onClick={toggle}
+            aria-label={
+              scheme === "light" ? t("shl.theme.toggleToDark") : t("shl.theme.toggleToLight")
+            }
+          >
+            {scheme === "light" ? "🌙" : "☀️"}
+          </button>
+        </div>
+      </header>
+      <main id="shl-main-content" className="shl-shell-content" tabIndex={-1}>
+        {children}
+      </main>
+    </div>
+  );
+}

web/shl/components/Table.tsx

@@ -0,0 +1,83 @@
+// Table-Basis-Komponente — SHL-01. WCAG: semantische <table>, scope auf Kopfzellen, sortierbare Spalten per Tastatur.
+
+import type { ReactNode } from "react";
+import { useI18n } from "../i18n/i18n";
+
+export interface TableColumn<Row> {
+  key: string;
+  header: string;
+  render: (row: Row) => ReactNode;
+  sortable?: boolean;
+}
+
+export interface TableProps<Row> {
+  columns: TableColumn<Row>[];
+  rows: Row[];
+  rowKey: (row: Row) => string;
+  sortKey?: string;
+  sortDirection?: "asc" | "desc";
+  onSort?: (key: string) => void;
+  caption?: string;
+}
+
+export function Table<Row>({
+  columns,
+  rows,
+  rowKey,
+  sortKey,
+  sortDirection,
+  onSort,
+  caption,
+}: TableProps<Row>) {
+  const { t } = useI18n();
+
+  return (
+    <table className="shl-table">
+      {caption && <caption>{caption}</caption>}
+      <thead>
+        <tr>
+          {columns.map((column) => {
+            const isSorted = column.key === sortKey;
+            const ariaSort = column.sortable
+              ? isSorted
+                ? sortDirection === "asc"
+                  ? "ascending"
+                  : "descending"
+                : "none"
+              : undefined;
+            return (
+              <th key={column.key} scope="col" aria-sort={ariaSort}>
+                {column.sortable ? (
+                  <button
+                    type="button"
+                    onClick={() => onSort?.(column.key)}
+                    className="shl-table-sort-button"
+                  >
+                    {column.header}
+                  </button>
+                ) : (
+                  column.header
+                )}
+              </th>
+            );
+          })}
+        </tr>
+      </thead>
+      <tbody>
+        {rows.length === 0 ? (
+          <tr>
+            <td colSpan={columns.length}>{t("shl.table.noRows")}</td>
+          </tr>
+        ) : (
+          rows.map((row) => (
+            <tr key={rowKey(row)}>
+              {columns.map((column) => (
+                <td key={column.key}>{column.render(row)}</td>
+              ))}
+            </tr>
+          ))
+        )}
+      </tbody>
+    </table>
+  );
+}

web/shl/components/Toast.tsx

@@ -0,0 +1,67 @@
+"use client";
+
+// Toast-Basis-Komponente — SHL-01. WCAG: aria-live sorgt dafür, dass Screenreader Meldungen ansagen.
+
+import { createContext, useCallback, useContext, useMemo, useState } from "react";
+import type { ReactNode } from "react";
+import { useI18n } from "../i18n/i18n";
+
+export type ToastVariant = "info" | "success" | "danger" | "warning";
+
+export interface ToastMessage {
+  id: string;
+  text: string;
+  variant: ToastVariant;
+}
+
+interface ToastContextValue {
+  toasts: ToastMessage[];
+  push: (text: string, variant?: ToastVariant) => void;
+  dismiss: (id: string) => void;
+}
+
+const ToastContext = createContext<ToastContextValue | null>(null);
+
+export function ToastProvider({ children }: { children: ReactNode }) {
+  const [toasts, setToasts] = useState<ToastMessage[]>([]);
+  const { t } = useI18n();
+
+  const dismiss = useCallback((id: string) => {
+    setToasts((current) => current.filter((toast) => toast.id !== id));
+  }, []);
+
+  const push = useCallback((text: string, variant: ToastVariant = "info") => {
+    const id = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    setToasts((current) => [...current, { id, text, variant }]);
+  }, []);
+
+  const value = useMemo(() => ({ toasts, push, dismiss }), [toasts, push, dismiss]);
+
+  return (
+    <ToastContext.Provider value={value}>
+      {children}
+      <div className="shl-toast-region" role="status" aria-live="polite" aria-atomic="false">
+        {toasts.map((toast) => (
+          <div key={toast.id} className={`shl-toast shl-toast-${toast.variant}`}>
+            <span>{toast.text}</span>
+            <button
+              type="button"
+              onClick={() => dismiss(toast.id)}
+              aria-label={t("shl.toast.dismiss")}
+            >
+              ×
+            </button>
+          </div>
+        ))}
+      </div>
+    </ToastContext.Provider>
+  );
+}
+
+export function useToast(): ToastContextValue {
+  const ctx = useContext(ToastContext);
+  if (!ctx) {
+    throw new Error("useToast muss innerhalb von <ToastProvider> aufgerufen werden");
+  }
+  return ctx;
+}

web/shl/i18n/i18n.tsx

@@ -0,0 +1,75 @@
+"use client";
+
+// i18n-Rahmen (mind. Deutsch/Englisch) — SHL-01 Akzeptanzkriterium 5.
+// Liefert nur den Umschaltmechanismus + Basis-Komponenten-Texte.
+// Modul-Frontends liefern ihre eigenen fachlichen Textbausteine über registerMessages(),
+// statt einen eigenen i18n-Mechanismus zu bauen (siehe UI-UX-KONZEPT.md Abschnitt 4).
+
+import { createContext, useContext, useMemo, useState } from "react";
+import type { ReactNode } from "react";
+
+export type Locale = "de" | "en";
+
+type MessageDict = Record<string, string>;
+type MessageBundle = Record<Locale, MessageDict>;
+
+const baseMessages: MessageBundle = {
+  de: {
+    "shl.dialog.close": "Schließen",
+    "shl.toast.dismiss": "Meldung schließen",
+    "shl.table.noRows": "Keine Einträge vorhanden",
+    "shl.theme.toggleToLight": "Helles Erscheinungsbild",
+    "shl.theme.toggleToDark": "Dunkles Erscheinungsbild",
+  },
+  en: {
+    "shl.dialog.close": "Close",
+    "shl.toast.dismiss": "Dismiss message",
+    "shl.table.noRows": "No entries",
+    "shl.theme.toggleToLight": "Switch to light theme",
+    "shl.theme.toggleToDark": "Switch to dark theme",
+  },
+};
+
+// Registry, in die Modul-Frontends ihre eigenen Textbausteine einhängen.
+const registry: MessageBundle = { de: { ...baseMessages.de }, en: { ...baseMessages.en } };
+
+export function registerMessages(locale: Locale, messages: MessageDict): void {
+  registry[locale] = { ...registry[locale], ...messages };
+}
+
+interface I18nContextValue {
+  locale: Locale;
+  setLocale: (locale: Locale) => void;
+  t: (key: string, fallback?: string) => string;
+}
+
+const I18nContext = createContext<I18nContextValue | null>(null);
+
+export function I18nProvider({
+  initialLocale = "de",
+  children,
+}: {
+  initialLocale?: Locale;
+  children: ReactNode;
+}) {
+  const [locale, setLocale] = useState<Locale>(initialLocale);
+
+  const value = useMemo<I18nContextValue>(
+    () => ({
+      locale,
+      setLocale,
+      t: (key: string, fallback?: string) => registry[locale][key] ?? fallback ?? key,
+    }),
+    [locale],
+  );
+
+  return <I18nContext.Provider value={value}>{children}</I18nContext.Provider>;
+}
+
+export function useI18n(): I18nContextValue {
+  const ctx = useContext(I18nContext);
+  if (!ctx) {
+    throw new Error("useI18n muss innerhalb von <I18nProvider> aufgerufen werden");
+  }
+  return ctx;
+}

web/shl/index.ts

@@ -0,0 +1,25 @@
+// Öffentliche Schnittstelle des Pakets @nexarch/shl — Modul-Frontends importieren ausschließlich hierüber,
+// nicht aus internen Unterpfaden (SHL-01 Akzeptanzkriterium 2: dokumentiert, versioniert, importierbar statt kopiert).
+
+export { colorTokens, spacing, breakpoints, typography, cssVariables } from "./tokens/tokens";
+export type { ColorScheme, ColorTokens } from "./tokens/tokens";
+
+export { ThemeProvider, useTheme, currentColors } from "./theme/ThemeProvider";
+
+export { I18nProvider, useI18n, registerMessages } from "./i18n/i18n";
+export type { Locale } from "./i18n/i18n";
+
+export { Shell } from "./components/Shell";
+export type { ShellProps, ModuleLink } from "./components/Shell";
+
+export { Dialog } from "./components/Dialog";
+export type { DialogProps } from "./components/Dialog";
+
+export { Table } from "./components/Table";
+export type { TableProps, TableColumn } from "./components/Table";
+
+export { TextField, SelectField, CheckboxField } from "./components/FormElements";
+export type { TextFieldProps, SelectFieldProps, CheckboxFieldProps } from "./components/FormElements";
+
+export { ToastProvider, useToast } from "./components/Toast";
+export type { ToastMessage, ToastVariant } from "./components/Toast";

web/shl/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@nexarch/shl",
+  "version": "0.1.0",
+  "private": true,
+  "description": "NEXARCH UI-Shell & Design-System (Core SHL-01) — gemeinsames Paket für alle Modul-Frontends.",
+  "main": "index.ts",
+  "types": "index.ts",
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.4.8",
+    "@testing-library/react": "^16.0.0",
+    "@types/react": "18.3.3",
+    "@types/react-dom": "18.3.0",
+    "jsdom": "^24.1.1",
+    "typescript": "5.5.3",
+    "vitest": "^2.0.0"
+  }
+}

web/shl/theme/ThemeProvider.tsx

@@ -0,0 +1,81 @@
+"use client";
+
+// Zentrales Theming (Hell/Dunkel) — SHL-01 Akzeptanzkriterium 6.
+// Einzige Quelle für Hell/Dunkel-Werte; Modul-Frontends schalten nur um, bauen kein eigenes Theming.
+
+import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
+import type { ReactNode } from "react";
+import { colorTokens, cssVariables, type ColorScheme } from "../tokens/tokens";
+
+const STORAGE_KEY = "nexarch-shl-theme";
+
+interface ThemeContextValue {
+  scheme: ColorScheme;
+  setScheme: (scheme: ColorScheme) => void;
+  toggle: () => void;
+}
+
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+function readStoredScheme(): ColorScheme | null {
+  if (typeof window === "undefined") return null;
+  try {
+    const stored = window.localStorage.getItem(STORAGE_KEY);
+    return stored === "light" || stored === "dark" ? stored : null;
+  } catch {
+    // localStorage kann in privaten Fenstern/eingeschränkten Kontexten fehlschlagen — kein Absturz, nur kein persistierter Zustand.
+    return null;
+  }
+}
+
+function systemPrefersDark(): boolean {
+  if (typeof window === "undefined" || !window.matchMedia) return false;
+  return window.matchMedia("(prefers-color-scheme: dark)").matches;
+}
+
+export function ThemeProvider({ children }: { children: ReactNode }) {
+  const [scheme, setSchemeState] = useState<ColorScheme>("light");
+
+  useEffect(() => {
+    const stored = readStoredScheme();
+    setSchemeState(stored ?? (systemPrefersDark() ? "dark" : "light"));
+  }, []);
+
+  const setScheme = useCallback((next: ColorScheme) => {
+    setSchemeState(next);
+    try {
+      window.localStorage.setItem(STORAGE_KEY, next);
+    } catch {
+      // Speichern optional — Umschaltung funktioniert auch ohne Persistenz.
+    }
+  }, []);
+
+  const toggle = useCallback(() => {
+    setScheme(scheme === "light" ? "dark" : "light");
+  }, [scheme, setScheme]);
+
+  useEffect(() => {
+    const vars = cssVariables(scheme);
+    const root = document.documentElement;
+    for (const [key, value] of Object.entries(vars)) {
+      root.style.setProperty(key, value);
+    }
+    root.dataset.shlTheme = scheme;
+  }, [scheme]);
+
+  const value = useMemo(() => ({ scheme, setScheme, toggle }), [scheme, setScheme, toggle]);
+
+  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
+}
+
+export function useTheme(): ThemeContextValue {
+  const ctx = useContext(ThemeContext);
+  if (!ctx) {
+    throw new Error("useTheme muss innerhalb von <ThemeProvider> aufgerufen werden");
+  }
+  return ctx;
+}
+
+export function currentColors(scheme: ColorScheme) {
+  return colorTokens[scheme];
+}

web/shl/tokens/tokens.ts

@@ -0,0 +1,96 @@
+// Design-Tokens: einzige Quelle für Farbe, Abstand, Typografie im gesamten Frontend-Verbund.
+// Modul-Frontends importieren diese Tokens, überschreiben sie nicht lokal (SHL-01 Akzeptanzkriterium 3).
+// Kontrastwerte sind gegen WCAG 2.1 AA geprüft (Akzeptanzkriterium 1/4): mindestens 4.5:1 für Fließtext.
+
+export type ColorScheme = "light" | "dark";
+
+export interface ColorTokens {
+  background: string;
+  surface: string;
+  surfaceRaised: string;
+  border: string;
+  textPrimary: string;
+  textSecondary: string;
+  accent: string;
+  accentContrast: string;
+  danger: string;
+  dangerContrast: string;
+  success: string;
+  warning: string;
+  focusRing: string;
+}
+
+// Kontrastwerte geprüft: textPrimary auf background/surface >= 7:1, textSecondary >= 4.5:1,
+// accentContrast auf accent >= 4.5:1 (WCAG AA, siehe SHL-01 Prüfung 3).
+export const colorTokens: Record<ColorScheme, ColorTokens> = {
+  light: {
+    background: "#FFFFFF",
+    surface: "#F5F6F8",
+    surfaceRaised: "#FFFFFF",
+    border: "#D7DBE0",
+    textPrimary: "#14181F",
+    textSecondary: "#4B5563",
+    accent: "#1D4ED8",
+    accentContrast: "#FFFFFF",
+    danger: "#B91C1C",
+    dangerContrast: "#FFFFFF",
+    success: "#15803D",
+    warning: "#B45309",
+    focusRing: "#1D4ED8",
+  },
+  dark: {
+    background: "#0F1115",
+    surface: "#181B21",
+    surfaceRaised: "#20242C",
+    border: "#333944",
+    textPrimary: "#F2F4F7",
+    textSecondary: "#B4BAC4",
+    accent: "#5B8DEF",
+    accentContrast: "#0F1115",
+    danger: "#F87171",
+    dangerContrast: "#0F1115",
+    success: "#4ADE80",
+    warning: "#FBBF24",
+    focusRing: "#5B8DEF",
+  },
+};
+
+export const spacing = {
+  xs: "4px",
+  sm: "8px",
+  md: "16px",
+  lg: "24px",
+  xl: "32px",
+  xxl: "48px",
+} as const;
+
+export const breakpoints = {
+  mobile: "0px",
+  tablet: "768px",
+  desktop: "1200px",
+} as const;
+
+export const typography = {
+  fontFamily: "'Inter', 'Segoe UI', system-ui, sans-serif",
+  fontFamilyMono: "'JetBrains Mono', ui-monospace, monospace",
+  sizeSm: "13px",
+  sizeMd: "15px",
+  sizeLg: "18px",
+  sizeXl: "24px",
+  lineHeight: 1.5,
+  weightRegular: 400,
+  weightMedium: 500,
+  weightBold: 600,
+} as const;
+
+export function cssVariables(scheme: ColorScheme): Record<string, string> {
+  const c = colorTokens[scheme];
+  const vars: Record<string, string> = {};
+  for (const [key, value] of Object.entries(c)) {
+    vars[`--shl-color-${key.replace(/([A-Z])/g, "-$1").toLowerCase()}`] = value;
+  }
+  for (const [key, value] of Object.entries(spacing)) {
+    vars[`--shl-spacing-${key}`] = value;
+  }
+  return vars;
+}

web/shl/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "jsx": "react-jsx",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "declaration": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true
+  },
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules"]
+}

web/shl/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "jsdom",
+    setupFiles: ["./vitest.setup.ts"],
+  },
+});

web/shl/vitest.setup.ts

@@ -0,0 +1,9 @@
+import "@testing-library/jest-dom/vitest";
+import { afterEach } from "vitest";
+import { cleanup } from "@testing-library/react";
+
+// Ohne explizites Cleanup bleiben zwischen den it()-Blöcken gerenderte Dialoge im DOM stehen
+// (mehrere <html>/<body>-Bäume stapeln sich), wodurch getByRole() mehrere Treffer statt einen findet.
+afterEach(() => {
+  cleanup();
+});