Shuffle/docs/specs/1-auth-spike-ergebnisse.md

# Spike B0 – Ergebnisse zu GoTrue (Spec #1, KTO-01)

| | |
|---|---|
| Issue | #1 (KTO-01), Aufgabe B0 |
| Spec | `docs/specs/1-auth-registrierung-anmeldung.md` (§ 4.1, 4.3, 5.4, 7.1, 8.2, 9.1) |
| Datum | 2026-11-02 |
| Autor | backend-dev |
| Versionen | Supabase CLI 3.0.0, GoTrue `v2.197.0` (Image `public.ecr.aws/supabase/gotrue:v2.197.0`), Postgres 17.11, Mailpit v1.31.3 |

## Vorgehen und Grenzen der Aussagekraft

- Die lokale CLI wurde mit einer **temporären** `config.toml` gestartet: `enable_confirmations = true`, `minimum_password_length = 10`, `email_sent = 100`, `max_frequency = "1s"`, Vorlagen für Bestätigung und Reset mit `.Data.locale`-Verzweigung (Vorlagen und Änderungen sind wieder entfernt; `config.toml` im Repo ist unverändert, das ist Aufgabe B2).
- Alle Requests liefen gegen `http://127.0.0.1:54321/auth/v1` (Kong, wie die App). Die Drosselungstests (c, d) liefen zusätzlich gegen einen **zweiten GoTrue-Container** desselben Images im Netz der CLI, mit den Umgebungsvariablen des CLI-Containers plus `GOTRUE_RATE_LIMIT_HEADER=X-Forwarded-For` und `GOTRUE_RATE_LIMIT_EMAIL_SENT=5`. Das entspricht dem Self-Hosting-Pfad (Env statt `config.toml`).
- **Korrektur während des Spikes:** Die erste Messung zu Krit. 4 zeigte 422 `user_already_exists`; die Ursache war `GOTRUE_SMS_AUTOCONFIRM=true` (CLI-Standard), nicht GoTrue selbst. Ein Wiederholungstest mit `[auth.sms] enable_confirmations = true` bestätigt das Verhalten der Spec (siehe A1).
- **Nicht aussagekräftig lokal:** SMTP-Anbieter, Verhalten hinter dem echten Produktions-Gateway, Header-Behandlung durch den Proxy, Mailzustellung. Die Mail-Rate-Limits der CLI gelten nicht (siehe d).
- Die Versionsprüfung (h) basiert auf der `docker-compose.yml` im Supabase-Repository (Stand heute, Branch `master`); eine eigene Self-Hosting-Instanz gibt es noch nicht.

## Kurzfassung: Abweichungen von der Spec

| # | Abweichung | Wirkung |
|---|---|---|
| **A1** | **Der Enumerationsschutz (Krit. 4) hängt an einer weiteren Einstellung: `GOTRUE_SMS_AUTOCONFIRM` muss `false` sein.** Die CLI-Vorlage setzt `[auth.sms] enable_confirmations = false` und damit `GOTRUE_SMS_AUTOCONFIRM=true`. Dann liefert Signup mit einer *bestätigten* Adresse **422 `user_already_exists`**. Mit `[auth.sms] enable_confirmations = true` (`GOTRUE_SMS_AUTOCONFIRM=false`) kommt wie in der Spec **200 mit erfundenem Nutzer** (zufällige ID, `identities` leer, keine Mail, Log `user_repeated_signup`). | Neue Zeile AUTH-CFG-24 für B2/B3 (`auth.sms.enable_confirmations = true`, Env `GOTRUE_SMS_AUTOCONFIRM=false`). Die Selbsthosting-Vorlage `docker/.env.example` setzt `ENABLE_PHONE_AUTOCONFIRM=true`, die Falle gilt dort also auch. Die Spec-Annahme 4.3 stimmt dann. |
| **A2** | **Ohne `GOTRUE_RATE_LIMIT_HEADER` gibt es gar keine IP-Drosselung** (weder Login noch Signup noch Refresh). Auch mit gesetzter Konfiguration wird ein Request **ohne** diesen Header nicht gedrosselt (60 Fehllogins ohne `X-Forwarded-For` gegen den Container mit Header-Konfiguration: kein 429). Die lokale CLI kann den Header nicht setzen. | AUTH-CFG-13 ist Pflicht, nicht optional. GoTrue darf nur über den Proxy erreichbar sein, der den Header setzt (sonst umgeht ein direkter Zugriff die Drosselung). Drosselungstests (Krit. 7) sind gegen die CLI nicht möglich (Frage Q1). Betrifft B2, B3, D1, D2, T3. |
| **A3** | `email_sent` wirkt in der lokalen CLI nicht (`GOTRUE_RATE_LIMIT_EMAIL_SENT=360000`, obwohl `email_sent = 100` gesetzt war). Wirkt im Self-Hosting-Env und ist dort **instanzweit**. | AUTH-CFG-09 lokal nicht testbar; Seiteneffekt auf Enumeration (siehe d). |
| **A4** | Trigger-Fehler kommen als **HTTP 500 mit der Meldung des Triggers** im Body (`{"code":"P0001","message":"display_name_invalid"}`), nicht als generisches „Database error saving new user“. | Der Client kann den Grund unterscheiden. Verhalten ist versionsabhängig, siehe (f). |
| **A5** | Das JWT einer Recovery-Sitzung trägt `amr = [{"method":"otp"}]`, **identisch** zur Sitzung nach Bestätigungslink. Es ist also nicht als Recovery erkennbar. | Der `amr`-Weg aus 5.4 entfällt; es gilt R12 (Pfad „Wenn nein“). |
| **A6** | Für den Linkablauf zählt `auth.users.confirmation_sent_at` bzw. `recovery_sent_at`, **nicht** `auth.one_time_tokens.created_at`. | T3 setzt die Spalten an `auth.users` zurück. |
| **A7** | `/otp` und `/magiclink` lassen sich nicht abschalten, und ein neues Konto per `/otp` ist möglich, **wenn** der Aufrufer gültige Metadaten (`data`) mitschickt. Ohne Metadaten blockiert der Trigger (500). | AUTH-CFG-20 (Gateway-Sperre) bleibt nötig; der Trigger ersetzt sie nicht. |

Alle übrigen Annahmen der Spec wurden bestätigt (Details unten).

## Ergebnis je Punkt

### (a) Betreffzeile und Vorlage werten `.Data.locale` aus

- **Annahme:** Vorlage und Betreff lassen sich mit `{{ if and .Data (eq (index .Data "locale") "de") }}` verzweigen; sonst Englisch.
- **Test:** Signup mit `locale` de, en und ohne `locale`; Mails in Mailpit gelesen. Danach `profiles.locale` auf `en` gesetzt (Sync-Trigger) und Passwort-Reset angefordert.
- **Ergebnis: bestätigt.** `de` führte zu deutschem Betreff und Text, `en` und fehlende Angabe zu Englisch. Betreff und Text verzweigen gleich. Nach der Profiländerung auf `en` kam die Reset-Mail englisch (Sync-Trigger wirkt Ende-zu-Ende). `index .Data "locale"` ist sicher, wenn der Schlüssel fehlt (leer, kein Fehler). Die CLI liefert die Vorlagen per interner URL (`GOTRUE_MAILER_TEMPLATES_*=http://…kong:8088/email/…`), wie beim Self-Hosting.
- **Konsequenz B2:** Der Rückfall „zweisprachiger Betreff“ ist nicht nötig. `{{ .Data.locale }}` und `index` funktionieren beide; für Else-Zweig `index` verwenden.

### (b) `type`-Werte für `token_hash`

- **Test:** `POST /verify` mit `token_hash` aus der Mail.
- **Ergebnis: bestätigt.** Bestätigung: `type=email` **und** `type=signup` werden akzeptiert (beide getestet, Sitzung wird ausgestellt, `email_confirmed_at` gesetzt). Reset: `type=recovery`. Ein Token ist nach der Einlösung verbraucht: zweiter Versuch 403 `otp_expired` („Email link is invalid or has expired“).
- **Konsequenz B2/A2/A4:** Bestätigungsvorlage mit `type=email`, Reset mit `type=recovery`. Der Client mappt `otp_expired` (403) auf `linkInvalidOrExpired`, auch für „schon benutzt“.

### (c) Limiter beim Passwort-Login (AUTH-CFG-10)

- **Annahme:** Passwort-Login nutzt den Token-Limiter (150 je 5 min je IP, Burst 30).
- **Test:** Fehlgeschlagene Logins in Schleife. (1) Gegen die CLI über Kong: 600 Logins, 300 Refresh-Aufrufe, 80 Signups, 80 Recovers in wenigen Sekunden, **kein einziges 429**. (2) Gegen den Spike-Container mit `GOTRUE_RATE_LIMIT_HEADER=X-Forwarded-For` und fester Quell-IP: Login #31 wird mit **429 `over_request_rate_limit`** abgelehnt (Burst 30). Nach 20 s waren wieder 10 Logins möglich (etwa 0,5 pro Sekunde, also 150 je 300 s). Signup: ebenfalls Burst 30, danach 429 (Limiter `RATE_LIMIT_OTP` = 30 je 5 min). Eine zweite Quell-IP war währenddessen nicht betroffen. Die 429-Antwort hat **keinen** `Retry-After`- oder `X-RateLimit-*`-Header, nur `X-Sb-Error-Code: over_request_rate_limit`.
- **Ergebnis: Limiter bestätigt, aber mit schwerwiegender Einschränkung (A2).** Passwort-Login nutzt `GOTRUE_RATE_LIMIT_TOKEN_REFRESH` (150 je 5 min, Burst 30); Signup/Recover/Resend nutzen `GOTRUE_RATE_LIMIT_OTP` (30 je 5 min). **Ohne `GOTRUE_RATE_LIMIT_HEADER` greift keiner der Limiter.** Die CLI setzt den Header nicht und bietet keinen Schalter dafür; lokal und im CI (CLI) gibt es deshalb keine Drosselung. Zusätzlich zeigen die Audit-Logs `ip_address: ""`.
- **Konsequenz:**
  - AUTH-CFG-13 ist für Staging/Prod **zwingend** (sonst keine Drosselung von Passwort-Raten, Krit. 7). Der Proxy muss den Header setzen und Client-Werte überschreiben.
  - T3/D2: Der Drosselungstest (Krit. 7) kann nicht gegen die CLI laufen. Optionen siehe Frage Q1.
  - Die Tabelle AUTH-CFG-10/11: Env-Namen stimmen (`…_TOKEN_REFRESH`, `…_OTP`). Die Aussage „Signups, Recover, Resend teilen sich diesen Limiter“ ist nur für Signup geprüft; `/recover` wurde bei unbekannten Adressen nicht gedrosselt, weil keine Mail ausgelöst wird (nur das IP-Limit gilt, und das greift ohne Header nicht).

### (d) `email_sent` instanzweit?

- **Test:** Spike-Container mit `GOTRUE_RATE_LIMIT_EMAIL_SENT=5`. Sechs Signups mit verschiedenen Adressen und verschiedenen Quell-IPs.
- **Ergebnis: bestätigt, instanzweit.** Signup 1–5 ok, ab Signup 6 429 `over_email_send_rate_limit` („email rate limit exceeded“) für alle IPs. Das gilt auch für `/recover` an bestehende Adressen. In der **lokalen CLI** wirkt `email_sent` nicht: der CLI-Container läuft mit `GOTRUE_RATE_LIMIT_EMAIL_SENT=360000`, obwohl `config.toml` 100 enthielt (die CLI-Doku nennt „Requires auth.email.smtp to be enabled“). Der Standard der CLI-Vorlage (`email_sent = 2`) greift also lokal ebenfalls nicht.
- **Neue Nebenwirkung auf Krit. 4:** Ist das Mail-Limit erschöpft, antwortet `/recover` für eine **bestehende** Adresse mit 429, für eine unbekannte Adresse mit 200 (es wird keine Mail ausgelöst). Das ist ein Enumerations-Seitenkanal während der Sperre. Mögliche Gegenmaßnahmen: Limit höher setzen oder ein Proxy vor GoTrue. Siehe Frage Q2.
- **Konsequenz B2/B3:** AUTH-CFG-09 nur im Env-Block wirksam; in `config.toml` den Wert dokumentieren, aber als „lokal ohne Wirkung“ kennzeichnen. R3 bleibt bestehen.

### (e) Mailfänger

- **Ergebnis:** **Mailpit** v1.31.3 (Container `supabase_inbucket_shuffle`, Name historisch). Web-Oberfläche und API: `http://127.0.0.1:54324`. Relevante Endpunkte: `GET /api/v1/messages` (Liste mit `To[].Address`, `Subject`, `ID`), `GET /api/v1/message/{id}` (`HTML`, `Text`), `DELETE /api/v1/messages`. SMTP-Port nach außen nur mit `smtp_port` in `[local_smtp]`.
- **Konsequenz T3:** Der Mail-Helfer spricht die Mailpit-API. Das Token steht im HTML (und im Text) doppelt; das erste Vorkommen genügt. Mails je Test per `To` filtern (zufällige Adressen), nicht per globalem Löschen, wenn Tests parallel laufen.

### (f) Trigger-Fehler bei `signUp`

- **Test:** Signup ohne `display_name`, ohne Altersbestätigung (`age_confirmed:"false"`), ohne `terms_version`.
- **Ergebnis: abweichend (A4).** HTTP **500**, Header `X-Sb-Error-Code: unexpected_failure`, Body `{"code":"P0001","message":"display_name_invalid"}` (bzw. `age_confirmation_required`, …). Der Text des Triggers wird also durchgereicht. Im GoTrue-Log steht zusätzlich „current transaction is aborted“. Es entsteht kein Nutzer.
- **Konsequenz A1/A2 (Flutter):** `registrationRejected` darf an `AuthException.message` unterscheiden, ist aber nur zum Logging und für Zusatzhinweise gedacht; die Hauptvalidierung bleibt im Client. Das Format ist nicht stabil vertraglich zugesichert (bei GoTrue-Updates erneut prüfen; T3 sichert es mit einem API-Test ab).

### (g) `weak_password`

- **Test:** Signup mit 9 Zeichen.
- **Ergebnis: bestätigt.** HTTP 422, `error_code: weak_password`, `msg: "Password should be at least 10 characters."`, `weak_password.reasons = ["length"]`. Mit `password_requirements = ""` kommt kein Grund `characters`.
- **Konsequenz A1:** Mapping 4.4 stimmt.

### (h) Versionen CLI und Self-Hosting-Image

- **Ergebnis: bestätigt.** CLI 3.0.0 startet GoTrue `v2.197.0`. Die `docker-compose.yml` des Supabase-Repos (Branch `master`, heute) verwendet `supabase/gotrue:v2.197.0`. Das Image `public.ecr.aws/supabase/gotrue:v2.197.0` ließ sich mit den Env-Variablen der CLI direkt starten (zusätzlich erforderlich: `API_EXTERNAL_URL`).
- **Konsequenz B3/D1:** Das Self-Hosting-Image beim Aufsetzen auf `v2.197.0` pinnen (nicht `latest`) und bei jedem Update die Punkte (c), (d), (f) wiederholen. Die Postgres-Version im Compose (17.6.1.136) weicht von der CLI (17.11.0.011) im Patchstand ab; Hauptversion 17 stimmt mit `config.toml` überein.

### (i) Welche Spalte begrenzt die Linkgültigkeit?

- **Test:** Neuen Reset angefordert, nur `auth.users.recovery_sent_at` um 2 h zurückgesetzt, Token eingelöst. Dann neuen Reset, nur `auth.one_time_tokens.created_at` um 2 h zurückgesetzt, Token eingelöst. Für die Bestätigung `confirmation_sent_at` ebenso.
- **Ergebnis: bestätigt für `auth.users`, abweichend von der Tabelle.** Zurückgesetztes `recovery_sent_at` (bzw. `confirmation_sent_at`) ergibt 403 `otp_expired`. Zurückgesetztes `one_time_tokens.created_at` allein hat **keine** Wirkung (Einlösung gelang).
- **Konsequenz T3:** `e2e/support/db.ts` setzt `auth.users.recovery_sent_at` (Reset) bzw. `confirmation_sent_at` (Bestätigung) auf `now() - (otp_expiry + 1 s)`. Direktzugriff als `postgres` (Port 54322) genügt.

### (j) `amr` im Recovery-JWT

- **Test:** Access-Token nach `verify` mit `type=recovery`, nach `verify` mit `type=email` und nach Passwort-Login dekodiert.
- **Ergebnis: abweichend (A5).** Recovery: `amr = [{"method":"otp"}]`, `aal1`. Bestätigung: ebenfalls `otp`. Passwort-Login: `password`. Recovery ist von einer Bestätigungssitzung nicht unterscheidbar; nach dem Passwortwechsel in der Sitzung bleibt der Eintrag gleich.
- **Konsequenz A4/R12:** Pfad „Wenn nein“ aus 5.4: Der Guard `passwordRecovery` lebt nur im laufenden Prozess (Ereignis `passwordRecovery`). Eine Ableitung aus `amr = otp` würde auch frisch bestätigte Konten in den Reset-Screen zwingen und ist nicht zulässig. R12 bleibt als akzeptiertes Restrisiko.

## Weitere geprüfte Annahmen (4.3 und Tabelle 4.1)

| Annahme | Test | Ergebnis |
|---|---|---|
| **Krit. 4, bestätigte Adresse:** 200 mit erfundenem Nutzer, keine Mail | Signup mit bestätigter Adresse, zuerst mit CLI-Standard, dann mit `[auth.sms] enable_confirmations = true` | **Nur mit `GOTRUE_SMS_AUTOCONFIRM=false` bestätigt (A1):** Dann 200, zufällige ID (nicht die des echten Nutzers), `identities` leer, keine Mail, kein neues Konto, das ursprüngliche Passwort bleibt gültig. Mit dem CLI-Standard (`SMS_AUTOCONFIRM=true`) kommt stattdessen 422 `user_already_exists`. |
| **Krit. 4, unbestätigte Adresse:** Mail erneut, Passwort und Metadaten unverändert | Signup mit neuem Passwort und neuer `locale` für unbestätigte Adresse | **Bestätigt:** 200 mit echtem Nutzer, Bestätigungsmail erneut, Passwort-Hash und `user_metadata` unverändert, kein zweites Konto. |
| Resend / Reset immer 200 | `/resend` und `/recover` mit bestätigter, unbestätigter und unbekannter Adresse | **Bestätigt** (200 `{}`); Mail geht nur an eine existierende, passende Adresse. Einschränkung bei Mail-Limit: siehe (d). |
| **Krit. 6/7:** `email_not_confirmed` erst nach richtigem Passwort | Login unbestätigt mit richtigem/falschem Passwort, unbekannte Adresse | **Bestätigt:** richtig → 400 `email_not_confirmed`; falsch und unbekannt → 400 `invalid_credentials`, identische Meldung. |
| **Krit. 8:** Reset-Link einmalig | Zweites Einlösen | **Bestätigt** (403 `otp_expired`). |
| **Krit. 9:** Reset beendet andere Sitzungen | Sitzungen A, B; Reset über Recovery-Sitzung; Passwort geändert | **Bestätigt:** Refresh-Token von A und B → `refresh_token_not_found`. Der alte Access-Token von A wird von GoTrue (`/user`) mit 403 abgelehnt, **von PostgREST aber weiter akzeptiert (200)**, bis er abläuft. Das ist R8 (bis 60 min), bewusst akzeptiert. |
| `same_password` | Reset mit altem Passwort | **Bestätigt:** 422 `same_password`. |
| Passwortmindestlänge 10 | Signup mit 9 Zeichen | **Bestätigt** (siehe g). |
| Benachrichtigungen aus (Krit. 11) | Passwortänderung beobachtet | **Bestätigt:** Es kommt keine Mail. Der CLI-Standard ist „aus“; in `config.toml` trotzdem explizit setzen. |
| Magic Link abschaltbar (AUTH-CFG-20) | `/otp` und `/magiclink` für bestätigten Nutzer; `/otp` für neue Adresse | **Nicht abschaltbar (A7):** Bestätigter Nutzer bekommt Mail „Your sign-in link“. Neue Adresse **ohne** Metadaten: 500 durch den Trigger (`age_confirmation_required`), kein Nutzer. Neue Adresse **mit** gültigen Metadaten: Konto wird angelegt (unbestätigt, mit Passwort-Hash eines Zufallswerts) und eine Bestätigungsmail geht raus. Ein zweiter Aufruf innerhalb von `max_frequency` ergibt 429. |
| Zusätzliche Auffälligkeit | – | `GOTRUE_MAILER_SECURE_EMAIL_CHANGE_ENABLED=true` (CLI-Standard) bleibt für KTO-11 offen (AUTH-CFG-23). |

## Konsequenzen für B2, B3 und die übrigen Aufgaben

- **B2:** Alle Werte aus 4.1 in `config.toml`. `email_sent` und die Rate-Limit-Einstellungen sind lokal wirkungslos bzw. nur mit Header wirksam; das im Kommentar kenntlich machen. Vorlagen: `type=email` / `type=recovery`, `index .Data "locale"`.
- **B3:** Der Env-Block für Self-Hosting muss `GOTRUE_RATE_LIMIT_HEADER` als Pflicht aufführen, plus `GOTRUE_RATE_LIMIT_EMAIL_SENT`, `…_TOKEN_REFRESH`, `…_OTP`, `…_VERIFY`. Release-Checkliste: Drosselung am echten Gateway mit 31 Fehllogins einer IP prüfen; Test, dass ein gefälschter `X-Forwarded-For` überschrieben wird.
- **Spec-Anpassungen** (nach Entscheidung von Chris): 4.3 (Krit. 4, Enumeration), 5.4 (`amr`), 7.1 (Krit. 7, 8, 4), 8.2 (B0-Text), R2, R3, R6, R12.
- **B2/B3 (neu, A1):** Zeile AUTH-CFG-24 ergänzen: `auth.sms.enable_confirmations = true` bzw. `GOTRUE_SMS_AUTOCONFIRM=false` (SMS ist ausgeschaltet, die Einstellung steuert trotzdem den Enumerationsschutz bei E-Mail-Signup). T3 sichert das mit einem API-Test für Krit. 4 ab (bestätigte Adresse → 200, `identities` leer).
- **T3:** Drosselungstests nur gegen einen GoTrue mit gesetztem Header und Requests mit Header (Q1).
- **KTO-11-Hinweis:** `user_metadata.locale` kann der Nutzer selbst über `auth.updateUser(data: …)` ändern, die Mailsprache kann so von `profiles.locale` abweichen (Wirkung nur auf das eigene Konto). Der Client ändert die Sprache ausschließlich über `profiles`; der Sync-Trigger zieht `user_metadata` bei der nächsten Profiländerung nach.

## Offene Fragen an Chris

| # | Frage | Hintergrund |
|---|---|---|
| Q1 | **Krit. 7:** Die lokale CLI kann keine IP-Drosselung (kein `RATE_LIMIT_HEADER`). Soll der Drosselungstest im CI gegen einen zusätzlich gestarteten GoTrue-Container mit gesetztem Header laufen (wie in diesem Spike), oder nur als manuelle Prüfung auf Staging? | A2, Aufwand für D2/T3. |
| Q2 | Seitenkanal bei erschöpftem Mail-Limit (`/recover` bestehende Adresse 429, unbekannte 200). Akzeptiert (Limit 30/h, Angriff erzeugt vor allem Ausfälle), oder soll das Limit höher gesetzt bzw. durch einen Proxy ergänzt werden? | (d), R3, R6. |