Merge branch 'feature/shl-01-ui-shell-design-system-zentral' into feature/lic-04-lizenz-modul-verwaltungsoberflaeche

# 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,32 @@ 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 +
 
 ---

cmd/licadmin-devserver/main.go

@@ -0,0 +1,81 @@
+// licadmin-devserver stellt das LIC-04-Backend-API (internal/adminapi) fuer
+// die Next.js-Verwaltungsoberflaeche bereit. Getrennt von cmd/core, da die
+// Verdrahtung von license.Validator (Ed25519-Public-Key) in die zentrale
+// Server-Topologie erst mit API-01/IAM-01 (Auth vor internen Endpunkten)
+// sinnvoll ist — dieser Server dient der Entwicklung/dem Betrieb der
+// Verwaltungsoberflaeche gegen eine echte Datenbank, ohne cmd/core
+// anzufassen (Kein Umbau angrenzender Bereiche).
+package main
+
+import (
+	"context"
+	"crypto/ed25519"
+	"encoding/base64"
+	"log"
+	"net/http"
+	"os"
+	"time"
+
+	"gitea.perlbach24.de/scripte/nexarch/internal/adminapi"
+	"gitea.perlbach24.de/scripte/nexarch/internal/db"
+	"gitea.perlbach24.de/scripte/nexarch/internal/flag"
+	"gitea.perlbach24.de/scripte/nexarch/internal/license"
+	"gitea.perlbach24.de/scripte/nexarch/internal/usage"
+)
+
+func main() {
+	dsn := os.Getenv("NEXARCH_REGISTRY_DSN")
+	if dsn == "" {
+		log.Fatal("NEXARCH_REGISTRY_DSN nicht gesetzt")
+	}
+	pubKeyB64 := os.Getenv("NEXARCH_LICENSE_PUBLIC_KEY")
+	if pubKeyB64 == "" {
+		log.Fatal("NEXARCH_LICENSE_PUBLIC_KEY nicht gesetzt (base64, raw-url-encoding)")
+	}
+	pubKeyRaw, err := base64.RawURLEncoding.DecodeString(pubKeyB64)
+	if err != nil || len(pubKeyRaw) != ed25519.PublicKeySize {
+		log.Fatalf("NEXARCH_LICENSE_PUBLIC_KEY ungueltig: %v", err)
+	}
+
+	addr := os.Getenv("NEXARCH_LICADMIN_LISTEN_ADDR")
+	if addr == "" {
+		addr = ":8081"
+	}
+
+	ctx := context.Background()
+	pool, err := db.Connect(ctx, dsn)
+	if err != nil {
+		log.Fatalf("db: %v", err)
+	}
+	defer pool.Close()
+
+	licenseStore := license.NewStore(pool, license.NewValidator(ed25519.PublicKey(pubKeyRaw)))
+	flagStore := flag.NewStore(pool)
+	flagService := flag.NewService(flagStore, 5*time.Second)
+	usageStore := usage.NewStore(pool)
+	handler := adminapi.NewHandler(licenseStore, flagStore, flagService, usageStore)
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/admin/overview", withCORS(handler.OverviewHandler))
+	mux.HandleFunc("/admin/flags/toggle", withCORS(handler.ToggleFlagHandler))
+	mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(http.StatusOK) })
+
+	log.Printf("licadmin-devserver listening on %s", addr)
+	log.Fatal(http.ListenAndServe(addr, mux))
+}
+
+// withCORS erlaubt lokale Entwicklung des Next.js-Frontends auf einem
+// anderen Port als das Backend-API — ausschliesslich fuer diesen
+// Entwicklungsserver, keine Produktionshaertung.
+func withCORS(next http.HandlerFunc) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Access-Control-Allow-Origin", "*")
+		w.Header().Set("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
+		w.Header().Set("Access-Control-Allow-Headers", "Content-Type")
+		if r.Method == http.MethodOptions {
+			w.WriteHeader(http.StatusOK)
+			return
+		}
+		next(w, r)
+	}
+}

internal/adminapi/lichandler.go

@@ -0,0 +1,226 @@
+// Package adminapi implementiert Core LIC-04: das Backend-API fuer die
+// Lizenz-/Modul-Verwaltungsoberflaeche. Das Paket enthaelt KEINE eigene
+// Lizenz-/Flag-/Quota-Logik, sondern ist ein duenner Vermittler ueber
+// internal/license, internal/flag und internal/usage (Ticket-Vorgabe:
+// "Verwaltungsoberflaeche als duenner Client ... ohne eigene Lizenzlogik").
+package adminapi
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"strings"
+
+	"gitea.perlbach24.de/scripte/nexarch/internal/flag"
+	"gitea.perlbach24.de/scripte/nexarch/internal/license"
+	"gitea.perlbach24.de/scripte/nexarch/internal/usage"
+)
+
+// UsageMetrics sind die Metriken, die auf der Uebersichtsseite je Tenant
+// dargestellt werden (Akzeptanzkriterium 3). Neue Metriken hinzuzufuegen
+// beruehrt kein bestehendes Verhalten von internal/usage.
+var UsageMetrics = []string{"users", "storage_bytes", "api_calls"}
+
+// FlagOverview ist ein Flag zusammen mit der fuer den Tenant ausgewerteten
+// Berechtigung, es umzuschalten (Akzeptanzkriterium 2).
+type FlagOverview struct {
+	Key       string `json:"key"`
+	Enabled   bool   `json:"enabled"`
+	Licensed  bool   `json:"licensed"`
+	DenyGrund string `json:"deny_grund,omitempty"`
+}
+
+// UsageOverview ist eine Metrik mit Zaehlerstand, Quota und Status
+// (Akzeptanzkriterium 3).
+type UsageOverview struct {
+	Metric string       `json:"metric"`
+	Value  int64        `json:"value"`
+	Limit  int64        `json:"limit"`
+	Status usage.Status `json:"status"`
+}
+
+// Overview ist die vollstaendige Antwort fuer die Uebersichtsseite
+// (Akzeptanzkriterium 1: Lizenzstatus/Laufzeit/Module auf einen Blick).
+type Overview struct {
+	Plan       string          `json:"plan"`
+	Modules    []string        `json:"modules"`
+	IssuedAt   string          `json:"issued_at"`
+	ValidUntil string          `json:"valid_until"`
+	Expired    bool            `json:"expired"`
+	Flags      []FlagOverview  `json:"flags"`
+	Usage      []UsageOverview `json:"usage"`
+}
+
+// ErrFlagNotLicensed wird geliefert, wenn ein Administrator versucht, ein
+// Flag zu aktivieren, dessen zugehoeriges Modul die Lizenz nicht umfasst
+// (Akzeptanzkriterium 2 / Pruefung 1).
+var ErrFlagNotLicensed = errors.New("adminapi: modul ist durch die aktuelle lizenz nicht freigeschaltet")
+
+// Handler buendelt die drei Vorbedingungs-Dienste hinter einem gemeinsamen
+// HTTP-API fuer das Frontend.
+type Handler struct {
+	licenseStore *license.Store
+	flagStore    *flag.Store
+	flagService  *flag.Service
+	usageStore   *usage.Store
+}
+
+func NewHandler(licenseStore *license.Store, flagStore *flag.Store, flagService *flag.Service, usageStore *usage.Store) *Handler {
+	return &Handler{licenseStore: licenseStore, flagStore: flagStore, flagService: flagService, usageStore: usageStore}
+}
+
+// isModuleLicensed prueft, ob ein Flag-Schluessel als lizenziertes Modul
+// gilt. Konvention: ein Flag-Key der Form "module:<name>" ist an das
+// gleichnamige Modul in Payload.Modules gebunden; alle anderen Flag-Keys
+// gelten als lizenzunabhaengige, rein funktionale Schalter.
+func isModuleLicensed(key string, modules []string) (moduleName string, isModuleFlag bool, licensed bool) {
+	const prefix = "module:"
+	if !strings.HasPrefix(key, prefix) {
+		return "", false, true
+	}
+	moduleName = strings.TrimPrefix(key, prefix)
+	for _, m := range modules {
+		if m == moduleName {
+			return moduleName, true, true
+		}
+	}
+	return moduleName, true, false
+}
+
+// Overview liefert die kombinierte Uebersicht fuer einen Tenant
+// (Akzeptanzkriterium 1 + 3).
+func (h *Handler) Overview(ctx context.Context, tenantID string) (Overview, error) {
+	lic, err := h.licenseStore.Status(ctx, tenantID)
+	if err != nil {
+		return Overview{}, fmt.Errorf("lizenzstatus lesen: %w", err)
+	}
+	_, expiredErr := h.licenseStore.RequireActive(ctx, tenantID)
+	expired := errors.Is(expiredErr, license.ErrLicenseExpired)
+
+	flags, err := h.flagStore.List(ctx)
+	if err != nil {
+		return Overview{}, fmt.Errorf("flags lesen: %w", err)
+	}
+
+	tenantSlug := tenantID // Auswertung erwartet den Tenant-Bezug als String; Aufloesung ID->Slug obliegt dem Aufrufer (siehe Handler-Tests).
+	flagOverviews := make([]FlagOverview, 0, len(flags))
+	for _, f := range flags {
+		_, _, licensed := isModuleLicensed(f.Key, lic.Modules)
+		fo := FlagOverview{
+			Key:      f.Key,
+			Enabled:  h.flagService.IsEnabled(ctx, tenantSlug, f.Key),
+			Licensed: licensed,
+		}
+		if !licensed {
+			fo.DenyGrund = "Modul ist im aktuellen Lizenzplan nicht enthalten"
+		}
+		flagOverviews = append(flagOverviews, fo)
+	}
+
+	usageOverviews := make([]UsageOverview, 0, len(UsageMetrics))
+	for _, metric := range UsageMetrics {
+		value, limit, status, err := h.usageStore.Check(ctx, tenantID, metric)
+		if err != nil {
+			return Overview{}, fmt.Errorf("nutzungsstand lesen (%s): %w", metric, err)
+		}
+		usageOverviews = append(usageOverviews, UsageOverview{
+			Metric: metric, Value: value, Limit: limit, Status: status,
+		})
+	}
+
+	return Overview{
+		Plan:       lic.Plan,
+		Modules:    lic.Modules,
+		IssuedAt:   lic.IssuedAt.Format("2006-01-02T15:04:05Z07:00"),
+		ValidUntil: lic.ValidUntil.Format("2006-01-02T15:04:05Z07:00"),
+		Expired:    expired,
+		Flags:      flagOverviews,
+		Usage:      usageOverviews,
+	}, nil
+}
+
+// ToggleFlag schaltet ein Flag global an/aus, NACHDEM geprueft wurde, dass
+// das zugehoerige Modul lizenziert ist (Akzeptanzkriterium 2 / Pruefung 1).
+// Ein nicht lizenziertes Modul wird mit ErrFlagNotLicensed abgelehnt, bevor
+// irgendein Schreibzugriff erfolgt.
+func (h *Handler) ToggleFlag(ctx context.Context, tenantID, key string, enabled bool) error {
+	lic, err := h.licenseStore.Status(ctx, tenantID)
+	if err != nil {
+		return fmt.Errorf("lizenzstatus lesen: %w", err)
+	}
+
+	if enabled {
+		if _, _, licensed := isModuleLicensed(key, lic.Modules); !licensed {
+			return ErrFlagNotLicensed
+		}
+	}
+
+	existing, err := h.flagStore.Get(ctx, key)
+	if err != nil && !errors.Is(err, flag.ErrNotFound) {
+		return fmt.Errorf("flag lesen: %w", err)
+	}
+	existing.Key = key
+	existing.Enabled = enabled
+
+	if err := h.flagStore.Set(ctx, existing); err != nil {
+		return fmt.Errorf("flag speichern: %w", err)
+	}
+	h.flagService.Invalidate(key)
+	return nil
+}
+
+// --- HTTP-Bindung ---
+
+func (h *Handler) OverviewHandler(w http.ResponseWriter, r *http.Request) {
+	tenantID := r.URL.Query().Get("tenant")
+	if tenantID == "" {
+		writeError(w, http.StatusBadRequest, "tenant-parameter fehlt")
+		return
+	}
+	overview, err := h.Overview(r.Context(), tenantID)
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, err.Error())
+		return
+	}
+	writeJSON(w, http.StatusOK, overview)
+}
+
+type toggleRequest struct {
+	Tenant  string `json:"tenant"`
+	Key     string `json:"key"`
+	Enabled bool   `json:"enabled"`
+}
+
+func (h *Handler) ToggleFlagHandler(w http.ResponseWriter, r *http.Request) {
+	var req toggleRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeError(w, http.StatusBadRequest, "ungueltiger anfrage-koerper")
+		return
+	}
+	if req.Tenant == "" || req.Key == "" {
+		writeError(w, http.StatusBadRequest, "tenant und key sind erforderlich")
+		return
+	}
+
+	err := h.ToggleFlag(r.Context(), req.Tenant, req.Key, req.Enabled)
+	switch {
+	case err == nil:
+		writeJSON(w, http.StatusOK, map[string]string{"status": "ok"})
+	case errors.Is(err, ErrFlagNotLicensed):
+		writeError(w, http.StatusForbidden, ErrFlagNotLicensed.Error())
+	default:
+		writeError(w, http.StatusInternalServerError, err.Error())
+	}
+}
+
+func writeJSON(w http.ResponseWriter, status int, body any) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	_ = json.NewEncoder(w).Encode(body)
+}
+
+func writeError(w http.ResponseWriter, status int, message string) {
+	writeJSON(w, status, map[string]string{"error": message})
+}

internal/adminapi/lichandler_test.go

@@ -0,0 +1,275 @@
+package adminapi
+
+import (
+	"bytes"
+	"context"
+	"crypto/ed25519"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"gitea.perlbach24.de/scripte/nexarch/internal/flag"
+	"gitea.perlbach24.de/scripte/nexarch/internal/license"
+	"gitea.perlbach24.de/scripte/nexarch/internal/usage"
+)
+
+type testEnv struct {
+	handler  *Handler
+	tenantID string
+	pool     *pgxpool.Pool
+}
+
+func setupTest(t *testing.T) (testEnv, 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 tenants (
+			id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+			slug TEXT NOT NULL UNIQUE,
+			name TEXT NOT NULL,
+			db_name TEXT NOT NULL UNIQUE,
+			db_dsn TEXT NOT NULL,
+			status TEXT NOT NULL DEFAULT 'active',
+			created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+		);
+		CREATE TABLE IF NOT EXISTS tenant_licenses (
+			tenant_id UUID PRIMARY KEY REFERENCES tenants(id),
+			plan TEXT NOT NULL,
+			modules TEXT[] NOT NULL,
+			issued_at TIMESTAMPTZ NOT NULL,
+			valid_until TIMESTAMPTZ NOT NULL,
+			raw_key TEXT NOT NULL,
+			installed_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 usage_counters (
+			tenant_id UUID NOT NULL, metric TEXT NOT NULL, value BIGINT NOT NULL DEFAULT 0,
+			updated_at TIMESTAMPTZ NOT NULL DEFAULT now(), PRIMARY KEY (tenant_id, metric)
+		);
+		CREATE TABLE IF NOT EXISTS usage_quotas (
+			tenant_id UUID NOT NULL, metric TEXT NOT NULL, limit_value BIGINT NOT NULL,
+			PRIMARY KEY (tenant_id, metric)
+		);
+	`); err != nil {
+		t.Fatalf("schema: %v", err)
+	}
+
+	slug := fmt.Sprintf("adminapi_test_%d", time.Now().UnixNano())
+	var tenantID string
+	if err := pool.QueryRow(ctx, `
+		INSERT INTO tenants (slug, name, db_name, db_dsn)
+		VALUES ($1, 'Adminapi Test', $1, 'unused') RETURNING id
+	`, slug).Scan(&tenantID); err != nil {
+		t.Fatalf("test-tenant anlegen: %v", err)
+	}
+
+	pub, priv, err := ed25519.GenerateKey(nil)
+	if err != nil {
+		t.Fatalf("schluesselpaar: %v", err)
+	}
+	issuer := license.NewIssuer(priv)
+	licenseStore := license.NewStore(pool, license.NewValidator(pub))
+
+	payload := license.Payload{
+		TenantSlug: slug,
+		Plan:       "professional",
+		Modules:    []string{"dms", "mail"},
+		IssuedAt:   time.Now().Truncate(time.Second),
+		ValidUntil: time.Now().Add(30 * 24 * time.Hour).Truncate(time.Second),
+	}
+	key, err := issuer.Issue(payload)
+	if err != nil {
+		t.Fatalf("lizenz ausstellen: %v", err)
+	}
+	if _, err := licenseStore.Install(ctx, tenantID, key); err != nil {
+		t.Fatalf("lizenz installieren: %v", err)
+	}
+
+	flagStore := flag.NewStore(pool)
+	flagService := flag.NewService(flagStore, time.Millisecond) // sehr kurze TTL, damit Tests nicht auf Cache-Ablauf warten muessen
+	usageStore := usage.NewStore(pool)
+
+	handler := NewHandler(licenseStore, flagStore, flagService, usageStore)
+
+	cleanup := func() {
+		_, _ = pool.Exec(ctx, `DELETE FROM usage_quotas WHERE tenant_id = $1`, tenantID)
+		_, _ = pool.Exec(ctx, `DELETE FROM usage_counters WHERE tenant_id = $1`, tenantID)
+		_, _ = pool.Exec(ctx, `DELETE FROM tenant_licenses WHERE tenant_id = $1`)
+		_, _ = pool.Exec(ctx, `DELETE FROM tenants WHERE id = $1`, tenantID)
+		_, _ = pool.Exec(ctx, `DELETE FROM feature_flags WHERE key LIKE 'adminapi\_test\_%' ESCAPE '\'`)
+		pool.Close()
+	}
+	return testEnv{handler: handler, tenantID: tenantID, pool: pool}, cleanup
+}
+
+// Akzeptanzkriterium 1: Lizenzstatus, Laufzeit und Module sind auf einen
+// Blick abfragbar.
+func TestOverview_ShowsLicenseStatusAndModules(t *testing.T) {
+	env, cleanup := setupTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	overview, err := env.handler.Overview(ctx, env.tenantID)
+	if err != nil {
+		t.Fatalf("overview: %v", err)
+	}
+	if overview.Plan != "professional" {
+		t.Fatalf("plan = %q, want professional", overview.Plan)
+	}
+	if len(overview.Modules) != 2 {
+		t.Fatalf("module = %v, want 2 eintraege", overview.Modules)
+	}
+	if overview.Expired {
+		t.Fatal("lizenz sollte nicht abgelaufen sein")
+	}
+}
+
+// Akzeptanzkriterium 2 + Pruefung 1: Umschalten eines nicht lizenzierten
+// Features wird verhindert und verstaendlich begruendet.
+func TestToggleFlag_RejectsUnlicensedModule(t *testing.T) {
+	env, cleanup := setupTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	err := env.handler.ToggleFlag(ctx, env.tenantID, "module:archive", true)
+	if err == nil {
+		t.Fatal("erwartet fehler beim aktivieren eines nicht lizenzierten moduls")
+	}
+	if err.Error() == "" {
+		t.Fatal("fehlermeldung sollte verstaendlich sein, nicht leer")
+	}
+	t.Logf("erhaltene begruendung: %v", err)
+
+	// Sicherstellen, dass NICHTS geschrieben wurde: Flag existiert weiterhin nicht.
+	if _, ferr := flag.NewStore(env.pool).Get(ctx, "module:archive"); ferr == nil {
+		t.Fatal("flag haette wegen fehlender lizenz nicht angelegt werden duerfen")
+	}
+}
+
+// Akzeptanzkriterium 2: lizenziertes Modul laesst sich umschalten.
+func TestToggleFlag_AllowsLicensedModule(t *testing.T) {
+	env, cleanup := setupTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	if err := env.handler.ToggleFlag(ctx, env.tenantID, "module:dms", true); err != nil {
+		t.Fatalf("erwartet erfolg fuer lizenziertes modul, habe: %v", err)
+	}
+
+	overview, err := env.handler.Overview(ctx, env.tenantID)
+	if err != nil {
+		t.Fatalf("overview: %v", err)
+	}
+	found := false
+	for _, f := range overview.Flags {
+		if f.Key == "module:dms" {
+			found = true
+			if !f.Enabled || !f.Licensed {
+				t.Fatalf("flag-status unerwartet: %+v", f)
+			}
+		}
+	}
+	if !found {
+		t.Fatal("erwartet 'module:dms' in der uebersicht nach dem umschalten")
+	}
+}
+
+// Akzeptanzkriterium 3 + Pruefung 2: Nutzungsstand stimmt mit den
+// Backend-Zaehlern ueberein.
+func TestOverview_UsageMatchesBackendCounters(t *testing.T) {
+	env, cleanup := setupTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	usageStore := usage.NewStore(env.pool)
+	if err := usageStore.Increment(ctx, env.tenantID, "users", 7); err != nil {
+		t.Fatalf("increment: %v", err)
+	}
+	if err := usageStore.SetQuota(ctx, env.tenantID, "users", 10); err != nil {
+		t.Fatalf("setquota: %v", err)
+	}
+
+	overview, err := env.handler.Overview(ctx, env.tenantID)
+	if err != nil {
+		t.Fatalf("overview: %v", err)
+	}
+
+	var got *UsageOverview
+	for i := range overview.Usage {
+		if overview.Usage[i].Metric == "users" {
+			got = &overview.Usage[i]
+		}
+	}
+	if got == nil {
+		t.Fatal("erwartet metrik 'users' in der uebersicht")
+	}
+	if got.Value != 7 || got.Limit != 10 || got.Status != usage.StatusOK {
+		t.Fatalf("nutzungsstand stimmt nicht mit backend-zaehler ueberein: %+v (want value=7 limit=10 status=ok, da 7/10=70%% unter der 80%%-warnschwelle liegt)", got)
+	}
+}
+
+// Akzeptanzkriterium 2 / Pruefung 1 auf HTTP-Ebene: der Endpunkt liefert
+// 403 mit verstaendlicher Fehlermeldung, kein interner Serverfehler.
+func TestToggleFlagHandler_HTTPForbiddenOnUnlicensed(t *testing.T) {
+	env, cleanup := setupTest(t)
+	defer cleanup()
+
+	body, _ := json.Marshal(toggleRequest{Tenant: env.tenantID, Key: "module:archive", Enabled: true})
+	req := httptest.NewRequest(http.MethodPost, "/admin/flags/toggle", bytes.NewReader(body))
+	rec := httptest.NewRecorder()
+
+	env.handler.ToggleFlagHandler(rec, req)
+
+	if rec.Code != http.StatusForbidden {
+		t.Fatalf("status = %d, want 403", rec.Code)
+	}
+	var resp map[string]string
+	if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("body parsen: %v", err)
+	}
+	if resp["error"] == "" {
+		t.Fatal("erwartet verstaendliche fehlermeldung im response-body")
+	}
+}
+
+func TestOverviewHandler_HTTPReturnsCombinedData(t *testing.T) {
+	env, cleanup := setupTest(t)
+	defer cleanup()
+
+	req := httptest.NewRequest(http.MethodGet, "/admin/overview?tenant="+env.tenantID, nil)
+	rec := httptest.NewRecorder()
+	env.handler.OverviewHandler(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200", rec.Code)
+	}
+	var overview Overview
+	if err := json.Unmarshal(rec.Body.Bytes(), &overview); err != nil {
+		t.Fatalf("body parsen: %v", err)
+	}
+	if overview.Plan != "professional" {
+		t.Fatalf("plan = %q, want professional", overview.Plan)
+	}
+}

internal/flag/flag.go

@@ -0,0 +1,110 @@
+// 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
+}
+
+// List liefert alle definierten Flags (Admin-Uebersicht, siehe LIC-04) —
+// rein additiv, aendert nichts am bestehenden Verhalten von Set/Get.
+func (s *Store) List(ctx context.Context) ([]Flag, error) {
+	rows, err := s.pool.Query(ctx, `
+		SELECT key, enabled, rollout_percentage, target_tenant_slugs
+		FROM feature_flags ORDER BY key
+	`)
+	if err != nil {
+		return nil, fmt.Errorf("flags auflisten: %w", err)
+	}
+	defer rows.Close()
+
+	var out []Flag
+	for rows.Next() {
+		var f Flag
+		if err := rows.Scan(&f.Key, &f.Enabled, &f.RolloutPercentage, &f.TargetTenantSlugs); err != nil {
+			return nil, fmt.Errorf("flag-zeile lesen: %w", err)
+		}
+		out = append(out, f)
+	}
+	return out, rows.Err()
+}
+
+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

@@ -0,0 +1,43 @@
+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

@@ -0,0 +1,87 @@
+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

@@ -0,0 +1,179 @@
+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/license/license.go

@@ -0,0 +1,106 @@
+// Package license implementiert Core LIC-01: Lizenzmodell je Tenant (Plan,
+// Modul-Umfang, Laufzeit) und die kryptographische Pruefung signierter
+// Lizenzschluessel. Feature-Flag-AUSWERTUNG zur Laufzeit (LIC-02) und die
+// Verwaltungsoberflaeche (LIC-04) sind ausdruecklich nicht Teil dieses Pakets
+// — hier geht es nur um Ausstellung/Validierung/Persistenz (Unleash-Vorbild:
+// klare Trennung Flag-Verwaltung vs. Flag-Auswertung).
+package license
+
+import (
+	"crypto/ed25519"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"time"
+)
+
+var (
+	ErrInvalidSignature = errors.New("license: signatur ungueltig")
+	ErrMalformedKey     = errors.New("license: lizenzschluessel hat ungueltiges format")
+)
+
+// Payload ist der signierte Lizenzinhalt (Akzeptanzkriterium 3: Plan,
+// Modul-Liste, Laufzeit).
+type Payload struct {
+	TenantSlug string    `json:"tenant_slug"`
+	Plan       string    `json:"plan"`
+	Modules    []string  `json:"modules"`
+	IssuedAt   time.Time `json:"issued_at"`
+	ValidUntil time.Time `json:"valid_until"`
+}
+
+// Issuer stellt signierte Lizenzschluessel aus. Haelt den PRIVATEN
+// Ed25519-Schluessel — lebt in der Praxis beim Lizenzgeber, nicht im
+// laufenden Core-Prozess (der nur den Validator mit dem oeffentlichen
+// Schluessel braucht).
+type Issuer struct {
+	priv ed25519.PrivateKey
+}
+
+func NewIssuer(priv ed25519.PrivateKey) *Issuer {
+	return &Issuer{priv: priv}
+}
+
+// Issue liefert den Lizenzschluessel im Format base64(payload-json) "." base64(signatur).
+func (i *Issuer) Issue(payload Payload) (string, error) {
+	raw, err := json.Marshal(payload)
+	if err != nil {
+		return "", fmt.Errorf("payload serialisieren: %w", err)
+	}
+	sig := ed25519.Sign(i.priv, raw)
+
+	return base64.RawURLEncoding.EncodeToString(raw) + "." + base64.RawURLEncoding.EncodeToString(sig), nil
+}
+
+// Validator prueft Lizenzschluessel gegen den OEFFENTLICHEN Ed25519-Schluessel
+// — das ist alles, was der laufende Core-Prozess kennen muss.
+type Validator struct {
+	pub ed25519.PublicKey
+}
+
+func NewValidator(pub ed25519.PublicKey) *Validator {
+	return &Validator{pub: pub}
+}
+
+// Parse prueft die Signatur (Akzeptanzkriterium 1 / Pruefung 1) und liefert
+// bei Erfolg den entschluesselten Payload. Ein manipulierter Schluessel wird
+// hier zuverlaessig erkannt, unabhaengig davon, ob die Laufzeit noch gueltig
+// waere — Signaturpruefung und Ablaufpruefung sind bewusst getrennt
+// (Signatur bei Einspielen, Ablauf bei jeder Nutzung, siehe Store.RequireActive).
+func (v *Validator) Parse(key string) (Payload, error) {
+	rawPart, sigPart, ok := splitOnce(key, '.')
+	if !ok {
+		return Payload{}, ErrMalformedKey
+	}
+
+	raw, err := base64.RawURLEncoding.DecodeString(rawPart)
+	if err != nil {
+		return Payload{}, ErrMalformedKey
+	}
+	sig, err := base64.RawURLEncoding.DecodeString(sigPart)
+	if err != nil {
+		return Payload{}, ErrMalformedKey
+	}
+
+	if !ed25519.Verify(v.pub, raw, sig) {
+		return Payload{}, ErrInvalidSignature
+	}
+
+	var p Payload
+	if err := json.Unmarshal(raw, &p); err != nil {
+		// Signatur war gueltig, aber Payload nicht mehr parsebar — sollte bei
+		// unveraenderten Schluesseln nie vorkommen, trotzdem kein Panic.
+		return Payload{}, fmt.Errorf("%w: payload nicht lesbar", ErrMalformedKey)
+	}
+	return p, nil
+}
+
+func splitOnce(s string, sep byte) (before, after string, ok bool) {
+	for i := 0; i < len(s); i++ {
+		if s[i] == sep {
+			return s[:i], s[i+1:], true
+		}
+	}
+	return "", "", false
+}

internal/license/license_test.go

@@ -0,0 +1,106 @@
+package license
+
+import (
+	"crypto/ed25519"
+	"errors"
+	"testing"
+	"time"
+)
+
+func testKeyPair(t *testing.T) (ed25519.PublicKey, ed25519.PrivateKey) {
+	t.Helper()
+	pub, priv, err := ed25519.GenerateKey(nil)
+	if err != nil {
+		t.Fatalf("schluesselpaar erzeugen: %v", err)
+	}
+	return pub, priv
+}
+
+func TestIssueAndParse_RoundTrip(t *testing.T) {
+	pub, priv := testKeyPair(t)
+	issuer := NewIssuer(priv)
+	validator := NewValidator(pub)
+
+	payload := Payload{
+		TenantSlug: "acme",
+		Plan:       "pro",
+		Modules:    []string{"dms", "mail"},
+		IssuedAt:   time.Now().Truncate(time.Second),
+		ValidUntil: time.Now().Add(365 * 24 * time.Hour).Truncate(time.Second),
+	}
+
+	key, err := issuer.Issue(payload)
+	if err != nil {
+		t.Fatalf("issue: %v", err)
+	}
+
+	got, err := validator.Parse(key)
+	if err != nil {
+		t.Fatalf("parse: %v", err)
+	}
+	if got.TenantSlug != payload.TenantSlug || got.Plan != payload.Plan || len(got.Modules) != 2 {
+		t.Fatalf("payload nach parse unerwartet: %+v", got)
+	}
+}
+
+// Akzeptanzkriterium 1 + Pruefung 1: manipulierter Schluessel wird zuverlaessig erkannt.
+func TestParse_RejectsTamperedKey(t *testing.T) {
+	pub, priv := testKeyPair(t)
+	issuer := NewIssuer(priv)
+	validator := NewValidator(pub)
+
+	key, err := issuer.Issue(Payload{TenantSlug: "acme", Plan: "pro", ValidUntil: time.Now().Add(time.Hour)})
+	if err != nil {
+		t.Fatalf("issue: %v", err)
+	}
+
+	// Ein Zeichen im signierten Teil aendern.
+	tampered := []byte(key)
+	changed := false
+	for i, c := range tampered {
+		if c != '.' {
+			if c == 'A' {
+				tampered[i] = 'B'
+			} else {
+				tampered[i] = 'A'
+			}
+			changed = true
+			break
+		}
+	}
+	if !changed {
+		t.Fatal("testaufbau fehlerhaft: nichts zum manipulieren gefunden")
+	}
+
+	if _, err := validator.Parse(string(tampered)); !errors.Is(err, ErrInvalidSignature) {
+		t.Fatalf("erwartet ErrInvalidSignature, habe %v", err)
+	}
+}
+
+func TestParse_RejectsWrongKeyPair(t *testing.T) {
+	_, priv := testKeyPair(t)
+	otherPub, _ := testKeyPair(t)
+
+	issuer := NewIssuer(priv)
+	validator := NewValidator(otherPub) // falscher oeffentlicher Schluessel
+
+	key, err := issuer.Issue(Payload{TenantSlug: "acme", Plan: "pro"})
+	if err != nil {
+		t.Fatalf("issue: %v", err)
+	}
+	if _, err := validator.Parse(key); !errors.Is(err, ErrInvalidSignature) {
+		t.Fatalf("erwartet ErrInvalidSignature, habe %v", err)
+	}
+}
+
+func TestParse_RejectsMalformedKey(t *testing.T) {
+	pub, _ := testKeyPair(t)
+	validator := NewValidator(pub)
+
+	cases := []string{"", "keine-punkt-trennung", "!!!.!!!"}
+	for _, c := range cases {
+		if _, err := validator.Parse(c); !errors.Is(err, ErrMalformedKey) {
+			t.Fatalf("Parse(%q): erwartet ErrMalformedKey, habe %v", c, err)
+		}
+	}
+}

internal/license/store.go

@@ -0,0 +1,88 @@
+package license
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+var (
+	ErrNoLicense      = errors.New("license: kein lizenzdatensatz fuer diesen tenant")
+	ErrLicenseExpired = errors.New("license: lizenz abgelaufen")
+)
+
+// Store persistiert den Lizenzumfang je Tenant in der Control-Plane-Registry
+// (siehe internal/tenant.Registry — dieselbe Datenbank, aber ein eigener,
+// unabhaengiger Store, um internal/tenant nicht um lizenzfremde Belange zu
+// erweitern).
+type Store struct {
+	pool      *pgxpool.Pool
+	validator *Validator
+}
+
+func NewStore(pool *pgxpool.Pool, validator *Validator) *Store {
+	return &Store{pool: pool, validator: validator}
+}
+
+// Install prueft die Signatur des Lizenzschluessels (Akzeptanzkriterium 1)
+// und ersetzt den bisherigen Lizenzdatensatz des Tenants vollstaendig. Ein
+// bereits abgelaufener, aber korrekt signierter Schluessel wird trotzdem
+// gespeichert — der Ablauf wird erst bei der Nutzung (RequireActive)
+// bewertet, nicht beim Einspielen.
+func (s *Store) Install(ctx context.Context, tenantID, licenseKey string) (Payload, error) {
+	payload, err := s.validator.Parse(licenseKey)
+	if err != nil {
+		return Payload{}, err
+	}
+
+	_, err = s.pool.Exec(ctx, `
+		INSERT INTO tenant_licenses (tenant_id, plan, modules, issued_at, valid_until, raw_key, installed_at)
+		VALUES ($1, $2, $3, $4, $5, $6, now())
+		ON CONFLICT (tenant_id) DO UPDATE SET
+			plan = $2, modules = $3, issued_at = $4, valid_until = $5, raw_key = $6, installed_at = now()
+	`, tenantID, payload.Plan, payload.Modules, payload.IssuedAt, payload.ValidUntil, licenseKey)
+	if err != nil {
+		return Payload{}, fmt.Errorf("lizenz speichern: %w", err)
+	}
+	return payload, nil
+}
+
+func (s *Store) get(ctx context.Context, tenantID string) (Payload, error) {
+	var p Payload
+	row := s.pool.QueryRow(ctx, `
+		SELECT plan, modules, issued_at, valid_until
+		FROM tenant_licenses WHERE tenant_id = $1
+	`, tenantID)
+	if err := row.Scan(&p.Plan, &p.Modules, &p.IssuedAt, &p.ValidUntil); err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return Payload{}, ErrNoLicense
+		}
+		return Payload{}, fmt.Errorf("lizenz lesen: %w", err)
+	}
+	return p, nil
+}
+
+// Status liefert den persistierten Lizenzumfang unabhaengig vom Ablauf
+// (Akzeptanzkriterium 3: Plan, Modul-Liste, Laufzeit abfragbar).
+func (s *Store) Status(ctx context.Context, tenantID string) (Payload, error) {
+	return s.get(ctx, tenantID)
+}
+
+// RequireActive liefert den Lizenzumfang NUR, wenn die Lizenz noch nicht
+// abgelaufen ist — sonst ErrLicenseExpired statt eines harten Fehlers/Panics
+// (Akzeptanzkriterium 2: definierter eingeschraenkter Zustand). Aufrufende
+// Module (LIC-02/03) entscheiden, was "eingeschraenkt" konkret bedeutet.
+func (s *Store) RequireActive(ctx context.Context, tenantID string) (Payload, error) {
+	p, err := s.get(ctx, tenantID)
+	if err != nil {
+		return Payload{}, err
+	}
+	if time.Now().After(p.ValidUntil) {
+		return Payload{}, ErrLicenseExpired
+	}
+	return p, nil
+}

internal/license/store_test.go

@@ -0,0 +1,177 @@
+package license
+
+import (
+	"context"
+	"crypto/ed25519"
+	"errors"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+func setupStoreTest(t *testing.T) (*Store, *Issuer, 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 tenants (
+			id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+			slug TEXT NOT NULL UNIQUE,
+			name TEXT NOT NULL,
+			db_name TEXT NOT NULL UNIQUE,
+			db_dsn TEXT NOT NULL,
+			status TEXT NOT NULL DEFAULT 'active',
+			created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+		);
+		CREATE TABLE IF NOT EXISTS tenant_licenses (
+			tenant_id UUID PRIMARY KEY REFERENCES tenants(id),
+			plan TEXT NOT NULL,
+			modules TEXT[] NOT NULL,
+			issued_at TIMESTAMPTZ NOT NULL,
+			valid_until TIMESTAMPTZ NOT NULL,
+			raw_key TEXT NOT NULL,
+			installed_at TIMESTAMPTZ NOT NULL DEFAULT now()
+		);
+	`); err != nil {
+		t.Fatalf("schema: %v", err)
+	}
+
+	var tenantID string
+	if err := pool.QueryRow(ctx, `
+		INSERT INTO tenants (slug, name, db_name, db_dsn)
+		VALUES ('lic_test_tenant', 'Lic Test', 'tenant_lic_test', 'unused')
+		RETURNING id
+	`).Scan(&tenantID); err != nil {
+		t.Fatalf("test-tenant anlegen: %v", err)
+	}
+
+	pub, priv, err := ed25519.GenerateKey(nil)
+	if err != nil {
+		t.Fatalf("schluesselpaar: %v", err)
+	}
+	issuer := NewIssuer(priv)
+	store := NewStore(pool, NewValidator(pub))
+
+	cleanup := func() {
+		_, _ = pool.Exec(ctx, `DELETE FROM tenant_licenses WHERE tenant_id = $1`, tenantID)
+		_, _ = pool.Exec(ctx, `DELETE FROM tenants WHERE id = $1`, tenantID)
+		pool.Close()
+	}
+	return store, issuer, tenantID, cleanup
+}
+
+// Akzeptanzkriterium 3: Lizenzumfang persistiert und abfragbar.
+func TestStore_InstallAndStatus(t *testing.T) {
+	store, issuer, tenantID, cleanup := setupStoreTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	payload := Payload{
+		TenantSlug: "lic_test_tenant",
+		Plan:       "enterprise",
+		Modules:    []string{"dms", "mail", "archive"},
+		IssuedAt:   time.Now().Truncate(time.Second),
+		ValidUntil: time.Now().Add(30 * 24 * time.Hour).Truncate(time.Second),
+	}
+	key, err := issuer.Issue(payload)
+	if err != nil {
+		t.Fatalf("issue: %v", err)
+	}
+
+	if _, err := store.Install(ctx, tenantID, key); err != nil {
+		t.Fatalf("install: %v", err)
+	}
+
+	status, err := store.Status(ctx, tenantID)
+	if err != nil {
+		t.Fatalf("status: %v", err)
+	}
+	if status.Plan != "enterprise" || len(status.Modules) != 3 {
+		t.Fatalf("status unerwartet: %+v", status)
+	}
+}
+
+func TestStore_InstallRejectsInvalidSignature(t *testing.T) {
+	store, _, tenantID, cleanup := setupStoreTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	_, otherPriv, _ := ed25519.GenerateKey(nil)
+	foreignIssuer := NewIssuer(otherPriv) // signiert mit falschem schluessel
+
+	key, err := foreignIssuer.Issue(Payload{TenantSlug: "lic_test_tenant", Plan: "pro", ValidUntil: time.Now().Add(time.Hour)})
+	if err != nil {
+		t.Fatalf("issue: %v", err)
+	}
+
+	if _, err := store.Install(ctx, tenantID, key); !errors.Is(err, ErrInvalidSignature) {
+		t.Fatalf("erwartet ErrInvalidSignature, habe %v", err)
+	}
+}
+
+// Akzeptanzkriterium 2 + Pruefung 2: abgelaufene Lizenz fuehrt zu definiertem
+// eingeschraenktem Zustand (ErrLicenseExpired), nicht zu einem Absturz.
+func TestStore_RequireActive_DetectsExpiry(t *testing.T) {
+	store, issuer, tenantID, cleanup := setupStoreTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	expired := Payload{
+		TenantSlug: "lic_test_tenant",
+		Plan:       "pro",
+		Modules:    []string{"dms"},
+		IssuedAt:   time.Now().Add(-48 * time.Hour),
+		ValidUntil: time.Now().Add(-24 * time.Hour), // bereits abgelaufen
+	}
+	key, err := issuer.Issue(expired)
+	if err != nil {
+		t.Fatalf("issue: %v", err)
+	}
+
+	// Einspielen einer bereits abgelaufenen, aber korrekt signierten Lizenz
+	// muss funktionieren (Ablauf wird erst bei Nutzung bewertet).
+	if _, err := store.Install(ctx, tenantID, key); err != nil {
+		t.Fatalf("install sollte trotz ablauf funktionieren: %v", err)
+	}
+
+	func() {
+		defer func() {
+			if r := recover(); r != nil {
+				t.Fatalf("RequireActive hat gepanict statt einen fehler zu liefern: %v", r)
+			}
+		}()
+		if _, err := store.RequireActive(ctx, tenantID); !errors.Is(err, ErrLicenseExpired) {
+			t.Fatalf("erwartet ErrLicenseExpired, habe %v", err)
+		}
+	}()
+
+	// Aber der Umfang bleibt weiterhin abfragbar (Status, im Unterschied zu RequireActive).
+	status, err := store.Status(ctx, tenantID)
+	if err != nil {
+		t.Fatalf("status sollte trotz ablauf funktionieren: %v", err)
+	}
+	if status.Plan != "pro" {
+		t.Fatalf("status unerwartet: %+v", status)
+	}
+}
+
+func TestStore_RequireActive_NoLicense(t *testing.T) {
+	store, _, tenantID, cleanup := setupStoreTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	if _, err := store.RequireActive(ctx, tenantID); !errors.Is(err, ErrNoLicense) {
+		t.Fatalf("erwartet ErrNoLicense, habe %v", err)
+	}
+}

internal/tenant/lifecycle.go

@@ -1,241 +0,0 @@
-package tenant
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"log/slog"
-	"time"
-
-	"github.com/jackc/pgx/v5"
-	"github.com/jackc/pgx/v5/pgxpool"
-)
-
-var (
-	ErrTenantNotFound    = errors.New("tenant: nicht gefunden")
-	ErrInvalidTransition = errors.New("tenant: ungueltiger zustandsuebergang")
-	// ErrTenantNotActive wird von Lifecycle.CheckActive verwendet — bewusst
-	// EIN Fehler fuer suspendiert/zur-Loeschung-vorgemerkt/geloescht, da der
-	// Aufrufer (z.B. Login) nur wissen muss "kein Zugriff", nicht welcher der
-	// Nicht-aktiv-Zustaende genau vorliegt.
-	ErrTenantNotActive = errors.New("tenant: nicht aktiv")
-)
-
-func scanTenantWithLifecycle(row pgx.Row) (Tenant, error) {
-	var t Tenant
-	if err := row.Scan(&t.ID, &t.Slug, &t.Name, &t.DBName, &t.DBDSN, &t.Status,
-		&t.CreatedAt, &t.PreviousStatus, &t.DeletionScheduledAt); err != nil {
-		return Tenant{}, err
-	}
-	return t, nil
-}
-
-// transition fuehrt einen bewachten Zustandsuebergang aus: das UPDATE greift
-// nur, wenn der aktuelle Status einer von allowedFrom ist (atomarer
-// Check-and-Set, kein Race zwischen Lesen und Schreiben). Greift es nicht,
-// wird zwischen "Tenant existiert nicht" und "Uebergang nicht erlaubt"
-// unterschieden, damit AC1 ("ungueltige Uebergaenge werden abgewiesen") einen
-// sprechenden Fehler liefert statt eines stillen No-Ops.
-func (r *Registry) transition(ctx context.Context, slug string, allowedFrom []Status, to Status, previousStatus *string, deletionAt *time.Time) (Tenant, error) {
-	from := make([]string, len(allowedFrom))
-	for i, s := range allowedFrom {
-		from[i] = string(s)
-	}
-
-	row := r.pool.QueryRow(ctx, `
-		UPDATE tenants
-		SET status = $2, previous_status = $3, deletion_scheduled_at = $4
-		WHERE slug = $1 AND status = ANY($5)
-		RETURNING id, slug, name, db_name, db_dsn, status, created_at, previous_status, deletion_scheduled_at
-	`, slug, string(to), previousStatus, deletionAt, from)
-
-	t, err := scanTenantWithLifecycle(row)
-	if err == nil {
-		return t, nil
-	}
-	if !errors.Is(err, pgx.ErrNoRows) {
-		return Tenant{}, fmt.Errorf("zustandsuebergang: %w", err)
-	}
-
-	existing, getErr := r.GetBySlug(ctx, slug)
-	if getErr != nil {
-		return Tenant{}, ErrTenantNotFound
-	}
-	return Tenant{}, fmt.Errorf("%w: von %q nach %q (aktuell: %q)", ErrInvalidTransition, allowedFrom, to, existing.Status)
-}
-
-// Suspend haelt die Daten des Mandanten unveraendert, sperrt aber den Zugriff
-// (Akzeptanzkriterium 1) — es findet keine Loeschung/Migration statt.
-func (r *Registry) Suspend(ctx context.Context, slug string) (Tenant, error) {
-	return r.transition(ctx, slug, []Status{StatusActive}, StatusSuspended, nil, nil)
-}
-
-// Reactivate stellt den Zustand vor der Suspendierung vollstaendig wieder her
-// (Akzeptanzkriterium 2) — da Suspend keine weiteren Daten veraendert, genuegt
-// die Rueckkehr nach StatusActive.
-func (r *Registry) Reactivate(ctx context.Context, slug string) (Tenant, error) {
-	return r.transition(ctx, slug, []Status{StatusSuspended}, StatusActive, nil, nil)
-}
-
-// ScheduleDeletion merkt den Mandanten zur Loeschung vor und startet die
-// Karenzzeit (Akzeptanzkriterium 3). previous_status wird festgehalten, damit
-// CancelDeletion exakt dorthin zurueckkehren kann (aktiv ODER suspendiert).
-func (r *Registry) ScheduleDeletion(ctx context.Context, slug string, grace time.Duration) (Tenant, error) {
-	existing, err := r.GetBySlug(ctx, slug)
-	if err != nil {
-		return Tenant{}, ErrTenantNotFound
-	}
-	prev := string(existing.Status)
-	deletionAt := time.Now().Add(grace)
-	return r.transition(ctx, slug, []Status{StatusActive, StatusSuspended}, StatusPendingDeletion, &prev, &deletionAt)
-}
-
-// CancelDeletion widerruft eine Loeschvormerkung innerhalb der Karenzzeit und
-// stellt exakt den zuvor gesicherten Zustand wieder her.
-func (r *Registry) CancelDeletion(ctx context.Context, slug string) (Tenant, error) {
-	existing, err := r.GetBySlug(ctx, slug)
-	if err != nil {
-		return Tenant{}, ErrTenantNotFound
-	}
-	if existing.Status != StatusPendingDeletion || existing.PreviousStatus == nil {
-		return Tenant{}, fmt.Errorf("%w: von %q nach aktiv/suspendiert (aktuell: %q)", ErrInvalidTransition, StatusPendingDeletion, existing.Status)
-	}
-	restoreTo := Status(*existing.PreviousStatus)
-	return r.transition(ctx, slug, []Status{StatusPendingDeletion}, restoreTo, nil, nil)
-}
-
-// Lifecycle fuehrt die tatsaechliche, physische Loeschung nach Ablauf der
-// Karenzzeit aus (Datenbank-Drop) und stellt die Zugriffsschutz-Pruefung
-// bereit. Getrennt von Registry, weil hierfuer zusaetzlich der adminPool
-// (fuer DROP DATABASE) noetig ist, siehe internal/tenant.Provisioner.
-type Lifecycle struct {
-	registry  *Registry
-	adminPool *pgxpool.Pool
-	// retention ist die Pruef-Schnittstelle gegen Archive RET-03/CMP-06 (TEN-08).
-	// Default NoRetentionCheck{}, bis Archive angebunden ist — siehe retention.go.
-	retention RetentionChecker
-}
-
-func NewLifecycle(registry *Registry, adminPool *pgxpool.Pool) *Lifecycle {
-	return &Lifecycle{registry: registry, adminPool: adminPool, retention: NoRetentionCheck{}}
-}
-
-// WithRetentionChecker ersetzt den Retention-Checker (z.B. im Test durch einen
-// Fake, oder in Produktion durch den echten Archive-RET-03-Client). Gibt
-// dasselbe *Lifecycle zurueck, um Verkettung beim Aufbau zu erlauben.
-func (l *Lifecycle) WithRetentionChecker(checker RetentionChecker) *Lifecycle {
-	l.retention = checker
-	return l
-}
-
-// CheckActive verweigert Zugriff fuer jeden Nicht-aktiv-Zustand und loggt den
-// Vorgang strukturiert (Akzeptanzkriterium 1 / Pruefung 2).
-func (l *Lifecycle) CheckActive(ctx context.Context, slug string) error {
-	t, err := l.registry.GetBySlug(ctx, slug)
-	if err != nil {
-		return ErrTenantNotFound
-	}
-	if t.Status != StatusActive {
-		slog.Warn("zugriff auf nicht-aktiven mandanten verweigert",
-			"tenant_slug", slug, "tenant_status", t.Status)
-		return ErrTenantNotActive
-	}
-	return nil
-}
-
-// ProcessDueDeletions loescht alle Mandanten-Datenbanken, deren Karenzzeit
-// abgelaufen ist (Akzeptanzkriterium 3 / Pruefung 3). FOR UPDATE SKIP LOCKED
-// folgt der projektweiten Postgres-Jobqueue-Konvention (siehe
-// SKALIERUNGSKONZEPT.md) und macht die Funktion sicher fuer mehrere parallel
-// laufende Core-Instanzen.
-func (l *Lifecycle) ProcessDueDeletions(ctx context.Context) (int, error) {
-	tx, err := l.registry.pool.Begin(ctx)
-	if err != nil {
-		return 0, fmt.Errorf("sweep-transaktion starten: %w", err)
-	}
-	defer func() { _ = tx.Rollback(ctx) }()
-
-	rows, err := tx.Query(ctx, `
-		SELECT id, slug, db_name FROM tenants
-		WHERE status = $1 AND deletion_scheduled_at <= now()
-		FOR UPDATE SKIP LOCKED
-	`, string(StatusPendingDeletion))
-	if err != nil {
-		return 0, fmt.Errorf("faellige loeschungen abfragen: %w", err)
-	}
-
-	type due struct{ id, slug, dbName string }
-	var candidates []due
-	for rows.Next() {
-		var d due
-		if err := rows.Scan(&d.id, &d.slug, &d.dbName); err != nil {
-			rows.Close()
-			return 0, fmt.Errorf("faellige loeschung lesen: %w", err)
-		}
-		candidates = append(candidates, d)
-	}
-	rows.Close()
-	if err := rows.Err(); err != nil {
-		return 0, err
-	}
-
-	processed := 0
-	for _, c := range candidates {
-		// TEN-08: vor der physischen Loeschung gegen Archive RET-03/CMP-06 pruefen.
-		// Solange eine Sperre besteht, bleibt der Tenant in pending_deletion
-		// ("zur Loeschung vorgemerkt, aber gesperrt") — der Grund wird
-		// festgehalten (Akzeptanzkriterium 2), die naechste Sweeper-Runde
-		// prueft automatisch erneut (Akzeptanzkriterium 3), ohne dass ein
-		// manueller Re-Trigger noetig waere.
-		result, err := l.retention.CheckTenantRetention(ctx, c.id)
-		if err != nil {
-			return processed, fmt.Errorf("retention-pruefung fuer tenant %q: %w", c.id, err)
-		}
-		if result.Blocked {
-			slog.Warn("tenant-loeschung wegen aufbewahrungspflicht/legal-hold zurueckgehalten",
-				"tenant_slug", c.slug, "reason", result.Reason)
-			if _, err := tx.Exec(ctx, `
-				UPDATE tenants SET retention_block_reason = $2, retention_checked_at = now()
-				WHERE id = $1
-			`, c.id, result.Reason); err != nil {
-				return processed, fmt.Errorf("retention-sperrgrund fuer tenant %q speichern: %w", c.id, err)
-			}
-			continue
-		}
-
-		if _, err := l.adminPool.Exec(ctx, fmt.Sprintf(`DROP DATABASE IF EXISTS %q`, c.dbName)); err != nil {
-			return processed, fmt.Errorf("tenant-datenbank %q loeschen: %w", c.dbName, err)
-		}
-		if _, err := tx.Exec(ctx, `
-			UPDATE tenants
-			SET status = $2, previous_status = NULL, deletion_scheduled_at = NULL,
-			    retention_block_reason = NULL, retention_checked_at = now()
-			WHERE id = $1
-		`, c.id, string(StatusDeleted)); err != nil {
-			return processed, fmt.Errorf("tenant %q als geloescht markieren: %w", c.id, err)
-		}
-		processed++
-	}
-
-	if err := tx.Commit(ctx); err != nil {
-		return 0, fmt.Errorf("sweep-transaktion committen: %w", err)
-	}
-	return processed, nil
-}
-
-// RunSweeper triggert ProcessDueDeletions periodisch, bis ctx beendet wird —
-// die "In-Prozess-Worker-Goroutine" aus der projektweiten Jobqueue-Konvention.
-func (l *Lifecycle) RunSweeper(ctx context.Context, interval time.Duration) {
-	ticker := time.NewTicker(interval)
-	defer ticker.Stop()
-	for {
-		select {
-		case <-ctx.Done():
-			return
-		case <-ticker.C:
-			if _, err := l.ProcessDueDeletions(ctx); err != nil {
-				slog.Error("tenant-loeschung-sweep fehlgeschlagen", "error", err)
-			}
-		}
-	}
-}

internal/tenant/lifecycle_test.go

@@ -1,255 +0,0 @@
-package tenant
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"os"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/jackc/pgx/v5/pgxpool"
-)
-
-func newLifecycleTestSetup(t *testing.T) (*Registry, *Lifecycle, *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()
-
-	adminPool, err := pgxpool.New(ctx, adminDSN)
-	if err != nil {
-		t.Fatalf("admin pool: %v", err)
-	}
-	registryPool, err := pgxpool.New(ctx, adminDSN)
-	if err != nil {
-		t.Fatalf("registry pool: %v", err)
-	}
-	if _, err := registryPool.Exec(ctx, `
-		CREATE TABLE IF NOT EXISTS tenants (
-			id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-			slug TEXT NOT NULL UNIQUE,
-			name TEXT NOT NULL,
-			db_name TEXT NOT NULL UNIQUE,
-			db_dsn TEXT NOT NULL,
-			status TEXT NOT NULL DEFAULT 'active',
-			created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
-			previous_status TEXT,
-			deletion_scheduled_at TIMESTAMPTZ,
-			retention_block_reason TEXT,
-			retention_checked_at TIMESTAMPTZ
-		)`); err != nil {
-		t.Fatalf("registry-schema: %v", err)
-	}
-
-	registry := NewRegistry(registryPool)
-	dsnTemplate := strings.Replace(adminDSN, "/postgres?", "/%s?", 1)
-	provisioner := NewProvisioner(adminPool, registry, dsnTemplate)
-	lifecycle := NewLifecycle(registry, adminPool)
-
-	cleanup := func() {
-		registryPool.Close()
-		adminPool.Close()
-	}
-	_ = provisioner
-	return registry, lifecycle, adminPool, cleanup
-}
-
-func provisionTestTenant(t *testing.T, registry *Registry, adminPool *pgxpool.Pool, slug string) {
-	t.Helper()
-	dsnTemplate := strings.Replace(os.Getenv("TEST_ADMIN_DSN"), "/postgres?", "/%s?", 1)
-	provisioner := NewProvisioner(adminPool, registry, dsnTemplate)
-	if _, err := provisioner.Provision(context.Background(), slug, slug); err != nil {
-		t.Fatalf("provision %s: %v", slug, err)
-	}
-	t.Cleanup(func() {
-		ctx := context.Background()
-		_, _ = adminPool.Exec(ctx, fmt.Sprintf(`DROP DATABASE IF EXISTS %q`, dbNameForSlug(slug)))
-		_, _ = registry.pool.Exec(ctx, `DELETE FROM tenants WHERE slug = $1`, slug)
-	})
-}
-
-// Akzeptanzkriterium 1 (Suspend) + 2 (Reactivate) + Pruefung 1 (Uebergaenge).
-func TestLifecycle_SuspendAndReactivate(t *testing.T) {
-	registry, _, adminPool, cleanup := newLifecycleTestSetup(t)
-	defer cleanup()
-	provisionTestTenant(t, registry, adminPool, "lc_suspend")
-	ctx := context.Background()
-
-	suspended, err := registry.Suspend(ctx, "lc_suspend")
-	if err != nil {
-		t.Fatalf("suspend: %v", err)
-	}
-	if suspended.Status != StatusSuspended {
-		t.Fatalf("status = %q, want suspended", suspended.Status)
-	}
-
-	reactivated, err := registry.Reactivate(ctx, "lc_suspend")
-	if err != nil {
-		t.Fatalf("reactivate: %v", err)
-	}
-	if reactivated.Status != StatusActive {
-		t.Fatalf("status = %q, want active", reactivated.Status)
-	}
-}
-
-// Pruefung 1: ungueltige Uebergaenge werden abgewiesen.
-func TestLifecycle_RejectsInvalidTransitions(t *testing.T) {
-	registry, _, adminPool, cleanup := newLifecycleTestSetup(t)
-	defer cleanup()
-	provisionTestTenant(t, registry, adminPool, "lc_invalid")
-	ctx := context.Background()
-
-	// Reactivate auf einem bereits aktiven Tenant ist kein gueltiger Uebergang.
-	if _, err := registry.Reactivate(ctx, "lc_invalid"); !errors.Is(err, ErrInvalidTransition) {
-		t.Fatalf("erwartet ErrInvalidTransition, habe %v", err)
-	}
-
-	if _, err := registry.Suspend(ctx, "lc_invalid"); err != nil {
-		t.Fatalf("suspend: %v", err)
-	}
-	// Suspend auf einem bereits suspendierten Tenant ist ebenfalls ungueltig.
-	if _, err := registry.Suspend(ctx, "lc_invalid"); !errors.Is(err, ErrInvalidTransition) {
-		t.Fatalf("erwartet ErrInvalidTransition, habe %v", err)
-	}
-
-	// CancelDeletion ohne vorherige Loeschvormerkung ist ungueltig.
-	if _, err := registry.CancelDeletion(ctx, "lc_invalid"); !errors.Is(err, ErrInvalidTransition) {
-		t.Fatalf("erwartet ErrInvalidTransition, habe %v", err)
-	}
-
-	if _, err := registry.Suspend(ctx, "unbekannter-slug-xyz"); !errors.Is(err, ErrTenantNotFound) {
-		t.Fatalf("erwartet ErrTenantNotFound, habe %v", err)
-	}
-}
-
-// Akzeptanzkriterium 3: Loeschung zweistufig mit Karenzzeit, innerhalb der
-// Frist widerrufbar — sowohl aus 'active' als auch aus 'suspended' heraus,
-// mit exakter Wiederherstellung des jeweiligen Vorzustands.
-func TestLifecycle_ScheduleAndCancelDeletion_RestoresExactPreviousState(t *testing.T) {
-	registry, _, adminPool, cleanup := newLifecycleTestSetup(t)
-	defer cleanup()
-	provisionTestTenant(t, registry, adminPool, "lc_cancel_active")
-	provisionTestTenant(t, registry, adminPool, "lc_cancel_suspended")
-	ctx := context.Background()
-
-	// Fall 1: aus 'active' heraus vorgemerkt und widerrufen.
-	scheduled, err := registry.ScheduleDeletion(ctx, "lc_cancel_active", time.Hour)
-	if err != nil {
-		t.Fatalf("schedule deletion: %v", err)
-	}
-	if scheduled.Status != StatusPendingDeletion {
-		t.Fatalf("status = %q, want pending_deletion", scheduled.Status)
-	}
-	if scheduled.DeletionScheduledAt == nil {
-		t.Fatal("erwartet gesetzte deletion_scheduled_at")
-	}
-
-	restored, err := registry.CancelDeletion(ctx, "lc_cancel_active")
-	if err != nil {
-		t.Fatalf("cancel deletion: %v", err)
-	}
-	if restored.Status != StatusActive {
-		t.Fatalf("status = %q, want active (vorheriger zustand)", restored.Status)
-	}
-
-	// Fall 2: aus 'suspended' heraus vorgemerkt und widerrufen — muss zu
-	// 'suspended' zurueckkehren, NICHT zu 'active'.
-	if _, err := registry.Suspend(ctx, "lc_cancel_suspended"); err != nil {
-		t.Fatalf("suspend: %v", err)
-	}
-	if _, err := registry.ScheduleDeletion(ctx, "lc_cancel_suspended", time.Hour); err != nil {
-		t.Fatalf("schedule deletion: %v", err)
-	}
-	restoredSuspended, err := registry.CancelDeletion(ctx, "lc_cancel_suspended")
-	if err != nil {
-		t.Fatalf("cancel deletion: %v", err)
-	}
-	if restoredSuspended.Status != StatusSuspended {
-		t.Fatalf("status = %q, want suspended (vorheriger zustand)", restoredSuspended.Status)
-	}
-}
-
-// Akzeptanzkriterium 1 + Pruefung 2: suspendierter Tenant erzeugt bei jedem
-// Zugriffsversuch einen klaren Fehler.
-func TestLifecycle_CheckActive_RejectsNonActive(t *testing.T) {
-	registry, lifecycle, adminPool, cleanup := newLifecycleTestSetup(t)
-	defer cleanup()
-	provisionTestTenant(t, registry, adminPool, "lc_checkactive")
-	ctx := context.Background()
-
-	if err := lifecycle.CheckActive(ctx, "lc_checkactive"); err != nil {
-		t.Fatalf("aktiver tenant sollte durchgehen, habe %v", err)
-	}
-
-	if _, err := registry.Suspend(ctx, "lc_checkactive"); err != nil {
-		t.Fatalf("suspend: %v", err)
-	}
-
-	for i := 0; i < 3; i++ {
-		if err := lifecycle.CheckActive(ctx, "lc_checkactive"); !errors.Is(err, ErrTenantNotActive) {
-			t.Fatalf("versuch %d: erwartet ErrTenantNotActive, habe %v", i, err)
-		}
-	}
-
-	if err := lifecycle.CheckActive(ctx, "nie-registriert"); !errors.Is(err, ErrTenantNotFound) {
-		t.Fatalf("erwartet ErrTenantNotFound, habe %v", err)
-	}
-}
-
-// Akzeptanzkriterium 3 + Pruefung 3: Loeschvorgang nach Ablauf der Karenzzeit
-// automatisch ausgeloest (hier durch direkten Aufruf von ProcessDueDeletions,
-// das RunSweeper periodisch aufruft).
-func TestLifecycle_ProcessDueDeletions(t *testing.T) {
-	registry, lifecycle, adminPool, cleanup := newLifecycleTestSetup(t)
-	defer cleanup()
-	provisionTestTenant(t, registry, adminPool, "lc_due")
-	provisionTestTenant(t, registry, adminPool, "lc_not_due")
-	ctx := context.Background()
-
-	// lc_due: Karenzzeit liegt bereits in der Vergangenheit -> faellig.
-	if _, err := registry.ScheduleDeletion(ctx, "lc_due", -time.Minute); err != nil {
-		t.Fatalf("schedule deletion (due): %v", err)
-	}
-	// lc_not_due: Karenzzeit liegt weit in der Zukunft -> nicht faellig.
-	if _, err := registry.ScheduleDeletion(ctx, "lc_not_due", time.Hour); err != nil {
-		t.Fatalf("schedule deletion (not due): %v", err)
-	}
-
-	processed, err := lifecycle.ProcessDueDeletions(ctx)
-	if err != nil {
-		t.Fatalf("process due deletions: %v", err)
-	}
-	if processed != 1 {
-		t.Fatalf("erwartet genau 1 verarbeitete loeschung, habe %d", processed)
-	}
-
-	due, err := registry.GetBySlug(ctx, "lc_due")
-	if err != nil {
-		t.Fatalf("get lc_due: %v", err)
-	}
-	if due.Status != StatusDeleted {
-		t.Fatalf("lc_due status = %q, want deleted", due.Status)
-	}
-
-	notDue, err := registry.GetBySlug(ctx, "lc_not_due")
-	if err != nil {
-		t.Fatalf("get lc_not_due: %v", err)
-	}
-	if notDue.Status != StatusPendingDeletion {
-		t.Fatalf("lc_not_due status = %q, want pending_deletion (noch nicht faellig)", notDue.Status)
-	}
-
-	// Datenbank von lc_due wurde tatsaechlich physisch entfernt.
-	var exists bool
-	if err := adminPool.QueryRow(ctx, `SELECT EXISTS(SELECT 1 FROM pg_database WHERE datname = $1)`,
-		dbNameForSlug("lc_due")).Scan(&exists); err != nil {
-		t.Fatalf("pg_database pruefen: %v", err)
-	}
-	if exists {
-		t.Fatal("erwartet, dass die tenant-datenbank von lc_due geloescht wurde")
-	}
-}

internal/tenant/registry.go

@@ -35,20 +35,13 @@ func (r *Registry) insertTx(ctx context.Context, tx pgx.Tx, t Tenant) (Tenant, e
 }
 
 func (r *Registry) GetBySlug(ctx context.Context, slug string) (Tenant, error) {
-	// previous_status/deletion_scheduled_at werden mitgelesen, damit TEN-04
-	// (internal/tenant/lifecycle.go) den vollstaendigen Lebenszyklus-Zustand
-	// ueber GetBySlug ansehen kann, statt eine eigene Abfrage zu duplizieren.
-	// retention_block_reason/retention_checked_at (TEN-08) aus demselben Grund
-	// fuer die Admin-Einsehbarkeit des Sperrgrunds (Akzeptanzkriterium 2).
 	var t Tenant
 	row := r.pool.QueryRow(ctx, `
-		SELECT id, slug, name, db_name, db_dsn, status, created_at, previous_status, deletion_scheduled_at,
-		       retention_block_reason, retention_checked_at
+		SELECT id, slug, name, db_name, db_dsn, status, created_at
 		FROM tenants WHERE slug = $1
 	`, slug)
 
-	if err := row.Scan(&t.ID, &t.Slug, &t.Name, &t.DBName, &t.DBDSN, &t.Status, &t.CreatedAt,
-		&t.PreviousStatus, &t.DeletionScheduledAt, &t.RetentionBlockReason, &t.RetentionCheckedAt); err != nil {
+	if err := row.Scan(&t.ID, &t.Slug, &t.Name, &t.DBName, &t.DBDSN, &t.Status, &t.CreatedAt); err != nil {
 		return Tenant{}, fmt.Errorf("tenant laden: %w", err)
 	}
 	return t, nil

internal/tenant/retention.go

@@ -1,34 +0,0 @@
-package tenant
-
-import "context"
-
-// RetentionResult ist das Ergebnis einer Pruefung gegen Archive RET-03/CMP-06
-// vor einer endgueltigen Tenant-Loeschung (TEN-08).
-type RetentionResult struct {
-	// Blocked ist true, solange GoBD-relevante Daten des Tenants unter
-	// Aufbewahrungspflicht oder Legal Hold stehen (Akzeptanzkriterium 1).
-	Blocked bool
-	// Reason beschreibt Aufbewahrungsklasse/Frist oder Legal-Hold-Grund,
-	// fuer Admins einsehbar (Akzeptanzkriterium 2). Nur aussagekraeftig, wenn Blocked true ist.
-	Reason string
-}
-
-// RetentionChecker ist die Schnittstelle zu Archive RET-03 (Loeschworkflow &
-// Aufbewahrungssperre) / CMP-06 (Vier-Augen-Freigabe fuer Loeschungen).
-// Core kennt bewusst keine Retention-Logik selbst — diese Kachel ruft nur auf,
-// siehe TEN-08 "Nicht Bestandteil dieser Kachel". Solange Archive RET-03 noch
-// nicht implementiert ist, wird ein no-op-Checker verwendet (siehe
-// NoRetentionCheck), der niemals blockiert — Core faellt damit auf das
-// TEN-04-Verhalten vor diesem Ticket zurueck, statt fehlzuschlagen.
-type RetentionChecker interface {
-	CheckTenantRetention(ctx context.Context, tenantID string) (RetentionResult, error)
-}
-
-// NoRetentionCheck ist der Platzhalter-Checker, solange Archive RET-03 noch
-// nicht angebunden ist — blockiert nie. Wird in Produktion durch den echten
-// HTTP-Client gegen Archive ersetzt, sobald RET-03 existiert.
-type NoRetentionCheck struct{}
-
-func (NoRetentionCheck) CheckTenantRetention(context.Context, string) (RetentionResult, error) {
-	return RetentionResult{Blocked: false}, nil
-}

internal/tenant/retention_test.go

@@ -1,164 +0,0 @@
-package tenant
-
-import (
-	"context"
-	"testing"
-	"time"
-)
-
-// fakeRetentionChecker simuliert Archive RET-03/CMP-06 in Tests — echte
-// Anbindung existiert noch nicht (siehe retention.go), diese Kachel ruft nur auf.
-type fakeRetentionChecker struct {
-	blocked map[string]string // tenantID -> Grund
-}
-
-func (f fakeRetentionChecker) CheckTenantRetention(_ context.Context, tenantID string) (RetentionResult, error) {
-	if reason, ok := f.blocked[tenantID]; ok {
-		return RetentionResult{Blocked: true, Reason: reason}, nil
-	}
-	return RetentionResult{Blocked: false}, nil
-}
-
-// Akzeptanzkriterium 1 + Pruefung 1: Loeschung eines Tenants mit aktiver
-// GoBD-Aufbewahrungspflicht wird abgewiesen, Grund wird protokolliert
-// (Akzeptanzkriterium 2).
-func TestLifecycle_ProcessDueDeletions_BlockedByRetention(t *testing.T) {
-	registry, lifecycle, adminPool, cleanup := newLifecycleTestSetup(t)
-	defer cleanup()
-	provisionTestTenant(t, registry, adminPool, "lc_retention_blocked")
-	ctx := context.Background()
-
-	tenantBeforeSchedule, err := registry.GetBySlug(ctx, "lc_retention_blocked")
-	if err != nil {
-		t.Fatalf("get tenant: %v", err)
-	}
-	if _, err := registry.ScheduleDeletion(ctx, "lc_retention_blocked", -time.Minute); err != nil {
-		t.Fatalf("schedule deletion: %v", err)
-	}
-
-	lifecycle.WithRetentionChecker(fakeRetentionChecker{
-		blocked: map[string]string{
-			tenantBeforeSchedule.ID: "GoBD-Aufbewahrungsfrist bis 2034-01-01 (Buchungsbeleg-Klasse)",
-		},
-	})
-
-	processed, err := lifecycle.ProcessDueDeletions(ctx)
-	if err != nil {
-		t.Fatalf("process due deletions: %v", err)
-	}
-	if processed != 0 {
-		t.Fatalf("erwartet 0 tatsaechlich verarbeitete loeschungen, habe %d", processed)
-	}
-
-	after, err := registry.GetBySlug(ctx, "lc_retention_blocked")
-	if err != nil {
-		t.Fatalf("get tenant nach sweep: %v", err)
-	}
-	if after.Status != StatusPendingDeletion {
-		t.Fatalf("status = %q, want pending_deletion (gesperrt, nicht geloescht)", after.Status)
-	}
-	if after.RetentionBlockReason == nil || *after.RetentionBlockReason == "" {
-		t.Fatal("erwartet gesetzten retention_block_reason (Akzeptanzkriterium 2)")
-	}
-	if after.RetentionCheckedAt == nil {
-		t.Fatal("erwartet gesetzten retention_checked_at")
-	}
-
-	var exists bool
-	if err := adminPool.QueryRow(ctx, `SELECT EXISTS(SELECT 1 FROM pg_database WHERE datname = $1)`,
-		dbNameForSlug("lc_retention_blocked")).Scan(&exists); err != nil {
-		t.Fatalf("pg_database pruefen: %v", err)
-	}
-	if !exists {
-		t.Fatal("tenant-datenbank haette NICHT geloescht werden duerfen (retention-sperre)")
-	}
-}
-
-// Akzeptanzkriterium 1 + Pruefung 2: Loeschung eines Tenants mit Legal Hold
-// wird ebenfalls abgewiesen — derselbe Mechanismus wie GoBD-Frist, nur anderer Grund.
-func TestLifecycle_ProcessDueDeletions_BlockedByLegalHold(t *testing.T) {
-	registry, lifecycle, adminPool, cleanup := newLifecycleTestSetup(t)
-	defer cleanup()
-	provisionTestTenant(t, registry, adminPool, "lc_legal_hold")
-	ctx := context.Background()
-
-	tenant, err := registry.GetBySlug(ctx, "lc_legal_hold")
-	if err != nil {
-		t.Fatalf("get tenant: %v", err)
-	}
-	if _, err := registry.ScheduleDeletion(ctx, "lc_legal_hold", -time.Minute); err != nil {
-		t.Fatalf("schedule deletion: %v", err)
-	}
-
-	lifecycle.WithRetentionChecker(fakeRetentionChecker{
-		blocked: map[string]string{
-			tenant.ID: "Legal Hold: laufendes Gerichtsverfahren, Aktenzeichen XY-2026-042",
-		},
-	})
-
-	if _, err := lifecycle.ProcessDueDeletions(ctx); err != nil {
-		t.Fatalf("process due deletions: %v", err)
-	}
-
-	after, err := registry.GetBySlug(ctx, "lc_legal_hold")
-	if err != nil {
-		t.Fatalf("get tenant nach sweep: %v", err)
-	}
-	if after.Status != StatusPendingDeletion {
-		t.Fatalf("status = %q, want pending_deletion", after.Status)
-	}
-	if after.RetentionBlockReason == nil || *after.RetentionBlockReason == "" {
-		t.Fatal("erwartet gesetzten retention_block_reason")
-	}
-}
-
-// Akzeptanzkriterium 3 + Pruefung 3: nach Aufhebung aller Sperren wird die
-// Loeschung bei der naechsten Sweep-Runde automatisch ausgefuehrt — kein
-// manueller Re-Trigger noetig, derselbe Sweeper-Aufruf greift erneut.
-func TestLifecycle_ProcessDueDeletions_ExecutesAfterRetentionCleared(t *testing.T) {
-	registry, lifecycle, adminPool, cleanup := newLifecycleTestSetup(t)
-	defer cleanup()
-	provisionTestTenant(t, registry, adminPool, "lc_retention_cleared")
-	ctx := context.Background()
-
-	tenant, err := registry.GetBySlug(ctx, "lc_retention_cleared")
-	if err != nil {
-		t.Fatalf("get tenant: %v", err)
-	}
-	if _, err := registry.ScheduleDeletion(ctx, "lc_retention_cleared", -time.Minute); err != nil {
-		t.Fatalf("schedule deletion: %v", err)
-	}
-
-	blockingChecker := fakeRetentionChecker{blocked: map[string]string{tenant.ID: "Aufbewahrungsfrist laeuft noch"}}
-	lifecycle.WithRetentionChecker(blockingChecker)
-
-	if _, err := lifecycle.ProcessDueDeletions(ctx); err != nil {
-		t.Fatalf("erster sweep (blockiert): %v", err)
-	}
-	blockedState, err := registry.GetBySlug(ctx, "lc_retention_cleared")
-	if err != nil {
-		t.Fatalf("get tenant nach erstem sweep: %v", err)
-	}
-	if blockedState.Status != StatusPendingDeletion {
-		t.Fatalf("status nach erstem sweep = %q, want pending_deletion", blockedState.Status)
-	}
-
-	// Sperre aufgehoben: naechster Checker blockiert nicht mehr (fakeRetentionChecker.blocked leer).
-	lifecycle.WithRetentionChecker(fakeRetentionChecker{})
-
-	processed, err := lifecycle.ProcessDueDeletions(ctx)
-	if err != nil {
-		t.Fatalf("zweiter sweep (unblockiert): %v", err)
-	}
-	if processed != 1 {
-		t.Fatalf("erwartet genau 1 verarbeitete loeschung im zweiten sweep, habe %d", processed)
-	}
-
-	final, err := registry.GetBySlug(ctx, "lc_retention_cleared")
-	if err != nil {
-		t.Fatalf("get tenant nach zweitem sweep: %v", err)
-	}
-	if final.Status != StatusDeleted {
-		t.Fatalf("status = %q, want deleted", final.Status)
-	}
-}

internal/tenant/tenant.go

@@ -12,10 +12,6 @@ type Status string
 
 const (
 	StatusActive Status = "active"
-	// Lebenszyklus-Zustaende aus TEN-04 (siehe internal/tenant/lifecycle.go).
-	StatusSuspended       Status = "suspended"
-	StatusPendingDeletion Status = "pending_deletion"
-	StatusDeleted         Status = "deleted"
 )
 
 type Tenant struct {
@@ -26,16 +22,6 @@ type Tenant struct {
 	DBDSN     string
 	Status    Status
 	CreatedAt time.Time
-	// PreviousStatus und DeletionScheduledAt sind nur waehrend
-	// StatusPendingDeletion gesetzt (TEN-04) — sie halten fest, in welchen
-	// Zustand CancelDeletion zurueckkehrt und wann die Karenzzeit ablaeuft.
-	PreviousStatus      *string
-	DeletionScheduledAt *time.Time
-	// RetentionBlockReason ist nur gesetzt, wenn eine faellige Loeschung wegen
-	// GoBD-Aufbewahrungspflicht oder Legal Hold zurueckgehalten wurde (TEN-08,
-	// siehe internal/tenant/retention.go) — fuer Admins einsehbar (Akzeptanzkriterium 2).
-	RetentionBlockReason *string
-	RetentionCheckedAt   *time.Time
 }
 
 // slugPattern erzwingt sichere, als SQL-Identifier verwendbare Slugs, damit

internal/usage/aggregation.go

@@ -0,0 +1,32 @@
+package usage
+
+import (
+	"context"
+	"log/slog"
+	"time"
+)
+
+// AggregateFunc berechnet/aktualisiert Zaehlerstaende aus einer autoritativen
+// Quelle (z.B. "zaehle Zeilen in einer Modul-Tabelle") — die konkrete Quelle
+// haengt vom jeweiligen Modul ab und ist nicht Teil dieser Kachel. Das
+// Aggregations-Grundgerüst selbst (periodischer Trigger) ist es.
+type AggregateFunc func(ctx context.Context) error
+
+// RunPeriodicAggregation ruft aggregate in festen Abstaenden auf, bis ctx
+// beendet wird — dieselbe In-Prozess-Worker-Goroutine-Konvention wie
+// internal/tenant.Lifecycle.RunSweeper (Akzeptanzkriterium 1: "periodisch
+// aggregiert").
+func RunPeriodicAggregation(ctx context.Context, interval time.Duration, aggregate AggregateFunc) {
+	ticker := time.NewTicker(interval)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+			if err := aggregate(ctx); err != nil {
+				slog.Error("nutzungszaehler-aggregation fehlgeschlagen", "error", err)
+			}
+		}
+	}
+}

internal/usage/usage.go

@@ -0,0 +1,144 @@
+// Package usage implementiert Core LIC-03: Nutzungszaehler je Tenant
+// (Benutzeranzahl, Speicherverbrauch, API-Aufrufe, ...) und die Pruefung
+// gegen konfigurierte Quotas. Quotas sind Konfiguration (Tabellenzeile), kein
+// Hardcode — Zitadel/Unleash-Vorbild.
+package usage
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+var ErrNoQuota = errors.New("usage: keine quota fuer diese metrik konfiguriert")
+
+// Status ist die definierte Reaktion einer Quota-Pruefung (Akzeptanzkriterium 2).
+type Status string
+
+const (
+	StatusOK       Status = "ok"
+	StatusWarning  Status = "warning"  // Schwelle (80%) erreicht, aber noch nicht ueberschritten
+	StatusExceeded Status = "exceeded" // Quota ueberschritten — neue Ressourcen sollten gesperrt werden
+)
+
+// warningThreshold liegt bei 80% der Quota.
+const warningThreshold = 0.8
+
+type Store struct {
+	pool *pgxpool.Pool
+}
+
+func NewStore(pool *pgxpool.Pool) *Store {
+	return &Store{pool: pool}
+}
+
+// Increment erhoeht einen Zaehler ATOMAR ueber ein einziges SQL-Statement
+// (UPSERT mit value = value + delta) statt Read-Modify-Write in Go — das
+// haelt Zaehlerstaende bei parallelen Schreibzugriffen konsistent
+// (Akzeptanzkriterium 1 / Pruefung 2), ohne eine Anwendungs-Transaktion mit
+// Lock zu brauchen.
+func (s *Store) Increment(ctx context.Context, tenantID, metric string, delta int64) error {
+	_, err := s.pool.Exec(ctx, `
+		INSERT INTO usage_counters (tenant_id, metric, value, updated_at)
+		VALUES ($1, $2, $3, now())
+		ON CONFLICT (tenant_id, metric) DO UPDATE
+			SET value = usage_counters.value + $3, updated_at = now()
+	`, tenantID, metric, delta)
+	if err != nil {
+		return fmt.Errorf("zaehler erhoehen: %w", err)
+	}
+	return nil
+}
+
+// Get liefert den aktuellen Zaehlerstand — 0, wenn noch nie erhoeht wurde.
+// Der Wert ist strikt tenant-gescoped (Akzeptanzkriterium 3 / Pruefung 3).
+func (s *Store) Get(ctx context.Context, tenantID, metric string) (int64, error) {
+	var value int64
+	err := s.pool.QueryRow(ctx, `
+		SELECT value FROM usage_counters WHERE tenant_id = $1 AND metric = $2
+	`, tenantID, metric).Scan(&value)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return 0, nil
+		}
+		return 0, fmt.Errorf("zaehler lesen: %w", err)
+	}
+	return value, nil
+}
+
+// SetQuota legt die Obergrenze fuer (tenantID, metric) fest — Konfiguration,
+// kein Hardcode.
+func (s *Store) SetQuota(ctx context.Context, tenantID, metric string, limit int64) error {
+	_, err := s.pool.Exec(ctx, `
+		INSERT INTO usage_quotas (tenant_id, metric, limit_value)
+		VALUES ($1, $2, $3)
+		ON CONFLICT (tenant_id, metric) DO UPDATE SET limit_value = $3
+	`, tenantID, metric, limit)
+	if err != nil {
+		return fmt.Errorf("quota setzen: %w", err)
+	}
+	return nil
+}
+
+func (s *Store) GetQuota(ctx context.Context, tenantID, metric string) (int64, error) {
+	var limit int64
+	err := s.pool.QueryRow(ctx, `
+		SELECT limit_value FROM usage_quotas WHERE tenant_id = $1 AND metric = $2
+	`, tenantID, metric).Scan(&limit)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return 0, ErrNoQuota
+		}
+		return 0, fmt.Errorf("quota lesen: %w", err)
+	}
+	return limit, nil
+}
+
+// Check liefert Zaehlerstand, konfigurierte Quota und die daraus abgeleitete
+// Reaktion (Akzeptanzkriterium 2 / Pruefung 1). Ist keine Quota konfiguriert,
+// gilt die Metrik als unbegrenzt (StatusOK).
+func (s *Store) Check(ctx context.Context, tenantID, metric string) (value, limit int64, status Status, err error) {
+	value, err = s.Get(ctx, tenantID, metric)
+	if err != nil {
+		return 0, 0, "", err
+	}
+
+	limit, err = s.GetQuota(ctx, tenantID, metric)
+	if errors.Is(err, ErrNoQuota) {
+		return value, 0, StatusOK, nil
+	}
+	if err != nil {
+		return 0, 0, "", err
+	}
+
+	switch {
+	case value > limit:
+		return value, limit, StatusExceeded, nil
+	case limit > 0 && float64(value) >= warningThreshold*float64(limit):
+		return value, limit, StatusWarning, nil
+	default:
+		return value, limit, StatusOK, nil
+	}
+}
+
+// Reaction wird aufgerufen, wenn Check einen Nicht-OK-Status liefert
+// (Akzeptanzkriterium 2: "definierte Reaktion").
+type Reaction func(ctx context.Context, tenantID, metric string, value, limit int64, status Status)
+
+// Enforce fuehrt Check aus und ruft react auf, wenn der Status nicht OK ist —
+// die konkrete "Sperre neuer Ressourcen"/Benachrichtigung liegt beim
+// Aufrufer (z.B. TEN-02 vor dem Anlegen eines neuen Benutzers), Enforce
+// garantiert nur, dass die Reaktion zuverlaessig ausgeloest wird.
+func (s *Store) Enforce(ctx context.Context, tenantID, metric string, react Reaction) (Status, error) {
+	value, limit, status, err := s.Check(ctx, tenantID, metric)
+	if err != nil {
+		return "", err
+	}
+	if status != StatusOK && react != nil {
+		react(ctx, tenantID, metric, value, limit, status)
+	}
+	return status, nil
+}

internal/usage/usage_test.go

@@ -0,0 +1,206 @@
+package usage
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+func setupTest(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 usage_counters (
+			tenant_id UUID NOT NULL, metric TEXT NOT NULL, value BIGINT NOT NULL DEFAULT 0,
+			updated_at TIMESTAMPTZ NOT NULL DEFAULT now(), PRIMARY KEY (tenant_id, metric)
+		);
+		CREATE TABLE IF NOT EXISTS usage_quotas (
+			tenant_id UUID NOT NULL, metric TEXT NOT NULL, limit_value BIGINT NOT NULL,
+			PRIMARY KEY (tenant_id, metric)
+		);
+	`); err != nil {
+		t.Fatalf("schema: %v", err)
+	}
+
+	cleanup := func() { pool.Close() }
+	return NewStore(pool), cleanup
+}
+
+func newTenantID() string {
+	return fmt.Sprintf("00000000-0000-0000-0000-%012d", time.Now().UnixNano()%1e12)
+}
+
+// Akzeptanzkriterium 1 + Pruefung 2: Aggregationsjob liefert bei parallelen
+// Schreibzugriffen konsistente Zaehlerstaende.
+func TestIncrement_ConsistentUnderConcurrentWrites(t *testing.T) {
+	store, cleanup := setupTest(t)
+	defer cleanup()
+	ctx := context.Background()
+	tenant := newTenantID()
+
+	const goroutines = 50
+	var wg sync.WaitGroup
+	for i := 0; i < goroutines; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			if err := store.Increment(ctx, tenant, "api_calls", 1); err != nil {
+				t.Errorf("increment: %v", err)
+			}
+		}()
+	}
+	wg.Wait()
+
+	value, err := store.Get(ctx, tenant, "api_calls")
+	if err != nil {
+		t.Fatalf("get: %v", err)
+	}
+	if value != goroutines {
+		t.Fatalf("erwartet %d, habe %d (hinweis auf lost update unter nebenlaeufigkeit)", goroutines, value)
+	}
+}
+
+// Akzeptanzkriterium 3 + Pruefung 3: Zaehlerstand eines Tenants beeinflusst
+// nicht den eines anderen.
+func TestIncrement_IsolatedBetweenTenants(t *testing.T) {
+	store, cleanup := setupTest(t)
+	defer cleanup()
+	ctx := context.Background()
+	tenantA, tenantB := newTenantID(), newTenantID()
+
+	if err := store.Increment(ctx, tenantA, "users", 5); err != nil {
+		t.Fatalf("increment a: %v", err)
+	}
+	if err := store.Increment(ctx, tenantB, "users", 1); err != nil {
+		t.Fatalf("increment b: %v", err)
+	}
+
+	valA, err := store.Get(ctx, tenantA, "users")
+	if err != nil {
+		t.Fatalf("get a: %v", err)
+	}
+	valB, err := store.Get(ctx, tenantB, "users")
+	if err != nil {
+		t.Fatalf("get b: %v", err)
+	}
+	if valA != 5 || valB != 1 {
+		t.Fatalf("erwartet a=5 b=1, habe a=%d b=%d", valA, valB)
+	}
+}
+
+// Akzeptanzkriterium 2 + Pruefung 1: Quota-Ueberschreitung wird automatisiert
+// erkannt und die definierte Reaktion ausgeloest.
+func TestEnforce_TriggersReactionOnExceeded(t *testing.T) {
+	store, cleanup := setupTest(t)
+	defer cleanup()
+	ctx := context.Background()
+	tenant := newTenantID()
+
+	if err := store.SetQuota(ctx, tenant, "users", 10); err != nil {
+		t.Fatalf("set quota: %v", err)
+	}
+	if err := store.Increment(ctx, tenant, "users", 11); err != nil {
+		t.Fatalf("increment: %v", err)
+	}
+
+	var reacted bool
+	var gotStatus Status
+	status, err := store.Enforce(ctx, tenant, "users", func(ctx context.Context, tenantID, metric string, value, limit int64, status Status) {
+		reacted = true
+		gotStatus = status
+	})
+	if err != nil {
+		t.Fatalf("enforce: %v", err)
+	}
+	if status != StatusExceeded {
+		t.Fatalf("erwartet StatusExceeded, habe %q", status)
+	}
+	if !reacted || gotStatus != StatusExceeded {
+		t.Fatal("erwartet ausgeloeste reaktion mit StatusExceeded")
+	}
+}
+
+func TestCheck_WarningThresholdAndOK(t *testing.T) {
+	store, cleanup := setupTest(t)
+	defer cleanup()
+	ctx := context.Background()
+	tenant := newTenantID()
+
+	if err := store.SetQuota(ctx, tenant, "storage_mb", 100); err != nil {
+		t.Fatalf("set quota: %v", err)
+	}
+
+	if err := store.Increment(ctx, tenant, "storage_mb", 50); err != nil {
+		t.Fatalf("increment: %v", err)
+	}
+	_, _, status, err := store.Check(ctx, tenant, "storage_mb")
+	if err != nil {
+		t.Fatalf("check: %v", err)
+	}
+	if status != StatusOK {
+		t.Fatalf("bei 50%% erwartet StatusOK, habe %q", status)
+	}
+
+	if err := store.Increment(ctx, tenant, "storage_mb", 35); err != nil { // insgesamt 85%
+		t.Fatalf("increment: %v", err)
+	}
+	_, _, status, err = store.Check(ctx, tenant, "storage_mb")
+	if err != nil {
+		t.Fatalf("check: %v", err)
+	}
+	if status != StatusWarning {
+		t.Fatalf("bei 85%% erwartet StatusWarning, habe %q", status)
+	}
+}
+
+func TestCheck_NoQuotaMeansUnlimited(t *testing.T) {
+	store, cleanup := setupTest(t)
+	defer cleanup()
+	ctx := context.Background()
+	tenant := newTenantID()
+
+	if err := store.Increment(ctx, tenant, "api_calls", 1_000_000); err != nil {
+		t.Fatalf("increment: %v", err)
+	}
+	_, _, status, err := store.Check(ctx, tenant, "api_calls")
+	if err != nil {
+		t.Fatalf("check: %v", err)
+	}
+	if status != StatusOK {
+		t.Fatalf("ohne konfigurierte quota erwartet StatusOK, habe %q", status)
+	}
+}
+
+func TestRunPeriodicAggregation_CallsRepeatedly(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), 120*time.Millisecond)
+	defer cancel()
+
+	var mu sync.Mutex
+	calls := 0
+	RunPeriodicAggregation(ctx, 20*time.Millisecond, func(ctx context.Context) error {
+		mu.Lock()
+		calls++
+		mu.Unlock()
+		return nil
+	})
+
+	mu.Lock()
+	defer mu.Unlock()
+	if calls < 3 {
+		t.Fatalf("erwartet mehrfache aufrufe innerhalb von 120ms bei 20ms interval, habe %d", calls)
+	}
+}

migrations/0003_tenant_lifecycle.down.sql

@@ -1,2 +0,0 @@
-ALTER TABLE tenants DROP COLUMN previous_status;
-ALTER TABLE tenants DROP COLUMN deletion_scheduled_at;

migrations/0003_tenant_lifecycle.up.sql

@@ -1,6 +0,0 @@
--- Lebenszyklus-Zustaende fuer Mandanten (TEN-04, siehe core-kanban/tickets/TEN-04.md).
--- previous_status haelt den Zustand VOR einer Loeschvormerkung, damit
--- CancelDeletion "den vorherigen Zustand vollstaendig wiederherstellt"
--- (aktiv ODER suspendiert), statt hart auf 'active' zurueckzusetzen.
-ALTER TABLE tenants ADD COLUMN previous_status TEXT;
-ALTER TABLE tenants ADD COLUMN deletion_scheduled_at TIMESTAMPTZ;

migrations/0004_tenant_licenses.down.sql

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

migrations/0004_tenant_licenses.up.sql

@@ -0,0 +1,12 @@
+-- Lizenzumfang pro Mandant (LIC-01, siehe core-kanban/tickets/LIC-01.md).
+-- Genau ein Lizenzdatensatz pro Tenant (tenant_id PK) — ein neues Einspielen
+-- ersetzt den vorherigen Datensatz vollstaendig statt eine Historie zu fuehren.
+CREATE TABLE tenant_licenses (
+    tenant_id     UUID PRIMARY KEY REFERENCES tenants(id),
+    plan          TEXT NOT NULL,
+    modules       TEXT[] NOT NULL,
+    issued_at     TIMESTAMPTZ NOT NULL,
+    valid_until   TIMESTAMPTZ NOT NULL,
+    raw_key       TEXT NOT NULL,
+    installed_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);

migrations/0004_tenant_retention_block.down.sql

@@ -1,2 +0,0 @@
-ALTER TABLE tenants DROP COLUMN retention_block_reason;
-ALTER TABLE tenants DROP COLUMN retention_checked_at;

migrations/0004_tenant_retention_block.up.sql

@@ -1,6 +0,0 @@
--- TEN-08: Haelt fest, warum eine faellige Tenant-Loeschung zurueckgehalten wurde
--- (GoBD-Aufbewahrungspflicht oder Legal Hold aus Archive RET-03), damit Admins
--- den Grund einsehen koennen (Akzeptanzkriterium 2), ohne dass die Registry
--- selbst modulspezifische Retention-Logik kennen muss — nur den Grund-Text.
-ALTER TABLE tenants ADD COLUMN retention_block_reason TEXT;
-ALTER TABLE tenants ADD COLUMN retention_checked_at TIMESTAMPTZ;

migrations/0005_usage_counters.down.sql

@@ -0,0 +1,2 @@
+DROP TABLE IF EXISTS usage_quotas;
+DROP TABLE IF EXISTS usage_counters;

migrations/0005_usage_counters.up.sql

@@ -0,0 +1,15 @@
+-- Nutzungszaehler & Quotas je Tenant (LIC-03, siehe core-kanban/tickets/LIC-03.md).
+CREATE TABLE usage_counters (
+    tenant_id  UUID NOT NULL,
+    metric     TEXT NOT NULL,
+    value      BIGINT NOT NULL DEFAULT 0,
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (tenant_id, metric)
+);
+
+CREATE TABLE usage_quotas (
+    tenant_id   UUID NOT NULL,
+    metric      TEXT NOT NULL,
+    limit_value BIGINT NOT NULL,
+    PRIMARY KEY (tenant_id, metric)
+);

scripts/reset-test-env.sh

@@ -13,7 +13,7 @@ ROLE="nexarch_test"
 
 export PGPASSWORD="$PASS"
 
-psql -h localhost -U "$ROLE" -d postgres -v ON_ERROR_STOP=1 -c "DROP TABLE IF EXISTS tenants;"
+psql -h localhost -U "$ROLE" -d postgres -v ON_ERROR_STOP=1 -c "DROP TABLE IF EXISTS tenants CASCADE;"
 
 dbs=$(psql -h localhost -U "$ROLE" -d postgres -tAc "SELECT datname FROM pg_database WHERE datname LIKE 'tenant\_%' ESCAPE '\'")
 for db in $dbs; do

scripts/run-checks.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Ein-Kommando-Pruefung fuer den aktuellen Code-Stand auf dem Testhost:
+# Registry+Tenant-DBs zuruecksetzen, dann build/vet/test in einem Rutsch.
+# -p 1 ist Pflicht, da mehrere Pakete dieselbe physische Registry-Tabelle auf
+# dem Testhost teilen (siehe [[project-nexarch-test-infra]]).
+#
+# Aufruf: NEXARCH_TEST_DB_PASSWORD=... ./scripts/run-checks.sh
+set -euo pipefail
+
+PASS="${NEXARCH_TEST_DB_PASSWORD:?Setze NEXARCH_TEST_DB_PASSWORD vor dem Aufruf}"
+cd "$(dirname "$0")/.."
+
+NEXARCH_TEST_DB_PASSWORD="$PASS" bash scripts/reset-test-env.sh
+
+export TEST_ADMIN_DSN="postgresql://nexarch_test:${PASS}@localhost:5432/postgres?sslmode=disable"
+
+echo "== go build =="
+go build ./...
+
+echo "== go vet =="
+go vet ./...
+
+echo "== go test (-p 1) =="
+go test ./... -p 1 -count=1

web/lic-admin/app/layout.tsx

@@ -0,0 +1,30 @@
+import { ThemeProvider, I18nProvider, ToastProvider, typography } from "@nexarch/shl";
+
+export const metadata = {
+  title: "NEXARCH Lizenz- und Modulverwaltung",
+};
+
+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/lic-admin/app/page.tsx

@@ -0,0 +1,173 @@
+"use client";
+
+import { useState } from "react";
+import { fetchOverview, toggleFlag, type Overview } from "@/lib/api";
+
+const STATUS_LABEL: Record<string, string> = {
+  ok: "In Ordnung",
+  warning: "Nahe am Limit",
+  exceeded: "Limit überschritten",
+};
+
+const STATUS_COLOR: Record<string, string> = {
+  ok: "#2e7d32",
+  warning: "#ed6c02",
+  exceeded: "#c62828",
+};
+
+export default function Page() {
+  const [tenantId, setTenantId] = useState("");
+  const [overview, setOverview] = useState<Overview | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [toggleError, setToggleError] = useState<string | null>(null);
+
+  async function load() {
+    if (!tenantId.trim()) return;
+    setLoading(true);
+    setError(null);
+    try {
+      const data = await fetchOverview(tenantId.trim());
+      setOverview(data);
+    } catch (e: any) {
+      setError(e.message ?? "Unbekannter Fehler");
+      setOverview(null);
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  async function onToggle(key: string, next: boolean) {
+    setToggleError(null);
+    try {
+      await toggleFlag(tenantId.trim(), key, next);
+      await load();
+    } catch (e: any) {
+      setToggleError(e.message ?? "Umschalten fehlgeschlagen");
+    }
+  }
+
+  return (
+    <main style={{ maxWidth: 800, margin: "0 auto", padding: "2rem 1rem" }}>
+      <h1>Lizenz- und Modulverwaltung</h1>
+
+      <div style={{ display: "flex", gap: "0.5rem", marginBottom: "1.5rem" }}>
+        <input
+          value={tenantId}
+          onChange={(e) => setTenantId(e.target.value)}
+          placeholder="Tenant-ID eingeben"
+          style={{ flex: 1, padding: "0.5rem", fontSize: "1rem" }}
+        />
+        <button onClick={load} disabled={loading} style={{ padding: "0.5rem 1rem" }}>
+          {loading ? "Lädt…" : "Anzeigen"}
+        </button>
+      </div>
+
+      {error && (
+        <p style={{ color: "#c62828" }} role="alert">
+          Fehler: {error}
+        </p>
+      )}
+
+      {overview && (
+        <>
+          <section style={{ background: "white", padding: "1rem", borderRadius: 8, marginBottom: "1.5rem" }}>
+            <h2>Lizenzstatus</h2>
+            <p>
+              <strong>Plan:</strong> {overview.plan}{" "}
+              {overview.expired && (
+                <span style={{ color: "#c62828", fontWeight: "bold" }}>
+                  (abgelaufen)
+                </span>
+              )}
+            </p>
+            <p>
+              <strong>Gültig bis:</strong>{" "}
+              {new Date(overview.valid_until).toLocaleDateString("de-DE")}
+            </p>
+            <p>
+              <strong>Freigeschaltete Module:</strong>{" "}
+              {overview.modules.length > 0 ? overview.modules.join(", ") : "keine"}
+            </p>
+          </section>
+
+          <section style={{ background: "white", padding: "1rem", borderRadius: 8, marginBottom: "1.5rem" }}>
+            <h2>Feature-Flags</h2>
+            {toggleError && (
+              <p style={{ color: "#c62828" }} role="alert">
+                {toggleError}
+              </p>
+            )}
+            {overview.flags.length === 0 && <p>Keine Feature-Flags definiert.</p>}
+            <ul style={{ listStyle: "none", padding: 0 }}>
+              {overview.flags.map((f) => (
+                <li
+                  key={f.key}
+                  style={{
+                    display: "flex",
+                    justifyContent: "space-between",
+                    alignItems: "center",
+                    padding: "0.5rem 0",
+                    borderBottom: "1px solid #eee",
+                  }}
+                >
+                  <div>
+                    <div>{f.key}</div>
+                    {!f.licensed && f.deny_grund && (
+                      <div style={{ fontSize: "0.85rem", color: "#c62828" }}>
+                        {f.deny_grund}
+                      </div>
+                    )}
+                  </div>
+                  <label>
+                    <input
+                      type="checkbox"
+                      checked={f.enabled}
+                      disabled={!f.licensed && !f.enabled}
+                      onChange={(e) => onToggle(f.key, e.target.checked)}
+                    />{" "}
+                    aktiv
+                  </label>
+                </li>
+              ))}
+            </ul>
+          </section>
+
+          <section style={{ background: "white", padding: "1rem", borderRadius: 8 }}>
+            <h2>Nutzungsstand</h2>
+            {overview.usage.map((u) => {
+              const pct = u.limit > 0 ? Math.min(100, (u.value / u.limit) * 100) : 0;
+              return (
+                <div key={u.metric} style={{ marginBottom: "1rem" }}>
+                  <div style={{ display: "flex", justifyContent: "space-between" }}>
+                    <span>{u.metric}</span>
+                    <span style={{ color: STATUS_COLOR[u.status] }}>
+                      {u.value} / {u.limit > 0 ? u.limit : "unbegrenzt"} —{" "}
+                      {STATUS_LABEL[u.status]}
+                    </span>
+                  </div>
+                  <div
+                    style={{
+                      background: "#eee",
+                      borderRadius: 4,
+                      height: 8,
+                      overflow: "hidden",
+                    }}
+                  >
+                    <div
+                      style={{
+                        width: `${u.limit > 0 ? pct : 0}%`,
+                        background: STATUS_COLOR[u.status],
+                        height: "100%",
+                      }}
+                    />
+                  </div>
+                </div>
+              );
+            })}
+          </section>
+        </>
+      )}
+    </main>
+  );
+}

web/lic-admin/lib/api.ts

@@ -0,0 +1,63 @@
+// Duenner Client fuer das LIC-04-Backend-API (internal/adminapi) — enthaelt
+// keinerlei eigene Lizenz-/Flag-Logik, nur Datenabruf und -weitergabe.
+export type FlagOverview = {
+  key: string;
+  enabled: boolean;
+  licensed: boolean;
+  deny_grund?: string;
+};
+
+export type UsageOverview = {
+  metric: string;
+  value: number;
+  limit: number;
+  status: "ok" | "warning" | "exceeded";
+};
+
+export type Overview = {
+  plan: string;
+  modules: string[];
+  issued_at: string;
+  valid_until: string;
+  expired: boolean;
+  flags: FlagOverview[];
+  usage: UsageOverview[];
+};
+
+function apiBase(): string {
+  const base = process.env.NEXT_PUBLIC_ADMIN_API_URL;
+  if (!base) {
+    throw new Error(
+      "NEXT_PUBLIC_ADMIN_API_URL ist nicht gesetzt (Umgebungsvariable erforderlich)"
+    );
+  }
+  return base;
+}
+
+export async function fetchOverview(tenantId: string): Promise<Overview> {
+  const res = await fetch(
+    `${apiBase()}/admin/overview?tenant=${encodeURIComponent(tenantId)}`,
+    { cache: "no-store" }
+  );
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new Error(body.error || `Anfrage fehlgeschlagen (${res.status})`);
+  }
+  return res.json();
+}
+
+export async function toggleFlag(
+  tenantId: string,
+  key: string,
+  enabled: boolean
+): Promise<void> {
+  const res = await fetch(`${apiBase()}/admin/flags/toggle`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ tenant: tenantId, key, enabled }),
+  });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new Error(body.error || `Umschalten fehlgeschlagen (${res.status})`);
+  }
+}

web/lic-admin/next.config.mjs

@@ -0,0 +1,7 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  // @nexarch/shl liegt als file:-Dependency mit TS-Quellen in node_modules —
+  // Next.js transpiliert node_modules standardmäßig nicht, siehe web/shl/README.md.
+  transpilePackages: ["@nexarch/shl"],
+};
+export default nextConfig;

web/lic-admin/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "nexarch-lic-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/lic-admin/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "es2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "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();
+});