Merge branch 'feature/shl-01-ui-shell-design-system-zentral' into feature/aud-04-audit-log-ansicht

# Conflicts:
#	DEVLOG.md

.gitignore

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

DEVLOG.md

@@ -64,6 +64,9 @@ Keine Änderungen ermittelbar.
 ## 2026-08-27 17:28 – 17:29 (1m)
 **Beschreibung:** Claude Code Session
 **Projekt:** code
+## 2026-08-28 21:44 – 21:44 (0m)
+**Beschreibung:** Claude Code Session
+**Projekt:** nexarch
 
 ### Commits
 Keine Commits in dieser Session.
@@ -127,5 +130,32 @@ Keine Commits in dieser Session.
 - internal/config/config.go           | 29 +++++++++++++++++++++++++++++
 - internal/db/db.go                   | 11 +++++++++++
 - migrations/0001_tenant_registry.sql | 10 ++++++++++
+- web/shl/README.md                   | 45 +++++++++++++++++++++++++++++++++++++++++++++
+- web/shl/__tests__/Dialog.test.tsx   | 38 ++++++++++++++++++++++++++++++++++++++
+- web/shl/__tests__/tokens.test.ts    | 39 +++++++++++++++++++++++++++++++++++++++
+- web/shl/components/Dialog.tsx       | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+- web/shl/components/FormElements.tsx | 98 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+- web/shl/components/Shell.tsx        | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+- web/shl/components/Table.tsx        | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+- web/shl/components/Toast.tsx        | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+- web/shl/i18n/i18n.tsx               | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+- web/shl/index.ts                    | 25 +++++++++++++++++++++++++
+- web/shl/package.json                | 23 +++++++++++++++++++++++
+- web/shl/theme/ThemeProvider.tsx     | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+- web/shl/tokens/tokens.ts            | 96 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+- web/shl/tsconfig.json               | 18 ++++++++++++++++++
+
+---
+## 2026-08-28 21:51 – 21:57 (5m)
+**Beschreibung:** Claude Code Session
+**Projekt:** nexarch
+
+### Commits
+- 3c226da SHL-01: fix — vitest jsdom-environment + jest-dom-Setup (3 Dialog-Tests schlugen ohne DOM fehl)
+
+### Geänderte Dateien
+- web/shl/package.json     | 2 ++
+- web/shl/vitest.config.ts | 8 ++++++++
+- web/shl/vitest.setup.ts  | 1 +
 
 ---

cmd/auditlog-devserver/main.go

@@ -0,0 +1,69 @@
+// auditlog-devserver stellt AUD-03s ExportHandler (internal/audit) fuer die
+// Next.js-Audit-Log-Ansicht (AUD-04) bereit. Getrennt von cmd/core aus
+// demselben Grund wie die anderen *-devserver (siehe LIC-04/TEN-05): echte
+// Auth/RBAC ist noch nicht in die zentrale Server-Topologie verdrahtet.
+//
+// Authorize wird hier mit einem geteilten Admin-Token ueber
+// crypto/subtle.ConstantTimeCompare umgesetzt — demselben Timing-safe-Muster
+// wie internal/audit.timingsafe (AUD-02), NICHT ueber eine neue
+// Rollen-/Rechteschicht, da diese Kachel ausdruecklich nur von AUD-03
+// abhaengt und keine Rechteverwaltung duplizieren soll.
+package main
+
+import (
+	"context"
+	"log"
+	"net/http"
+	"os"
+
+	"gitea.perlbach24.de/scripte/nexarch/internal/audit"
+	"gitea.perlbach24.de/scripte/nexarch/internal/auditadmin"
+	"gitea.perlbach24.de/scripte/nexarch/internal/db"
+)
+
+func main() {
+	dsn := os.Getenv("NEXARCH_REGISTRY_DSN")
+	if dsn == "" {
+		log.Fatal("NEXARCH_REGISTRY_DSN nicht gesetzt")
+	}
+	adminToken := os.Getenv("NEXARCH_AUDIT_ADMIN_TOKEN")
+	if adminToken == "" {
+		log.Fatal("NEXARCH_AUDIT_ADMIN_TOKEN nicht gesetzt")
+	}
+	addr := os.Getenv("NEXARCH_AUDITLOG_LISTEN_ADDR")
+	if addr == "" {
+		addr = ":8083"
+	}
+
+	ctx := context.Background()
+	pool, err := db.Connect(ctx, dsn)
+	if err != nil {
+		log.Fatalf("db: %v", err)
+	}
+	defer pool.Close()
+
+	auditLog := audit.NewLog(pool)
+	tokenAuthorize := auditadmin.NewTokenAuthorizer(adminToken)
+	authorize := func(_ context.Context, caller string) bool { return tokenAuthorize(caller) }
+	handler := audit.NewExportHandler(auditLog, authorize)
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/audit/export", withCORS(handler.Export))
+	mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(http.StatusOK) })
+
+	log.Printf("auditlog-devserver listening on %s", addr)
+	log.Fatal(http.ListenAndServe(addr, mux))
+}
+
+func withCORS(next http.HandlerFunc) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Access-Control-Allow-Origin", "*")
+		w.Header().Set("Access-Control-Allow-Methods", "GET, OPTIONS")
+		w.Header().Set("Access-Control-Allow-Headers", "Content-Type")
+		if r.Method == http.MethodOptions {
+			w.WriteHeader(http.StatusOK)
+			return
+		}
+		next(w, r)
+	}
+}

cmd/core/main.go

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

go.mod

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

go.sum

@@ -1,8 +1,6 @@
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/golang-jwt/jwt/v5 v5.3.1 h1:kYf81DTWFe7t+1VvL7eS+jKFVWaUnK9cB1qbwn63YCY=
-github.com/golang-jwt/jwt/v5 v5.3.1/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=
 github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
 github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
 github.com/jackc/pgservicefile v0.0.0-20221227161230-091c0ba34f0a h1:bbPeKD0xmW/Y25WS6cokEszi5g+S0QxI/d45PkRi7Nk=

internal/apiserver/context.go

@@ -1,20 +0,0 @@
-package apiserver
-
-import "context"
-
-type contextKey int
-
-const requestContextKey contextKey = iota
-
-// RequestContext ist der Tenant-/Benutzerkontext, den die Middleware-Kette
-// fuer nachgelagerte Handler bereitstellt (Akzeptanzkriterium 3).
-type RequestContext struct {
-	UserID     string
-	TenantSlug string
-}
-
-// FromContext liest den von der Middleware gesetzten Kontext.
-func FromContext(ctx context.Context) (RequestContext, bool) {
-	rc, ok := ctx.Value(requestContextKey).(RequestContext)
-	return rc, ok
-}

internal/apiserver/errors.go

@@ -1,31 +0,0 @@
-// Package apiserver implementiert Core API-01: das REST-Grundgerüst mit
-// URL-Versionierung, einheitlichem Fehlerformat und Middleware-Kette
-// (Auth, Tenant-/Benutzerkontext, Logging).
-package apiserver
-
-import (
-	"encoding/json"
-	"net/http"
-)
-
-// errorBody ist das EINE Fehlerschema fuer alle Endpunkte unter /api/{version}/
-// (Akzeptanzkriterium 2).
-type errorBody struct {
-	Error struct {
-		Code    string `json:"code"`
-		Message string `json:"message"`
-	} `json:"error"`
-}
-
-// WriteError schreibt einen Fehler im einheitlichen Schema. code ist ein
-// stabiler, maschinenlesbarer Bezeichner (z.B. "unauthenticated"), message
-// ein fuer Menschen lesbarer deutscher Text.
-func WriteError(w http.ResponseWriter, status int, code, message string) {
-	var body errorBody
-	body.Error.Code = code
-	body.Error.Message = message
-
-	w.Header().Set("Content-Type", "application/json")
-	w.WriteHeader(status)
-	_ = json.NewEncoder(w).Encode(body)
-}

internal/apiserver/middleware.go

@@ -1,56 +0,0 @@
-package apiserver
-
-import (
-	"context"
-	"log/slog"
-	"net/http"
-	"time"
-
-	"gitea.perlbach24.de/scripte/nexarch/internal/auth"
-)
-
-// authAndTenantContext prueft die Session (wiederverwendet auth.TokenIssuer.Verify
-// aus IAM-02 — keine zweite JWT-Implementierung) und setzt bei Erfolg
-// RequestContext fuer nachgelagerte Handler (Akzeptanzkriterium 3). Anders
-// als auth.RequireAuth (Klartext-Fehler) antwortet diese Middleware im
-// einheitlichen API-01-Fehlerschema (Akzeptanzkriterium 2), damit ALLE
-// Endpunkte unter /api/{version}/ dasselbe Format liefern, auch bei
-// Auth-Fehlern.
-func authAndTenantContext(issuer *auth.TokenIssuer, next http.HandlerFunc) http.HandlerFunc {
-	return func(w http.ResponseWriter, r *http.Request) {
-		cookie, err := r.Cookie(auth.CookieName)
-		if err != nil {
-			WriteError(w, http.StatusUnauthorized, "unauthenticated", "nicht angemeldet")
-			return
-		}
-
-		claims, err := issuer.Verify(cookie.Value)
-		if err != nil {
-			WriteError(w, http.StatusUnauthorized, "unauthenticated", "nicht angemeldet")
-			return
-		}
-
-		rc := RequestContext{UserID: claims.UserID, TenantSlug: claims.TenantSlug}
-		next(w, r.WithContext(context.WithValue(r.Context(), requestContextKey, rc)))
-	}
-}
-
-type statusRecorder struct {
-	http.ResponseWriter
-	status int
-}
-
-func (s *statusRecorder) WriteHeader(code int) {
-	s.status = code
-	s.ResponseWriter.WriteHeader(code)
-}
-
-// loggingMiddleware protokolliert jede Anfrage strukturiert.
-func loggingMiddleware(next http.HandlerFunc) http.HandlerFunc {
-	return func(w http.ResponseWriter, r *http.Request) {
-		rec := &statusRecorder{ResponseWriter: w, status: http.StatusOK}
-		start := time.Now()
-		next(rec, r)
-		slog.Info("api-anfrage", "method", r.Method, "path", r.URL.Path, "status", rec.status, "dauer", time.Since(start))
-	}
-}

internal/apiserver/server.go

@@ -1,49 +0,0 @@
-package apiserver
-
-import (
-	"net/http"
-
-	"gitea.perlbach24.de/scripte/nexarch/internal/auth"
-)
-
-// Server registriert versionierte API-Routen (Akzeptanzkriterium 1: unter
-// /api/{version}/...) und verdrahtet fuer jede Route dieselbe Middleware-
-// Kette (Logging -> Auth+Tenantkontext -> Handler).
-type Server struct {
-	mux    *http.ServeMux
-	issuer *auth.TokenIssuer
-	routes []string
-}
-
-func NewServer(issuer *auth.TokenIssuer) *Server {
-	return &Server{mux: http.NewServeMux(), issuer: issuer}
-}
-
-// Handle registriert pattern unter der angegebenen Version, z.B.
-// Handle("v1", "/things", h) -> erreichbar unter /api/v1/things. Verschiedene
-// Versionen sind unabhaengige Pfade — eine neue Version beeintraechtigt
-// bestehende nicht (Akzeptanzkriterium 1 / Pruefung 3).
-func (s *Server) Handle(version, pattern string, h http.HandlerFunc) {
-	full := "/api/" + version + pattern
-	s.routes = append(s.routes, full)
-	s.mux.HandleFunc(full, loggingMiddleware(authAndTenantContext(s.issuer, h)))
-}
-
-// RegisteredPaths liefert alle ueber Handle/HandleV1 tatsaechlich
-// registrierten Pfade — die einzige Quelle der Wahrheit fuer den
-// Drift-Abgleich mit dem OpenAPI-Dokument (API-04, siehe internal/openapi).
-// Rein additive Buchfuehrung, keine Verhaltensaenderung von Handle.
-func (s *Server) RegisteredPaths() []string {
-	out := make([]string, len(s.routes))
-	copy(out, s.routes)
-	return out
-}
-
-// HandleV1 ist die Kurzform fuer die aktuelle Hauptversion.
-func (s *Server) HandleV1(pattern string, h http.HandlerFunc) {
-	s.Handle("v1", pattern, h)
-}
-
-func (s *Server) Handler() http.Handler {
-	return s.mux
-}

internal/apiserver/server_test.go

@@ -1,149 +0,0 @@
-package apiserver
-
-import (
-	"encoding/json"
-	"net/http"
-	"net/http/httptest"
-	"testing"
-
-	"gitea.perlbach24.de/scripte/nexarch/internal/auth"
-)
-
-func newTestServer() (*Server, *auth.TokenIssuer) {
-	issuer := auth.NewTokenIssuer("test-secret-nur-fuer-tests")
-	return NewServer(issuer), issuer
-}
-
-func withAuthCookie(req *http.Request, token string) *http.Request {
-	req.AddCookie(&http.Cookie{Name: auth.CookieName, Value: token})
-	return req
-}
-
-// Akzeptanzkriterium 1: API unter versioniertem Pfad erreichbar.
-func TestHandleV1_RegistersUnderVersionedPath(t *testing.T) {
-	srv, issuer := newTestServer()
-	srv.HandleV1("/things", func(w http.ResponseWriter, r *http.Request) {
-		w.WriteHeader(http.StatusOK)
-	})
-
-	token, err := issuer.Issue("user-1", "acme")
-	if err != nil {
-		t.Fatalf("issue: %v", err)
-	}
-
-	req := withAuthCookie(httptest.NewRequest(http.MethodGet, "/api/v1/things", nil), token)
-	rec := httptest.NewRecorder()
-	srv.Handler().ServeHTTP(rec, req)
-	if rec.Code != http.StatusOK {
-		t.Fatalf("status = %d, want 200", rec.Code)
-	}
-}
-
-// Akzeptanzkriterium 2 + Pruefung 1 (Stichprobe): mehrere Endpunkte liefern
-// bei fehlerhafter Anfrage dasselbe Fehlerschema.
-func TestErrorFormat_ConsistentAcrossEndpoints(t *testing.T) {
-	srv, _ := newTestServer()
-	srv.HandleV1("/endpunkt-a", func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(http.StatusOK) })
-	srv.HandleV1("/endpunkt-b", func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(http.StatusOK) })
-
-	for _, path := range []string{"/api/v1/endpunkt-a", "/api/v1/endpunkt-b"} {
-		req := httptest.NewRequest(http.MethodGet, path, nil) // ohne cookie -> 401
-		rec := httptest.NewRecorder()
-		srv.Handler().ServeHTTP(rec, req)
-
-		if rec.Code != http.StatusUnauthorized {
-			t.Fatalf("%s: status = %d, want 401", path, rec.Code)
-		}
-		var body errorBody
-		if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
-			t.Fatalf("%s: fehlerantwort nicht im erwarteten json-schema: %v (body: %s)", path, err, rec.Body.String())
-		}
-		if body.Error.Code == "" || body.Error.Message == "" {
-			t.Fatalf("%s: erwartet nicht-leeren code/message, habe %+v", path, body)
-		}
-	}
-}
-
-// Akzeptanzkriterium 3 + Pruefung 2: Middleware-Kette setzt Tenant-/
-// Benutzerkontext zuverlaessig, nachweislich fuer mehrere Endpunkte.
-func TestMiddleware_SetsRequestContextForEveryEndpoint(t *testing.T) {
-	srv, issuer := newTestServer()
-
-	var gotA, gotB RequestContext
-	srv.HandleV1("/kontext-a", func(w http.ResponseWriter, r *http.Request) {
-		gotA, _ = FromContext(r.Context())
-		w.WriteHeader(http.StatusOK)
-	})
-	srv.HandleV1("/kontext-b", func(w http.ResponseWriter, r *http.Request) {
-		gotB, _ = FromContext(r.Context())
-		w.WriteHeader(http.StatusOK)
-	})
-
-	token, err := issuer.Issue("user-42", "tenant-x")
-	if err != nil {
-		t.Fatalf("issue: %v", err)
-	}
-
-	for path, got := range map[string]*RequestContext{"/api/v1/kontext-a": &gotA, "/api/v1/kontext-b": &gotB} {
-		req := withAuthCookie(httptest.NewRequest(http.MethodGet, path, nil), token)
-		rec := httptest.NewRecorder()
-		srv.Handler().ServeHTTP(rec, req)
-		if rec.Code != http.StatusOK {
-			t.Fatalf("%s: status = %d, want 200", path, rec.Code)
-		}
-		if got.UserID != "user-42" || got.TenantSlug != "tenant-x" {
-			t.Fatalf("%s: request-context unerwartet: %+v", path, *got)
-		}
-	}
-}
-
-// Akzeptanzkriterium 1 + Pruefung 3: eine neue v2-Route laesst sich anlegen,
-// ohne v1 zu beeintraechtigen.
-func TestVersioning_V2DoesNotAffectV1(t *testing.T) {
-	srv, issuer := newTestServer()
-	srv.HandleV1("/things", func(w http.ResponseWriter, r *http.Request) {
-		w.Write([]byte("v1-antwort"))
-	})
-	srv.Handle("v2", "/things", func(w http.ResponseWriter, r *http.Request) {
-		w.Write([]byte("v2-antwort"))
-	})
-
-	token, err := issuer.Issue("user-1", "acme")
-	if err != nil {
-		t.Fatalf("issue: %v", err)
-	}
-
-	reqV1 := withAuthCookie(httptest.NewRequest(http.MethodGet, "/api/v1/things", nil), token)
-	recV1 := httptest.NewRecorder()
-	srv.Handler().ServeHTTP(recV1, reqV1)
-	if recV1.Body.String() != "v1-antwort" {
-		t.Fatalf("v1 antwort = %q, want v1-antwort", recV1.Body.String())
-	}
-
-	reqV2 := withAuthCookie(httptest.NewRequest(http.MethodGet, "/api/v2/things", nil), token)
-	recV2 := httptest.NewRecorder()
-	srv.Handler().ServeHTTP(recV2, reqV2)
-	if recV2.Body.String() != "v2-antwort" {
-		t.Fatalf("v2 antwort = %q, want v2-antwort", recV2.Body.String())
-	}
-
-	// v1 nach dem Anlegen von v2 erneut pruefen — unveraendert.
-	reqV1Again := withAuthCookie(httptest.NewRequest(http.MethodGet, "/api/v1/things", nil), token)
-	recV1Again := httptest.NewRecorder()
-	srv.Handler().ServeHTTP(recV1Again, reqV1Again)
-	if recV1Again.Body.String() != "v1-antwort" {
-		t.Fatalf("v1 antwort nach v2-anlage = %q, want weiterhin v1-antwort", recV1Again.Body.String())
-	}
-}
-
-func TestAuthAndTenantContext_RejectsInvalidToken(t *testing.T) {
-	srv, _ := newTestServer()
-	srv.HandleV1("/geschuetzt", func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(http.StatusOK) })
-
-	req := withAuthCookie(httptest.NewRequest(http.MethodGet, "/api/v1/geschuetzt", nil), "kaputtes.token.hier")
-	rec := httptest.NewRecorder()
-	srv.Handler().ServeHTTP(rec, req)
-	if rec.Code != http.StatusUnauthorized {
-		t.Fatalf("status = %d, want 401", rec.Code)
-	}
-}

internal/audit/audit.go

@@ -0,0 +1,96 @@
+// Package audit implementiert Core AUD-01: das zentrale, vom allgemeinen
+// Anwendungs-Log getrennte Audit-Datenmodell fuer sicherheits- und
+// compliancerelevante Ereignisse (wer, was, wann, an welchem Tenant).
+// Unveraenderlichkeit (Append-only) ist AUD-02, Export/Filter-API ist AUD-03
+// — dieses Paket liefert nur das Datenmodell und den EINEN zentralen
+// Schreibpfad (Akzeptanzkriterium 3).
+package audit
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// SystemTenant ist der reservierte Tenant-Bezug fuer mandantenuebergreifende
+// Ereignisse (z.B. Superadmin-Aktionen) — es gibt bewusst KEINEN Weg, ein
+// Ereignis ganz ohne Tenant-Bezug zu schreiben (Akzeptanzkriterium 2).
+const SystemTenant = "system"
+
+var ErrMissingTenant = errors.New("audit: tenant_slug darf nicht leer sein")
+var ErrMissingActor = errors.New("audit: actor darf nicht leer sein")
+var ErrMissingAction = errors.New("audit: action darf nicht leer sein")
+
+// Event ist ein strukturiertes Audit-Ereignis (Akzeptanzkriterium 1: Akteur,
+// Aktion, Zielobjekt, Zeitpunkt, Tenant).
+type Event struct {
+	TenantSlug string
+	Actor      string
+	Action     string
+	Target     string
+	Metadata   map[string]any
+	OccurredAt time.Time
+}
+
+// Log ist der EINE zentrale Schreibpfad fuer Audit-Ereignisse — es gibt
+// bewusst keine zweite Schreibmoeglichkeit, damit kein Handler versehentlich
+// direkt in audit_events schreibt und dabei die Validierung umgeht
+// (Akzeptanzkriterium 3).
+type Log struct {
+	pool *pgxpool.Pool
+}
+
+func NewLog(pool *pgxpool.Pool) *Log {
+	return &Log{pool: pool}
+}
+
+// Record persistiert genau einen Audit-Eintrag. Fehlender Tenant-Bezug wird
+// bereits hier abgewiesen (klarer Fehler statt Constraint-Verletzung im
+// Normalfall) — die Datenbank-CHECK-Constraint aus der Migration ist die
+// zweite, unumgehbare Verteidigungslinie (Akzeptanzkriterium 2 / Pruefung 2).
+func (l *Log) Record(ctx context.Context, e Event) error {
+	if e.TenantSlug == "" {
+		return ErrMissingTenant
+	}
+	if e.Actor == "" {
+		return ErrMissingActor
+	}
+	if e.Action == "" {
+		return ErrMissingAction
+	}
+	if e.Metadata == nil {
+		e.Metadata = map[string]any{}
+	}
+	metadataJSON, err := json.Marshal(e.Metadata)
+	if err != nil {
+		return fmt.Errorf("metadaten serialisieren: %w", err)
+	}
+	if e.OccurredAt.IsZero() {
+		e.OccurredAt = time.Now()
+	}
+
+	_, err = l.pool.Exec(ctx, `
+		INSERT INTO audit_events (occurred_at, tenant_slug, actor, action, target, metadata)
+		VALUES ($1, $2, $3, $4, $5, $6)
+	`, e.OccurredAt, e.TenantSlug, e.Actor, e.Action, e.Target, metadataJSON)
+	if err != nil {
+		return fmt.Errorf("audit-ereignis schreiben: %w", err)
+	}
+	return nil
+}
+
+// CountByTenant ist eine schlanke Lesehilfe fuer Tests/Diagnose — die
+// eigentliche Filter-/Export-API ist AUD-03, hier bewusst nicht vorgezogen.
+func (l *Log) CountByTenant(ctx context.Context, tenantSlug string) (int, error) {
+	var n int
+	if err := l.pool.QueryRow(ctx, `
+		SELECT count(*) FROM audit_events WHERE tenant_slug = $1
+	`, tenantSlug).Scan(&n); err != nil {
+		return 0, fmt.Errorf("audit-ereignisse zaehlen: %w", err)
+	}
+	return n, nil
+}

internal/audit/audit_test.go

@@ -0,0 +1,132 @@
+package audit
+
+import (
+	"context"
+	"errors"
+	"os"
+	"testing"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+func setupAuditTest(t *testing.T) (*Log, *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 audit_events (
+			id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+			occurred_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+			tenant_slug TEXT NOT NULL CHECK (tenant_slug <> ''),
+			actor TEXT NOT NULL CHECK (actor <> ''),
+			action TEXT NOT NULL CHECK (action <> ''),
+			target TEXT NOT NULL,
+			metadata JSONB NOT NULL DEFAULT '{}'::jsonb
+		)`); err != nil {
+		t.Fatalf("schema: %v", err)
+	}
+
+	cleanup := func() {
+		_, _ = pool.Exec(ctx, `DELETE FROM audit_events WHERE tenant_slug LIKE 'test\_%' ESCAPE '\' OR tenant_slug = $1`, SystemTenant)
+		pool.Close()
+	}
+	return NewLog(pool), pool, cleanup
+}
+
+// Akzeptanzkriterium 1 + Pruefung 1: ein sicherheitsrelevanter Vorgang
+// (hier: fehlgeschlagener Login) erzeugt zuverlaessig genau einen Eintrag.
+func TestRecord_PersistsExactlyOneEventPerSecurityIncident(t *testing.T) {
+	log, pool, cleanup := setupAuditTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	err := log.Record(ctx, Event{
+		TenantSlug: "test_acme",
+		Actor:      "alice@example.com",
+		Action:     "iam.login_failed",
+		Target:     "user:alice@example.com",
+		Metadata:   map[string]any{"reason": "falsches passwort"},
+	})
+	if err != nil {
+		t.Fatalf("record: %v", err)
+	}
+
+	count, err := log.CountByTenant(ctx, "test_acme")
+	if err != nil {
+		t.Fatalf("count: %v", err)
+	}
+	if count != 1 {
+		t.Fatalf("erwartet genau 1 audit-eintrag, habe %d", count)
+	}
+
+	var actor, action, target string
+	if err := pool.QueryRow(ctx, `
+		SELECT actor, action, target FROM audit_events WHERE tenant_slug = 'test_acme'
+	`).Scan(&actor, &action, &target); err != nil {
+		t.Fatalf("eintrag lesen: %v", err)
+	}
+	if actor != "alice@example.com" || action != "iam.login_failed" || target != "user:alice@example.com" {
+		t.Fatalf("eintrag unerwartet: actor=%q action=%q target=%q", actor, action, target)
+	}
+}
+
+// Akzeptanzkriterium 2 + Pruefung 2 (App-Ebene): fehlender Tenant-Bezug wird
+// bereits vom zentralen Schreibpfad abgewiesen.
+func TestRecord_RejectsMissingTenant(t *testing.T) {
+	log, _, cleanup := setupAuditTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	err := log.Record(ctx, Event{TenantSlug: "", Actor: "alice", Action: "irgendwas"})
+	if !errors.Is(err, ErrMissingTenant) {
+		t.Fatalf("erwartet ErrMissingTenant, habe %v", err)
+	}
+}
+
+// Akzeptanzkriterium 2 + Pruefung 2 (DB-Ebene): selbst ein direkter INSERT,
+// der Log.Record umgeht, wird durch die CHECK-Constraint verhindert — der
+// Schutz haengt nicht allein von der Go-Validierung ab.
+func TestConstraint_RejectsMissingTenantAtDatabaseLevel(t *testing.T) {
+	_, pool, cleanup := setupAuditTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	_, err := pool.Exec(ctx, `
+		INSERT INTO audit_events (tenant_slug, actor, action, target)
+		VALUES ('', 'alice', 'irgendwas', 'ziel')
+	`)
+	if err == nil {
+		t.Fatal("erwartet fehler durch CHECK-constraint bei leerem tenant_slug, habe nil")
+	}
+}
+
+func TestRecord_RejectsMissingActorAndAction(t *testing.T) {
+	log, _, cleanup := setupAuditTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	if err := log.Record(ctx, Event{TenantSlug: "test_acme", Actor: "", Action: "x"}); !errors.Is(err, ErrMissingActor) {
+		t.Fatalf("erwartet ErrMissingActor, habe %v", err)
+	}
+	if err := log.Record(ctx, Event{TenantSlug: "test_acme", Actor: "alice", Action: ""}); !errors.Is(err, ErrMissingAction) {
+		t.Fatalf("erwartet ErrMissingAction, habe %v", err)
+	}
+}
+
+func TestRecord_SystemTenantForCrossTenantEvents(t *testing.T) {
+	log, _, cleanup := setupAuditTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	if err := log.Record(ctx, Event{TenantSlug: SystemTenant, Actor: "superadmin", Action: "tenant.provisioned", Target: "tenant:acme"}); err != nil {
+		t.Fatalf("record mit SystemTenant: %v", err)
+	}
+}

internal/audit/export.go

@@ -0,0 +1,122 @@
+package audit
+
+import (
+	"context"
+	"encoding/csv"
+	"encoding/json"
+	"fmt"
+	"io"
+	"time"
+)
+
+// Filter grenzt einen Export ein (Akzeptanzkriterium 1). Leere/Nil-Felder
+// bedeuten "kein Filter auf diesem Feld".
+type Filter struct {
+	TenantSlug string
+	Actor      string
+	Action     string
+	From       *time.Time
+	To         *time.Time
+}
+
+func buildFilterQuery(f Filter) (string, []any) {
+	query := `SELECT occurred_at, tenant_slug, actor, action, target, metadata FROM audit_events WHERE 1=1`
+	var args []any
+
+	if f.TenantSlug != "" {
+		args = append(args, f.TenantSlug)
+		query += fmt.Sprintf(" AND tenant_slug = $%d", len(args))
+	}
+	if f.Actor != "" {
+		args = append(args, f.Actor)
+		query += fmt.Sprintf(" AND actor = $%d", len(args))
+	}
+	if f.Action != "" {
+		args = append(args, f.Action)
+		query += fmt.Sprintf(" AND action = $%d", len(args))
+	}
+	if f.From != nil {
+		args = append(args, *f.From)
+		query += fmt.Sprintf(" AND occurred_at >= $%d", len(args))
+	}
+	if f.To != nil {
+		args = append(args, *f.To)
+		query += fmt.Sprintf(" AND occurred_at <= $%d", len(args))
+	}
+	query += " ORDER BY occurred_at"
+	return query, args
+}
+
+// StreamCSV schreibt gefilterte Audit-Eintraege direkt als CSV in w, Zeile
+// fuer Zeile ueber rows.Next() — es wird zu keinem Zeitpunkt das gesamte
+// Ergebnis im Speicher aufgebaut (Akzeptanzkriterium 3 / Pruefung 1).
+func (l *Log) StreamCSV(ctx context.Context, filter Filter, w io.Writer) error {
+	query, args := buildFilterQuery(filter)
+	rows, err := l.pool.Query(ctx, query, args...)
+	if err != nil {
+		return fmt.Errorf("export abfragen: %w", err)
+	}
+	defer rows.Close()
+
+	cw := csv.NewWriter(w)
+	if err := cw.Write([]string{"occurred_at", "tenant_slug", "actor", "action", "target", "metadata"}); err != nil {
+		return fmt.Errorf("csv-header schreiben: %w", err)
+	}
+
+	for rows.Next() {
+		var occurredAt time.Time
+		var tenantSlug, actor, action, target string
+		var metadataJSON []byte
+		if err := rows.Scan(&occurredAt, &tenantSlug, &actor, &action, &target, &metadataJSON); err != nil {
+			return fmt.Errorf("zeile lesen: %w", err)
+		}
+		if err := cw.Write([]string{
+			occurredAt.Format(time.RFC3339), tenantSlug, actor, action, target, string(metadataJSON),
+		}); err != nil {
+			return fmt.Errorf("csv-zeile schreiben: %w", err)
+		}
+	}
+	cw.Flush()
+	if err := rows.Err(); err != nil {
+		return fmt.Errorf("export lesen: %w", err)
+	}
+	return cw.Error()
+}
+
+// exportRecord ist die JSON-Repraesentation einer exportierten Zeile.
+type exportRecord struct {
+	OccurredAt time.Time       `json:"occurred_at"`
+	TenantSlug string          `json:"tenant_slug"`
+	Actor      string          `json:"actor"`
+	Action     string          `json:"action"`
+	Target     string          `json:"target"`
+	Metadata   json.RawMessage `json:"metadata"`
+}
+
+// StreamJSON schreibt gefilterte Audit-Eintraege als JSON Lines (ein
+// JSON-Objekt pro Zeile) — bewusst kein einzelnes grosses JSON-Array, da
+// dessen korrektes Streaming (Kommas/Klammern ohne Zwischenpufferung)
+// unnoetige Komplexitaet fuer denselben Zweck waere. Wie StreamCSV
+// zeilenweise ueber rows.Next(), kein Aufbau im Speicher.
+func (l *Log) StreamJSON(ctx context.Context, filter Filter, w io.Writer) error {
+	query, args := buildFilterQuery(filter)
+	rows, err := l.pool.Query(ctx, query, args...)
+	if err != nil {
+		return fmt.Errorf("export abfragen: %w", err)
+	}
+	defer rows.Close()
+
+	enc := json.NewEncoder(w)
+	for rows.Next() {
+		var rec exportRecord
+		var metadataJSON []byte
+		if err := rows.Scan(&rec.OccurredAt, &rec.TenantSlug, &rec.Actor, &rec.Action, &rec.Target, &metadataJSON); err != nil {
+			return fmt.Errorf("zeile lesen: %w", err)
+		}
+		rec.Metadata = metadataJSON
+		if err := enc.Encode(rec); err != nil {
+			return fmt.Errorf("json-zeile schreiben: %w", err)
+		}
+	}
+	return rows.Err()
+}

internal/audit/export_handler.go

@@ -0,0 +1,73 @@
+package audit
+
+import (
+	"context"
+	"net/http"
+	"time"
+)
+
+// Authorize entscheidet, ob caller den Export ausfuehren darf. Die
+// eigentliche Rollen-/Rechtepruefung (RBAC-02 Policy-Enforcement) ist nicht
+// Teil dieser Kachel — ExportHandler kennt nur diese schmale Schnittstelle,
+// analog zum RetentionRegistrar-Muster aus AUD-05.
+type Authorize func(ctx context.Context, caller string) bool
+
+// ExportHandler stellt den Export als HTTP-Endpunkt bereit
+// (Akzeptanzkriterium 2: fuer berechtigte Rollen verfuegbar).
+type ExportHandler struct {
+	log       *Log
+	authorize Authorize
+}
+
+func NewExportHandler(log *Log, authorize Authorize) *ExportHandler {
+	return &ExportHandler{log: log, authorize: authorize}
+}
+
+// Export liest Filter-Query-Parameter (tenant, actor, action, from, to,
+// format) und schreibt DIREKT auf den ResponseWriter (io.Writer) — dieselbe
+// Streaming-Funktion wie in export.go, kein zusaetzlicher Pufferungsschritt.
+func (h *ExportHandler) Export(w http.ResponseWriter, r *http.Request) {
+	// "caller" identifiziert die anfragende Person fuer die Berechtigungs-
+	// pruefung — bewusst getrennt vom Filterfeld "actor" (das den
+	// AUDIT-Akteur meint, ueber den gefiltert wird).
+	caller := r.URL.Query().Get("caller")
+	if caller == "" || !h.authorize(r.Context(), caller) {
+		http.Error(w, "keine berechtigung fuer audit-log-export", http.StatusForbidden)
+		return
+	}
+
+	filter := Filter{
+		TenantSlug: r.URL.Query().Get("tenant"),
+		Actor:      r.URL.Query().Get("actor"),
+		Action:     r.URL.Query().Get("action"),
+	}
+	if from := r.URL.Query().Get("from"); from != "" {
+		t, err := time.Parse(time.RFC3339, from)
+		if err != nil {
+			http.Error(w, "ungueltiges from-datum, erwartet RFC3339", http.StatusBadRequest)
+			return
+		}
+		filter.From = &t
+	}
+	if to := r.URL.Query().Get("to"); to != "" {
+		t, err := time.Parse(time.RFC3339, to)
+		if err != nil {
+			http.Error(w, "ungueltiges to-datum, erwartet RFC3339", http.StatusBadRequest)
+			return
+		}
+		filter.To = &t
+	}
+
+	switch r.URL.Query().Get("format") {
+	case "json":
+		w.Header().Set("Content-Type", "application/x-ndjson")
+		if err := h.log.StreamJSON(r.Context(), filter, w); err != nil {
+			http.Error(w, "export fehlgeschlagen", http.StatusInternalServerError)
+		}
+	default:
+		w.Header().Set("Content-Type", "text/csv")
+		if err := h.log.StreamCSV(r.Context(), filter, w); err != nil {
+			http.Error(w, "export fehlgeschlagen", http.StatusInternalServerError)
+		}
+	}
+}

internal/audit/export_test.go

@@ -0,0 +1,222 @@
+package audit
+
+import (
+	"bytes"
+	"context"
+	"encoding/csv"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"runtime"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+func setupExportTest(t *testing.T) (*Log, 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 audit_events (
+			id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+			occurred_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+			tenant_slug TEXT NOT NULL CHECK (tenant_slug <> ''),
+			actor TEXT NOT NULL CHECK (actor <> ''),
+			action TEXT NOT NULL CHECK (action <> ''),
+			target TEXT NOT NULL,
+			metadata JSONB NOT NULL DEFAULT '{}'::jsonb
+		)`); err != nil {
+		t.Fatalf("schema: %v", err)
+	}
+
+	cleanup := func() { pool.Close() }
+	return NewLog(pool), cleanup
+}
+
+// Akzeptanzkriterium 1 + Pruefung 2: Filterkombinationen liefern korrekte
+// Teilmengen.
+func TestExport_FilterCombinations(t *testing.T) {
+	log, cleanup := setupExportTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	run := fmt.Sprintf("_%d", time.Now().UnixNano())
+	tenantA, tenantB := "test_fa"+run, "test_fb"+run
+	alice, bob := "alice"+run, "bob"+run
+
+	events := []Event{
+		{TenantSlug: tenantA, Actor: alice, Action: "login", Target: "x"},
+		{TenantSlug: tenantA, Actor: bob, Action: "login", Target: "x"},
+		{TenantSlug: tenantA, Actor: alice, Action: "logout", Target: "x"},
+		{TenantSlug: tenantB, Actor: alice, Action: "login", Target: "x"},
+	}
+	for _, e := range events {
+		if err := log.Record(ctx, e); err != nil {
+			t.Fatalf("record: %v", err)
+		}
+	}
+
+	cases := []struct {
+		name    string
+		filter  Filter
+		wantLen int
+	}{
+		{"nach tenant", Filter{TenantSlug: tenantA}, 3},
+		{"nach tenant+actor", Filter{TenantSlug: tenantA, Actor: alice}, 2},
+		{"nach tenant+actor+action", Filter{TenantSlug: tenantA, Actor: alice, Action: "login"}, 1},
+		{"nach actor ueber beide tenants", Filter{Actor: alice, Action: "login"}, 2},
+	}
+
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			var buf bytes.Buffer
+			if err := log.StreamCSV(ctx, c.filter, &buf); err != nil {
+				t.Fatalf("stream: %v", err)
+			}
+			rows, err := csv.NewReader(&buf).ReadAll()
+			if err != nil {
+				t.Fatalf("csv parsen: %v", err)
+			}
+			got := len(rows) - 1 // Header abziehen
+			if got != c.wantLen {
+				t.Fatalf("erwartet %d zeilen, habe %d", c.wantLen, got)
+			}
+		})
+	}
+}
+
+// Akzeptanzkriterium 1 + Pruefung 2: Zeitraum-Filter.
+func TestExport_TimeRangeFilter(t *testing.T) {
+	log, cleanup := setupExportTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	tenant := fmt.Sprintf("test_tr_%d", time.Now().UnixNano())
+	past := time.Now().Add(-48 * time.Hour)
+	future := time.Now().Add(48 * time.Hour)
+
+	if err := log.Record(ctx, Event{TenantSlug: tenant, Actor: "a", Action: "x", Target: "t", OccurredAt: time.Now()}); err != nil {
+		t.Fatalf("record: %v", err)
+	}
+
+	var buf bytes.Buffer
+	if err := log.StreamCSV(ctx, Filter{TenantSlug: tenant, From: &past, To: &future}, &buf); err != nil {
+		t.Fatalf("stream (innerhalb range): %v", err)
+	}
+	if got := countLines(buf.String()) - 1; got != 1 {
+		t.Fatalf("erwartet 1 eintrag innerhalb des zeitraums, habe %d", got)
+	}
+
+	farPast := time.Now().Add(-96 * time.Hour)
+	buf.Reset()
+	if err := log.StreamCSV(ctx, Filter{TenantSlug: tenant, From: &farPast, To: &past}, &buf); err != nil {
+		t.Fatalf("stream (ausserhalb range): %v", err)
+	}
+	if got := countLines(buf.String()) - 1; got != 0 {
+		t.Fatalf("erwartet 0 eintraege ausserhalb des zeitraums, habe %d", got)
+	}
+}
+
+func countLines(s string) int {
+	s = strings.TrimRight(s, "\n")
+	if s == "" {
+		return 0
+	}
+	return len(strings.Split(s, "\n"))
+}
+
+// Akzeptanzkriterium 3 + Pruefung 1: Export mit hoher Eintragszahl ohne
+// uebermaessigen Speicherverbrauch — Stichprobe per runtime.MemStats.
+func TestExport_StreamsLargeResultWithoutExcessiveMemory(t *testing.T) {
+	log, cleanup := setupExportTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	tenant := fmt.Sprintf("test_large_%d", time.Now().UnixNano())
+	const n = 20000
+	for i := 0; i < n; i++ {
+		if err := log.Record(ctx, Event{TenantSlug: tenant, Actor: "bulk", Action: "test.bulk", Target: fmt.Sprintf("obj-%d", i)}); err != nil {
+			t.Fatalf("record %d: %v", i, err)
+		}
+	}
+
+	runtime.GC()
+	var before runtime.MemStats
+	runtime.ReadMemStats(&before)
+
+	lineCount := 0
+	cw := &countingWriter{onWrite: func(p []byte) { lineCount += strings.Count(string(p), "\n") }}
+	if err := log.StreamCSV(ctx, Filter{TenantSlug: tenant}, cw); err != nil {
+		t.Fatalf("stream: %v", err)
+	}
+
+	runtime.GC()
+	var after runtime.MemStats
+	runtime.ReadMemStats(&after)
+
+	if lineCount != n+1 { // +1 Header
+		t.Fatalf("erwartet %d zeilen (inkl. header), habe %d", n+1, lineCount)
+	}
+
+	// Grobe Stichprobe: ein NICHT streamender Export haette hier locker
+	// mehrere MB an einmal gehaltenen Zeilen/Strings erzeugt. Grosszuegige
+	// Schwelle, da Go-Heap-Messungen naturgemaess rauschen.
+	const maxAcceptableGrowth = 3 * 1024 * 1024 // 3 MB
+	growth := int64(after.HeapAlloc) - int64(before.HeapAlloc)
+	t.Logf("heap-wachstum waehrend export von %d zeilen: %d bytes (schwelle: %d)", n, growth, maxAcceptableGrowth)
+	if growth > maxAcceptableGrowth {
+		t.Fatalf("heap ist um %d bytes gewachsen, erwartet unter %d (hinweis auf vollstaendige pufferung statt streaming)", growth, maxAcceptableGrowth)
+	}
+}
+
+type countingWriter struct {
+	onWrite func(p []byte)
+}
+
+func (w *countingWriter) Write(p []byte) (int, error) {
+	w.onWrite(p)
+	return len(p), nil
+}
+
+// Akzeptanzkriterium 2 + Pruefung 3: Zugriff ohne passende Berechtigung wird abgewiesen.
+func TestExportHandler_RejectsWithoutAuthorization(t *testing.T) {
+	log, cleanup := setupExportTest(t)
+	defer cleanup()
+
+	handler := NewExportHandler(log, func(ctx context.Context, caller string) bool {
+		return caller == "berechtigte-person@example.com"
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/audit/export?caller=unberechtigt@example.com", nil)
+	rec := httptest.NewRecorder()
+	handler.Export(rec, req)
+	if rec.Code != http.StatusForbidden {
+		t.Fatalf("unberechtigt: status = %d, want 403", rec.Code)
+	}
+
+	reqNoCaller := httptest.NewRequest(http.MethodGet, "/audit/export", nil)
+	recNoCaller := httptest.NewRecorder()
+	handler.Export(recNoCaller, reqNoCaller)
+	if recNoCaller.Code != http.StatusForbidden {
+		t.Fatalf("ohne caller: status = %d, want 403", recNoCaller.Code)
+	}
+
+	reqOK := httptest.NewRequest(http.MethodGet, "/audit/export?caller=berechtigte-person@example.com", nil)
+	recOK := httptest.NewRecorder()
+	handler.Export(recOK, reqOK)
+	if recOK.Code != http.StatusOK {
+		t.Fatalf("berechtigt: status = %d, want 200", recOK.Code)
+	}
+}

internal/auditadmin/authorize.go

@@ -0,0 +1,23 @@
+// Package auditadmin implementiert Core AUD-04: die Berechtigungspruefung
+// fuer die Audit-Log-Ansicht. Enthaelt bewusst KEINE eigene Filter-/
+// Export-Logik — die Ansicht ist "reiner Konsument der Export-API" (AUD-03,
+// internal/audit.ExportHandler); dieses Paket liefert nur die
+// audit.Authorize-Implementierung, die der Entwicklungs-/Testserver
+// (cmd/auditlog-devserver) einhaengt.
+package auditadmin
+
+import "crypto/subtle"
+
+// NewTokenAuthorizer liefert eine audit.Authorize-Funktion, die den
+// aufrufenden "caller"-Wert timing-safe gegen ein geteiltes Admin-Token
+// vergleicht — dasselbe Muster wie internal/audit.timingsafe (AUD-02),
+// NICHT ueber eine neue Rollen-/Rechteschicht, da AUD-04 ausdruecklich nur
+// von AUD-03 abhaengt.
+func NewTokenAuthorizer(adminToken string) func(caller string) bool {
+	return func(caller string) bool {
+		if caller == "" || adminToken == "" {
+			return false
+		}
+		return subtle.ConstantTimeCompare([]byte(caller), []byte(adminToken)) == 1
+	}
+}

internal/auditadmin/authorize_test.go

@@ -0,0 +1,33 @@
+package auditadmin
+
+import "testing"
+
+// Grundlage fuer Akzeptanzkriterium 1/2: die Oberflaeche darf Daten und den
+// Export nur bei korrektem Admin-Token abrufen.
+func TestNewTokenAuthorizer_AcceptsCorrectToken(t *testing.T) {
+	authorize := NewTokenAuthorizer("geheimes-token")
+	if !authorize("geheimes-token") {
+		t.Fatal("erwartet true fuer korrektes token")
+	}
+}
+
+func TestNewTokenAuthorizer_RejectsWrongToken(t *testing.T) {
+	authorize := NewTokenAuthorizer("geheimes-token")
+	if authorize("falsches-token") {
+		t.Fatal("erwartet false fuer falsches token")
+	}
+}
+
+func TestNewTokenAuthorizer_RejectsEmptyCaller(t *testing.T) {
+	authorize := NewTokenAuthorizer("geheimes-token")
+	if authorize("") {
+		t.Fatal("erwartet false fuer leeren aufrufer")
+	}
+}
+
+func TestNewTokenAuthorizer_RejectsWhenNoTokenConfigured(t *testing.T) {
+	authorize := NewTokenAuthorizer("")
+	if authorize("irgendwas") {
+		t.Fatal("erwartet false, wenn kein admin-token konfiguriert ist (fail-safe-default)")
+	}
+}

internal/auth/handler.go

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

internal/auth/login.go

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

internal/auth/login_test.go

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

internal/auth/middleware.go

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

internal/auth/password.go

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

internal/auth/password_bench_test.go

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

internal/auth/password_test.go

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

internal/auth/token.go

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

internal/auth/token_test.go

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

internal/openapi/handler.go

@@ -1,42 +0,0 @@
-package openapi
-
-import (
-	"encoding/json"
-	"fmt"
-	"net/http"
-)
-
-// DocumentHandler liefert das OpenAPI-Dokument als JSON — der Endpunkt, den
-// Swagger UI/Postman/etc. importieren (Akzeptanzkriterium 3).
-func DocumentHandler(doc Document) http.HandlerFunc {
-	return func(w http.ResponseWriter, r *http.Request) {
-		w.Header().Set("Content-Type", "application/json")
-		_ = json.NewEncoder(w).Encode(doc)
-	}
-}
-
-// SwaggerUIHandler liefert eine minimale HTML-Seite, die Swagger UI ueber
-// ein CDN laedt und gegen docURL rendert — Standardmuster fuer
-// "in gaengigen Tools darstellbar" (Akzeptanzkriterium 3), ohne eine eigene
-// Swagger-UI-Distribution einzubetten.
-func SwaggerUIHandler(docURL string) http.HandlerFunc {
-	page := fmt.Sprintf(`<!doctype html>
-<html>
-<head>
-  <title>NEXARCH Core API</title>
-  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist/swagger-ui.css" />
-</head>
-<body>
-  <div id="swagger-ui"></div>
-  <script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"></script>
-  <script>
-    window.onload = () => SwaggerUIBundle({ url: %q, dom_id: "#swagger-ui" });
-  </script>
-</body>
-</html>`, docURL)
-
-	return func(w http.ResponseWriter, r *http.Request) {
-		w.Header().Set("Content-Type", "text/html; charset=utf-8")
-		_, _ = w.Write([]byte(page))
-	}
-}

internal/openapi/openapi.go

@@ -1,158 +0,0 @@
-// Package openapi implementiert Core API-04: eine OpenAPI-3.x-Beschreibung
-// der Core-API, die automatisiert gegen die tatsaechlich registrierten
-// Routen von internal/apiserver.Server geprueft wird (Akzeptanzkriterium 2)
-// — kein manuell gepflegtes Dokument, das unbemerkt vom Code abweichen kann.
-package openapi
-
-import (
-	"fmt"
-	"sort"
-
-	"gitea.perlbach24.de/scripte/nexarch/internal/apiserver"
-)
-
-// Entry beschreibt EINEN dokumentierten Endpunkt inklusive eines
-// Beispielaufrufs (Akzeptanzkriterium 2 / Pruefung 2: "Beispielaufrufe aus
-// dem Dokument gegen die echte API erfolgreich ausgefuehrt").
-type Entry struct {
-	// Path ist der VOLLSTAENDIGE, versionierte Pfad (z.B. "/api/v1/things"),
-	// identisch zu dem, was apiserver.Server.RegisteredPaths() liefert.
-	Path        string
-	Method      string
-	Summary     string
-	Description string
-	// ExampleRequest wird von CheckExamples tatsaechlich gegen den Server
-	// ausgefuehrt (Cookie, Body etc. sind Sache des Aufrufers, siehe
-	// openapi_test.go) — dieses Paket fuehrt nur die HTTP-Anfrage aus und
-	// prueft ExpectStatus.
-	ExampleRequest ExampleRequest
-	ExpectStatus   int
-}
-
-// ExampleRequest ist minimal genug, um sowohl in das OpenAPI-Dokument als
-// auch als tatsaechliche HTTP-Anfrage verwendet zu werden — EIN Beispiel,
-// zwei Verwendungen, damit Dokument und Test nie auseinanderlaufen koennen.
-type ExampleRequest struct {
-	Method      string
-	Path        string
-	Description string
-}
-
-// Document ist eine bewusst schlanke OpenAPI-3.0-Repraesentation — genug,
-// um valide zu sein und von Swagger UI/Postman importiert zu werden
-// (Akzeptanzkriterium 3), ohne eine vollstaendige OpenAPI-Bibliothek zu
-// integrieren.
-type Document struct {
-	OpenAPI string                `json:"openapi"`
-	Info    Info                  `json:"info"`
-	Paths   map[string]PathItem   `json:"paths"`
-}
-
-type Info struct {
-	Title   string `json:"title"`
-	Version string `json:"version"`
-}
-
-type PathItem map[string]Operation
-
-type Operation struct {
-	Summary     string `json:"summary"`
-	Description string `json:"description,omitempty"`
-	Responses   map[string]Response `json:"responses"`
-}
-
-type Response struct {
-	Description string `json:"description"`
-}
-
-// BuildDocument erzeugt das OpenAPI-Dokument AUS denselben Entries, die auch
-// fuer den Drift-Abgleich (CheckNoDrift) und die Beispielausfuehrung
-// (siehe openapi_test.go) verwendet werden — eine einzige Quelle statt
-// eines separat gepflegten Dokuments.
-func BuildDocument(title, version string, entries []Entry) Document {
-	paths := make(map[string]PathItem)
-	for _, e := range entries {
-		item, ok := paths[e.Path]
-		if !ok {
-			item = PathItem{}
-		}
-		item[toLowerMethod(e.Method)] = Operation{
-			Summary:     e.Summary,
-			Description: e.Description,
-			Responses: map[string]Response{
-				fmt.Sprintf("%d", e.ExpectStatus): {Description: "Beispielhafte Antwort"},
-			},
-		}
-		paths[e.Path] = item
-	}
-	return Document{
-		OpenAPI: "3.0.3",
-		Info:    Info{Title: title, Version: version},
-		Paths:   paths,
-	}
-}
-
-func toLowerMethod(m string) string {
-	switch m {
-	case "GET", "get":
-		return "get"
-	case "POST", "post":
-		return "post"
-	case "PUT", "put":
-		return "put"
-	case "DELETE", "delete":
-		return "delete"
-	case "PATCH", "patch":
-		return "patch"
-	default:
-		return "get"
-	}
-}
-
-// ErrDrift wird von CheckNoDrift geliefert, wenn dokumentierte und
-// tatsaechlich registrierte Pfade auseinanderlaufen (Akzeptanzkriterium 2 /
-// Pruefung 1).
-type ErrDrift struct {
-	MissingInDocument []string // registriert, aber nicht dokumentiert
-	MissingAsRoute    []string // dokumentiert, aber nicht (mehr) registriert
-}
-
-func (e *ErrDrift) Error() string {
-	return fmt.Sprintf("openapi: drift erkannt — nicht dokumentiert: %v, nicht (mehr) registriert: %v",
-		e.MissingInDocument, e.MissingAsRoute)
-}
-
-// CheckNoDrift vergleicht die tatsaechlich registrierten Pfade eines
-// Servers mit den in entries dokumentierten Pfaden — vollstaendige
-// Uebereinstimmung der PATH-Menge (nicht Methode je Pfad, da
-// apiserver.Server.Handle methodenunabhaengig registriert). Ein absichtlich
-// entfernter Eintrag auf beiden Seiten (siehe Tests) macht diese Funktion
-// fehlschlagen, das ist der geforderte Drift-Nachweis.
-func CheckNoDrift(server *apiserver.Server, entries []Entry) error {
-	registered := make(map[string]bool)
-	for _, p := range server.RegisteredPaths() {
-		registered[p] = true
-	}
-	documented := make(map[string]bool)
-	for _, e := range entries {
-		documented[e.Path] = true
-	}
-
-	var missingInDoc, missingAsRoute []string
-	for p := range registered {
-		if !documented[p] {
-			missingInDoc = append(missingInDoc, p)
-		}
-	}
-	for p := range documented {
-		if !registered[p] {
-			missingAsRoute = append(missingAsRoute, p)
-		}
-	}
-	if len(missingInDoc) == 0 && len(missingAsRoute) == 0 {
-		return nil
-	}
-	sort.Strings(missingInDoc)
-	sort.Strings(missingAsRoute)
-	return &ErrDrift{MissingInDocument: missingInDoc, MissingAsRoute: missingAsRoute}
-}

internal/openapi/openapi_test.go

@@ -1,142 +0,0 @@
-package openapi
-
-import (
-	"encoding/json"
-	"net/http"
-	"net/http/httptest"
-	"strings"
-	"testing"
-
-	"gitea.perlbach24.de/scripte/nexarch/internal/apiserver"
-	"gitea.perlbach24.de/scripte/nexarch/internal/auth"
-)
-
-func newTestServerWithRoutes() (*apiserver.Server, *auth.TokenIssuer) {
-	issuer := auth.NewTokenIssuer("test-secret-nur-fuer-tests")
-	srv := apiserver.NewServer(issuer)
-	srv.HandleV1("/things", func(w http.ResponseWriter, r *http.Request) {
-		w.WriteHeader(http.StatusOK)
-	})
-	srv.HandleV1("/other", func(w http.ResponseWriter, r *http.Request) {
-		w.WriteHeader(http.StatusOK)
-	})
-	return srv, issuer
-}
-
-func testEntries() []Entry {
-	return []Entry{
-		{Path: "/api/v1/things", Method: "GET", Summary: "Dinge auflisten", ExpectStatus: http.StatusOK},
-		{Path: "/api/v1/other", Method: "GET", Summary: "Anderes abrufen", ExpectStatus: http.StatusOK},
-	}
-}
-
-// Akzeptanzkriterium 1: das Dokument deckt alle tatsaechlich registrierten
-// Endpunkte ab.
-func TestCheckNoDrift_PassesWhenDocumentMatchesRoutes(t *testing.T) {
-	srv, _ := newTestServerWithRoutes()
-	if err := CheckNoDrift(srv, testEntries()); err != nil {
-		t.Fatalf("erwartet keinen drift, habe: %v", err)
-	}
-}
-
-// Akzeptanzkriterium 2 + Pruefung 1: automatisierter Abgleich schlaegt bei
-// Drift fehl — hier absichtlich eine Route aus dem Dokument entfernt, waehrend
-// der Server sie weiterhin registriert hat.
-func TestCheckNoDrift_FailsWhenRouteMissingFromDocument(t *testing.T) {
-	srv, _ := newTestServerWithRoutes()
-	entries := []Entry{testEntries()[0]} // "/api/v1/other" absichtlich entfernt
-
-	err := CheckNoDrift(srv, entries)
-	if err == nil {
-		t.Fatal("erwartet drift-fehler, da eine registrierte route nicht dokumentiert ist")
-	}
-	driftErr, ok := err.(*ErrDrift)
-	if !ok {
-		t.Fatalf("erwartet *ErrDrift, habe %T", err)
-	}
-	if len(driftErr.MissingInDocument) != 1 || driftErr.MissingInDocument[0] != "/api/v1/other" {
-		t.Fatalf("erwartet '/api/v1/other' als nicht dokumentiert, habe: %v", driftErr.MissingInDocument)
-	}
-}
-
-// Symmetrischer Fall: Dokument nennt eine Route, die es beim Server gar
-// nicht (mehr) gibt (z.B. nach Entfernen eines Endpunkts im Code).
-func TestCheckNoDrift_FailsWhenDocumentedRouteNoLongerExists(t *testing.T) {
-	srv, _ := newTestServerWithRoutes()
-	entries := append(testEntries(), Entry{Path: "/api/v1/entfernt", Method: "GET", ExpectStatus: http.StatusOK})
-
-	err := CheckNoDrift(srv, entries)
-	if err == nil {
-		t.Fatal("erwartet drift-fehler fuer dokumentierte, aber nicht registrierte route")
-	}
-	driftErr := err.(*ErrDrift)
-	if len(driftErr.MissingAsRoute) != 1 || driftErr.MissingAsRoute[0] != "/api/v1/entfernt" {
-		t.Fatalf("erwartet '/api/v1/entfernt' als nicht (mehr) registriert, habe: %v", driftErr.MissingAsRoute)
-	}
-}
-
-// Akzeptanzkriterium 2 + Pruefung 2: Beispielaufrufe aus dem Dokument
-// werden GEGEN DIE ECHTE API (httptest, echte Middleware-Kette) ausgefuehrt.
-func TestExamples_ExecuteSuccessfullyAgainstRealServer(t *testing.T) {
-	srv, issuer := newTestServerWithRoutes()
-	token, err := issuer.Issue("user-1", "acme")
-	if err != nil {
-		t.Fatalf("issue: %v", err)
-	}
-
-	for _, e := range testEntries() {
-		req := httptest.NewRequest(e.Method, e.Path, nil)
-		req.AddCookie(&http.Cookie{Name: auth.CookieName, Value: token})
-		rec := httptest.NewRecorder()
-		srv.Handler().ServeHTTP(rec, req)
-
-		if rec.Code != e.ExpectStatus {
-			t.Fatalf("beispielaufruf %s %s: status = %d, want %d", e.Method, e.Path, rec.Code, e.ExpectStatus)
-		}
-	}
-}
-
-// Akzeptanzkriterium 3: Dokument ist ueber einen Endpunkt abrufbar und
-// valides JSON, das Tools wie Swagger UI importieren koennen.
-func TestDocumentHandler_ServesValidJSONWithAllPaths(t *testing.T) {
-	doc := BuildDocument("NEXARCH Core API", "v1", testEntries())
-
-	req := httptest.NewRequest(http.MethodGet, "/api/v1/openapi.json", nil)
-	rec := httptest.NewRecorder()
-	DocumentHandler(doc)(rec, req)
-
-	if rec.Code != http.StatusOK {
-		t.Fatalf("status = %d, want 200", rec.Code)
-	}
-
-	var decoded Document
-	if err := json.Unmarshal(rec.Body.Bytes(), &decoded); err != nil {
-		t.Fatalf("dokument nicht als json lesbar: %v", err)
-	}
-	if decoded.OpenAPI == "" {
-		t.Fatal("erwartet gesetztes openapi-versionsfeld")
-	}
-	for _, e := range testEntries() {
-		if _, ok := decoded.Paths[e.Path]; !ok {
-			t.Fatalf("pfad %s fehlt im dekodierten dokument", e.Path)
-		}
-	}
-}
-
-func TestSwaggerUIHandler_ServesHTMLReferencingDocumentURL(t *testing.T) {
-	req := httptest.NewRequest(http.MethodGet, "/api/v1/docs", nil)
-	rec := httptest.NewRecorder()
-	SwaggerUIHandler("/api/v1/openapi.json")(rec, req)
-
-	if rec.Code != http.StatusOK {
-		t.Fatalf("status = %d, want 200", rec.Code)
-	}
-	ct := rec.Header().Get("Content-Type")
-	if ct == "" {
-		t.Fatal("erwartet gesetzten Content-Type-Header")
-	}
-	body := rec.Body.String()
-	if !strings.Contains(body, "/api/v1/openapi.json") {
-		t.Fatal("erwartet referenz auf das openapi-dokument in der swagger-ui-seite")
-	}
-}

internal/user/handler.go

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

internal/user/store_test.go

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

internal/user/superadmin_store.go

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

internal/user/tenant_store.go

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

internal/user/user.go

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

internal/user/user_test.go

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

migrations/0002_superadmins.down.sql

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

migrations/0002_superadmins.up.sql

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

migrations/0004_audit_events.down.sql

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

migrations/0004_audit_events.up.sql

@@ -0,0 +1,17 @@
+-- Zentrales Audit-Log-Modell (AUD-01, siehe core-kanban/tickets/AUD-01.md).
+-- Getrennt vom allgemeinen Anwendungs-Log (Akzeptanzkriterium 2): eigene
+-- Tabelle, eigenes Paket (internal/audit), kein Log-Framework.
+-- tenant_slug ist NOT NULL + darf nicht leer sein (Akzeptanzkriterium 2 /
+-- Pruefung 2) — mandantenuebergreifende Ereignisse nutzen den reservierten
+-- Wert 'system', niemals NULL oder leeren String.
+CREATE TABLE audit_events (
+    id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    occurred_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+    tenant_slug  TEXT NOT NULL CHECK (tenant_slug <> ''),
+    actor        TEXT NOT NULL CHECK (actor <> ''),
+    action       TEXT NOT NULL CHECK (action <> ''),
+    target       TEXT NOT NULL,
+    metadata     JSONB NOT NULL DEFAULT '{}'::jsonb
+);
+
+CREATE INDEX audit_events_tenant_slug_idx ON audit_events (tenant_slug, occurred_at);

migrations/tenant/0001_users.down.sql

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

migrations/tenant/0001_users.up.sql

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

migrations/tenant/0002_users_password.down.sql

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

migrations/tenant/0002_users_password.up.sql

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

scripts/reset-test-env.sh

@@ -1,4 +1,11 @@
 #!/usr/bin/env bash
+# Setzt die nexarch-Testumgebung zurueck: loescht die geteilte
+# Registry-Tabelle "tenants" in der postgres-Wartungsdatenbank sowie alle
+# tenant_*-Datenbanken. Noetig, weil verschiedene Feature-Branches
+# unterschiedliche Registry-Schemata erwarten, aber dieselbe physische
+# Postgres-Instanz auf dem Testhost teilen (siehe [[project-nexarch-test-infra]]).
+#
+# Aufruf: NEXARCH_TEST_DB_PASSWORD=... ./scripts/reset-test-env.sh
 set -euo pipefail
 
 PASS="${NEXARCH_TEST_DB_PASSWORD:?Setze NEXARCH_TEST_DB_PASSWORD vor dem Aufruf}"
@@ -7,6 +14,7 @@ ROLE="nexarch_test"
 export PGPASSWORD="$PASS"
 
 psql -h localhost -U "$ROLE" -d postgres -v ON_ERROR_STOP=1 -c "DROP TABLE IF EXISTS tenants CASCADE;"
+psql -h localhost -U "$ROLE" -d postgres -v ON_ERROR_STOP=1 -c "DROP TABLE IF EXISTS audit_events CASCADE;"
 
 dbs=$(psql -h localhost -U "$ROLE" -d postgres -tAc "SELECT datname FROM pg_database WHERE datname LIKE 'tenant\_%' ESCAPE '\'")
 for db in $dbs; do

scripts/run-checks.sh

@@ -1,4 +1,10 @@
 #!/usr/bin/env bash
+# Ein-Kommando-Pruefung fuer den aktuellen Code-Stand auf dem Testhost:
+# Registry+Tenant-DBs zuruecksetzen, dann build/vet/test in einem Rutsch.
+# -p 1 ist Pflicht, da mehrere Pakete dieselbe physische Registry-Tabelle auf
+# dem Testhost teilen (siehe [[project-nexarch-test-infra]]).
+#
+# Aufruf: NEXARCH_TEST_DB_PASSWORD=... ./scripts/run-checks.sh
 set -euo pipefail
 
 PASS="${NEXARCH_TEST_DB_PASSWORD:?Setze NEXARCH_TEST_DB_PASSWORD vor dem Aufruf}"

web/audit-log/app/layout.tsx

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

web/audit-log/app/page.tsx

@@ -0,0 +1,159 @@
+"use client";
+
+import { useState } from "react";
+import { fetchRecords, exportURL, type AuditRecord, type AuditFilter } from "@/lib/api";
+
+const EMPTY_FILTER: AuditFilter = { tenant: "", actor: "", action: "", from: "", to: "" };
+
+export default function Page() {
+  const [caller, setCaller] = useState("");
+  const [filter, setFilter] = useState<AuditFilter>(EMPTY_FILTER);
+  const [records, setRecords] = useState<AuditRecord[] | null>(null);
+  const [selected, setSelected] = useState<AuditRecord | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  async function onSearch() {
+    setError(null);
+    setSelected(null);
+    try {
+      const data = await fetchRecords(caller.trim(), filter);
+      setRecords(data);
+    } catch (e: any) {
+      setError(e.message ?? "Unbekannter Fehler");
+      setRecords(null);
+    }
+  }
+
+  function onExport(format: "csv" | "json") {
+    const url = exportURL(caller.trim(), filter, format);
+    // Echter Datei-Download ueber Browser-Navigation, KEIN erneutes Parsen
+    // im Frontend (Akzeptanzkriterium 2: Export aus AUD-03 direkt ausloesbar).
+    window.open(url, "_blank");
+  }
+
+  return (
+    <main style={{ maxWidth: 1000, margin: "0 auto", padding: "2rem 1rem" }}>
+      <h1>Audit-Log</h1>
+
+      <div style={{ display: "grid", gap: "0.5rem", gridTemplateColumns: "repeat(3, 1fr)", marginBottom: "1rem" }}>
+        <input
+          value={caller}
+          onChange={(e) => setCaller(e.target.value)}
+          placeholder="Admin-Token (Berechtigung)"
+          style={{ padding: "0.5rem", gridColumn: "span 3" }}
+        />
+        <input
+          value={filter.tenant}
+          onChange={(e) => setFilter({ ...filter, tenant: e.target.value })}
+          placeholder="Tenant"
+          style={{ padding: "0.5rem" }}
+        />
+        <input
+          value={filter.actor}
+          onChange={(e) => setFilter({ ...filter, actor: e.target.value })}
+          placeholder="Akteur"
+          style={{ padding: "0.5rem" }}
+        />
+        <input
+          value={filter.action}
+          onChange={(e) => setFilter({ ...filter, action: e.target.value })}
+          placeholder="Aktion"
+          style={{ padding: "0.5rem" }}
+        />
+        <label>
+          Von
+          <input
+            type="datetime-local"
+            value={filter.from}
+            onChange={(e) =>
+              setFilter({ ...filter, from: e.target.value ? new Date(e.target.value).toISOString() : "" })
+            }
+            style={{ width: "100%", padding: "0.4rem" }}
+          />
+        </label>
+        <label>
+          Bis
+          <input
+            type="datetime-local"
+            value={filter.to}
+            onChange={(e) =>
+              setFilter({ ...filter, to: e.target.value ? new Date(e.target.value).toISOString() : "" })
+            }
+            style={{ width: "100%", padding: "0.4rem" }}
+          />
+        </label>
+      </div>
+
+      <div style={{ display: "flex", gap: "0.5rem", marginBottom: "1rem" }}>
+        <button onClick={onSearch}>Suchen</button>
+        <button onClick={() => onExport("csv")}>Export als CSV</button>
+        <button onClick={() => onExport("json")}>Export als JSON</button>
+      </div>
+
+      {error && (
+        <p style={{ color: "#c62828" }} role="alert">
+          Fehler: {error}
+        </p>
+      )}
+
+      {records && (
+        <table style={{ width: "100%", borderCollapse: "collapse", background: "white" }}>
+          <thead>
+            <tr style={{ textAlign: "left", borderBottom: "2px solid #ddd" }}>
+              <th style={{ padding: "0.5rem" }}>Zeitpunkt</th>
+              <th style={{ padding: "0.5rem" }}>Tenant</th>
+              <th style={{ padding: "0.5rem" }}>Akteur</th>
+              <th style={{ padding: "0.5rem" }}>Aktion</th>
+              <th style={{ padding: "0.5rem" }}></th>
+            </tr>
+          </thead>
+          <tbody>
+            {records.map((r, i) => (
+              <tr key={i} style={{ borderBottom: "1px solid #eee" }}>
+                <td style={{ padding: "0.5rem" }}>{new Date(r.occurred_at).toLocaleString("de-DE")}</td>
+                <td style={{ padding: "0.5rem" }}>{r.tenant_slug}</td>
+                <td style={{ padding: "0.5rem" }}>{r.actor}</td>
+                <td style={{ padding: "0.5rem" }}>{r.action}</td>
+                <td style={{ padding: "0.5rem" }}>
+                  <button onClick={() => setSelected(r)}>Details</button>
+                </td>
+              </tr>
+            ))}
+            {records.length === 0 && (
+              <tr>
+                <td colSpan={5} style={{ padding: "0.5rem" }}>
+                  Keine Einträge gefunden.
+                </td>
+              </tr>
+            )}
+          </tbody>
+        </table>
+      )}
+
+      {selected && (
+        <section style={{ background: "white", padding: "1rem", borderRadius: 8, marginTop: "1.5rem" }}>
+          <h2>Eintrag-Details</h2>
+          <dl>
+            <dt>Zeitpunkt</dt>
+            <dd>{new Date(selected.occurred_at).toLocaleString("de-DE")}</dd>
+            <dt>Tenant</dt>
+            <dd>{selected.tenant_slug}</dd>
+            <dt>Akteur</dt>
+            <dd>{selected.actor}</dd>
+            <dt>Aktion</dt>
+            <dd>{selected.action}</dd>
+            <dt>Ziel</dt>
+            <dd>{selected.target}</dd>
+            <dt>Metadaten</dt>
+            <dd>
+              <pre style={{ whiteSpace: "pre-wrap", background: "#f5f6f8", padding: "0.5rem" }}>
+                {JSON.stringify(selected.metadata, null, 2)}
+              </pre>
+            </dd>
+          </dl>
+          <button onClick={() => setSelected(null)}>Schließen</button>
+        </section>
+      )}
+    </main>
+  );
+}

web/audit-log/lib/api.ts

@@ -0,0 +1,63 @@
+// Duenner Client der AUD-03-Export-API (internal/audit.ExportHandler) —
+// keine eigene Aggregations-/Filterlogik im Frontend (Ticket-Vorgabe:
+// "reiner Konsument der Export-API"). Die JSON-Lines-Antwort wird nur
+// dekodiert, nicht neu berechnet oder gefiltert.
+export type AuditRecord = {
+  occurred_at: string;
+  tenant_slug: string;
+  actor: string;
+  action: string;
+  target: string;
+  metadata: unknown;
+};
+
+export type AuditFilter = {
+  tenant: string;
+  actor: string;
+  action: string;
+  from: string; // RFC3339, leer = kein Filter
+  to: string;
+};
+
+function apiBase(): string {
+  const base = process.env.NEXT_PUBLIC_AUDITLOG_API_URL;
+  if (!base) {
+    throw new Error(
+      "NEXT_PUBLIC_AUDITLOG_API_URL ist nicht gesetzt (Umgebungsvariable erforderlich)"
+    );
+  }
+  return base;
+}
+
+function buildParams(caller: string, filter: AuditFilter, format: "json" | "csv"): URLSearchParams {
+  const params = new URLSearchParams({ caller, format });
+  if (filter.tenant) params.set("tenant", filter.tenant);
+  if (filter.actor) params.set("actor", filter.actor);
+  if (filter.action) params.set("action", filter.action);
+  if (filter.from) params.set("from", filter.from);
+  if (filter.to) params.set("to", filter.to);
+  return params;
+}
+
+// exportURL liefert die Adresse desselben Endpunkts, den auch die
+// Export-Datei-Funktion (Akzeptanzkriterium 2) verwendet — Liste und Export
+// sind bewusst DERSELBE API-Aufruf mit unterschiedlichem "format".
+export function exportURL(caller: string, filter: AuditFilter, format: "json" | "csv"): string {
+  return `${apiBase()}/audit/export?${buildParams(caller, filter, format)}`;
+}
+
+// fetchRecords laedt die Liste als JSON-Lines und dekodiert Zeile fuer
+// Zeile — dieselben Filterparameter wie ein direkter API-Aufruf
+// (Akzeptanzkriterium 1 / Pruefung 1).
+export async function fetchRecords(caller: string, filter: AuditFilter): Promise<AuditRecord[]> {
+  const res = await fetch(exportURL(caller, filter, "json"), { cache: "no-store" });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(text || `Anfrage fehlgeschlagen (${res.status})`);
+  }
+  const text = await res.text();
+  return text
+    .split("\n")
+    .filter((line) => line.trim() !== "")
+    .map((line) => JSON.parse(line) as AuditRecord);
+}

web/audit-log/next.config.mjs

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

web/audit-log/package.json

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

web/audit-log/tsconfig.json

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

web/shl/README.md

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

web/shl/__tests__/Dialog.test.tsx

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

web/shl/__tests__/tokens.test.ts

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

web/shl/components/Dialog.tsx

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

web/shl/components/FormElements.tsx

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

web/shl/components/Shell.tsx

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

web/shl/components/Table.tsx

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

web/shl/components/Toast.tsx

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

web/shl/i18n/i18n.tsx

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

web/shl/index.ts

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

web/shl/package.json

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

web/shl/theme/ThemeProvider.tsx

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

web/shl/tokens/tokens.ts

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

web/shl/tsconfig.json

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

web/shl/vitest.config.ts

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

web/shl/vitest.setup.ts

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