Merge branch 'feature/rbac-04-modul-scoped-berechtigungen' into feature/qa-03-pruefgate-rechte-policy

2026-08-29 00:10:21 +02:00
parent e65625841c 3d5f53f103
commit ba23d4d90d
8 changed files with 457 additions and 0 deletions
@@ -0,0 +1,87 @@
+// Package flag implementiert Core LIC-02: einen Feature-Flag-Dienst mit
+// Strategien (global an/aus, Prozentsatz, Tenant-Zielgruppe) als Kernfunktion
+// des Core-Dienstes selbst — keine zusaetzliche Infrastruktur (Unleash-Server
+// + eigene DB), siehe "bewusst vermeiden" im LIC-02-Ticket.
+package flag
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"hash/fnv"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+var ErrNotFound = errors.New("flag: nicht gefunden")
+
+// Flag ist die zentrale Definition — Auswertung (Evaluate) ist bewusst davon
+// getrennt (Unleash-Prinzip: Flag-Verwaltung vs. Flag-Auswertung).
+type Flag struct {
+	Key               string
+	Enabled           bool
+	RolloutPercentage int
+	TargetTenantSlugs []string
+}
+
+// Store ist die Verwaltungsseite (Admin): Flags definieren/lesen.
+type Store struct {
+	pool *pgxpool.Pool
+}
+
+func NewStore(pool *pgxpool.Pool) *Store {
+	return &Store{pool: pool}
+}
+
+func (s *Store) Set(ctx context.Context, f Flag) error {
+	if f.TargetTenantSlugs == nil {
+		f.TargetTenantSlugs = []string{} // pgx uebertraegt ein nil-Slice sonst als SQL NULL statt leerem Array.
+	}
+	_, err := s.pool.Exec(ctx, `
+		INSERT INTO feature_flags (key, enabled, rollout_percentage, target_tenant_slugs, updated_at)
+		VALUES ($1, $2, $3, $4, now())
+		ON CONFLICT (key) DO UPDATE SET
+			enabled = $2, rollout_percentage = $3, target_tenant_slugs = $4, updated_at = now()
+	`, f.Key, f.Enabled, f.RolloutPercentage, f.TargetTenantSlugs)
+	if err != nil {
+		return fmt.Errorf("flag speichern: %w", err)
+	}
+	return nil
+}
+
+func (s *Store) Get(ctx context.Context, key string) (Flag, error) {
+	var f Flag
+	row := s.pool.QueryRow(ctx, `
+		SELECT key, enabled, rollout_percentage, target_tenant_slugs
+		FROM feature_flags WHERE key = $1
+	`, key)
+	if err := row.Scan(&f.Key, &f.Enabled, &f.RolloutPercentage, &f.TargetTenantSlugs); err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return Flag{}, ErrNotFound
+		}
+		return Flag{}, fmt.Errorf("flag lesen: %w", err)
+	}
+	return f, nil
+}
+
+// evaluate wendet die Strategien in fester Reihenfolge an: globaler
+// An/Aus-Schalter zuerst, dann Tenant-Zielgruppe, dann Prozentsatz-Rollout.
+// Ein unbekannter/nicht getroffener Fall ergibt false — Fail-Safe-Default,
+// kein Feature wird versehentlich aktiv.
+func evaluate(f Flag, tenantSlug string) bool {
+	if f.Enabled {
+		return true
+	}
+	for _, target := range f.TargetTenantSlugs {
+		if target == tenantSlug {
+			return true
+		}
+	}
+	if f.RolloutPercentage > 0 {
+		h := fnv.New32a()
+		_, _ = h.Write([]byte(f.Key + "|" + tenantSlug))
+		return int(h.Sum32()%100) < f.RolloutPercentage
+	}
+	return false
+}
@@ -0,0 +1,87 @@
+package flag
+
+import (
+	"context"
+	"log/slog"
+	"sync"
+	"time"
+)
+
+// DefaultCacheTTL ist die dokumentierte Cache-Invalidierungszeit
+// (Akzeptanzkriterium 2/3): eine Aenderung wirkt spaetestens nach dieser
+// Zeit auf allen Core-Instanzen, ohne dass ein Dienst neu gestartet werden
+// muss (Akzeptanzkriterium 3).
+const DefaultCacheTTL = 5 * time.Second
+
+type cacheEntry struct {
+	flag      Flag
+	expiresAt time.Time
+}
+
+// Service ist die Auswertungsseite (SDK/Client-Analogon zu Unleash) mit
+// lokalem TTL-Cache. Bewusst getrennt von Store (Verwaltung).
+type Service struct {
+	store *Store
+	ttl   time.Duration
+
+	mu    sync.RWMutex
+	cache map[string]cacheEntry
+}
+
+func NewService(store *Store, ttl time.Duration) *Service {
+	if ttl <= 0 {
+		ttl = DefaultCacheTTL
+	}
+	return &Service{store: store, ttl: ttl, cache: make(map[string]cacheEntry)}
+}
+
+// IsEnabled wertet ein Flag fuer einen Tenant aus. Liefert IMMER einen
+// bool ohne Fehlerwert — ein nicht erreichbarer Flag-Dienst darf abhaengige
+// Aufrufer nicht zum Absturz bringen oder zu Fehlerbehandlungscode zwingen,
+// der leicht vergessen wird (Akzeptanzkriterium 3 / Pruefung 3: dokumentiertes
+// Fallback-Verhalten = false, ggf. aus dem zuletzt bekannten Zwischenspeicher).
+func (s *Service) IsEnabled(ctx context.Context, tenantSlug, key string) bool {
+	f, ok := s.resolve(ctx, key)
+	if !ok {
+		return false
+	}
+	return evaluate(f, tenantSlug)
+}
+
+func (s *Service) resolve(ctx context.Context, key string) (Flag, bool) {
+	s.mu.RLock()
+	entry, exists := s.cache[key]
+	fresh := exists && time.Now().Before(entry.expiresAt)
+	s.mu.RUnlock()
+	if fresh {
+		return entry.flag, true
+	}
+
+	f, err := s.store.Get(ctx, key)
+	if err != nil {
+		if exists {
+			slog.Warn("feature-flag-dienst nicht erreichbar, nutze zwischengespeicherten stand",
+				"flag_key", key, "error", err)
+			return entry.flag, true
+		}
+		slog.Warn("feature-flag-dienst nicht erreichbar, kein zwischengespeicherter stand vorhanden, fallback: deaktiviert",
+			"flag_key", key, "error", err)
+		return Flag{}, false
+	}
+
+	s.mu.Lock()
+	s.cache[key] = cacheEntry{flag: f, expiresAt: time.Now().Add(s.ttl)}
+	s.mu.Unlock()
+	return f, true
+}
+
+// Invalidate erzwingt beim naechsten IsEnabled-Aufruf ein sofortiges Neuladen
+// aus der Datenbank statt auf den TTL-Ablauf zu warten — wird nach Store.Set
+// auf derselben Instanz aufgerufen, damit der Schreiber die eigene Aenderung
+// ohne Wartezeit sieht. Andere Core-Instanzen sehen sie spaetestens nach
+// DefaultCacheTTL (siehe Akzeptanzkriterium 3).
+func (s *Service) Invalidate(key string) {
+	s.mu.Lock()
+	delete(s.cache, key)
+	s.mu.Unlock()
+}
@@ -0,0 +1,90 @@
+package policy
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/jackc/pgx/v5"
+
+	"gitea.perlbach24.de/scripte/nexarch/internal/flag"
+	"gitea.perlbach24.de/scripte/nexarch/internal/rbac"
+)
+
+// ModuleScope verknuepft eine Policy-Regel mit einem Feature-Flag: existiert
+// ein ModuleScope fuer (role, permission), gilt die Regel nur zusaetzlich zur
+// Grundberechtigung, wenn FlagKey fuer den jeweiligen Tenant aktiv ist
+// (Akzeptanzkriterium 1: Rechte folgen der Lizenz).
+type ModuleScope struct {
+	Role       rbac.Role
+	Permission rbac.Permission
+	Module     string
+	FlagKey    string
+}
+
+// SetModuleScope verknuepft eine bestehende Policy-Regel mit einem Modul/
+// Feature-Flag. Die Regel selbst (Store.Grant) muss unabhaengig davon
+// existieren — ModuleScope schraenkt sie nur zusaetzlich ein.
+func (s *Store) SetModuleScope(ctx context.Context, role rbac.Role, perm rbac.Permission, module, flagKey string) error {
+	_, err := s.pool.Exec(ctx, `
+		INSERT INTO policy_module_scopes (role, permission, module, flag_key)
+		VALUES ($1, $2, $3, $4)
+		ON CONFLICT (role, permission) DO UPDATE SET module = $3, flag_key = $4
+	`, string(role), string(perm), module, flagKey)
+	if err != nil {
+		return fmt.Errorf("modul-scope setzen: %w", err)
+	}
+	return nil
+}
+
+func (s *Store) GetModuleScope(ctx context.Context, role rbac.Role, perm rbac.Permission) (ModuleScope, bool, error) {
+	var ms ModuleScope
+	ms.Role, ms.Permission = role, perm
+	err := s.pool.QueryRow(ctx, `
+		SELECT module, flag_key FROM policy_module_scopes WHERE role = $1 AND permission = $2
+	`, string(role), string(perm)).Scan(&ms.Module, &ms.FlagKey)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return ModuleScope{}, false, nil
+		}
+		return ModuleScope{}, false, fmt.Errorf("modul-scope lesen: %w", err)
+	}
+	return ms, true, nil
+}
+
+// AuthorizeForTenant ist dieselbe zentrale Entscheidungsfunktion wie
+// Authorize (Akzeptanzkriterium 3: keine zweite Enforcement-Schicht),
+// erweitert um die Modul-Scoping-Pruefung: eine sonst passende Regel greift
+// NICHT, wenn das zugehoerige Modul fuer den Tenant nicht aktiviert ist
+// (Akzeptanzkriterium 1). Feature-Flag-Aenderungen wirken ohne Neustart
+// (Akzeptanzkriterium 2), da flag.Service dieselbe TTL-Cache-Instanz der
+// aufrufenden Core-Instanz nutzt.
+func (e *Enforcer) AuthorizeForTenant(ctx context.Context, flags *flag.Service, tenantSlug string, role rbac.Role, perm rbac.Permission) error {
+	if err := e.Authorize(ctx, role, perm); err != nil {
+		return err
+	}
+
+	scope, found, err := e.store.GetModuleScope(ctx, role, perm)
+	if err != nil {
+		return err
+	}
+	if !found {
+		return nil // keine Modul-Bindung fuer diese Regel — Grundberechtigung reicht.
+	}
+
+	if !flags.IsEnabled(ctx, tenantSlug, scope.FlagKey) {
+		return fmt.Errorf("%w: modul %q ist fuer diesen mandanten nicht aktiviert", ErrDenied, scope.Module)
+	}
+	return nil
+}
+
+// GuardModuleScoped ist Guard mit zusaetzlicher Modul-Scoping-Pruefung —
+// dieselbe zentrale Enforcement-Funktion, kein paralleler Mechanismus
+// (Akzeptanzkriterium 3).
+func GuardModuleScoped[T any](ctx context.Context, e *Enforcer, flags *flag.Service, tenantSlug string, role rbac.Role, perm rbac.Permission, query func(ctx context.Context) (T, error)) (T, error) {
+	var zero T
+	if err := e.AuthorizeForTenant(ctx, flags, tenantSlug, role, perm); err != nil {
+		return zero, err
+	}
+	return query(ctx)
+}
@@ -0,0 +1,170 @@
+package policy
+
+import (
+	"context"
+	"errors"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"gitea.perlbach24.de/scripte/nexarch/internal/flag"
+	"gitea.perlbach24.de/scripte/nexarch/internal/rbac"
+)
+
+func setupModuleScopeTest(t *testing.T) (*Store, *Enforcer, *flag.Store, *flag.Service, 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 policy_rules (
+			role TEXT NOT NULL, permission TEXT NOT NULL,
+			granted_by TEXT NOT NULL, granted_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+			PRIMARY KEY (role, permission)
+		);
+		CREATE TABLE IF NOT EXISTS policy_rule_changes (
+			id UUID PRIMARY KEY DEFAULT gen_random_uuid(), role TEXT NOT NULL, permission TEXT NOT NULL,
+			action TEXT NOT NULL CHECK (action IN ('grant','revoke')), actor TEXT NOT NULL,
+			version INT NOT NULL, changed_at TIMESTAMPTZ NOT NULL DEFAULT now()
+		);
+		CREATE TABLE IF NOT EXISTS policy_module_scopes (
+			role TEXT NOT NULL, permission TEXT NOT NULL, module TEXT NOT NULL, flag_key TEXT NOT NULL,
+			PRIMARY KEY (role, permission)
+		);
+		CREATE TABLE IF NOT EXISTS feature_flags (
+			key TEXT PRIMARY KEY, enabled BOOLEAN NOT NULL DEFAULT false,
+			rollout_percentage INT NOT NULL DEFAULT 0, target_tenant_slugs TEXT[] NOT NULL DEFAULT '{}',
+			updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+		);
+	`); err != nil {
+		t.Fatalf("schema: %v", err)
+	}
+
+	store := NewStore(pool)
+	flagStore := flag.NewStore(pool)
+	flagService := flag.NewService(flagStore, 10*time.Millisecond) // kurze TTL fuer testbare invalidierung
+
+	cleanup := func() {
+		_, _ = pool.Exec(ctx, `DELETE FROM policy_module_scopes WHERE role LIKE 'test\_%' ESCAPE '\'`)
+		_, _ = pool.Exec(ctx, `DELETE FROM policy_rule_changes WHERE role LIKE 'test\_%' ESCAPE '\'`)
+		_, _ = pool.Exec(ctx, `DELETE FROM policy_rules WHERE role LIKE 'test\_%' ESCAPE '\'`)
+		_, _ = pool.Exec(ctx, `DELETE FROM feature_flags WHERE key LIKE 'test\_%' ESCAPE '\'`)
+		pool.Close()
+	}
+	return store, NewEnforcer(store), flagStore, flagService, cleanup
+}
+
+// Akzeptanzkriterium 1 + Pruefung 1: Berechtigung fuer nicht aktiviertes
+// Modul greift nicht, selbst bei sonst passender Rolle.
+func TestAuthorizeForTenant_DeniesWhenModuleNotActivated(t *testing.T) {
+	store, enforcer, _, flagService, cleanup := setupModuleScopeTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	role := rbac.Role("test_dms_nutzer")
+	perm := rbac.Permission("test_dokumente_lesen")
+	if err := store.Grant(ctx, role, perm, "admin@example.com"); err != nil {
+		t.Fatalf("grant: %v", err)
+	}
+	if err := store.SetModuleScope(ctx, role, perm, "dms", "test_dms_enabled"); err != nil {
+		t.Fatalf("set module scope: %v", err)
+	}
+	// Flag existiert nicht/ist nicht gesetzt -> IsEnabled liefert false (Fail-Safe-Default).
+
+	queryCalled := false
+	_, err := GuardModuleScoped(ctx, enforcer, flagService, "acme", role, perm, func(ctx context.Context) (string, error) {
+		queryCalled = true
+		return "daten", nil
+	})
+	if !errors.Is(err, ErrDenied) {
+		t.Fatalf("erwartet ErrDenied bei deaktiviertem modul, habe %v", err)
+	}
+	if queryCalled {
+		t.Fatal("query haette bei deaktiviertem modul nicht aufgerufen werden duerfen")
+	}
+}
+
+// Akzeptanzkriterium 2 + Pruefung 2: Aktivierung des Moduls macht die
+// Berechtigung ohne Neustart wirksam.
+func TestAuthorizeForTenant_BecomesActiveWithoutRestart(t *testing.T) {
+	store, enforcer, flagStore, flagService, cleanup := setupModuleScopeTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	role := rbac.Role("test_dms_nutzer2")
+	perm := rbac.Permission("test_dokumente_schreiben")
+	if err := store.Grant(ctx, role, perm, "admin@example.com"); err != nil {
+		t.Fatalf("grant: %v", err)
+	}
+	if err := store.SetModuleScope(ctx, role, perm, "dms", "test_dms_enabled2"); err != nil {
+		t.Fatalf("set module scope: %v", err)
+	}
+
+	if err := enforcer.AuthorizeForTenant(ctx, flagService, "acme", role, perm); !errors.Is(err, ErrDenied) {
+		t.Fatalf("vor aktivierung: erwartet ErrDenied, habe %v", err)
+	}
+
+	// Modul "im laufenden Betrieb" aktivieren — derselbe Prozess, kein Neustart.
+	if err := flagStore.Set(ctx, flag.Flag{Key: "test_dms_enabled2", Enabled: true}); err != nil {
+		t.Fatalf("flag setzen: %v", err)
+	}
+	time.Sleep(20 * time.Millisecond) // TTL abwarten statt Neustart
+
+	if err := enforcer.AuthorizeForTenant(ctx, flagService, "acme", role, perm); err != nil {
+		t.Fatalf("nach aktivierung sollte erlaubt sein: %v", err)
+	}
+}
+
+// Akzeptanzkriterium 3 + Pruefung 3: Zusammenspiel Modul-Scope + Rollenscope
+// in Kombinationsfaellen.
+func TestAuthorizeForTenant_CombinationsOfRoleAndModuleScope(t *testing.T) {
+	store, enforcer, flagStore, flagService, cleanup := setupModuleScopeTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	scopedRole := rbac.Role("test_scoped_rolle")
+	unscopedRole := rbac.Role("test_unscoped_rolle")
+	perm := rbac.Permission("test_kombiniert")
+
+	// Fall 1: Rolle ohne jegliche Regel -> verboten, unabhaengig vom Flag.
+	if err := enforcer.AuthorizeForTenant(ctx, flagService, "acme", rbac.Role("test_unbekannt"), perm); !errors.Is(err, ErrDenied) {
+		t.Fatalf("fall 1: erwartet ErrDenied (keine regel), habe %v", err)
+	}
+
+	// Fall 2: Regel vorhanden, KEIN Modul-Scope -> immer erlaubt (Grundrecht ohne Lizenzbindung).
+	if err := store.Grant(ctx, unscopedRole, perm, "admin@example.com"); err != nil {
+		t.Fatalf("grant unscoped: %v", err)
+	}
+	if err := enforcer.AuthorizeForTenant(ctx, flagService, "acme", unscopedRole, perm); err != nil {
+		t.Fatalf("fall 2: erwartet erlaubt ohne modul-scope, habe %v", err)
+	}
+
+	// Fall 3: Regel + Modul-Scope, Flag aus -> verboten.
+	if err := store.Grant(ctx, scopedRole, perm, "admin@example.com"); err != nil {
+		t.Fatalf("grant scoped: %v", err)
+	}
+	if err := store.SetModuleScope(ctx, scopedRole, perm, "mail", "test_mail_enabled"); err != nil {
+		t.Fatalf("set module scope: %v", err)
+	}
+	if err := enforcer.AuthorizeForTenant(ctx, flagService, "acme", scopedRole, perm); !errors.Is(err, ErrDenied) {
+		t.Fatalf("fall 3: erwartet ErrDenied (modul aus), habe %v", err)
+	}
+
+	// Fall 4: Regel + Modul-Scope, Flag an -> erlaubt.
+	if err := flagStore.Set(ctx, flag.Flag{Key: "test_mail_enabled", Enabled: true}); err != nil {
+		t.Fatalf("flag setzen: %v", err)
+	}
+	time.Sleep(20 * time.Millisecond)
+	if err := enforcer.AuthorizeForTenant(ctx, flagService, "acme", scopedRole, perm); err != nil {
+		t.Fatalf("fall 4: erwartet erlaubt (modul an), habe %v", err)
+	}
+}