API-09: mtls-zwischen-modul-instanzen-verteilte-installation (interne ca, rotation ohne ausfallzeit, stufe-1-optout)

internal/apiserver/server.go

@@ -12,7 +12,6 @@ import (
 type Server struct {
 	mux    *http.ServeMux
 	issuer *auth.TokenIssuer
-	routes []string
 }
 
 func NewServer(issuer *auth.TokenIssuer) *Server {
@@ -25,20 +24,9 @@ func NewServer(issuer *auth.TokenIssuer) *Server {
 // 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)

internal/mtls/ca.go

@@ -0,0 +1,158 @@
+// Package mtls implementiert Core API-09: gegenseitige TLS-Authentifizierung
+// zwischen Core/DMS/Mail/Archive/Workflow/AI/Connect-Instanzen fuer
+// Stufe-2/3-Installationen (siehe SKALIERUNGSKONZEPT.md) — schuetzt die
+// VERTRAULICHKEIT des Transportwegs, dort wo API-05 (asymmetrische
+// JWT-Signatur) und API-02 (Service-Credential) nur Authentizitaet/
+// Integritaet, aber keine Transportverschluesselung zwischen getrennten
+// Hosts absichern.
+//
+// Zertifikatsverteilung (Akzeptanzkriterium 1): Authority.IssueCert liefert
+// PEM-kodiertes Zertifikat + privaten Schluessel, die ueber denselben Weg
+// wie andere Secrets verteilt werden (Umgebungsvariablen/Secret-Store,
+// niemals im Code) — automatisierbar, da IssueCert ein reiner
+// Funktionsaufruf ohne manuelle Schritte ist.
+package mtls
+
+import (
+	"crypto/ed25519"
+	"crypto/rand"
+	"crypto/tls"
+	"crypto/x509"
+	"crypto/x509/pkix"
+	"encoding/pem"
+	"fmt"
+	"math/big"
+	"net"
+	"time"
+)
+
+// Authority ist eine interne Zertifizierungsstelle fuer Modul-zu-Modul-
+// mTLS. Haelt — analog zu internal/moduletrust.KeyManager (API-05) — ALLE
+// noch gueltigen historischen CA-Zertifikate im Vertrauensspeicher, damit
+// eine Rotation bereits ausgestellte Leaf-Zertifikate nicht ungueltig macht
+// (Akzeptanzkriterium 3: Rotation ohne Ausfallzeit).
+type Authority struct {
+	current    caGeneration
+	trustPool  *x509.CertPool
+	generations []caGeneration
+}
+
+type caGeneration struct {
+	cert *x509.Certificate
+	key  ed25519.PrivateKey
+}
+
+// NewAuthority erzeugt eine frische interne CA.
+func NewAuthority() (*Authority, error) {
+	gen, err := newCAGeneration()
+	if err != nil {
+		return nil, err
+	}
+	pool := x509.NewCertPool()
+	pool.AddCert(gen.cert)
+	return &Authority{current: gen, trustPool: pool, generations: []caGeneration{gen}}, nil
+}
+
+func newCAGeneration() (caGeneration, error) {
+	pub, priv, err := ed25519.GenerateKey(rand.Reader)
+	if err != nil {
+		return caGeneration{}, fmt.Errorf("ca-schluesselpaar erzeugen: %w", err)
+	}
+	serial, err := rand.Int(rand.Reader, big.NewInt(1<<62))
+	if err != nil {
+		return caGeneration{}, fmt.Errorf("seriennummer erzeugen: %w", err)
+	}
+	template := &x509.Certificate{
+		SerialNumber:          serial,
+		Subject:               pkix.Name{CommonName: "nexarch-internal-ca"},
+		NotBefore:             time.Now().Add(-time.Minute),
+		NotAfter:              time.Now().Add(5 * 365 * 24 * time.Hour),
+		KeyUsage:              x509.KeyUsageCertSign | x509.KeyUsageCRLSign,
+		BasicConstraintsValid: true,
+		IsCA:                  true,
+	}
+	der, err := x509.CreateCertificate(rand.Reader, template, template, pub, priv)
+	if err != nil {
+		return caGeneration{}, fmt.Errorf("ca-zertifikat erstellen: %w", err)
+	}
+	cert, err := x509.ParseCertificate(der)
+	if err != nil {
+		return caGeneration{}, fmt.Errorf("ca-zertifikat parsen: %w", err)
+	}
+	return caGeneration{cert: cert, key: priv}, nil
+}
+
+// Rotate erzeugt eine NEUE CA-Generation fuer zukuenftige IssueCert-Aufrufe,
+// behaelt aber ALLE bisherigen CA-Zertifikate im Vertrauensspeicher —
+// bereits ausgestellte Leaf-Zertifikate bleiben dadurch gueltig, eine
+// laufende mTLS-Verbindung wird durch Rotate NICHT unterbrochen
+// (Akzeptanzkriterium 3 / Pruefung 2).
+func (a *Authority) Rotate() error {
+	gen, err := newCAGeneration()
+	if err != nil {
+		return err
+	}
+	a.trustPool.AddCert(gen.cert)
+	a.generations = append(a.generations, gen)
+	a.current = gen
+	return nil
+}
+
+// TrustPool liefert den Vertrauensspeicher mit ALLEN (auch historischen,
+// noch nicht abgelaufenen) CA-Zertifikaten — Grundlage der
+// Server-seitigen Client-Zertifikatspruefung (Akzeptanzkriterium 2).
+func (a *Authority) TrustPool() *x509.CertPool {
+	return a.trustPool
+}
+
+// IssuedCert ist ein ausgestelltes Leaf-Zertifikat inklusive privatem
+// Schluessel, PEM-kodiert zur Verteilung (Akzeptanzkriterium 1).
+type IssuedCert struct {
+	CertPEM []byte
+	KeyPEM  []byte
+}
+
+// IssueCert stellt ein Leaf-Zertifikat fuer EINE Modul-Instanz aus, signiert
+// mit der AKTUELLEN CA-Generation (Akzeptanzkriterium 1).
+func (a *Authority) IssueCert(commonName string, validity time.Duration) (IssuedCert, error) {
+	pub, priv, err := ed25519.GenerateKey(rand.Reader)
+	if err != nil {
+		return IssuedCert{}, fmt.Errorf("leaf-schluesselpaar erzeugen: %w", err)
+	}
+	serial, err := rand.Int(rand.Reader, big.NewInt(1<<62))
+	if err != nil {
+		return IssuedCert{}, fmt.Errorf("seriennummer erzeugen: %w", err)
+	}
+	template := &x509.Certificate{
+		SerialNumber: serial,
+		Subject:      pkix.Name{CommonName: commonName},
+		NotBefore:    time.Now().Add(-time.Minute),
+		NotAfter:     time.Now().Add(validity),
+		KeyUsage:     x509.KeyUsageDigitalSignature,
+		ExtKeyUsage:  []x509.ExtKeyUsage{x509.ExtKeyUsageClientAuth, x509.ExtKeyUsageServerAuth},
+		// DNSNames/IPAddresses decken lokale Testumgebungen ab (127.0.0.1,
+		// localhost) — in echten Stufe-2/3-Installationen entspricht
+		// commonName dem tatsaechlichen internen Hostnamen der Instanz.
+		DNSNames:    []string{commonName, "localhost"},
+		IPAddresses: []net.IP{net.IPv4(127, 0, 0, 1), net.IPv6loopback},
+	}
+	der, err := x509.CreateCertificate(rand.Reader, template, a.current.cert, pub, a.current.key)
+	if err != nil {
+		return IssuedCert{}, fmt.Errorf("leaf-zertifikat erstellen: %w", err)
+	}
+
+	certPEM := pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: der})
+	keyBytes, err := x509.MarshalPKCS8PrivateKey(priv)
+	if err != nil {
+		return IssuedCert{}, fmt.Errorf("leaf-schluessel serialisieren: %w", err)
+	}
+	keyPEM := pem.EncodeToMemory(&pem.Block{Type: "PRIVATE KEY", Bytes: keyBytes})
+
+	return IssuedCert{CertPEM: certPEM, KeyPEM: keyPEM}, nil
+}
+
+// TLSCertificate wandelt ein IssuedCert in ein tls.Certificate um, wie es
+// tls.Config.Certificates erwartet.
+func (c IssuedCert) TLSCertificate() (tls.Certificate, error) {
+	return tls.X509KeyPair(c.CertPEM, c.KeyPEM)
+}

internal/mtls/config.go

@@ -0,0 +1,46 @@
+package mtls
+
+import "crypto/tls"
+
+// Mode legt fest, ob mTLS erzwungen wird. Fuer Stufe-1-Einzel-LXC ist mTLS
+// laut Ticket "optional/nicht zwingend" (lokale Kommunikation) — ModeOff
+// liefert einen ganz normalen TLS-Server OHNE Client-Zertifikatspruefung,
+// damit Stufe-1-Betrieb unveraendert weiterlaeuft (Akzeptanzkriterium 3 /
+// Pruefung 3).
+type Mode string
+
+const (
+	ModeOff      Mode = "off"      // Stufe 1: kein mTLS-Zwang
+	ModeRequired Mode = "required" // Stufe 2/3: Client-Zertifikat zwingend
+)
+
+// ServerTLSConfig liefert die tls.Config fuer eine Modul-Instanz, die
+// eingehende Verbindungen ANDERER Modul-Instanzen annimmt.
+//
+//   - ModeRequired: verlangt UND verifiziert ein Client-Zertifikat gegen
+//     authority.TrustPool() (Akzeptanzkriterium 2) — eine Verbindung ohne
+//     gueltiges Zertifikat wird vom TLS-Handshake selbst abgelehnt, bevor
+//     irgendein Anwendungscode erreicht wird.
+//   - ModeOff: normales TLS ohne Client-Zertifikatspruefung
+//     (Akzeptanzkriterium 3 / Pruefung 3: Stufe-1-Betrieb funktioniert
+//     weiterhin ohne mTLS-Zwang).
+func ServerTLSConfig(mode Mode, serverCert tls.Certificate, authority *Authority) *tls.Config {
+	cfg := &tls.Config{Certificates: []tls.Certificate{serverCert}}
+	if mode == ModeRequired {
+		cfg.ClientAuth = tls.RequireAndVerifyClientCert
+		cfg.ClientCAs = authority.TrustPool()
+	}
+	return cfg
+}
+
+// ClientTLSConfig liefert die tls.Config fuer eine Modul-Instanz, die eine
+// Verbindung zu einer ANDEREN Modul-Instanz aufbaut — praesentiert das
+// eigene Zertifikat und vertraut Gegenstellen, die von derselben Authority
+// signiert wurden.
+func ClientTLSConfig(mode Mode, clientCert tls.Certificate, authority *Authority) *tls.Config {
+	cfg := &tls.Config{RootCAs: authority.TrustPool()}
+	if mode == ModeRequired {
+		cfg.Certificates = []tls.Certificate{clientCert}
+	}
+	return cfg
+}

internal/mtls/mtls_test.go

@@ -0,0 +1,185 @@
+package mtls
+
+import (
+	"crypto/tls"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+)
+
+func newTLSServer(t *testing.T, cfg *tls.Config) *httptest.Server {
+	t.Helper()
+	server := httptest.NewUnstartedServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte("ok"))
+	}))
+	server.TLS = cfg
+	server.StartTLS()
+	return server
+}
+
+func fetch(t *testing.T, url string, clientCfg *tls.Config) (int, error) {
+	t.Helper()
+	client := &http.Client{
+		Transport: &http.Transport{TLSClientConfig: clientCfg},
+		Timeout:   3 * time.Second,
+	}
+	resp, err := client.Get(url)
+	if err != nil {
+		return 0, err
+	}
+	defer resp.Body.Close()
+	_, _ = io.ReadAll(resp.Body)
+	return resp.StatusCode, nil
+}
+
+// Akzeptanzkriterium 1: Zertifikatsverteilung ist ein reiner
+// Funktionsaufruf, das Ergebnis ist gueltiges, wiederverwendbares
+// PEM-Material.
+func TestIssueCert_ProducesValidPEMRoundTrip(t *testing.T) {
+	authority, err := NewAuthority()
+	if err != nil {
+		t.Fatalf("newauthority: %v", err)
+	}
+	issued, err := authority.IssueCert("dms", time.Hour)
+	if err != nil {
+		t.Fatalf("issuecert: %v", err)
+	}
+	if _, err := issued.TLSCertificate(); err != nil {
+		t.Fatalf("ausgestelltes zertifikat nicht als tls.Certificate ladbar: %v", err)
+	}
+}
+
+// Akzeptanzkriterium 2 + Pruefung 1: eine Verbindung ohne gueltiges
+// Client-Zertifikat wird abgelehnt, eine mit gueltigem angenommen.
+func TestServerTLSConfig_RejectsMissingClientCert(t *testing.T) {
+	authority, err := NewAuthority()
+	if err != nil {
+		t.Fatalf("newauthority: %v", err)
+	}
+	serverIssued, err := authority.IssueCert("core", time.Hour)
+	if err != nil {
+		t.Fatalf("server-zertifikat ausstellen: %v", err)
+	}
+	serverCert, err := serverIssued.TLSCertificate()
+	if err != nil {
+		t.Fatalf("server-zertifikat laden: %v", err)
+	}
+
+	server := newTLSServer(t, ServerTLSConfig(ModeRequired, serverCert, authority))
+	defer server.Close()
+
+	// Client OHNE Zertifikat, aber mit korrektem RootCA-Vertrauen fuer den
+	// Server — der Handshake muss trotzdem an der fehlenden Client-Auth
+	// scheitern.
+	_, err = fetch(t, server.URL, &tls.Config{RootCAs: authority.TrustPool()})
+	if err == nil {
+		t.Fatal("erwartet fehlschlagenden handshake ohne client-zertifikat")
+	}
+
+	clientIssued, err := authority.IssueCert("mail", time.Hour)
+	if err != nil {
+		t.Fatalf("client-zertifikat ausstellen: %v", err)
+	}
+	clientCert, err := clientIssued.TLSCertificate()
+	if err != nil {
+		t.Fatalf("client-zertifikat laden: %v", err)
+	}
+	status, err := fetch(t, server.URL, ClientTLSConfig(ModeRequired, clientCert, authority))
+	if err != nil {
+		t.Fatalf("erwartet erfolgreiche verbindung mit gueltigem client-zertifikat: %v", err)
+	}
+	if status != http.StatusOK {
+		t.Fatalf("status = %d, want 200", status)
+	}
+}
+
+// Akzeptanzkriterium 3 + Pruefung 2: Rotation der CA unterbricht laufenden
+// Betrieb nicht — ein VOR der Rotation ausgestelltes Leaf-Zertifikat
+// funktioniert danach weiter, UND ein NACH der Rotation neu ausgestelltes
+// funktioniert ebenfalls, gegen denselben, weiterlaufenden Server (kein
+// Neustart noetig, da TrustPool() denselben *x509.CertPool zurueckliefert,
+// den Rotate() erweitert).
+func TestAuthority_RotateWithoutDowntime(t *testing.T) {
+	authority, err := NewAuthority()
+	if err != nil {
+		t.Fatalf("newauthority: %v", err)
+	}
+	serverIssued, err := authority.IssueCert("core", time.Hour)
+	if err != nil {
+		t.Fatalf("server-zertifikat ausstellen: %v", err)
+	}
+	serverCert, err := serverIssued.TLSCertificate()
+	if err != nil {
+		t.Fatalf("server-zertifikat laden: %v", err)
+	}
+
+	server := newTLSServer(t, ServerTLSConfig(ModeRequired, serverCert, authority))
+	defer server.Close() // EIN Server-Prozess ueber die gesamte Rotation hinweg — kein Neustart.
+
+	preRotationIssued, err := authority.IssueCert("dms", time.Hour)
+	if err != nil {
+		t.Fatalf("client-zertifikat (vor rotation) ausstellen: %v", err)
+	}
+	preRotationCert, _ := preRotationIssued.TLSCertificate()
+
+	if err := authority.Rotate(); err != nil {
+		t.Fatalf("rotate: %v", err)
+	}
+
+	// VOR der Rotation ausgestelltes Zertifikat funktioniert WEITERHIN, ohne
+	// dass der Server neu gestartet wurde.
+	status, err := fetch(t, server.URL, ClientTLSConfig(ModeRequired, preRotationCert, authority))
+	if err != nil {
+		t.Fatalf("vor-rotation-zertifikat haette weiterhin funktionieren sollen: %v", err)
+	}
+	if status != http.StatusOK {
+		t.Fatalf("status = %d, want 200 (vor-rotation-zertifikat)", status)
+	}
+
+	// NACH der Rotation neu ausgestelltes Zertifikat funktioniert ebenfalls,
+	// gegen DENSELBEN laufenden Server.
+	postRotationIssued, err := authority.IssueCert("mail", time.Hour)
+	if err != nil {
+		t.Fatalf("client-zertifikat (nach rotation) ausstellen: %v", err)
+	}
+	postRotationCert, _ := postRotationIssued.TLSCertificate()
+
+	status, err = fetch(t, server.URL, ClientTLSConfig(ModeRequired, postRotationCert, authority))
+	if err != nil {
+		t.Fatalf("nach-rotation-zertifikat haette funktionieren sollen: %v", err)
+	}
+	if status != http.StatusOK {
+		t.Fatalf("status = %d, want 200 (nach-rotation-zertifikat)", status)
+	}
+}
+
+// Akzeptanzkriterium 3 + Pruefung 3: Stufe-1-Betrieb (ModeOff) funktioniert
+// weiterhin OHNE mTLS-Zwang — ein Client ganz ohne Zertifikat kommt durch.
+func TestServerTLSConfig_ModeOffWorksWithoutClientCert(t *testing.T) {
+	authority, err := NewAuthority()
+	if err != nil {
+		t.Fatalf("newauthority: %v", err)
+	}
+	serverIssued, err := authority.IssueCert("core", time.Hour)
+	if err != nil {
+		t.Fatalf("server-zertifikat ausstellen: %v", err)
+	}
+	serverCert, err := serverIssued.TLSCertificate()
+	if err != nil {
+		t.Fatalf("server-zertifikat laden: %v", err)
+	}
+
+	server := newTLSServer(t, ServerTLSConfig(ModeOff, serverCert, authority))
+	defer server.Close()
+
+	status, err := fetch(t, server.URL, ClientTLSConfig(ModeOff, tls.Certificate{}, authority))
+	if err != nil {
+		t.Fatalf("stufe-1-betrieb (ModeOff) haette ohne client-zertifikat funktionieren sollen: %v", err)
+	}
+	if status != http.StatusOK {
+		t.Fatalf("status = %d, want 200", status)
+	}
+}

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")
-	}
-}