managarten/uload/docs/auth-implementation-notes.md

🔐 Authentication Implementation Notes für ulo.ad

Übersicht

Diese Dokumentation beschreibt wichtige Implementierungsdetails und Lösungen für häufige Probleme im Authentication-Flow von ulo.ad.

---

⚠️ Wichtige SvelteKit + PocketBase Quirks

1. Login Redirect Problem

Problem: Nach erfolgreichem Login wird fälschlicherweise "Invalid email or password" angezeigt, obwohl der Login funktioniert hat.

Ursache: SvelteKit's redirect() Funktion wirft intern eine Exception. Wenn diese im try-catch-Block steht, wird sie als Login-Fehler interpretiert.

❌ Falsch:

// src/routes/login/+page.server.ts
try {
	await locals.pb.collection('users').authWithPassword(email, password);
	redirect(303, '/dashboard'); // ⚠️ Wirft Exception!
} catch (err) {
	return fail(400, { error: 'Invalid email or password' }); // Fängt redirect!
}

✅ Richtig:

// src/routes/login/+page.server.ts
try {
	await locals.pb.collection('users').authWithPassword(email, password);
	locals.user = locals.pb.authStore.model;
} catch (err) {
	console.error('Login error:', err);
	return fail(400, { error: 'Invalid email or password' });
}

// Redirect AUSSERHALB des try-catch!
redirect(303, '/dashboard');

---

2. E-Mail Verifizierung Fehler

Problem: PocketBase verifiziert den User erfolgreich, wirft aber trotzdem einen Fehler beim confirmVerification() Aufruf.

Lösung:

// src/routes/verify-email/+page.server.ts
try {
	await pb.collection('users').confirmVerification(token);
	redirect(303, '/login?verified=true');
} catch (error) {
	// PocketBase wirft IMMER einen Fehler, auch bei Erfolg!
	if (errorMessage.includes('expired')) {
		redirect(303, '/login?error=token-expired');
	} else {
		// Behandle als Erfolg
		redirect(303, '/login?verified=true');
	}
}

---

3. Registrierung mit E-Mail-Versand

Problem: E-Mail-Verifizierung wird nicht gesendet, wenn nach der Registrierung Auth-Operationen durchgeführt werden.

Reihenfolge ist kritisch:

// src/routes/register/+page.server.ts

// 1. User erstellen
const newUser = await pb.collection('users').create({...});

// 2. ZUERST E-Mail senden (vor Auth-Operationen!)
await pb.collection('users').requestVerification(email);

// 3. DANN andere Operationen (z.B. Profil-Card erstellen)
await pb.collection('users').authWithPassword(email, password);
// ... weitere Operationen
pb.authStore.clear();

// 4. Zur Login-Seite weiterleiten (KEIN Auto-Login!)
redirect(303, '/login?registered=true');

---

📋 Best Practices

Redirects in SvelteKit

1. Immer außerhalb von try-catch: Redirects gehören nicht in try-catch-Blöcke
2. Return vs. Throw: redirect() wirft eine Exception, return fail() gibt einen Wert zurück
3. Error-First: Erst alle Fehler behandeln, dann erfolgreiche Redirects

PocketBase Authentication

1. authStore.clear(): Immer aufrufen wenn temporäre Auth benötigt wurde
2. locals.user: Nach Login setzen für sofortige Verfügbarkeit
3. Verification: Fehler als Erfolg behandeln (PocketBase Quirk)

E-Mail-Versand

1. Reihenfolge beachten: E-Mails vor Auth-Operationen senden
2. Template-Komplexität: Bei Problemen vereinfachte Templates ohne Unicode verwenden
3. Error-Handling: E-Mail-Fehler nicht den ganzen Flow blockieren lassen

---

🐛 Debugging-Tipps

Login-Probleme

# Console logs prüfen
console.error('Login error:', err);

# PocketBase Admin prüfen
http://localhost:8090/_/
# → Logs → Auth Logs

E-Mail-Probleme

# SMTP Logs in PocketBase
http://localhost:8090/_/
# → Logs → Mails

# Template testen mit einfacher Version
docs/mail/email-templates-simplified.md

Session-Probleme

// Session-Status prüfen
console.log('Auth store valid:', locals.pb.authStore.isValid);
console.log('Current user:', locals.pb.authStore.model);

---

📁 Relevante Dateien

/src/routes/
├── login/
│   ├── +page.server.ts       # Login-Action mit korrektem Redirect
│   └── +page.svelte          # Status-Messages für Verifizierung
├── register/
│   └── +page.server.ts       # Registrierung mit E-Mail-Versand
├── verify-email/
│   └── +page.server.ts       # Verifizierung mit Fehler-als-Erfolg
└── (app)/
    └── +layout.server.ts     # User in locals setzen

/src/hooks.server.ts          # PocketBase Client initialisieren

---

✅ Checkliste für neue Auth-Features

• Redirects außerhalb von try-catch
• E-Mail-Versand vor Auth-Operationen
• PocketBase Fehler als mögliche Erfolge behandeln
• authStore.clear() nach temporären Auth-Operationen
• Proper error logging für Debugging
• User-freundliche Fehlermeldungen (bilingual)

---

Erstellt: 15. Januar 2025
Version: 1.0
Für: ulo.ad Authentication System