tessera-ctl/docs/mandantentrennung-datenbankrolle.md

Tessera – Mandantentrennung auf Datenbankebene (WINDOWS #18)

Diese Anleitung richtet sich an dieselben Kolleg:innen wie das Betriebshandbuch und behandelt nur einen einzigen Punkt: die Datenbankrolle, mit der Tessera verbindet, und warum die bestehenden Sicherheitsregeln (Row-Level Security) heute keine Wirkung haben.

Inhaltsverzeichnis

1. Der Befund
2. Was bereits vorbereitet ist
3. Der Sperrgrund — warum die Umstellung noch nicht erfolgt ist
4. Die Umstellung, Schritt fuer Schritt
5. Die Vorher-Pruefung
6. Der Rueckweg

---

1. Der Befund

Tessera trennt die Daten mehrerer Mandanten auf zwei Ebenen: im Anwendungscode (where: { tenantId }) und zusaetzlich auf Datenbankebene ueber PostgreSQL Row-Level Security (RLS) — ein „zweites Sicherheitsnetz" fuer den Fall, dass im Code einmal ein tenantId-Filter vergessen wird.

Dieses zweite Netz existiert seit Juni 2026 auf sieben Tabellen und wurde am 2026-09-09 mit einer wichtigen Einschraenkung nachgemessen: es greift derzeit nicht. Die API verbindet laut docker-compose.yml als Rolle tessera. Diese Rolle entsteht aus der Umgebungsvariable POSTGRES_USER und ist damit automatisch Superuser des PostgreSQL-Clusters. PostgreSQL wendet Row-Level Security auf Superuser-Rollen grundsaetzlich nicht an — auch nicht auf Rollen mit dem Recht BYPASSRLS, das Superuser automatisch mitbringen. Der Zusatz FORCE ROW LEVEL SECURITY in den bestehenden Migrationen aendert daran nichts: er erzwingt Policies nur gegenueber dem Tabelleneigentuemer, nicht gegenueber Rollen mit Umgehungsrecht — und die Rolle tessera ist beides zugleich.

Praktisch nachgemessen am 2026-09-09: ein SELECT count(*) FROM "Group" ohne gesetzten Mandantenkontext liefert zwei Zeilen, obwohl die vorhandene Policy USING ("tenantId" = current_tenant_id()) bei fehlendem Kontext null Zeilen liefern muesste. Die Isolation zwischen Mandanten haengt heute vollstaendig am where-Filter im Anwendungscode — nicht an der Datenbank.

Dieser Befund ist als WINDOWS #18 im Fehler-Ledger festgehalten. Kein akutes Risiko, solange Tessera nur intern und einmandantig laeuft — aber zwingend zu beheben, bevor Tessera an einen zweiten, externen Mandanten geht.

2. Was bereits vorbereitet ist

Diese Aenderung liefert die vier Bausteine, die fuer eine wirksame Trennung noetig sind:

• Eine eigene Datenbankrolle tessera_app ohne Superuser- und ohne BYPASSRLS-Recht (Migration 20260909130000_rls_app_role).
• Getrennte Verbindungen fuer Migration und Laufzeit. prisma migrate deploy braucht die Rechte des Tabelleneigentuemers, die Anwendung soll sie nicht haben — apps/api/scripts/migrate-and-start.sh trennt beide Schritte ueber die neue Variable TESSERA_MIGRATE_DATABASE_URL.
• Ein Pruefwerkzeug, das den Nachweis fuehrt statt ihn zu behaupten: apps/api/scripts/rls-preflight.mjs misst gegen eine angegebene Verbindung Rollenrechte, Setzbarkeit des Mandantenkontexts, sichtbare Zeilen mit und ohne Kontext sowie vorhandene Zugriffsrechte.
• Vollstaendige Policy-Abdeckung. Migration 20260909140000_rls_remaining_tenant_tables ergaenzt die bislang fehlenden 16 Tabellen; alle 20 Tabellen mit tenantId tragen jetzt eine Regel.
• Eine zweite Sitzungsvariable fuer die Benutzerdimension. Neben app.current_tenant (Migration 20260618112133_rls_policies, current_tenant_id()) setzt die Rolle seit Migration 20260911120000_rls_user_dimension_personal_tables (Etappe 3b, 260911-nke) zusaetzlich app.current_user. Die zugehoerige Funktion current_user_id() faltet den Leerstring per NULLIF auf NULL — der Helfer forTenant() sendet "kein Benutzer" ausdruecklich als Leerstring, nicht als weggelassene Variable, damit ein Aufruf ohne Benutzer nie einen Benutzer aus einer fruaheren Transaktion derselben Verbindung erben kann. Kein GRANT EXECUTE noetig — wie bei current_tenant_id() vergibt PostgreSQL EXECUTE auf Funktionen standardmaessig an PUBLIC. Die Regeln der zehn persoenlichen Tabellen (CalendarSource, DashboardLayout, FavoriteLink, SearchProvider, TenderEmailConfig, TenderNotificationPref, TenderRssFeedSource, TenderSavedSearch, TenderTriage, WidgetInstance) pruefen current_user_id() IS NULL OR "userId" = current_user_id() — ein Aufruf OHNE gesetzten Benutzer (Admin, Hintergrunddienst) sieht weiterhin den ganzen Mandanten, das macht die Aenderung fuer heutige Aufrufer wirkungslos.
• Eine dritte Sitzungsvariable fuer den Systemkontext. Migration 20260914120000_rls_system_context_read (Etappe 3c, 260914-eym) bringt app.system_context und die Funktion is_system_context() — COALESCE(current_setting('app.system_context', true) = 'true', false), damit die Regel ohne gesetzte Variable FALSE sieht, nicht NULL — sowie je eine zusaetzliche PERMISSIVE Regel system_read_policy ... FOR SELECT USING (is_system_context()) auf genau den fuenf Tabellen, die die Hintergrunddienste ueber alle Mandanten LESEN (DkvModuleConfig, LdapConfig, LdapFieldMapping, TenderMatch, TenderSavedSearch). Permissive Regeln werden ODER-verknuepft: fuer SELECT gilt (Mandantenregel ODER Systemregel), fuer INSERT/UPDATE/DELETE weiter NUR die Mandantenregel — unter Systemkontext ist current_tenant_id() der Leerstring, jedes Schreiben faellt durch (gemessen: 42501 / count 0 / P2025). Der Helfer forSystem() setzt app.system_context = 'true' und die beiden anderen Variablen AUSDRUECKLICH leer; forTenant() und withTenantTransaction() setzen umgekehrt app.system_context = '' — kein Kontext erbt vom anderen (local=true als erstes Netz, der Reset als zweites, beides im Werkzeug gemessen und durch Rueckbau belegt). Kein GRANT EXECUTE noetig, wie bei den beiden anderen Funktionen.

3. Der Sperrgrund — warum die Umstellung noch nicht erfolgt ist

Die Verbindung ist bewusst noch nicht umgestellt, und sie darf noch nicht umgestellt werden.

Nachgemessen und korrigiert am 2026-09-09 (260909-eor, Aufgabe 3): die zuvor hier genannte Zahl 182 stammte aus einer groeberen Zaehlung vor dieser Etappe und ist ueberholt. Die aktuelle, maschinell ermittelte und durch apps/api/src/prisma/rls-access-inventory.spec.ts dauerhaft gepruefte Bestandsaufnahme steht in docs/mandantentrennung-zugriffsklassifikation.md: 227 this.prisma.*-Fundstellen in apps/api/src (ohne Tests), zusammengefasst zu 59 (Datei, Modell)-Paaren, davon 31 muss-mandantengebunden und 9 beides (Hintergrunddienst mit sowohl uebergreifendem Lesen als auch mandantengebundenem Schreiben je Zeile) — zusammen der eigentliche Arbeitsvorrat fuer die Umstellung. 16 Paare betreffen keine mandantengebundene Tabelle (plattformweite Daten wie der Ausschreibungs- und Modulkatalog, D-03) und 3 sind bewusst uebergreifend mit ausgeschriebenem Grund. Zusaetzlich zu beachten: das entdeckte, aber in dieser Etappe nicht behobene forTenant()-Verbindungsproblem (WINDOWS #20, siehe unten). WINDOWS #19 (nullbares tenantId bei SearchProvider/TenderRssFeedSource) ist GESCHLOSSEN (260910-jab, Migration 20260910120000_rls_widen_membership_grant_and_platform_read) — siehe docs/mandantentrennung-zugriffsklassifikation.md, Abschnitt "Zwei belegte Befunde", und .planning/WINDOWS.md. Offen geblieben ist der Verwaltungsweg fuer plattformweite Zeilen unter der Anwendungsrolle (WINDOWS #24).

Darunter war bis Aufgabe 2 dieser Etappe auch der Anmeldeweg selbst, der strukturell nicht anders funktionieren konnte: apps/api/src/auth/auth.service.ts suchte den Benutzer anhand des Benutzernamens, bevor der Mandant bekannt war. Das ist inzwischen geloest — drei enge SECURITY-DEFINER-Funktionen (auth_lookup_user_by_username, auth_lookup_user_by_email, auth_lookup_reset_token, Migration 20260909160000_auth_lookup_functions) uebernehmen die drei pre-tenant Lesezugriffe, alle nachfolgenden Schreibzugriffe laufen ueber forTenant().

Weiterhin betroffen sind Hintergrunddienste, die von Natur aus ohne Mandantenkontext laufen: der AD-Abgleich, der Ausschreibungs-Digest, die Ausschreibungs-Sofortmeldung und die Erstanlage des Administrators beim ersten Start — Details und Begruendung je Fundstelle in docs/mandantentrennung-zugriffsklassifikation.md.

Diese Stellen brauchen einen ausdruecklichen, benannten Systemkontext (oder eine gezielte Umstellung auf forTenant()), bevor der Schalter umgelegt werden darf. Das ist eigene Arbeit und nicht Teil dieser Aenderung (Etappe 2/3 der Mandantentrennung). Ein gruener Bericht des Pruefwerkzeugs aus Abschnitt 5 belegt ausschliesslich, dass die Datenbankseite stimmt — er sagt nichts ueber diese Zugriffe aus.

Nachtrag (260914-eym, Etappe 3c): der Systemkontext ist gebaut — siehe den Punkt "Eine dritte Sitzungsvariable" in Abschnitt 2 und docs/mandantentrennung-etappe2-fehlerrichtung.md, Abschnitt "## Systemkontext (Etappe 3c, 260914-eym)". Vier Hintergrunddienst-Dateien lesen ueber forSystem(), der Mail-Startpfad ist entfernt, die Erstanlage des Administrators liest nur Tenant (keine Regel). Die Vorher-Pruefung ohne-kontext-leer in rls-preflight.mjs (Abschnitt 5) bleibt GUELTIG und wird durch die neue Regel NICHT gelockert: ohne gesetzte Variable ist is_system_context() false — Werkzeugbeleg is-system-context-ungesetzt-false (rls-scratch-check.mjs, Rohwert null -> false). Etappe 4 ergaenzt die Vorher-Pruefung um mit-systemkontext-sichtbar (mit app.system_context = 'true' sind die fuenf Tabellen lesbar); rls-preflight.mjs ist in 3c bewusst nicht angefasst.

Zusaetzlicher Sperrgrund, ebenfalls am 2026-09-09 gemessen (WINDOWS #20): forTenant() selbst war bis Aufgabe 1 dieser Etappe defekt — set_config() lief auf einer anderen Datenbankverbindung als die eigentliche Abfrage, sodass selbst die 6 bisherigen forTenant()-Aufrufstellen (alle in apps/api/src/ldap/ldap.service.ts sowie tenant.middleware.ts/ tenant.guard.ts) den Mandantenkontext nie tatsaechlich gesetzt haben. Das ist inzwischen repariert (Array-Form von $transaction, prisma-tenant.extension.ts) und durch apps/api/scripts/rls-scratch-check.mjs live nachgewiesen. Ohne diese Reparatur waere jede Umstellung auf forTenant() in den folgenden Etappen wirkungslos gewesen.

4. Die Umstellung, Schritt fuer Schritt

Erst durchfuehren, wenn Abschnitt 3 abgearbeitet ist. Reihenfolge einhalten — die Migration muss weiterhin als Tabelleneigentuemer laufen.

1. Kennwort der Rolle einmalig setzen, als Datenbank-Superuser:

   ALTER ROLE tessera_app WITH PASSWORD '<hier ein starkes, generiertes Kennwort einsetzen>';
   

   Dieser Befehl gehoert in keine Datei und in kein Protokoll — er wird direkt an psql uebergeben und danach aus der Shell-Historie entfernt.

2. In der .env des Servers TESSERA_MIGRATE_DATABASE_URL auf die bisherige Verbindung (Rolle tessera, Tabelleneigentuemer) setzen und DATABASE_URL auf die neue Rolle tessera_app umbiegen — in dieser Reihenfolge, denn prisma migrate deploy muss weiterhin mit Eigentuemerrechten laufen, waehrend die Anwendung selbst die eingeschraenkte Rolle bekommt.

3. Vor dem Neustart die Vorher-Pruefung aus Abschnitt 5 gegen die neue Rolle ausfuehren.

4. API-Dienst neu erstellen (docker compose up -d --build --force-recreate api, siehe Betriebshandbuch Abschnitt 4).

5. Die Vorher-Pruefung

TESSERA_PREFLIGHT_DATABASE_URL="postgresql://tessera_app:<kennwort>@<host>:5432/tessera" \
  node apps/api/scripts/rls-preflight.mjs

Das Werkzeug meldet fuenf Pruefungen: Rollenrechte, Setzbarkeit des Mandantenkontexts, keine sichtbaren Zeilen ohne Kontext, sichtbare Zeilen mit Kontext, vollstaendige Zugriffsrechte. Es veraendert nichts — es liest ausschliesslich.

Ein gruener Bericht ist die Freigabebedingung fuer Schritt 4 aus Abschnitt 4 — aber er ist keine Freigabe fuer die Umstellung insgesamt. Er bestaetigt nur, dass die Datenbankseite stimmt. Die unskalierten Zugriffe aus Abschnitt 3 (siehe docs/mandantentrennung-zugriffsklassifikation.md fuer den aktuellen Stand) misst er nicht und kann sie nicht messen — dafuer muesste er den Anwendungscode lesen, nicht die Datenbank.

6. Der Rueckweg

Wenn die API nach einer Umstellung nicht mehr hochkommt:

Das sichtbare Bild: der api-Container bleibt ungesund (Healthcheck schlaegt fehl), und das Protokoll (docker compose logs api) zeigt einen Authentifizierungs- oder Rechtefehler von PostgreSQL — etwa eine fehlgeschlagene Anmeldung oder eine verweigerte Berechtigung.

Weg zurueck, zwei Schritte:

1. DATABASE_URL in der .env wieder auf die bisherige Verbindung (Rolle tessera) setzen.
2. docker compose up -d --build --force-recreate api ausfuehren.

Die Rolle tessera_app darf dabei unangetastet bestehen bleiben — sie schadet nicht, solange niemand mit ihr verbindet.

Wichtiger Hinweis fuer den Server: /opt/tessera/docker-compose.yml ist keine Arbeitskopie dieses Repositorys. Aenderungen an docker-compose.yml oder docker-compose.prod.yml in diesem Repository erreichen den Server nicht automatisch. Wer TESSERA_MIGRATE_DATABASE_URL dort verfuegbar haben will, traegt die Zeile selbst in /opt/tessera/docker-compose.yml ein (vorher sichern) — genau wie es bereits fuer andere nachtraegliche Variablen dokumentiert ist (Betriebshandbuch, Abschnitt zur Server-Konfiguration).