flat-pilot/docs/hauspilot-auth-integration.md

# HausPilot: Authentifizierungs- und Benutzerintegration

## Ergebnis der Boilerplate-Analyse

HausPilot verwendet unveraendert die vorhandene Backend-for-Frontend-
Authentifizierung. Das Boilerplate spricht keinen bestimmten Hersteller fest,
sondern einen ueber `OIDC_ISSUER` konfigurierten OpenID-Connect-Provider. Der
Login ist ein OIDC Authorization Code Flow mit PKCE, `state` und `nonce`.

Der Browser startet den Login ueber `GET /api/auth/login`. Der Callback liegt
fest unter `<APP_BASE_URL>/api/auth/callback`. Der Backend-Callback validiert
Issuer, Audience, Signaturalgorithmus, Nonce und Subject, laedt gegebenenfalls
UserInfo und legt den lokalen Benutzer an oder aktualisiert ihn. Die stabile
Identitaet beim Provider ist `(issuer, subject)`; fachliche Beziehungen verwenden
ausschliesslich die interne UUID `users.id`.

OIDC Access-, Refresh- und ID-Tokens werden verschluesselt in der MySQL-Tabelle
`sessions` gespeichert. Der Browser erhaelt nur eine signierte, HttpOnly
Session-ID und ein lesbares CSRF-Cookie. Schreibende Requests senden dieses
Cookie ueber den vorhandenen `csrfInterceptor` als `X-CSRF-Token`. Idle- und
Absolute-Timeout werden beim serverseitigen Session-Resolve geprueft. Es gibt
keinen zweiten Token-Refresh im Browser.

Der globale `PermissionsGuard` loest die Session auf, prueft den globalen
Benutzerstatus und setzt `AuthenticatedRequest.user` mit interner UUID,
Session-ID und effektiven Permissions. Controller verwenden weiterhin
`@RequirePermissions(...)`. Deaktivierte Benutzer werden beim Login und bei
jeder Session-Aufloesung abgewiesen; ihre historischen fachlichen Beziehungen
werden nicht geloescht.

Angular ermittelt den aktuellen Benutzer ueber `AuthService.ensureLoaded()` und
`GET /api/me`. Der Auth-State liegt ausschliesslich in dessen Signals. Der
vorhandene `permissionGuard` steuert nur Navigation und Darstellung; das Backend
bleibt verbindlich. Logout erfolgt ausschliesslich ueber `/api/auth/logout`,
widerruft die lokale Session, loescht Session- und CSRF-Cookie und verwendet
danach den OIDC `end_session_endpoint` beziehungsweise `OIDC_LOGOUT_URL`.

## Registrierung und Benutzerprofil

Das Boilerplate besitzt keinen lokalen Registrierungs- oder Passwortdialog und
keine lokale Passwort-Entity. Konten werden durch den vorhandenen Identity
Provider registriert oder bereitgestellt und beim ersten erfolgreichen OIDC-
Login lokal synchronisiert. HausPilot fuehrt daher keine zweite Registrierung
ein. Nach dem ersten Login werden offene Einladungen nur angezeigt, niemals
automatisch angenommen.

Die lokale `UserEntity` speichert UUID, Issuer, Subject, Anzeigename, E-Mail,
Aktivstatus, globale Rollen und Einstellungen. Name und E-Mail werden bei jedem
Login aus dem OIDC-Profil aktualisiert. Aktive Mitgliedschaften bleiben auch bei
einer E-Mail-Aenderung ueber `users.id` stabil. Offene Einladungen bleiben an die
normalisierte urspruengliche Zieladresse gebunden.

Die Integration uebernimmt ausserdem den standardisierten OIDC-Claim
`email_verified`. Eine Einladung kann nur angenommen werden, wenn der Provider
die aktuelle Zieladresse als verifiziert bestaetigt. Fehlt diese Bestaetigung,
wird die Annahme sicher abgewiesen.

## Globale und projektbezogene Autorisierung

Globale Rollen (`admin`, `user` und verwaltete globale Rollen) bleiben von den
HausPilot-Projektrollen getrennt. Eine globale Basis-Permission erlaubt nur die
Verwendung der Projekt-API. Sie erzeugt weder eine Mitgliedschaft noch einen
Zugriff auf ein privates Projekt. Insbesondere erhaelt ein globaler Administrator
keinen impliziten Projektzugriff.

Projektrollen sind `owner`, `administrator`, `editor` und `reader`. Jede
Projektabfrage prueft serverseitig eine aktive Mitgliedschaft und die fuer die
Aktion erforderliche Rolle. Unterentitaeten werden immer zusammen mit der
Projekt-ID geladen beziehungsweise geprueft. Eigentuermer-, Autor- und
Einladender-IDs sind keine DTO-Felder, sondern stammen aus dem vorhandenen
serverseitigen Current-User-Kontext.

Projektanlage, Eigentuemermitgliedschaft und Erstellungsaktivitaet werden in
einer Datenbanktransaktion gespeichert. Projektrollen entstehen nur durch diese
Projektanlage, explizite Einladungsannahme oder eine berechtigte Aenderung im
Projekt; OIDC-Gruppen und globale Rollen werden nicht abgebildet.

## Einladungen und sicherer Rueckkehrpfad

Einladungen speichern die normalisierte E-Mail-Adresse und optional die bekannte
interne Benutzer-ID. Der zufaellige Einladungstoken wird nur im Link ausgegeben;
in MySQL liegt ausschliesslich sein SHA-256-Hash. Annahme und Ablehnung verlangen
eine gueltige bestehende Session. Das Backend prueft Status, Ablauf,
Widerruf, Zieladresse, `email_verified`, aktiven Benutzer und eine noch nicht
bestehende aktive Mitgliedschaft. Fehlermeldungen geben nur eine maskierte
Adresse aus.

Ist ein Besucher nicht angemeldet, verweist Angular auf den bestehenden
`/api/auth/login`-Flow. Der gewuenschte Rueckweg wird serverseitig im kurzlebigen
OIDC-Login-State gehalten. Erlaubt sind nur interne Pfade; Schemes,
Protokoll-relative URLs und Backslashes werden verworfen. Nach dem Callback baut
das Backend das Ziel relativ zu `FRONTEND_BASE_URL` auf. Tokens oder OIDC-Daten
werden nie in Rueckkehrparametern gespeichert.

## Benachrichtigungen, Mail und Cleanup

Das vorhandene `NotificationsService` erzeugt fuer bereits bekannte aktive
Benutzer eine persoenliche In-App-Benachrichtigung. Normale Endpunkte bleiben auf
den Session-Benutzer beschraenkt. Das Boilerplate hat keinen Mail-Service, keine
Templates, Queue oder Retry-Jobs. HausPilot fuehrt keine parallele
Mail-Infrastruktur ein; der Versandstatus einer Einladung wird daher explizit
als `not_configured` gespeichert. Der Einladungsdatensatz bleibt konsistent und
kann spaeter an eine architektonisch beschlossene Mail-Komponente angebunden
werden.

Projektseiten halten Daten nur komponentenlokal. Bei 401 setzt der vorhandene
globale Auth-State den Benutzer zurueck; dadurch werden geschuetzte Seiten
entfernt und das bestehende Notification-Polling samt personenbezogenem Cache
gestoppt. Ein regulaerer Logout verlaesst die SPA und startet sie ohne alten
In-Memory-State neu. HausPilot fuehrt keine Live-Verbindungen ein.

## Relevante Konfiguration

- OIDC: `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`,
  `OIDC_SCOPES`, `OIDC_ALLOWED_ALGORITHMS`, optional `OIDC_LOGOUT_URL`
- Redirects: `APP_BASE_URL`, `FRONTEND_BASE_URL`
- Session: `SESSION_COOKIE_NAME`, Idle-/Absolute-Timeout,
  `SESSION_SECRET`, `SESSION_ENCRYPTION_KEY`
- Browser-Schutz: `CORS_ORIGINS`, `CSRF_HEADER_NAME`, Secure/SameSite-Cookies,
  Helmet, Rate Limits und Logging-Redaction

Es wurde keine parallele Authentifizierungs-, Benutzer-, Passwort-, Token-,
Registrierungs-, Mail-, Queue- oder Live-Connection-Infrastruktur eingefuehrt.