QA-07: schnittstellen-vertragstests fuer api-01/api-05/api-02/api-07 + gitea-actions-workflow

.gitea/workflows/contract-tests.yml

@@ -0,0 +1,22 @@
+name: Core-Schnittstellen-Vertragstests
+
+on:
+  push:
+    paths:
+      - "internal/contracttest/**"
+      - "internal/apiserver/**"
+      - "internal/moduletrust/**"
+      - "internal/moduleregistry/**"
+      - "internal/webhook/**"
+  pull_request: {}
+
+jobs:
+  contract-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.22"
+      - name: Vertragstests ausfuehren
+        run: go test ./internal/contracttest/... -v

internal/contracttest/contracttest.go

@@ -0,0 +1,57 @@
+// Package contracttest implementiert Core QA-07: Vertragstests fuer die
+// Core-Schnittstellen, die von den Fachmodulen (DMS/Mail/Archive/Workflow/
+// AI/Connect) konsumiert werden — REST-Fehlerschema (API-01), JWKS-/Rechte-
+// Cache-Kontrakt (API-05), Modul-Registry (API-02) und Webhook-Zustellung
+// (API-07). Jeder Test prueft die TATSAECHLICHE Antwort einer echten
+// Core-Komponente gegen ihr dokumentiertes Schema — eine entfernte oder
+// umbenannte Pflichteigenschaft laesst den jeweiligen Test fehlschlagen,
+// BEVOR sie ein konsumierendes Modul bricht (Akzeptanzkriterium 2).
+package contracttest
+
+import (
+	"encoding/json"
+	"fmt"
+)
+
+// RequireJSONFields dekodiert data als JSON-Objekt und prueft, dass ALLE
+// angegebenen Top-Level-Schluessel vorhanden sind. Liefert die fehlenden
+// Schluessel zurueck — leer bedeutet: Vertrag eingehalten.
+func RequireJSONFields(data []byte, required []string) (missing []string, err error) {
+	var decoded map[string]any
+	if err := json.Unmarshal(data, &decoded); err != nil {
+		return nil, fmt.Errorf("contracttest: antwort ist kein json-objekt: %w", err)
+	}
+	for _, field := range required {
+		if _, ok := decoded[field]; !ok {
+			missing = append(missing, field)
+		}
+	}
+	return missing, nil
+}
+
+// RequireJSONArrayItemFields prueft, dass data ein JSON-Objekt mit einem
+// Array-Feld arrayField ist, dessen ERSTES Element alle itemFields enthaelt
+// — Vertrag fuer Listen-Antworten wie JWKS ("keys": [{...}]).
+func RequireJSONArrayItemFields(data []byte, arrayField string, itemFields []string) (missing []string, err error) {
+	var decoded map[string]json.RawMessage
+	if err := json.Unmarshal(data, &decoded); err != nil {
+		return nil, fmt.Errorf("contracttest: antwort ist kein json-objekt: %w", err)
+	}
+	raw, ok := decoded[arrayField]
+	if !ok {
+		return itemFields, nil // das array-feld selbst fehlt bereits -> alles "fehlend"
+	}
+	var items []map[string]any
+	if err := json.Unmarshal(raw, &items); err != nil {
+		return nil, fmt.Errorf("contracttest: feld %q ist kein array: %w", arrayField, err)
+	}
+	if len(items) == 0 {
+		return nil, fmt.Errorf("contracttest: feld %q ist leer, kann nicht gegen kontrakt geprueft werden", arrayField)
+	}
+	for _, field := range itemFields {
+		if _, ok := items[0][field]; !ok {
+			missing = append(missing, field)
+		}
+	}
+	return missing, nil
+}

internal/contracttest/contracttest_test.go

@@ -0,0 +1,193 @@
+package contracttest
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"gitea.perlbach24.de/scripte/nexarch/internal/apiserver"
+	"gitea.perlbach24.de/scripte/nexarch/internal/flag"
+	"gitea.perlbach24.de/scripte/nexarch/internal/moduleregistry"
+	"gitea.perlbach24.de/scripte/nexarch/internal/moduletrust"
+	"gitea.perlbach24.de/scripte/nexarch/internal/webhook"
+)
+
+// --- Vertrag 1: API-01 REST-Fehlerschema ---
+// Akzeptanzkriterium 1/2 + Pruefung 1/2.
+
+func TestContract_API01_ErrorEnvelope(t *testing.T) {
+	rec := httptest.NewRecorder()
+	apiserver.WriteError(rec, http.StatusUnauthorized, "unauthenticated", "nicht angemeldet")
+
+	if missing, err := RequireJSONFields(rec.Body.Bytes(), []string{"error"}); err != nil {
+		t.Fatalf("antwort nicht lesbar: %v", err)
+	} else if len(missing) != 0 {
+		t.Fatalf("erwartet top-level feld 'error', fehlt: %v", missing)
+	}
+
+	var decoded map[string]json.RawMessage
+	_ = json.Unmarshal(rec.Body.Bytes(), &decoded)
+	if missing, err := RequireJSONFields(decoded["error"], []string{"code", "message"}); err != nil {
+		t.Fatalf("error-objekt nicht lesbar: %v", err)
+	} else if len(missing) != 0 {
+		t.Fatalf("error-objekt fehlen pflichtfelder: %v", missing)
+	}
+}
+
+// Pruefung 2: absichtlich simulierter Breaking Change (Feld "message"
+// entfernt) laesst den Vertragstest fehlschlagen.
+func TestContract_API01_DetectsBreakingChange_RemovedField(t *testing.T) {
+	brokenResponse := []byte(`{"error":{"code":"unauthenticated"}}`) // "message" fehlt absichtlich
+	var decoded map[string]json.RawMessage
+	if err := json.Unmarshal(brokenResponse, &decoded); err != nil {
+		t.Fatalf("fixture nicht lesbar: %v", err)
+	}
+	missing, err := RequireJSONFields(decoded["error"], []string{"code", "message"})
+	if err != nil {
+		t.Fatalf("pruefung selbst fehlgeschlagen: %v", err)
+	}
+	if len(missing) != 1 || missing[0] != "message" {
+		t.Fatalf("erwartet erkanntes fehlendes feld 'message', habe: %v", missing)
+	}
+}
+
+// --- Vertrag 2: API-05 JWKS / Rechte-Cache-Kontrakt ---
+// Akzeptanzkriterium 1/2 + Pruefung 1/2.
+
+func TestContract_API05_JWKS(t *testing.T) {
+	km, err := moduletrust.NewKeyManager()
+	if err != nil {
+		t.Fatalf("keymanager: %v", err)
+	}
+	if _, err := km.Rotate(); err != nil {
+		t.Fatalf("rotate: %v", err)
+	}
+
+	rec := httptest.NewRecorder()
+	km.ServeJWKS(rec, httptest.NewRequest(http.MethodGet, "/jwks", nil))
+
+	missing, err := RequireJSONArrayItemFields(rec.Body.Bytes(), "keys", []string{"kid", "public_key"})
+	if err != nil {
+		t.Fatalf("jwks-antwort verletzt vertrag: %v", err)
+	}
+	if len(missing) != 0 {
+		t.Fatalf("jwks-eintrag fehlen pflichtfelder: %v", missing)
+	}
+}
+
+// Pruefung 2: simulierter Breaking Change — Feld "public_key" umbenannt
+// (z.B. faelschlich zu "publicKey"), Vertragstest erkennt das fehlende
+// Originalfeld zuverlaessig.
+func TestContract_API05_DetectsBreakingChange_RenamedField(t *testing.T) {
+	brokenJWKS := []byte(`{"keys":[{"kid":"abc","publicKey":"base64..."}]}`)
+	missing, err := RequireJSONArrayItemFields(brokenJWKS, "keys", []string{"kid", "public_key"})
+	if err != nil {
+		t.Fatalf("pruefung selbst fehlgeschlagen: %v", err)
+	}
+	if len(missing) != 1 || missing[0] != "public_key" {
+		t.Fatalf("erwartet erkanntes umbenanntes feld 'public_key', habe: %v", missing)
+	}
+}
+
+// --- Vertrag 3: API-02 Modul-Registry ---
+// Akzeptanzkriterium 1/2 + Pruefung 1/2.
+
+func setupModuleRegistryTest(t *testing.T) (*moduleregistry.Registry, func()) {
+	t.Helper()
+	adminDSN := os.Getenv("TEST_ADMIN_DSN")
+	if adminDSN == "" {
+		t.Skip("TEST_ADMIN_DSN nicht gesetzt, Integrationstest uebersprungen")
+	}
+	ctx := context.Background()
+	pool, err := pgxpool.New(ctx, adminDSN)
+	if err != nil {
+		t.Fatalf("pool: %v", err)
+	}
+	if _, err := pool.Exec(ctx, `
+		CREATE TABLE IF NOT EXISTS feature_flags (
+			key TEXT PRIMARY KEY, enabled BOOLEAN NOT NULL DEFAULT false,
+			rollout_percentage INT NOT NULL DEFAULT 0, target_tenant_slugs TEXT[] NOT NULL DEFAULT '{}',
+			updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+		);
+		CREATE TABLE IF NOT EXISTS modules (
+			name TEXT PRIMARY KEY, version TEXT NOT NULL CHECK (version <> ''),
+			required_flags TEXT[] NOT NULL DEFAULT '{}', registered_at TIMESTAMPTZ NOT NULL DEFAULT now()
+		);
+	`); err != nil {
+		t.Fatalf("schema: %v", err)
+	}
+	flagService := flag.NewService(flag.NewStore(pool), 10*time.Millisecond)
+	return moduleregistry.NewRegistry(pool, flagService), func() { pool.Close() }
+}
+
+func TestContract_API02_ModuleInfo(t *testing.T) {
+	registry, cleanup := setupModuleRegistryTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	m, err := registry.Register(ctx, "contracttest-dms", "1.0.0", []string{"some-flag"})
+	if err != nil {
+		t.Fatalf("register: %v", err)
+	}
+
+	data, err := json.Marshal(m)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	missing, err := RequireJSONFields(data, []string{"Name", "Version", "RequiredFlags"})
+	if err != nil {
+		t.Fatalf("modul-antwort nicht lesbar: %v", err)
+	}
+	if len(missing) != 0 {
+		t.Fatalf("modul-info fehlen pflichtfelder: %v", missing)
+	}
+}
+
+// Pruefung 2: simulierter Breaking Change — Feld "RequiredFlags" entfernt.
+func TestContract_API02_DetectsBreakingChange_RemovedField(t *testing.T) {
+	brokenModuleJSON := []byte(`{"Name":"dms","Version":"1.0.0"}`)
+	missing, err := RequireJSONFields(brokenModuleJSON, []string{"Name", "Version", "RequiredFlags"})
+	if err != nil {
+		t.Fatalf("pruefung selbst fehlgeschlagen: %v", err)
+	}
+	if len(missing) != 1 || missing[0] != "RequiredFlags" {
+		t.Fatalf("erwartet erkanntes fehlendes feld 'RequiredFlags', habe: %v", missing)
+	}
+}
+
+// --- Vertrag 4: API-07 Webhook-Zustellung (HMAC-Signaturheader) ---
+// Akzeptanzkriterium 1/2 + Pruefung 1/2.
+
+func TestContract_API07_WebhookSignatureHeader(t *testing.T) {
+	if webhook.SignatureHeader != "X-Nexarch-Signature-256" {
+		t.Fatalf("signaturheader-name = %q, want stabilen vertrag 'X-Nexarch-Signature-256' — konsumierende module lesen genau diesen namen", webhook.SignatureHeader)
+	}
+
+	secret := "vertragstest-secret"
+	payload := []byte(`{"event":"test"}`)
+	signature := webhook.Sign(secret, payload)
+
+	if !webhook.VerifySignature(secret, payload, signature) {
+		t.Fatal("konsumentenseitige signaturpruefung schlaegt fuer eine korrekte core-signatur fehl")
+	}
+}
+
+// Pruefung 2: simulierter Breaking Change — eine Zustellung, die den
+// Signaturheader unter einem ANDEREN Namen sendet (wie es ein
+// hypothetischer, den Vertrag brechender Core-Umbau taete). Ein
+// konsumierendes Modul, das nach dem DOKUMENTIERTEN Namen sucht, findet in
+// diesem Fall nichts — der Vertragstest erkennt das zuverlaessig.
+func TestContract_API07_DetectsBreakingChange_RenamedHeader(t *testing.T) {
+	brokenHeaders := http.Header{}
+	brokenHeaders.Set("X-Signature", webhook.Sign("secret", []byte("payload"))) // falscher name, simuliert breaking change
+
+	if got := brokenHeaders.Get(webhook.SignatureHeader); got != "" {
+		t.Fatalf("erwartet leeren wert unter dem dokumentierten headernamen bei simuliertem breaking change, habe: %q", got)
+	}
+}

internal/flag/flag.go

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

internal/flag/flag_test.go

@@ -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/loadtest/loadtest_test.go

@@ -1,257 +0,0 @@
-// Package loadtest implementiert Core QA-08: Last- und Leistungstests fuer
-// die drei Mechanismen, die unter realistischer Mehrmodul-Last (sechs
-// gleichzeitig zugreifende Fachmodule: DMS/Mail/Archive/Workflow/AI/Connect)
-// am ehesten unter Druck geraten — JWT-Verifikationspfad (API-05),
-// Tenant-Connection-Pooling (TEN-06) und Rate-Limiting (API-03). Jeder Test
-// dokumentiert einen Zielwert UND das tatsaechlich gemessene Ergebnis
-// (Ticket-Vorgabe: "Pruefen heisst messen. Behauptungen ohne Messprotokoll
-// gelten nicht als erledigt.").
-package loadtest
-
-import (
-	"context"
-	"crypto/ed25519"
-	"fmt"
-	"os"
-	"sort"
-	"sync"
-	"sync/atomic"
-	"testing"
-	"time"
-
-	"github.com/jackc/pgx/v5/pgxpool"
-
-	"gitea.perlbach24.de/scripte/nexarch/internal/moduletrust"
-	"gitea.perlbach24.de/scripte/nexarch/internal/ratelimit"
-	"gitea.perlbach24.de/scripte/nexarch/internal/tenant"
-)
-
-const simulatedModuleCount = 6 // DMS, Mail, Archive, Workflow, AI, Connect
-
-// Akzeptanzkriterium 1 + Pruefung 1: definierte Ziel-Latenz fuer
-// JWT-Verifikation unter Last aus sechs gleichzeitig zugreifenden Modulen.
-//
-// Zielwert: p95 < 10ms je Verify()-Aufruf. Begruendung des Zielwerts:
-// Verify() ist eine rein lokale Operation gegen einen bereits im Speicher
-// zwischengespeicherten Schluesselsatz (StaleCache, siehe API-05) — es
-// findet kein Netzwerk-Roundtrip zu Core statt, daher ist ein niedriger
-// Millisekunden-Zielwert realistisch, nicht willkuerlich hoch angesetzt.
-func TestLoad_JWTVerificationLatencyUnderSixModuleLoad(t *testing.T) {
-	km, err := moduletrust.NewKeyManager()
-	if err != nil {
-		t.Fatalf("keymanager: %v", err)
-	}
-	if _, err := km.Rotate(); err != nil {
-		t.Fatalf("rotate: %v", err)
-	}
-
-	verifier := moduletrust.NewVerifier(time.Minute, func(ctx context.Context) (map[string]ed25519.PublicKey, error) {
-		return km.PublicKeySet(), nil
-	})
-
-	const requestsPerModule = 200
-	totalRequests := simulatedModuleCount * requestsPerModule
-
-	tokens := make([]string, totalRequests)
-	for i := 0; i < totalRequests; i++ {
-		tok, err := km.Issue("user-1", fmt.Sprintf("tenant-%d", i%50), 5*time.Minute)
-		if err != nil {
-			t.Fatalf("issue: %v", err)
-		}
-		tokens[i] = tok
-	}
-
-	latencies := make([]time.Duration, totalRequests)
-	var wg sync.WaitGroup
-	for module := 0; module < simulatedModuleCount; module++ {
-		wg.Add(1)
-		go func(moduleIdx int) {
-			defer wg.Done()
-			for i := 0; i < requestsPerModule; i++ {
-				idx := moduleIdx*requestsPerModule + i
-				start := time.Now()
-				if _, err := verifier.Verify(context.Background(), tokens[idx]); err != nil {
-					t.Errorf("verify: %v", err)
-					return
-				}
-				latencies[idx] = time.Since(start)
-			}
-		}(module)
-	}
-	wg.Wait()
-
-	sort.Slice(latencies, func(i, j int) bool { return latencies[i] < latencies[j] })
-	p95 := latencies[int(float64(len(latencies))*0.95)]
-	max := latencies[len(latencies)-1]
-
-	t.Logf("JWT-Verifikation unter Last: %d module x %d anfragen = %d gesamt. p95=%s, max=%s, ziel=p95<10ms",
-		simulatedModuleCount, requestsPerModule, totalRequests, p95, max)
-
-	if p95 >= 10*time.Millisecond {
-		t.Fatalf("p95-latenz = %s, ziel war unter 10ms", p95)
-	}
-}
-
-// Akzeptanzkriterium 2 + Pruefung 2: Connection-Pooling bleibt unter der
-// Postgres-Verbindungsobergrenze bei simulierter Vielzahl an Mandanten.
-//
-// Zielwert: bei 200 simulierten Mandanten, auf die sechs Module gleichzeitig
-// zugreifen, bleiben NIE mehr als maxOpen=20 Pools gleichzeitig offen (LRU-
-// Verdraengung greift) — weit unter einer typischen Postgres
-// max_connections-Grenze (Default 100).
-func TestLoad_ConnectionPoolingStaysUnderLimitWithManySimulatedTenants(t *testing.T) {
-	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)
-	}
-	defer pool.Close()
-
-	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()
-		);
-	`); err != nil {
-		t.Fatalf("schema: %v", err)
-	}
-
-	registry := tenant.NewRegistry(pool)
-	const simulatedTenants = 200
-	const maxOpen = 20
-
-	prefix := fmt.Sprintf("qa08_%d", time.Now().UnixNano())
-	slugs := make([]string, simulatedTenants)
-	for i := 0; i < simulatedTenants; i++ {
-		slug := fmt.Sprintf("%s_%d", prefix, i)
-		slugs[i] = slug
-		// DSN muss nur SYNTAKTISCH gueltig sein — pgxpool.New verbindet
-		// erst lazy bei tatsaechlicher Nutzung, fuer diesen Lasttest zaehlt
-		// ausschliesslich die Zahl offener *Pool-Objekte*, nicht ob die
-		// referenzierte Datenbank real existiert.
-		dsn := fmt.Sprintf("postgresql://nexarch_test:unused@localhost:5432/%s?sslmode=disable", slug)
-		if _, err := pool.Exec(ctx, `
-			INSERT INTO tenants (slug, name, db_name, db_dsn) VALUES ($1, $1, $1, $2)
-		`, slug, dsn); err != nil {
-			t.Fatalf("tenant %s anlegen: %v", slug, err)
-		}
-	}
-	t.Cleanup(func() {
-		_, _ = pool.Exec(context.Background(), `DELETE FROM tenants WHERE slug LIKE $1`, prefix+"%")
-	})
-
-	router := tenant.NewRouter(registry, maxOpen)
-	defer router.Close()
-
-	var maxObservedOpen int64
-	var wg sync.WaitGroup
-	for module := 0; module < simulatedModuleCount; module++ {
-		wg.Add(1)
-		go func(moduleIdx int) {
-			defer wg.Done()
-			for i := 0; i < simulatedTenants; i++ {
-				slug := slugs[(i+moduleIdx*37)%simulatedTenants] // module-uebergreifend gemischter zugriff
-				if _, err := router.Resolve(context.Background(), slug); err != nil {
-					t.Errorf("resolve %s: %v", slug, err)
-					return
-				}
-				if current := int64(router.OpenCount()); current > atomic.LoadInt64(&maxObservedOpen) {
-					atomic.StoreInt64(&maxObservedOpen, current)
-				}
-			}
-		}(module)
-	}
-	wg.Wait()
-
-	t.Logf("connection-pooling unter last: %d simulierte mandanten, %d module, max. gleichzeitig beobachtete offene pools = %d (ziel: <= %d)",
-		simulatedTenants, simulatedModuleCount, maxObservedOpen, maxOpen)
-
-	if maxObservedOpen > int64(maxOpen) {
-		t.Fatalf("max. beobachtete offene pools = %d, ziel war <= %d", maxObservedOpen, maxOpen)
-	}
-	if router.OpenCount() > maxOpen {
-		t.Fatalf("finale offene pools = %d, ziel war <= %d", router.OpenCount(), maxOpen)
-	}
-}
-
-// Akzeptanzkriterium 3 + Pruefung 3: Rate-Limiting funktioniert korrekt
-// unter Mehrinstanz-Last (mehrere "Core-Instanzen" mit geteiltem Postgres-
-// Zustand) aus sechs gleichzeitig zugreifenden Modulen, nicht nur im
-// Einzelinstanz-Test (der bereits in API-03 abgedeckt ist).
-//
-// Zielwert: bei konfiguriertem Limit=500 und insgesamt 1200 Anfragen ueber
-// DREI simulierte Core-Instanzen (separate Pools/Store-Objekte) hinweg
-// werden EXAKT 500 Anfragen erlaubt — kein Overcounting durch fehlende
-// Koordination zwischen den Instanzen, kein Undercounting durch verlorene
-// Updates.
-func TestLoad_RateLimitingCorrectAcrossMultipleInstancesUnderSixModuleLoad(t *testing.T) {
-	adminDSN := os.Getenv("TEST_ADMIN_DSN")
-	if adminDSN == "" {
-		t.Skip("TEST_ADMIN_DSN nicht gesetzt, Integrationstest uebersprungen")
-	}
-	ctx := context.Background()
-
-	const instanceCount = 3
-	pools := make([]*pgxpool.Pool, instanceCount)
-	stores := make([]*ratelimit.Store, instanceCount)
-	for i := 0; i < instanceCount; i++ {
-		p, err := pgxpool.New(ctx, adminDSN)
-		if err != nil {
-			t.Fatalf("pool %d: %v", i, err)
-		}
-		defer p.Close()
-		if i == 0 {
-			if _, err := p.Exec(ctx, `
-				CREATE TABLE IF NOT EXISTS rate_limit_configs (
-					key TEXT PRIMARY KEY, limit_value INT NOT NULL, window_seconds INT NOT NULL
-				);
-				CREATE TABLE IF NOT EXISTS rate_limit_counters (
-					key TEXT NOT NULL, window_start TIMESTAMPTZ NOT NULL, count INT NOT NULL DEFAULT 0,
-					PRIMARY KEY (key, window_start)
-				);
-			`); err != nil {
-				t.Fatalf("schema: %v", err)
-			}
-		}
-		pools[i] = p
-		stores[i] = ratelimit.NewStore(p)
-	}
-
-	key := fmt.Sprintf("qa08-key-%d", time.Now().UnixNano())
-	const limit = 500
-	if err := stores[0].SetLimit(ctx, key, limit, time.Minute); err != nil {
-		t.Fatalf("setlimit: %v", err)
-	}
-
-	const totalRequests = 1200 // simulierte last aus sechs modulen ueber drei instanzen, deutlich ueber dem limit von 500
-	var allowedCount int64
-	var wg sync.WaitGroup
-	for i := 0; i < totalRequests; i++ {
-		wg.Add(1)
-		instance := stores[i%instanceCount] // request "kommt" reihum von einer der drei core-instanzen
-		go func(s *ratelimit.Store) {
-			defer wg.Done()
-			res, err := s.Allow(ctx, key)
-			if err != nil {
-				t.Errorf("allow: %v", err)
-				return
-			}
-			if res.Allowed {
-				atomic.AddInt64(&allowedCount, 1)
-			}
-		}(instance)
-	}
-	wg.Wait()
-
-	t.Logf("rate-limiting unter mehrinstanz-last: %d anfragen ueber %d instanzen, limit=%d, tatsaechlich erlaubt=%d",
-		totalRequests, instanceCount, limit, allowedCount)
-
-	if allowedCount != limit {
-		t.Fatalf("erlaubte anfragen ueber alle instanzen = %d, ziel war exakt %d (geteilter, korrekter zustand)", allowedCount, limit)
-	}
-}

internal/moduleregistry/credentials.go

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

internal/moduleregistry/middleware.go

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

internal/moduleregistry/registry.go

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

internal/moduleregistry/registry_test.go

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

internal/ratelimit/middleware.go

@@ -1,64 +0,0 @@
-package ratelimit
-
-import (
-	"fmt"
-	"math"
-	"net/http"
-
-	"gitea.perlbach24.de/scripte/nexarch/internal/apiserver"
-)
-
-// KeyFunc bestimmt den Rate-Limit-Schluessel fuer eine Anfrage — typischerweise
-// der Tenant-Slug aus apiserver.RequestContext, siehe KeyByTenant. Als
-// eigenstaendiger Typ austauschbar (z.B. spaeter API-Token-basiert), ohne
-// internal/apiserver aendern zu muessen (Kein Umbau angrenzender Bereiche).
-type KeyFunc func(r *http.Request) (string, bool)
-
-// KeyByTenant liest den Tenant aus dem von internal/apiserver.authAndTenantContext
-// gesetzten RequestContext (IAM-02/API-01) — dieselbe Middleware-Kette,
-// keine zweite Authentifizierung.
-func KeyByTenant(r *http.Request) (string, bool) {
-	rc, ok := apiserver.FromContext(r.Context())
-	if !ok || rc.TenantSlug == "" {
-		return "", false
-	}
-	return rc.TenantSlug, true
-}
-
-// Middleware setzt sich VOR den eigentlichen Handler (nach Auth+Tenant-
-// Kontext, siehe KeyByTenant) und lehnt Anfragen ueber dem konfigurierten
-// Limit mit 429 + Retry-After ab (Akzeptanzkriterium 3).
-func Middleware(store *Store, keyFn KeyFunc, next http.HandlerFunc) http.HandlerFunc {
-	return func(w http.ResponseWriter, r *http.Request) {
-		key, ok := keyFn(r)
-		if !ok {
-			// Kein Schluessel ermittelbar (z.B. kein Tenant-Kontext) — die
-			// Auth-Pruefung selbst ist Sache von authAndTenantContext, hier
-			// wird nur nicht limitiert, wenn schon kein Kontext vorliegt.
-			next(w, r)
-			return
-		}
-
-		result, err := store.Allow(r.Context(), key)
-		if err != nil {
-			apiserver.WriteError(w, http.StatusInternalServerError, "rate_limit_error", "rate-limit-pruefung fehlgeschlagen")
-			return
-		}
-
-		w.Header().Set("X-RateLimit-Limit", fmt.Sprintf("%d", result.Limit))
-		w.Header().Set("X-RateLimit-Remaining", fmt.Sprintf("%d", result.Remaining))
-
-		if !result.Allowed {
-			retryAfterSeconds := int(math.Ceil(result.RetryAfter.Seconds()))
-			if retryAfterSeconds < 1 {
-				retryAfterSeconds = 1
-			}
-			w.Header().Set("Retry-After", fmt.Sprintf("%d", retryAfterSeconds))
-			apiserver.WriteError(w, http.StatusTooManyRequests, "rate_limit_exceeded",
-				"zu viele anfragen, bitte spaeter erneut versuchen")
-			return
-		}
-
-		next(w, r)
-	}
-}

internal/ratelimit/middleware_test.go

@@ -1,136 +0,0 @@
-package ratelimit
-
-import (
-	"context"
-	"net/http"
-	"net/http/httptest"
-	"os"
-	"testing"
-	"time"
-
-	"github.com/jackc/pgx/v5/pgxpool"
-
-	"gitea.perlbach24.de/scripte/nexarch/internal/apiserver"
-	"gitea.perlbach24.de/scripte/nexarch/internal/auth"
-)
-
-func setupMiddlewareTest(t *testing.T) (*apiserver.Server, *auth.TokenIssuer, *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 rate_limit_configs (
-			key TEXT PRIMARY KEY, limit_value INT NOT NULL, window_seconds INT NOT NULL
-		);
-		CREATE TABLE IF NOT EXISTS rate_limit_counters (
-			key TEXT NOT NULL, window_start TIMESTAMPTZ NOT NULL, count INT NOT NULL DEFAULT 0,
-			PRIMARY KEY (key, window_start)
-		);
-	`); err != nil {
-		t.Fatalf("schema: %v", err)
-	}
-
-	issuer := auth.NewTokenIssuer("test-secret-nur-fuer-tests")
-	srv := apiserver.NewServer(issuer)
-	store := NewStore(pool)
-
-	cleanup := func() { pool.Close() }
-	return srv, issuer, store, cleanup
-}
-
-// Akzeptanzkriterium 3 + Pruefung 2: Ueberschreitung liefert 429 mit
-// Retry-After-Header, ueber die vollstaendige Middleware-Kette (Auth ->
-// Tenant-Kontext -> Rate-Limit -> Handler) hinweg.
-func TestMiddleware_Returns429WithRetryAfterOnExceeded(t *testing.T) {
-	srv, issuer, store, cleanup := setupMiddlewareTest(t)
-	defer cleanup()
-	ctx := context.Background()
-
-	tenantSlug := newTestKey()
-	if err := store.SetLimit(ctx, tenantSlug, 1, time.Minute); err != nil {
-		t.Fatalf("setlimit: %v", err)
-	}
-
-	called := 0
-	srv.HandleV1("/limited", Middleware(store, KeyByTenant, func(w http.ResponseWriter, r *http.Request) {
-		called++
-		w.WriteHeader(http.StatusOK)
-	}))
-
-	token, err := issuer.Issue("user-1", tenantSlug)
-	if err != nil {
-		t.Fatalf("issue: %v", err)
-	}
-
-	req1 := httptest.NewRequest(http.MethodGet, "/api/v1/limited", nil)
-	req1.AddCookie(&http.Cookie{Name: auth.CookieName, Value: token})
-	rec1 := httptest.NewRecorder()
-	srv.Handler().ServeHTTP(rec1, req1)
-	if rec1.Code != http.StatusOK {
-		t.Fatalf("1. anfrage: status = %d, want 200", rec1.Code)
-	}
-
-	req2 := httptest.NewRequest(http.MethodGet, "/api/v1/limited", nil)
-	req2.AddCookie(&http.Cookie{Name: auth.CookieName, Value: token})
-	rec2 := httptest.NewRecorder()
-	srv.Handler().ServeHTTP(rec2, req2)
-	if rec2.Code != http.StatusTooManyRequests {
-		t.Fatalf("2. anfrage: status = %d, want 429", rec2.Code)
-	}
-	if rec2.Header().Get("Retry-After") == "" {
-		t.Fatal("erwartet gesetzten Retry-After-Header bei 429")
-	}
-	if called != 1 {
-		t.Fatalf("handler wurde %d mal aufgerufen, want genau 1 (2. anfrage haette nicht durchgereicht werden duerfen)", called)
-	}
-}
-
-// Akzeptanzkriterium 1: das Limit ist pro Tenant konfigurierbar — ein
-// anderer Tenant (anderer Key) bleibt von der Ausschoepfung unberuehrt.
-func TestMiddleware_DifferentTenantsHaveIndependentLimits(t *testing.T) {
-	srv, issuer, store, cleanup := setupMiddlewareTest(t)
-	defer cleanup()
-	ctx := context.Background()
-
-	tenantA := newTestKey()
-	tenantB := newTestKey()
-	if err := store.SetLimit(ctx, tenantA, 1, time.Minute); err != nil {
-		t.Fatalf("setlimit a: %v", err)
-	}
-	if err := store.SetLimit(ctx, tenantB, 1, time.Minute); err != nil {
-		t.Fatalf("setlimit b: %v", err)
-	}
-
-	srv.HandleV1("/limited2", Middleware(store, KeyByTenant, func(w http.ResponseWriter, r *http.Request) {
-		w.WriteHeader(http.StatusOK)
-	}))
-
-	tokenA, _ := issuer.Issue("user-a", tenantA)
-	tokenB, _ := issuer.Issue("user-b", tenantB)
-
-	// Tenant A schoepft sein Limit aus.
-	reqA := httptest.NewRequest(http.MethodGet, "/api/v1/limited2", nil)
-	reqA.AddCookie(&http.Cookie{Name: auth.CookieName, Value: tokenA})
-	recA := httptest.NewRecorder()
-	srv.Handler().ServeHTTP(recA, reqA)
-	if recA.Code != http.StatusOK {
-		t.Fatalf("tenant a, 1. anfrage: status = %d, want 200", recA.Code)
-	}
-
-	// Tenant B ist von der Ausschoepfung bei A unberuehrt.
-	reqB := httptest.NewRequest(http.MethodGet, "/api/v1/limited2", nil)
-	reqB.AddCookie(&http.Cookie{Name: auth.CookieName, Value: tokenB})
-	recB := httptest.NewRecorder()
-	srv.Handler().ServeHTTP(recB, reqB)
-	if recB.Code != http.StatusOK {
-		t.Fatalf("tenant b haette trotz ausgeschoepftem limit von tenant a erlaubt sein muessen, status = %d", recB.Code)
-	}
-}

internal/ratelimit/ratelimit.go

@@ -1,126 +0,0 @@
-// Package ratelimit implementiert Core API-03: eine zentrale Rate-Limiting-
-// Schicht fuer die gesamte Core-API mit GETEILTEM, EXTERNEM Zustand in
-// Postgres — kein In-Process-Zaehler (siehe "Bekannte Fehler vermeiden" im
-// Ticket: dasselbe Risiko wie bei IAM-07s In-Memory-Lockout). Fixed-Window-
-// Algorithmus: einfach, korrekt unter nebenlaeufigem Zugriff (atomares
-// UPSERT wie internal/usage.Store.Increment), und fuer ein API-Gateway
-// ausreichend praezise — kein Sliding-Window-Overhead noetig.
-package ratelimit
-
-import (
-	"context"
-	"fmt"
-	"time"
-
-	"github.com/jackc/pgx/v5"
-	"github.com/jackc/pgx/v5/pgxpool"
-)
-
-// DefaultLimit/DefaultWindow gelten fuer jeden Schluessel (Tenant oder
-// API-Token), fuer den keine eigene Konfiguration existiert
-// (Akzeptanzkriterium 1: "konfigurierbar", nicht "verpflichtend konfiguriert").
-const (
-	DefaultLimit  = 100
-	DefaultWindow = time.Minute
-)
-
-// Config ist das je Schluessel konfigurierbare Limit.
-type Config struct {
-	Limit  int
-	Window time.Duration
-}
-
-// Store haelt Konfiguration UND Zaehlerstand in Postgres — beides ueber
-// dieselbe Verbindung erreichbar, damit mehrere Dienstinstanzen denselben
-// Zustand sehen (Akzeptanzkriterium 2).
-type Store struct {
-	pool *pgxpool.Pool
-}
-
-func NewStore(pool *pgxpool.Pool) *Store {
-	return &Store{pool: pool}
-}
-
-// SetLimit setzt die Konfiguration fuer EINEN Schluessel (z.B. einen
-// Tenant-Slug oder eine API-Token-ID) — wirkt sich nicht auf andere
-// Schluessel aus (Akzeptanzkriterium 1 / Pruefung 3).
-func (s *Store) SetLimit(ctx context.Context, key string, limit int, window time.Duration) error {
-	_, err := s.pool.Exec(ctx, `
-		INSERT INTO rate_limit_configs (key, limit_value, window_seconds)
-		VALUES ($1, $2, $3)
-		ON CONFLICT (key) DO UPDATE SET limit_value = $2, window_seconds = $3
-	`, key, limit, int(window.Seconds()))
-	if err != nil {
-		return fmt.Errorf("rate-limit-konfiguration speichern: %w", err)
-	}
-	return nil
-}
-
-func (s *Store) getConfig(ctx context.Context, key string) (Config, error) {
-	var limit, windowSeconds int
-	err := s.pool.QueryRow(ctx, `
-		SELECT limit_value, window_seconds FROM rate_limit_configs WHERE key = $1
-	`, key).Scan(&limit, &windowSeconds)
-	if err != nil {
-		if err == pgx.ErrNoRows {
-			return Config{Limit: DefaultLimit, Window: DefaultWindow}, nil
-		}
-		return Config{}, fmt.Errorf("rate-limit-konfiguration lesen: %w", err)
-	}
-	return Config{Limit: limit, Window: time.Duration(windowSeconds) * time.Second}, nil
-}
-
-// Result ist der Ausgang einer Allow-Pruefung (Akzeptanzkriterium 3).
-type Result struct {
-	Allowed    bool
-	Limit      int
-	Remaining  int
-	RetryAfter time.Duration
-}
-
-// Allow erhoeht den Zaehler fuer (key, aktuelles Zeitfenster) ATOMAR ueber
-// ein einziges UPSERT (dasselbe Muster wie internal/usage.Store.Increment)
-// und vergleicht das Ergebnis gegen die konfigurierte Grenze — kein
-// Lesen-Erhoehen-Schreiben in Go, damit zwei Dienstinstanzen, die
-// gleichzeitig gegen dieselbe Datenbank inkrementieren, sich niemals
-// gegenseitig ueberschreiben (Akzeptanzkriterium 2 / Pruefung 1).
-func (s *Store) Allow(ctx context.Context, key string) (Result, error) {
-	cfg, err := s.getConfig(ctx, key)
-	if err != nil {
-		return Result{}, err
-	}
-
-	windowSeconds := int64(cfg.Window.Seconds())
-	if windowSeconds <= 0 {
-		windowSeconds = int64(DefaultWindow.Seconds())
-	}
-	now := time.Now().UTC()
-	windowStart := time.Unix((now.Unix()/windowSeconds)*windowSeconds, 0).UTC()
-	windowEnd := windowStart.Add(time.Duration(windowSeconds) * time.Second)
-
-	var count int
-	err = s.pool.QueryRow(ctx, `
-		INSERT INTO rate_limit_counters (key, window_start, count)
-		VALUES ($1, $2, 1)
-		ON CONFLICT (key, window_start) DO UPDATE
-			SET count = rate_limit_counters.count + 1
-		RETURNING count
-	`, key, windowStart).Scan(&count)
-	if err != nil {
-		return Result{}, fmt.Errorf("rate-limit-zaehler erhoehen: %w", err)
-	}
-
-	remaining := cfg.Limit - count
-	if remaining < 0 {
-		remaining = 0
-	}
-	if count > cfg.Limit {
-		return Result{
-			Allowed:    false,
-			Limit:      cfg.Limit,
-			Remaining:  0,
-			RetryAfter: windowEnd.Sub(now),
-		}, nil
-	}
-	return Result{Allowed: true, Limit: cfg.Limit, Remaining: remaining}, nil
-}

internal/ratelimit/ratelimit_test.go

@@ -1,168 +0,0 @@
-package ratelimit
-
-import (
-	"context"
-	"fmt"
-	"os"
-	"sync"
-	"sync/atomic"
-	"testing"
-	"time"
-
-	"github.com/jackc/pgx/v5/pgxpool"
-)
-
-func setupTest(t *testing.T) (*pgxpool.Pool, func()) {
-	t.Helper()
-	adminDSN := os.Getenv("TEST_ADMIN_DSN")
-	if adminDSN == "" {
-		t.Skip("TEST_ADMIN_DSN nicht gesetzt, Integrationstest uebersprungen")
-	}
-	ctx := context.Background()
-
-	pool, err := pgxpool.New(ctx, adminDSN)
-	if err != nil {
-		t.Fatalf("pool: %v", err)
-	}
-	if _, err := pool.Exec(ctx, `
-		CREATE TABLE IF NOT EXISTS rate_limit_configs (
-			key TEXT PRIMARY KEY, limit_value INT NOT NULL, window_seconds INT NOT NULL
-		);
-		CREATE TABLE IF NOT EXISTS rate_limit_counters (
-			key TEXT NOT NULL, window_start TIMESTAMPTZ NOT NULL, count INT NOT NULL DEFAULT 0,
-			PRIMARY KEY (key, window_start)
-		);
-	`); err != nil {
-		t.Fatalf("schema: %v", err)
-	}
-
-	cleanup := func() { pool.Close() }
-	return pool, cleanup
-}
-
-func newTestKey() string {
-	return fmt.Sprintf("test-key-%d", time.Now().UnixNano())
-}
-
-// Akzeptanzkriterium 3 + Pruefung 2: Ueberschreitung des Limits wird
-// nachweislich erkannt.
-func TestAllow_RejectsAfterLimitExceeded(t *testing.T) {
-	pool, cleanup := setupTest(t)
-	defer cleanup()
-	store := NewStore(pool)
-	ctx := context.Background()
-	key := newTestKey()
-
-	if err := store.SetLimit(ctx, key, 3, time.Minute); err != nil {
-		t.Fatalf("setlimit: %v", err)
-	}
-
-	for i := 0; i < 3; i++ {
-		res, err := store.Allow(ctx, key)
-		if err != nil {
-			t.Fatalf("allow %d: %v", i, err)
-		}
-		if !res.Allowed {
-			t.Fatalf("anfrage %d haette erlaubt sein muessen, limit=3", i)
-		}
-	}
-
-	res, err := store.Allow(ctx, key)
-	if err != nil {
-		t.Fatalf("allow (4.): %v", err)
-	}
-	if res.Allowed {
-		t.Fatal("4. anfrage haette abgelehnt werden muessen (limit=3)")
-	}
-	if res.RetryAfter <= 0 {
-		t.Fatalf("erwartet positive retry-after-dauer, habe %v", res.RetryAfter)
-	}
-}
-
-// Akzeptanzkriterium 1 / Pruefung 3: Konfigurationsaenderung wirkt sich
-// NICHT auf andere Schluessel (Tenants) aus.
-func TestSetLimit_DoesNotAffectOtherKeys(t *testing.T) {
-	pool, cleanup := setupTest(t)
-	defer cleanup()
-	store := NewStore(pool)
-	ctx := context.Background()
-	keyA := newTestKey()
-	keyB := newTestKey()
-
-	if err := store.SetLimit(ctx, keyA, 1, time.Minute); err != nil {
-		t.Fatalf("setlimit a: %v", err)
-	}
-
-	resA1, _ := store.Allow(ctx, keyA)
-	resA2, _ := store.Allow(ctx, keyA)
-	if !resA1.Allowed || resA2.Allowed {
-		t.Fatalf("key a: erwartet erlaubt,abgelehnt, habe %v,%v", resA1.Allowed, resA2.Allowed)
-	}
-
-	// keyB hat keine eigene Konfiguration -> DefaultLimit, unbeeinflusst von keyA.
-	resB, err := store.Allow(ctx, keyB)
-	if err != nil {
-		t.Fatalf("allow b: %v", err)
-	}
-	if !resB.Allowed {
-		t.Fatal("key b haette trotz limit-ueberschreitung bei key a erlaubt sein muessen")
-	}
-	if resB.Limit != DefaultLimit {
-		t.Fatalf("key b limit = %d, want default %d", resB.Limit, DefaultLimit)
-	}
-}
-
-// Akzeptanzkriterium 2 + Pruefung 1: zwei "Dienstinstanzen" (zwei
-// unabhaengige Pools/Store-Objekte) gegen dieselbe Datenbank setzen
-// dasselbe Limit korrekt durch — kein In-Process-Zustand kann das leisten.
-func TestAllow_TwoInstancesShareStateCorrectly(t *testing.T) {
-	adminDSN := os.Getenv("TEST_ADMIN_DSN")
-	if adminDSN == "" {
-		t.Skip("TEST_ADMIN_DSN nicht gesetzt, Integrationstest uebersprungen")
-	}
-	pool, cleanup := setupTest(t)
-	defer cleanup()
-
-	ctx := context.Background()
-	pool2, err := pgxpool.New(ctx, adminDSN)
-	if err != nil {
-		t.Fatalf("zweiter pool (simuliert zweite instanz): %v", err)
-	}
-	defer pool2.Close()
-
-	storeInstance1 := NewStore(pool)
-	storeInstance2 := NewStore(pool2)
-
-	key := newTestKey()
-	const limit = 20
-	if err := storeInstance1.SetLimit(ctx, key, limit, time.Minute); err != nil {
-		t.Fatalf("setlimit: %v", err)
-	}
-
-	const totalRequests = 50
-	var allowedCount int64
-	var wg sync.WaitGroup
-	for i := 0; i < totalRequests; i++ {
-		wg.Add(1)
-		store := storeInstance1
-		if i%2 == 0 {
-			store = storeInstance2 // Haelfte der Anfragen "kommt" von der zweiten Instanz
-		}
-		go func(s *Store) {
-			defer wg.Done()
-			res, err := s.Allow(ctx, key)
-			if err != nil {
-				t.Errorf("allow: %v", err)
-				return
-			}
-			if res.Allowed {
-				atomic.AddInt64(&allowedCount, 1)
-			}
-		}(store)
-	}
-	wg.Wait()
-
-	if allowedCount != limit {
-		t.Fatalf("erlaubte anfragen ueber beide instanzen = %d, want exakt %d (geteilter zustand)", allowedCount, limit)
-	}
-}

internal/tenant/router.go

@@ -1,136 +0,0 @@
-package tenant
-
-import (
-	"container/list"
-	"context"
-	"errors"
-	"fmt"
-	"sync"
-
-	"github.com/jackc/pgx/v5/pgxpool"
-)
-
-// ErrMissingTenantContext wird geliefert, wenn keine Tenant-Kennung
-// uebergeben wurde — es gibt bewusst keinen impliziten Default-Tenant
-// (TEN-06 Akzeptanzkriterium 3).
-var ErrMissingTenantContext = errors.New("tenant: kein tenant-kontext angegeben")
-
-// ErrUnknownTenant wird geliefert, wenn die Tenant-Kennung in der Registry
-// nicht existiert.
-var ErrUnknownTenant = errors.New("tenant: unbekannter tenant")
-
-// Router loest den Tenant-Kontext (Slug, aus dem JWT-Claim von API-05) in
-// eine wiederverwendbare Verbindung zur richtigen Tenant-Datenbank auf.
-// Ein LRU-verwalteter Cache begrenzt die Zahl gleichzeitig offener
-// pgxpool.Pool-Instanzen, damit die Zahl offener Postgres-Verbindungen NICHT
-// linear mit der Mandantenzahl waechst (Akzeptanzkriterium 2).
-type Router struct {
-	registry *Registry
-	maxOpen  int
-
-	mu    sync.Mutex
-	order *list.List               // vorne = zuletzt benutzt
-	items map[string]*list.Element // slug -> element mit *routerEntry
-}
-
-type routerEntry struct {
-	slug string
-	pool *pgxpool.Pool
-}
-
-func NewRouter(registry *Registry, maxOpen int) *Router {
-	if maxOpen < 1 {
-		maxOpen = 1
-	}
-	return &Router{
-		registry: registry,
-		maxOpen:  maxOpen,
-		order:    list.New(),
-		items:    make(map[string]*list.Element),
-	}
-}
-
-// Resolve liefert einen wiederverwendeten Pool fuer den angegebenen Tenant.
-// Ist der Tenant bereits im Cache, wird KEINE neue Verbindung aufgebaut
-// (Akzeptanzkriterium 2 / Pruefung 3).
-func (r *Router) Resolve(ctx context.Context, tenantSlug string) (*pgxpool.Pool, error) {
-	if tenantSlug == "" {
-		return nil, ErrMissingTenantContext
-	}
-
-	r.mu.Lock()
-	if el, ok := r.items[tenantSlug]; ok {
-		r.order.MoveToFront(el)
-		pool := el.Value.(*routerEntry).pool
-		r.mu.Unlock()
-		return pool, nil
-	}
-	r.mu.Unlock()
-
-	// Registry-Lookup und Verbindungsaufbau bewusst ausserhalb des Locks,
-	// damit ein langsamer Verbindungsaufbau nicht alle anderen Tenants blockiert.
-	t, err := r.registry.GetBySlug(ctx, tenantSlug)
-	if err != nil {
-		return nil, fmt.Errorf("%w: %s", ErrUnknownTenant, tenantSlug)
-	}
-
-	pool, err := pgxpool.New(ctx, t.DBDSN)
-	if err != nil {
-		return nil, fmt.Errorf("verbindung zu tenant %q aufbauen: %w", tenantSlug, err)
-	}
-
-	r.mu.Lock()
-	defer r.mu.Unlock()
-
-	// Zwischen Unlock oben und hier koennte ein paralleler Aufruf denselben
-	// Tenant bereits eingefuegt haben — dann die eigene, ueberzaehlige
-	// Verbindung wieder schliessen und die vorhandene verwenden.
-	if el, ok := r.items[tenantSlug]; ok {
-		r.order.MoveToFront(el)
-		existing := el.Value.(*routerEntry).pool
-		pool.Close()
-		return existing, nil
-	}
-
-	el := r.order.PushFront(&routerEntry{slug: tenantSlug, pool: pool})
-	r.items[tenantSlug] = el
-
-	if r.order.Len() > r.maxOpen {
-		r.evictOldest()
-	}
-
-	return pool, nil
-}
-
-// evictOldest schliesst den am laengsten nicht genutzten Pool. Muss mit
-// gehaltenem r.mu aufgerufen werden.
-func (r *Router) evictOldest() {
-	oldest := r.order.Back()
-	if oldest == nil {
-		return
-	}
-	entry := oldest.Value.(*routerEntry)
-	r.order.Remove(oldest)
-	delete(r.items, entry.slug)
-	entry.pool.Close()
-}
-
-// OpenCount liefert die aktuelle Zahl offen gehaltener Tenant-Pools —
-// dient Tests/Monitoring, um AC2 nachzuweisen.
-func (r *Router) OpenCount() int {
-	r.mu.Lock()
-	defer r.mu.Unlock()
-	return r.order.Len()
-}
-
-// Close schliesst alle offen gehaltenen Tenant-Pools, z.B. beim
-// Herunterfahren des Core-Prozesses.
-func (r *Router) Close() {
-	r.mu.Lock()
-	defer r.mu.Unlock()
-	for el := r.order.Front(); el != nil; el = el.Next() {
-		el.Value.(*routerEntry).pool.Close()
-	}
-	r.order.Init()
-	r.items = make(map[string]*list.Element)
-}

internal/tenant/router_test.go

@@ -1,160 +0,0 @@
-package tenant
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"os"
-	"strings"
-	"testing"
-
-	"github.com/jackc/pgx/v5/pgxpool"
-)
-
-func newTestRouterSetup(t *testing.T, tenantCount int) (*Router, []Tenant, 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()
-		)`); err != nil {
-		t.Fatalf("registry-schema: %v", err)
-	}
-
-	registry := NewRegistry(registryPool)
-	dsnTemplate := strings.Replace(adminDSN, "/postgres?", "/%s?", 1)
-	provisioner := NewProvisioner(adminPool, registry, dsnTemplate)
-
-	var tenants []Tenant
-	var slugs []string
-	for i := 0; i < tenantCount; i++ {
-		slug := fmt.Sprintf("router_t%d", i)
-		slugs = append(slugs, slug)
-		tn, err := provisioner.Provision(ctx, slug, slug)
-		if err != nil {
-			t.Fatalf("provision %s: %v", slug, err)
-		}
-		tenants = append(tenants, tn)
-	}
-
-	router := NewRouter(registry, 2) // klein gewaehlt, um Eviction im Test zu erzwingen
-
-	cleanup := func() {
-		router.Close()
-		for _, slug := range slugs {
-			_, _ = adminPool.Exec(ctx, fmt.Sprintf(`DROP DATABASE IF EXISTS %q`, dbNameForSlug(slug)))
-		}
-		_, _ = registryPool.Exec(ctx, `DELETE FROM tenants WHERE slug = ANY($1)`, slugs)
-		registryPool.Close()
-		adminPool.Close()
-	}
-	return router, tenants, cleanup
-}
-
-// Akzeptanzkriterium 1: Verbindung wird zuverlaessig anhand des Tenant-Kontexts aufgeloest.
-func TestRouter_ResolvesCorrectTenantDatabase(t *testing.T) {
-	router, tenants, cleanup := newTestRouterSetup(t, 2)
-	defer cleanup()
-	ctx := context.Background()
-
-	pool, err := router.Resolve(ctx, tenants[0].Slug)
-	if err != nil {
-		t.Fatalf("resolve: %v", err)
-	}
-	var dbName string
-	if err := pool.QueryRow(ctx, `SELECT current_database()`).Scan(&dbName); err != nil {
-		t.Fatalf("current_database: %v", err)
-	}
-	if dbName != tenants[0].DBName {
-		t.Fatalf("current_database() = %q, want %q", dbName, tenants[0].DBName)
-	}
-}
-
-// Akzeptanzkriterium 3 + Pruefung 2: fehlender/unbekannter Tenant-Kontext
-// wird explizit abgewiesen statt irgendeine Verbindung zu liefern.
-func TestRouter_RejectsMissingOrUnknownTenant(t *testing.T) {
-	router, _, cleanup := newTestRouterSetup(t, 1)
-	defer cleanup()
-	ctx := context.Background()
-
-	if _, err := router.Resolve(ctx, ""); !errors.Is(err, ErrMissingTenantContext) {
-		t.Fatalf("erwartet ErrMissingTenantContext, habe %v", err)
-	}
-	if _, err := router.Resolve(ctx, "nie-registrierter-slug"); !errors.Is(err, ErrUnknownTenant) {
-		t.Fatalf("erwartet ErrUnknownTenant, habe %v", err)
-	}
-}
-
-// Akzeptanzkriterium 2 + Pruefung 3: Verbindungswiederverwendung nachweislich
-// gemessen — zweiter Resolve-Aufruf liefert exakt denselben Pool, kein
-// erneuter Verbindungsaufbau.
-func TestRouter_ReusesConnectionForSameTenant(t *testing.T) {
-	router, tenants, cleanup := newTestRouterSetup(t, 1)
-	defer cleanup()
-	ctx := context.Background()
-
-	first, err := router.Resolve(ctx, tenants[0].Slug)
-	if err != nil {
-		t.Fatalf("resolve 1: %v", err)
-	}
-	second, err := router.Resolve(ctx, tenants[0].Slug)
-	if err != nil {
-		t.Fatalf("resolve 2: %v", err)
-	}
-	if first != second {
-		t.Fatal("erwartet identische pool-instanz bei wiederholtem resolve, habe unterschiedliche")
-	}
-}
-
-// Akzeptanzkriterium 2 + Pruefung 1: Lasttest mit mehr simulierten Mandanten
-// als maxOpen — die Zahl gleichzeitig offener Tenant-Pools bleibt begrenzt
-// (LRU-Eviction), waechst also NICHT linear mit der Mandantenzahl.
-func TestRouter_BoundsOpenConnectionsUnderLoad(t *testing.T) {
-	const tenantCount = 6
-	router, tenants, cleanup := newTestRouterSetup(t, tenantCount)
-	defer cleanup()
-	ctx := context.Background()
-
-	for _, tn := range tenants {
-		if _, err := router.Resolve(ctx, tn.Slug); err != nil {
-			t.Fatalf("resolve %s: %v", tn.Slug, err)
-		}
-		if router.OpenCount() > 2 {
-			t.Fatalf("OpenCount() = %d, erwartet <= maxOpen (2) nach jedem Resolve", router.OpenCount())
-		}
-	}
-
-	if router.OpenCount() != 2 {
-		t.Fatalf("erwartet genau maxOpen=2 offene pools nach %d tenants, habe %d", tenantCount, router.OpenCount())
-	}
-
-	// Evictete Tenants sind wieder ganz normal ueber die Registry aufloesbar
-	// (Cache-Miss fuehrt zu neuem, funktionierendem Pool, kein Fehlerzustand).
-	pool, err := router.Resolve(ctx, tenants[0].Slug)
-	if err != nil {
-		t.Fatalf("resolve nach eviction: %v", err)
-	}
-	var one int
-	if err := pool.QueryRow(ctx, `SELECT 1`).Scan(&one); err != nil {
-		t.Fatalf("query nach re-resolve: %v", err)
-	}
-}

internal/webhook/dispatcher.go

@@ -0,0 +1,177 @@
+package webhook
+
+import (
+	"bytes"
+	"context"
+	"crypto/subtle"
+	"encoding/hex"
+	"fmt"
+	"net/http"
+	"time"
+
+	"github.com/jackc/pgx/v5"
+)
+
+// DefaultMaxAttempts ist die konfigurierbare Obergrenze, ab der eine
+// Zustellung endgueltig als fehlgeschlagen gilt (Akzeptanzkriterium 2).
+const DefaultMaxAttempts = 5
+
+// DefaultBaseBackoff ist die Basisdauer fuer exponentielles Backoff:
+// naechster Versuch nach BaseBackoff * 2^attempt (Akzeptanzkriterium 2).
+const DefaultBaseBackoff = 2 * time.Second
+
+// Dispatcher liefert faellige Zustellungen aus. Konfigurierbar in Tests
+// (kleine BaseBackoff, kleine MaxAttempts), damit Retry/Backoff/Obergrenze
+// ohne minutenlange Wartezeit real durchlaufen werden koennen.
+type Dispatcher struct {
+	pool        pgxIface
+	client      *http.Client
+	MaxAttempts int
+	BaseBackoff time.Duration
+}
+
+// pgxIface ist die schmale Teilmenge von *pgxpool.Pool, die der Dispatcher
+// braucht — als Interface, damit Tests keine echte Verbindung fuer reine
+// Signatur-/Backoff-Logik brauchen (wird hier aber durchgehend mit echten
+// Integrationstests gegen Postgres verwendet, siehe dispatcher_test.go).
+type pgxIface interface {
+	Begin(ctx context.Context) (pgx.Tx, error)
+}
+
+func NewDispatcher(pool pgxIface, client *http.Client) *Dispatcher {
+	if client == nil {
+		client = &http.Client{Timeout: 5 * time.Second}
+	}
+	return &Dispatcher{pool: pool, client: client, MaxAttempts: DefaultMaxAttempts, BaseBackoff: DefaultBaseBackoff}
+}
+
+// backoffFor berechnet die Wartezeit vor dem naechsten Versuch: exponentiell
+// wachsend mit der Anzahl bereits unternommener Versuche.
+func (d *Dispatcher) backoffFor(attempt int) time.Duration {
+	return d.BaseBackoff * time.Duration(1<<uint(attempt))
+}
+
+// ProcessDue liefert ALLE derzeit faelligen Zustellungen aus — dasselbe
+// SELECT ... FOR UPDATE SKIP LOCKED-Muster wie
+// internal/tenant.Lifecycle.ProcessDueDeletions, damit mehrere Dispatcher-
+// Instanzen dieselbe Zustellung nie doppelt bearbeiten.
+func (d *Dispatcher) ProcessDue(ctx context.Context) (int, error) {
+	tx, err := d.pool.Begin(ctx)
+	if err != nil {
+		return 0, fmt.Errorf("transaktion starten: %w", err)
+	}
+	defer func() { _ = tx.Rollback(ctx) }()
+
+	rows, err := tx.Query(ctx, `
+		SELECT wd.id, wd.payload, wd.attempt, ws.target_url, ws.secret
+		FROM webhook_deliveries wd
+		JOIN webhook_subscriptions ws ON ws.id = wd.subscription_id
+		WHERE wd.status = $1 AND wd.next_attempt_at <= now()
+		FOR UPDATE OF wd SKIP LOCKED
+	`, StatusPending)
+	if err != nil {
+		return 0, fmt.Errorf("faellige zustellungen abfragen: %w", err)
+	}
+
+	var deliveries []delivery
+	for rows.Next() {
+		var del delivery
+		if err := rows.Scan(&del.ID, &del.Payload, &del.Attempt, &del.TargetURL, &del.Secret); err != nil {
+			rows.Close()
+			return 0, fmt.Errorf("zustellung lesen: %w", err)
+		}
+		deliveries = append(deliveries, del)
+	}
+	rows.Close()
+	if err := rows.Err(); err != nil {
+		return 0, err
+	}
+
+	for _, del := range deliveries {
+		d.attemptOne(ctx, tx, del)
+	}
+
+	if err := tx.Commit(ctx); err != nil {
+		return 0, fmt.Errorf("transaktion committen: %w", err)
+	}
+	return len(deliveries), nil
+}
+
+// attemptOne fuehrt GENAU EINEN Zustellversuch aus und aktualisiert den
+// Zustellungsdatensatz entsprechend — Erfolg (Akzeptanzkriterium 1/Pruefung
+// 1), erneuter Fehlversuch mit Backoff, oder endgueltiges Scheitern nach
+// DefaultMaxAttempts (Akzeptanzkriterium 2/Pruefung 2). Ein Fehler bei
+// GENAU EINER Zustellung darf die anderen in diesem Batch nicht verhindern.
+func (d *Dispatcher) attemptOne(ctx context.Context, tx pgx.Tx, del delivery) {
+	signature := Sign(del.Secret, del.Payload)
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, del.TargetURL, bytes.NewReader(del.Payload))
+	deliveryErr := err
+	var statusCode int
+	if err == nil {
+		req.Header.Set("Content-Type", "application/json")
+		req.Header.Set(SignatureHeader, signature)
+		resp, err := d.client.Do(req)
+		if err != nil {
+			deliveryErr = err
+		} else {
+			statusCode = resp.StatusCode
+			resp.Body.Close()
+			if statusCode < 200 || statusCode >= 300 {
+				deliveryErr = fmt.Errorf("unerwarteter statuscode %d", statusCode)
+			}
+		}
+	}
+
+	if deliveryErr == nil {
+		_, _ = tx.Exec(ctx, `
+			UPDATE webhook_deliveries SET status = $2, delivered_at = now(), attempt = attempt + 1
+			WHERE id = $1
+		`, del.ID, StatusDelivered)
+		return
+	}
+
+	nextAttempt := del.Attempt + 1
+	if nextAttempt >= d.MaxAttempts {
+		_, _ = tx.Exec(ctx, `
+			UPDATE webhook_deliveries SET status = $2, attempt = $3, last_error = $4
+			WHERE id = $1
+		`, del.ID, StatusFailed, nextAttempt, deliveryErr.Error())
+		return
+	}
+
+	nextAttemptAt := time.Now().Add(d.backoffFor(nextAttempt))
+	_, _ = tx.Exec(ctx, `
+		UPDATE webhook_deliveries SET attempt = $2, next_attempt_at = $3, last_error = $4
+		WHERE id = $1
+	`, del.ID, nextAttempt, nextAttemptAt, deliveryErr.Error())
+}
+
+// Run ruft ProcessDue in festen Abstaenden auf, bis ctx beendet wird —
+// dieselbe Konvention wie internal/tenant.Lifecycle.RunSweeper.
+func (d *Dispatcher) Run(ctx context.Context, interval time.Duration) {
+	ticker := time.NewTicker(interval)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+			_, _ = d.ProcessDue(ctx)
+		}
+	}
+}
+
+// VerifySignature prueft empfaengerseitig, ob signature zu payload und
+// secret passt — timing-safe (dasselbe Muster wie internal/audit.timingsafe),
+// damit ein Empfaenger die Authentizitaet einer Zustellung pruefen kann
+// (Akzeptanzkriterium 3).
+func VerifySignature(secret string, payload []byte, signature string) bool {
+	expected := Sign(secret, payload)
+	expectedBytes, err1 := hex.DecodeString(expected)
+	gotBytes, err2 := hex.DecodeString(signature)
+	if err1 != nil || err2 != nil {
+		return false
+	}
+	return subtle.ConstantTimeCompare(expectedBytes, gotBytes) == 1
+}

internal/webhook/webhook.go

@@ -0,0 +1,131 @@
+// Package webhook implementiert Core API-07: eine zentrale Webhook-Registry
+// und Zustellungs-Engine fuer alle Fachmodule (DMS/Mail/Archive/Workflow/AI).
+// Module reichen Ereignisse EINMAL zur Zustellung ein und implementieren
+// selbst KEINE eigene Retry-/Signatur-Logik — das ist der zentrale Zweck
+// dieser Kachel ("Bewusst vermeiden: jedes Modul baut seine eigene
+// Webhook-Zustellungs-Engine"). Zustellung laeuft ueber dieselbe
+// Postgres-Jobqueue-Konvention (SELECT ... FOR UPDATE SKIP LOCKED) wie
+// internal/tenant.Lifecycle.ProcessDueDeletions (TEN-04) und
+// internal/notify.Dispatcher (CFG-02) — kein Redis/AMQP.
+package webhook
+
+import (
+	"context"
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+const (
+	StatusPending   = "pending"
+	StatusDelivered = "delivered"
+	StatusFailed    = "failed"
+)
+
+// Subscription ist EIN externer Abonnent fuer einen Ereignistyp
+// (Akzeptanzkriterium 1: Module registrieren Ereignistypen, externe
+// Abonnenten registrieren Ziel-URLs — dieses Paket modelliert die
+// Abonnenten-Seite; welche Ereignistypen ein Modul anbietet, ist bewusst
+// NICHT Teil dieser Kachel).
+type Subscription struct {
+	ID         string
+	EventType  string
+	TargetURL  string
+	Secret     string
+	CreatedAt  time.Time
+}
+
+// Store persistiert Abonnements und Zustellversuche.
+type Store struct {
+	pool *pgxpool.Pool
+}
+
+func NewStore(pool *pgxpool.Pool) *Store {
+	return &Store{pool: pool}
+}
+
+// Subscribe registriert einen Abonnenten fuer einen Ereignistyp. secret wird
+// spaeter zur HMAC-Signierung jeder Zustellung an diesen Abonnenten
+// verwendet (Akzeptanzkriterium 3).
+func (s *Store) Subscribe(ctx context.Context, eventType, targetURL, secret string) (Subscription, error) {
+	var sub Subscription
+	sub.EventType, sub.TargetURL, sub.Secret = eventType, targetURL, secret
+	row := s.pool.QueryRow(ctx, `
+		INSERT INTO webhook_subscriptions (event_type, target_url, secret)
+		VALUES ($1, $2, $3)
+		RETURNING id, created_at
+	`, eventType, targetURL, secret)
+	if err := row.Scan(&sub.ID, &sub.CreatedAt); err != nil {
+		return Subscription{}, fmt.Errorf("abonnement anlegen: %w", err)
+	}
+	return sub, nil
+}
+
+// Enqueue reicht EIN Ereignis zur Zustellung an ALLE Abonnenten des
+// angegebenen Ereignistyps ein — dies ist die EINZIGE Schnittstelle, die
+// ein Fachmodul braucht (Akzeptanzkriterium 1). Jeder Abonnent erhaelt
+// einen eigenen, unabhaengigen Zustellversuch-Datensatz.
+func (s *Store) Enqueue(ctx context.Context, eventType string, payload any) (int, error) {
+	payloadJSON, err := json.Marshal(payload)
+	if err != nil {
+		return 0, fmt.Errorf("payload serialisieren: %w", err)
+	}
+
+	rows, err := s.pool.Query(ctx, `
+		SELECT id FROM webhook_subscriptions WHERE event_type = $1
+	`, eventType)
+	if err != nil {
+		return 0, fmt.Errorf("abonnenten ermitteln: %w", err)
+	}
+	var subscriptionIDs []string
+	for rows.Next() {
+		var id string
+		if err := rows.Scan(&id); err != nil {
+			rows.Close()
+			return 0, fmt.Errorf("abonnent lesen: %w", err)
+		}
+		subscriptionIDs = append(subscriptionIDs, id)
+	}
+	rows.Close()
+	if err := rows.Err(); err != nil {
+		return 0, err
+	}
+
+	for _, subID := range subscriptionIDs {
+		if _, err := s.pool.Exec(ctx, `
+			INSERT INTO webhook_deliveries (subscription_id, event_type, payload, status, next_attempt_at)
+			VALUES ($1, $2, $3, $4, now())
+		`, subID, eventType, payloadJSON, StatusPending); err != nil {
+			return 0, fmt.Errorf("zustellung einreihen: %w", err)
+		}
+	}
+	return len(subscriptionIDs), nil
+}
+
+// delivery ist ein interner Datensatz fuer EINEN Zustellversuch, inklusive
+// der zugehoerigen Abonnentendaten (per JOIN geladen).
+type delivery struct {
+	ID        string
+	TargetURL string
+	Secret    string
+	Payload   []byte
+	Attempt   int
+}
+
+// Sign berechnet die HMAC-SHA256-Signatur des Payloads (Akzeptanzkriterium
+// 3) — hex-kodiert, damit sie problemlos als HTTP-Header uebertragen werden
+// kann.
+func Sign(secret string, payload []byte) string {
+	mac := hmac.New(sha256.New, []byte(secret))
+	mac.Write(payload)
+	return hex.EncodeToString(mac.Sum(nil))
+}
+
+// SignatureHeader ist der HTTP-Header, unter dem die Signatur uebertragen
+// wird — dokumentierter Vertrag fuer Empfaenger (Akzeptanzkriterium 3).
+const SignatureHeader = "X-Nexarch-Signature-256"

internal/webhook/webhook_test.go

@@ -0,0 +1,205 @@
+package webhook
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+func setupTest(t *testing.T) (*Store, *pgxpool.Pool, func()) {
+	t.Helper()
+	adminDSN := os.Getenv("TEST_ADMIN_DSN")
+	if adminDSN == "" {
+		t.Skip("TEST_ADMIN_DSN nicht gesetzt, Integrationstest uebersprungen")
+	}
+	ctx := context.Background()
+
+	pool, err := pgxpool.New(ctx, adminDSN)
+	if err != nil {
+		t.Fatalf("pool: %v", err)
+	}
+	if _, err := pool.Exec(ctx, `
+		CREATE TABLE IF NOT EXISTS webhook_subscriptions (
+			id UUID PRIMARY KEY DEFAULT gen_random_uuid(), event_type TEXT NOT NULL,
+			target_url TEXT NOT NULL, secret TEXT NOT NULL, created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+		);
+		CREATE TABLE IF NOT EXISTS webhook_deliveries (
+			id UUID PRIMARY KEY DEFAULT gen_random_uuid(), subscription_id UUID NOT NULL REFERENCES webhook_subscriptions(id),
+			event_type TEXT NOT NULL, payload JSONB NOT NULL, status TEXT NOT NULL DEFAULT 'pending',
+			attempt INT NOT NULL DEFAULT 0, next_attempt_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+			last_error TEXT, created_at TIMESTAMPTZ NOT NULL DEFAULT now(), delivered_at TIMESTAMPTZ
+		);
+	`); err != nil {
+		t.Fatalf("schema: %v", err)
+	}
+
+	cleanup := func() { pool.Close() }
+	return NewStore(pool), pool, cleanup
+}
+
+func uniqueEventType(prefix string) string {
+	return prefix + "-" + time.Now().Format("150405.000000000")
+}
+
+// Akzeptanzkriterium 1 + Pruefung 1: ein Modul reicht ein Ereignis ein
+// (Enqueue) ohne eigene Zustellungslogik, der zentrale Dispatcher liefert
+// zuverlaessig aus.
+func TestEnqueueAndProcessDue_DeliversSuccessfully(t *testing.T) {
+	store, pool, cleanup := setupTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	var receivedBody []byte
+	var receivedSignature string
+	target := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		body, _ := io.ReadAll(r.Body)
+		receivedBody = body
+		receivedSignature = r.Header.Get(SignatureHeader)
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer target.Close()
+
+	eventType := uniqueEventType("dms.file.created")
+	sub, err := store.Subscribe(ctx, eventType, target.URL, "geheimes-secret")
+	if err != nil {
+		t.Fatalf("subscribe: %v", err)
+	}
+
+	n, err := store.Enqueue(ctx, eventType, map[string]string{"file_id": "42"})
+	if err != nil {
+		t.Fatalf("enqueue: %v", err)
+	}
+	if n != 1 {
+		t.Fatalf("erwartet 1 eingereihte zustellung, habe %d", n)
+	}
+
+	dispatcher := NewDispatcher(pool, target.Client())
+	processed, err := dispatcher.ProcessDue(ctx)
+	if err != nil {
+		t.Fatalf("processdue: %v", err)
+	}
+	if processed != 1 {
+		t.Fatalf("erwartet 1 verarbeitete zustellung, habe %d", processed)
+	}
+
+	var status string
+	if err := pool.QueryRow(ctx, `SELECT status FROM webhook_deliveries WHERE subscription_id = $1`, sub.ID).Scan(&status); err != nil {
+		t.Fatalf("status lesen: %v", err)
+	}
+	if status != StatusDelivered {
+		t.Fatalf("status = %q, want %q", status, StatusDelivered)
+	}
+
+	// Postgres' JSONB-Spalte kann die Byte-Repraesentation des Payloads
+	// gegenueber dem urspruenglichen json.Marshal kanonisieren (z.B.
+	// Leerzeichen) — das ist unschaedlich, denn der Dispatcher signiert
+	// IMMER exakt die Bytes, die er auch sendet. Die Pruefung vergleicht
+	// deshalb Signatur gegen tatsaechlich empfangene Bytes (Selbstkonsistenz),
+	// nicht gegen eine unabhaengig neu marshalte Referenz.
+	if !VerifySignature("geheimes-secret", receivedBody, receivedSignature) {
+		t.Fatalf("empfangene signatur %q passt nicht zum empfangenen payload %q", receivedSignature, receivedBody)
+	}
+	var decoded map[string]string
+	if err := json.Unmarshal(receivedBody, &decoded); err != nil {
+		t.Fatalf("empfangener payload nicht als json lesbar: %v", err)
+	}
+	if decoded["file_id"] != "42" {
+		t.Fatalf("empfangener payload = %v, want file_id=42", decoded)
+	}
+}
+
+// Akzeptanzkriterium 2 + Pruefung 2: fehlschlagendes Ziel loest Retry mit
+// wachsendem Backoff aus und endet nach der konfigurierten Obergrenze in
+// "failed".
+func TestProcessDue_RetriesWithBackoffThenMarksFailed(t *testing.T) {
+	store, pool, cleanup := setupTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	var callCount int32
+	target := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		atomic.AddInt32(&callCount, 1)
+		w.WriteHeader(http.StatusInternalServerError)
+	}))
+	defer target.Close()
+
+	eventType := uniqueEventType("mail.send.failed")
+	sub, err := store.Subscribe(ctx, eventType, target.URL, "secret")
+	if err != nil {
+		t.Fatalf("subscribe: %v", err)
+	}
+	if _, err := store.Enqueue(ctx, eventType, map[string]string{"x": "y"}); err != nil {
+		t.Fatalf("enqueue: %v", err)
+	}
+
+	dispatcher := NewDispatcher(pool, target.Client())
+	dispatcher.MaxAttempts = 2
+	dispatcher.BaseBackoff = 30 * time.Millisecond
+
+	// 1. Versuch: schlaegt fehl, ist aber noch nicht die Obergrenze.
+	if _, err := dispatcher.ProcessDue(ctx); err != nil {
+		t.Fatalf("processdue 1: %v", err)
+	}
+	var status string
+	var attempt int
+	if err := pool.QueryRow(ctx, `SELECT status, attempt FROM webhook_deliveries WHERE subscription_id = $1`, sub.ID).Scan(&status, &attempt); err != nil {
+		t.Fatalf("status lesen 1: %v", err)
+	}
+	if status != StatusPending || attempt != 1 {
+		t.Fatalf("nach 1. fehlschlag: status=%q attempt=%d, want pending/1", status, attempt)
+	}
+
+	// Sofort erneut verarbeiten: Backoff ist noch nicht abgelaufen -> nichts faellig.
+	processedTooEarly, err := dispatcher.ProcessDue(ctx)
+	if err != nil {
+		t.Fatalf("processdue (zu frueh): %v", err)
+	}
+	if processedTooEarly != 0 {
+		t.Fatal("erwartet 0 verarbeitete zustellungen, solange backoff nicht abgelaufen ist")
+	}
+
+	time.Sleep(dispatcher.backoffFor(1) + 20*time.Millisecond)
+
+	// 2. Versuch: erreicht MaxAttempts=2 -> endgueltig fehlgeschlagen.
+	if _, err := dispatcher.ProcessDue(ctx); err != nil {
+		t.Fatalf("processdue 2: %v", err)
+	}
+	if err := pool.QueryRow(ctx, `SELECT status, attempt FROM webhook_deliveries WHERE subscription_id = $1`, sub.ID).Scan(&status, &attempt); err != nil {
+		t.Fatalf("status lesen 2: %v", err)
+	}
+	if status != StatusFailed || attempt != 2 {
+		t.Fatalf("nach 2. fehlschlag: status=%q attempt=%d, want failed/2", status, attempt)
+	}
+	if atomic.LoadInt32(&callCount) != 2 {
+		t.Fatalf("erwartet genau 2 tatsaechliche zustellversuche, habe %d", callCount)
+	}
+}
+
+// Akzeptanzkriterium 3 + Pruefung 3: Signaturpruefung erkennt eine
+// manipulierte Payload zuverlaessig.
+func TestVerifySignature_DetectsTamperedPayload(t *testing.T) {
+	secret := "geteiltes-geheimnis"
+	payload := []byte(`{"file_id":"42"}`)
+	signature := Sign(secret, payload)
+
+	if !VerifySignature(secret, payload, signature) {
+		t.Fatal("erwartet gueltige signatur fuer unveraenderte payload")
+	}
+
+	tampered := []byte(`{"file_id":"99"}`)
+	if VerifySignature(secret, tampered, signature) {
+		t.Fatal("erwartet ungueltige signatur fuer manipulierte payload")
+	}
+
+	if VerifySignature("falsches-secret", payload, signature) {
+		t.Fatal("erwartet ungueltige signatur bei falschem secret")
+	}
+}