triqura-ecd/docs/design/AUTH_HOOK_SETUP.md

Auth Hook Setup Guide

Overzicht

Deze hook detecteert duplicate emails VOOR een user wordt aangemaakt, waardoor gebruikers direct feedback krijgen als hun email al geregistreerd is.

Voordelen:

• ✅ Server-side validatie (kan niet omzeild worden)
• ✅ Duidelijke foutmeldingen voor gebruikers
• ✅ Betrouwbaar (werkt ongeacht password)
• ✅ Case-insensitive email matching
• ✅ Email normalisatie (lowercase + trim)

Setup (Eerste Keer)

Stap 1: Deploy Migration

Optie A: Via Supabase Dashboard (Aanbevolen)

1. Ga naar: Supabase Dashboard → SQL Editor
2. Open het migration bestand: supabase/migrations/20251119094908_auth_hook_duplicate_email.sql
3. Kopieer de volledige inhoud
4. Plak in de SQL Editor
5. Klik "RUN" om de functie aan te maken

Optie B: Via Supabase CLI (Als geconfigureerd)

npx supabase db push

Stap 2: Verificatie & Instructies

Run het setup script om te verifiëren dat de functie bestaat:

pnpm run setup:auth-hook

Dit script:

• ✅ Checkt of de functie bestaat
• 📋 Geeft instructies voor Dashboard configuratie
• 🔗 Biedt directe links naar relevante Dashboard pagina's

Stap 3: Configureer Hook Link

⚠️ Deze stap moet handmatig via Dashboard (Supabase ondersteunt dit nog niet via API):

1. Ga naar: Supabase Dashboard → Auth → Hooks
2. Klik "Add a new hook" of "Enable Hooks"
3. Vul in:
   • Hook Type: "Send a hook on before a user is created" (before-user-created)
   • Select hook: "Postgres Function"
   • Schema: public
   • Function Name: hook_check_duplicate_email
4. Klik "Create hook" of "Save"

Stap 4: Test

Test de hook door:

1. Ga naar je signup pagina: http://localhost:3000/login
2. Probeer te registreren met een bestaand emailadres (bijv. demo@mini-ecd.demo)
3. Je zou een error moeten zien: "Dit emailadres is al geregistreerd. Probeer in te loggen of gebruik 'Wachtwoord vergeten?'."
4. Probeer te registreren met een nieuw emailadres
5. Dit zou normaal moeten werken (verificatie email verzonden)

Test Cases

Test Case	Scenario	Expected Result
TC1	Signup met nieuw email	✅ Account aangemaakt, email verzonden
TC2	Signup met bestaand email	❌ Error: "Dit emailadres is al geregistreerd..."
TC3	Signup met bestaand email (case variant: Email@Example.com)	❌ Error (case-insensitive match)
TC4	Signup met lege/NULL email	❌ Error: "Email adres is verplicht."
TC5	Hook disabled → signup met bestaand email	⚠️ Oude gedrag (geen error, maar ook geen email)

Herhaalbaarheid

• ✅ Functie code staat in migrations (version controlled)
• ⚠️ Hook link moet per omgeving handmatig worden geconfigureerd
• ✅ Documentatie staat in Git
• ✅ Setup script voor validatie en instructies

Technische Details

Wat Doet de Hook?

De hook_check_duplicate_email functie:

1. Ontvangt signup event van Supabase Auth
2. Haalt email adres uit event payload
3. Valideert email (niet NULL/empty)
4. Normaliseert email (lowercase + trim)
5. Checkt of email al bestaat in auth.users table (case-insensitive)
6. Als email bestaat → return error object
7. Als email nieuw is → return empty object (allow signup)

Security

• Security Definer: Functie draait met elevated permissions
• Search Path: Expliciet ingesteld op public, auth voor veilige schema access
• Permissions: Alleen supabase_auth_admin kan de functie uitvoeren
• Email Enumeration Protection: Werkt samen met bestaande email confirmation

Performance

• ⚡ Direct database check (geen extra HTTP calls)
• ⚡ Indexed lookup op auth.users.email
• ⚡ Minimale overhead (< 10ms typisch)

Toekomstige Verbeteringen

Zodra Supabase Management API Auth Hooks ondersteunt, kunnen we:

• Hook link volledig automatiseren
• Setup script uitbreiden met API calls
• CI/CD pipeline voor hook configuratie
• Automated tests voor hook functionaliteit

Flexibiliteit

De functie is geschreven in standaard PostgreSQL, waardoor:

• ✅ Werkt met elke auth provider die Postgres functies ondersteunt
• ✅ Makkelijk te migreren naar andere auth systemen
• ✅ Geen vendor lock-in voor de logica zelf

Troubleshooting

"Function does not exist" error

Probleem: De hook functie is niet aangemaakt in de database.

Oplossing:

1. Controleer of migration is uitgevoerd via Dashboard of CLI
2. Run pnpm run setup:auth-hook voor verificatie
3. Check Supabase logs voor SQL errors

Hook lijkt niet te werken

Probleem: Signup met bestaand email geeft geen error.

Mogelijke oorzaken:

1. Hook link niet geconfigureerd in Dashboard → Ga naar Auth → Hooks
2. Hook is disabled → Check hook status in Dashboard
3. Email confirmation staat uit → Check Auth → Email Templates

Verificatie:

-- Check of functie bestaat
SELECT routine_name
FROM information_schema.routines
WHERE routine_schema = 'public'
AND routine_name = 'hook_check_duplicate_email';

-- Test functie handmatig
SELECT hook_check_duplicate_email('{"user": {"email": "demo@mini-ecd.demo"}}'::jsonb);

Wrong error message

Probleem: Error message klopt niet of is in het Engels.

Oplossing:

1. Check of je de laatste versie van de migration hebt gebruikt
2. Update functie via SQL Editor met correcte error messages
3. Rebuild client error handling (app/login/page.tsx)

Related Documentation

• Supabase Auth Hooks Documentation
• Bouwplan: Auth Hook Implementation
• Main README

Support

Voor vragen of problemen:

1. Check deze documentatie
2. Check Supabase logs in Dashboard
3. Run pnpm run setup:auth-hook voor diagnostics
4. Review supabase/migrations/20251119094908_auth_hook_duplicate_email.sql