Merge PR #313: ENG-07 (Connect): Drittsystem-Zugangsdaten ueber Core-Tenant-KEK-Hierarchie

connect/docs/ENG-07-PRUEFPROTOKOLL.md

@@ -0,0 +1,52 @@
+# ENG-07 – Drittsystem-Zugangsdaten über Core-Tenant-KEK-Hierarchie verschlüsseln: Prüfprotokoll
+
+Basis: `main` (ENG-02, Verbindungs-Credential-Verwaltung, bereits fertig). Getestet auf Entwicklungshost 204, Wegwerf-Postgres-Schema je Testlauf (`connect/internal/testdb`, `TEST_TENANT_DSN`).
+
+## Ausgangslage
+
+`connect/internal/crypto` (ENG-02) implementiert bereits Envelope-Encryption mit einem austauschbaren `KEKProvider`-Interface ("vom Core API-10 in Produktion bezogen", laut Paket-Kommentar) — die Primitiven selbst entsprachen also schon dem Core-Muster. Es fehlte jedoch die konkrete Implementierung, die den Tenant-KEK tatsächlich über Core API-10 bezieht: Ohne sie hätte jede künftige Verdrahtung (M365-01, API-01) frei entscheiden können, woher der KEK kommt — genau die im Ticket beschriebene Gefahr eines zweiten, unabhängig zu härtenden Pfads.
+
+## Umsetzung
+
+- `connect/internal/crypto/kekprovider.go` (neu): `HTTPKEKProvider`, bezieht den Tenant-KEK über Cores API-10-Handler (`internal/kek.Handler.TenantKEKHandler`), authentifiziert über dieselben Service-Credential-Header (`X-Nexarch-Client-Id`/`X-Nexarch-Client-Secret`) wie DMS (`dms/internal/crypto.HTTPKEKProvider`) und Archive (`archive/internal/kekclient.HTTPProvider`) — identischer Vertrag, hier für Connect gespiegelt (eigenes Go-Modul, kein Import von Cores `internal/kek` über Modulgrenzen möglich). Implementiert das bereits bestehende `KEKProvider`-Interface aus `envelope.go`, keine neue Abstraktion.
+- `connect/internal/crypto/kekprovider_test.go` (neu): Vertragstest gegen `httptest`-Server (Header, Query-Parameter, JSON-Feldname `tenant_kek_base64`) plus Ablehnungsfall (Nicht-200-Status). Kein laufender Core-Prozess nötig — gleicher Kompromiss wie im DMS-Pendant (FDN-09-Pruefprotokoll).
+- `connect/internal/credential/corekek_test.go` (neu): Integrationstest, der `credential.Store` über die echte `HTTPKEKProvider`-Kette (statt des bisherigen reinen In-Memory-Test-Fakes) gegen die echte Postgres-Testdatenbank verdrahtet.
+- Keine Schemaänderung: `connector_credentials` (Migration `0001`) ist bereits KEK-agnostisch (`ciphertext`/`wrapped_dek`), keine Anpassung nötig.
+- `connect/internal/credential`, `connect/internal/erpconnector`, `connect/internal/crmconnector` unverändert — bestätigt AC3 strukturell (keine API-Änderung).
+
+## Akzeptanzkriterien
+
+1. **Zugangsdaten ausschließlich über Tenant-KEK gespeichert.** `TestStore_CoreKEK_SecretsAreEncryptedAtRest` verdrahtet `credential.Store` über `HTTPKEKProvider` gegen einen Core-API-10-förmigen Stub und bestätigt Put/Get-Rundtrip plus Chiffrat in der DB.
+2. **Kein verwertbarer Klartext bei direktem Lesezugriff.** Dieselbe Prüfung liest die rohe `ciphertext`-Spalte aus: weder der Klartext-Marker noch der JSON-Feldname `api_key` erscheinen darin.
+3. **Bestehende Connector-Authentifizierung funktioniert unverändert.** Komplette Testsuite (`go test ./... -p 1`) läuft grün, insbesondere `erpconnector`, `crmconnector`, `datevapi`, `datevexport`, `datevtransfer`, `dmsexchange`, `m365connector`, `m365calsync`, `m365docsync` sowie alle bisherigen `credential`-Tests aus ENG-02/ENG-06 unangetastet.
+
+## Prüfungen vor der Abnahme
+
+| Prüfung | Zielwert | Ergebnis |
+|---|---|---|
+| 1. Zugangsdaten in der DB direkt auslesen | nur Chiffrat sichtbar, kein Klartextfragment | bestanden (`TestStore_CoreKEK_SecretsAreEncryptedAtRest`, roh gelesene `ciphertext`-Spalte enthält weder Marker noch `api_key`) |
+| 2. Regressionstest Connector-Verbindungsaufbau (ERP/DATEV/M365/DMS2) | alle Connector-Pakete weiterhin grün | bestanden — `go test ./... -p 1`: 25 Pakete `ok`, 0 FAIL (siehe Gesamtlauf) |
+| 3. Entschlüsselung mit falschem Tenant-KEK schlägt fehl | `ErrDecryptFailed`, kein Cross-Tenant-Zugriff | bestanden (`TestStore_CoreKEK_WrongTenantKEK_Fails`: zweiter Core-Stub mit abweichendem KEK scheitert beim Öffnen derselben Zeile) |
+
+Zusätzlich (Vertragsnachweis des neuen HTTP-Clients, nicht in den Prüfungen oben enthalten, aber Voraussetzung dafür):
+
+| Test | Ergebnis |
+|---|---|
+| `TestHTTPKEKProvider_SendsCorrectContractToCore` | bestanden |
+| `TestHTTPKEKProvider_RejectsNonOKStatus` | bestanden |
+
+## Gesamtlauf
+
+`gofmt -l` (neue Dateien sauber, vorbestehende Fundstellen in anderen Paketen unverändert/nicht Teil dieser Kachel), `go vet ./...` (clean), `go build ./...` (clean), `go test ./... -p 1`: alle 25 testbaren Pakete `ok`, 0 FAIL, auf Host 204 gegen `TEST_TENANT_DSN` (echte Postgres-Instanz, kein Mocking).
+
+## QA und Entscheidungen
+
+- **Keine Core-Live-Verdrahtung im Test:** Wie im DMS-Pendant (FDN-09) gegen einen `httptest`-Server geprüft, der exakt Cores `TenantKEKHandler`-Vertrag nachbildet, statt gegen einen laufenden Core-Prozess — kein separat zu betreibender Core-Dienst in diesem Repo-Checkout verfügbar, gleicher akzeptierter Kompromiss wie bei den anderen Modulen.
+- **Kein `cmd/connect-app`-Wiring:** `credential.Store` wird (wie schon in ENG-02 festgehalten: "Kein HTTP-Dienst") noch von keinem `cmd/`-Binary produktiv konstruiert — M365-01/API-01 sind weiterhin nicht Bestandteil. Die kleinste Lösung für dieses Ticket liefert die einzige sanktionierte `KEKProvider`-Implementierung (`HTTPKEKProvider`), ohne ungenutzte Verdrahtung zu erfinden; Umgebungsvariablen-Konvention für eine künftige Verdrahtung folgt dem bestehenden Muster (`NEXARCH_CONNECT_APP_KEK_ENDPOINT_URL`/`_KEK_CLIENT_ID`/`_KEK_CLIENT_SECRET`, analog `NEXARCH_DMS_APP_KEK_*`).
+- **Keine Schemaänderung:** Die Tabelle war bereits envelope-generisch, es musste nur die Schlüsselquelle verbindlich gemacht werden.
+- 0 der 20 erlaubten Iterationen für Unklarheiten gebraucht; ein Testfehler während der Entwicklung (zwei `testdb.Pool`-Aufrufe erzeugen getrennte Schemata, daher "not found" statt `ErrDecryptFailed` im Cross-Tenant-Test) wurde durch gemeinsame Pool-Nutzung in `corekek_test.go` behoben.
+
+## Offen (nicht Bestandteil dieser Kachel)
+
+- `M365-01` (Microsoft-Graph-Anbindung) und `API-01` (Connect-Konfigurationsoberfläche) — laut ENG-02 weiterhin offen, dieses Ticket betrifft nur die Schlüsselquelle für bereits bestehende Zugangsdaten-Verschlüsselung.
+- Produktive Verdrahtung von `HTTPKEKProvider` in ein `cmd/`-Binary folgt mit der ersten Kachel, die `credential.Store` tatsächlich als HTTP-Dienst oder Konsument einsetzt.

connect/internal/credential/corekek_test.go

@@ -0,0 +1,120 @@
+package credential_test
+
+import (
+	"bytes"
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"testing"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"gitea.perlbach24.de/scripte/nexarch/connect/internal/credential"
+	connectcrypto "gitea.perlbach24.de/scripte/nexarch/connect/internal/crypto"
+	"gitea.perlbach24.de/scripte/nexarch/connect/internal/migrate"
+	"gitea.perlbach24.de/scripte/nexarch/connect/internal/testdb"
+)
+
+// coreKEKStub stands in for Core API-10's TenantKEKHandler, always serving
+// the given fixed KEK — enough to prove the HTTP contract end to end
+// without a running Core process (ENG-07 Pruefung 1/3; same "not wired to a
+// live Core" compromise as DMS FDN-09).
+func coreKEKStub(t *testing.T, kek []byte) *httptest.Server {
+	t.Helper()
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]string{
+			"tenant_kek_base64": base64.StdEncoding.EncodeToString(kek),
+		})
+	}))
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+func storeWithCoreKEK(pool *pgxpool.Pool, t *testing.T, kek []byte) *credential.Store {
+	t.Helper()
+	core := coreKEKStub(t, kek)
+	provider := connectcrypto.NewHTTPKEKProvider(core.URL, "connect-service-client", "connect-service-secret", nil)
+	return credential.NewStore(pool, connectcrypto.NewService(provider))
+}
+
+func migratedPool(t *testing.T) *pgxpool.Pool {
+	t.Helper()
+	dsn := os.Getenv("TEST_TENANT_DSN")
+	if dsn == "" {
+		t.Skip("TEST_TENANT_DSN nicht gesetzt, Integrationstest uebersprungen")
+	}
+	ctx := context.Background()
+	pool := testdb.Pool(t, dsn)
+	migrations, err := migrate.Load(findMigrationsDir(t))
+	if err != nil {
+		t.Fatalf("migrationen laden: %v", err)
+	}
+	if _, err := migrate.Up(ctx, pool, migrations); err != nil {
+		t.Fatalf("migrationen anwenden: %v", err)
+	}
+	return pool
+}
+
+// ENG-07 AC1/Pruefung 1: Zugangsdaten, verschluesselt ueber einen Core-API-10-
+// foermigen Tenant-KEK-Bezug (nicht nur den generischen Test-Fake), landen
+// in der Datenbank ausschliesslich als Chiffrat.
+func TestStore_CoreKEK_SecretsAreEncryptedAtRest(t *testing.T) {
+	pool := migratedPool(t)
+	kek := bytes.Repeat([]byte{0x33}, connectcrypto.KEKSize)
+	store := storeWithCoreKEK(pool, t, kek)
+	ctx := context.Background()
+	ref := credential.Ref{TenantSlug: "acme", ConnectorName: "test-connector", ConnectorInstanceID: "core-kek-1"}
+	marker := "MARKER-PLAINTEXT-MUST-NOT-APPEAR-CORE-KEK"
+
+	if err := store.Put(ctx, ref, credential.KindAPIKey, credential.Secret{APIKey: marker}, nil); err != nil {
+		t.Fatalf("put: %v", err)
+	}
+
+	got, kind, _, err := store.Get(ctx, ref)
+	if err != nil {
+		t.Fatalf("get: %v", err)
+	}
+	if kind != credential.KindAPIKey || got.APIKey != marker {
+		t.Fatalf("roundtrip mismatch: %+v kind=%s", got, kind)
+	}
+
+	var raw []byte
+	if err := pool.QueryRow(ctx, `
+		SELECT ciphertext FROM connector_credentials
+		WHERE tenant_slug = $1 AND connector_name = $2 AND connector_instance_id = $3
+	`, ref.TenantSlug, ref.ConnectorName, ref.ConnectorInstanceID).Scan(&raw); err != nil {
+		t.Fatalf("raw select: %v", err)
+	}
+	if bytes.Contains(raw, []byte(marker)) {
+		t.Fatal("klartext-marker im rohen ciphertext gefunden")
+	}
+	if bytes.Contains(raw, []byte("api_key")) {
+		t.Fatal("json-feldname im rohen ciphertext gefunden, sieht nach klartext-json aus")
+	}
+}
+
+// ENG-07 AC1/Pruefung 3: Ein anderer Tenant-KEK (simuliert ueber einen
+// zweiten Core-Stub, wie bei einem fremden Mandanten) darf dieselbe,
+// bereits gespeicherte Zeile nicht entschluesseln koennen.
+func TestStore_CoreKEK_WrongTenantKEK_Fails(t *testing.T) {
+	pool := migratedPool(t)
+	kekAcme := bytes.Repeat([]byte{0x44}, connectcrypto.KEKSize)
+	kekBeta := bytes.Repeat([]byte{0x55}, connectcrypto.KEKSize)
+
+	store := storeWithCoreKEK(pool, t, kekAcme)
+	ctx := context.Background()
+	ref := credential.Ref{TenantSlug: "acme", ConnectorName: "test-connector", ConnectorInstanceID: "core-kek-cross-tenant"}
+	if err := store.Put(ctx, ref, credential.KindAPIKey, credential.Secret{APIKey: "x"}, nil); err != nil {
+		t.Fatalf("put: %v", err)
+	}
+
+	foreignStore := storeWithCoreKEK(pool, t, kekBeta)
+	if _, _, _, err := foreignStore.Get(ctx, ref); !errors.Is(err, connectcrypto.ErrDecryptFailed) {
+		t.Fatalf("erwartet ErrDecryptFailed bei fremdem tenant-kek, habe %v", err)
+	}
+}

connect/internal/crypto/kekprovider.go

@@ -0,0 +1,75 @@
+// HTTPKEKProvider fetches the tenant KEK from Core API-10 over HTTP
+// (internal/kek.Handler.TenantKEKHandler) — Connect is a physically
+// separate Go module and cannot import Core's internal/kek package
+// directly, only via this HTTP contract. Same header/response scheme as
+// dms/internal/crypto.HTTPKEKProvider and archive/internal/kekclient.
+package crypto
+
+import (
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/url"
+
+	"gitea.perlbach24.de/scripte/nexarch/connect/internal/httpclient"
+)
+
+// tenantKEKResponse mirrors Core internal/kek.tenantKEKResponse (JSON
+// contract: tenant_kek_base64).
+type tenantKEKResponse struct {
+	TenantKEKBase64 string `json:"tenant_kek_base64"`
+}
+
+type HTTPKEKProvider struct {
+	endpointURL  string
+	clientID     string
+	clientSecret string
+	httpClient   *http.Client
+}
+
+func NewHTTPKEKProvider(endpointURL, clientID, clientSecret string, httpClient *http.Client) *HTTPKEKProvider {
+	if httpClient == nil {
+		httpClient = httpclient.Default()
+	}
+	return &HTTPKEKProvider{endpointURL: endpointURL, clientID: clientID, clientSecret: clientSecret, httpClient: httpClient}
+}
+
+// TenantKEK fetches tenantSlug's KEK fresh on every call (never cached) —
+// matches the KEKProvider interface in envelope.go.
+func (p *HTTPKEKProvider) TenantKEK(ctx context.Context, tenantSlug string) ([]byte, error) {
+	u, err := url.Parse(p.endpointURL)
+	if err != nil {
+		return nil, fmt.Errorf("crypto: invalid kek endpoint url: %w", err)
+	}
+	q := u.Query()
+	q.Set("tenant", tenantSlug)
+	u.RawQuery = q.Encode()
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, u.String(), nil)
+	if err != nil {
+		return nil, fmt.Errorf("crypto: build kek request: %w", err)
+	}
+	req.Header.Set("X-Nexarch-Client-Id", p.clientID)
+	req.Header.Set("X-Nexarch-Client-Secret", p.clientSecret)
+
+	resp, err := p.httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("crypto: send kek request: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("crypto: core rejected kek request: status %d", resp.StatusCode)
+	}
+
+	var body tenantKEKResponse
+	if err := json.NewDecoder(resp.Body).Decode(&body); err != nil {
+		return nil, fmt.Errorf("crypto: decode kek response: %w", err)
+	}
+	kek, err := base64.StdEncoding.DecodeString(body.TenantKEKBase64)
+	if err != nil {
+		return nil, fmt.Errorf("crypto: decode kek base64: %w", err)
+	}
+	return kek, nil
+}

connect/internal/crypto/kekprovider_test.go

@@ -0,0 +1,63 @@
+package crypto
+
+import (
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+// TestHTTPKEKProvider_SendsCorrectContractToCore proves HTTPKEKProvider
+// speaks the exact contract of Core internal/kek.Handler.TenantKEKHandler
+// (service-credential headers, tenant query param, JSON field name) — no
+// running Core process involved, verified against an httptest server that
+// mirrors that contract (same approach as dms/internal/crypto FDN-09).
+func TestHTTPKEKProvider_SendsCorrectContractToCore(t *testing.T) {
+	wantKEK := make([]byte, KEKSize)
+	for i := range wantKEK {
+		wantKEK[i] = byte(i)
+	}
+
+	var gotClientID, gotClientSecret, gotTenant string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotClientID = r.Header.Get("X-Nexarch-Client-Id")
+		gotClientSecret = r.Header.Get("X-Nexarch-Client-Secret")
+		gotTenant = r.URL.Query().Get("tenant")
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(tenantKEKResponse{TenantKEKBase64: base64.StdEncoding.EncodeToString(wantKEK)})
+	}))
+	defer srv.Close()
+
+	provider := NewHTTPKEKProvider(srv.URL, "connect-service-client", "connect-service-secret", nil)
+	got, err := provider.TenantKEK(context.Background(), "acme")
+	if err != nil {
+		t.Fatalf("tenantkek: %v", err)
+	}
+
+	if gotClientID != "connect-service-client" || gotClientSecret != "connect-service-secret" {
+		t.Fatalf("service credential headers wrong: id=%q secret=%q", gotClientID, gotClientSecret)
+	}
+	if gotTenant != "acme" {
+		t.Fatalf("tenant query param = %q, want %q", gotTenant, "acme")
+	}
+	if len(got) != KEKSize || got[0] != wantKEK[0] {
+		t.Fatalf("returned kek does not match expected")
+	}
+}
+
+// TestHTTPKEKProvider_RejectsNonOKStatus proves a rejection by Core (e.g.
+// module not active for this tenant, ErrForbidden on Core's side) surfaces
+// as an error instead of a silently empty/zero KEK.
+func TestHTTPKEKProvider_RejectsNonOKStatus(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Error(w, "access to this tenant denied", http.StatusForbidden)
+	}))
+	defer srv.Close()
+
+	provider := NewHTTPKEKProvider(srv.URL, "x", "y", nil)
+	if _, err := provider.TenantKEK(context.Background(), "foreign-tenant"); err == nil {
+		t.Fatal("expected error on rejected kek fetch, got nil")
+	}
+}