atahango/belgeler/EMAIL_VERIFICATION.md

Email Doğrulama Sistemi

Genel Bakış

AuthCentral'da kullanıcılar iki şekilde kayıt olabilir:

1. Email/Password ile Kayıt: Email doğrulaması gerektirir
2. OAuth (Google/GitHub): Otomatik olarak doğrulanmış kabul edilir

Email/Password ile Kayıt Akışı

1. Kullanıcı Kaydı

POST /v1/auth/register
{
  "username": "johndoe",
  "email": "john@example.com",
  "password": "securepass123"
}

Yanıt:

{
  "message": "User created. Please verify your email.",
  "user_id": "...",
  "username": "johndoe",
  "email": "john@example.com",
  "email_verified": false,
  "verification_token": "..."
}

Not: Kullanıcı oluşturulur ancak email_verified: false olarak ayarlanır.

2. Email Doğrulama

Kullanıcıya otomatik olarak doğrulama email'i gönderilir. Email'deki linke tıklayarak doğrulama yapılır:

GET /v1/auth/verify-email?token=VERIFICATION_TOKEN

Yanıt:

{
  "message": "Email verified successfully"
}

3. Login Denemesi (Email Doğrulanmadan)

Email doğrulanmadan login yapılamaz:

POST /v1/auth/login
{
  "email": "john@example.com",
  "password": "securepass123"
}

Hata Yanıtı:

{
  "error": "email not verified"
}

4. Login (Email Doğrulandıktan Sonra)

Email doğrulandıktan sonra başarıyla login yapılabilir:

POST /v1/auth/login
{
  "email": "john@example.com",
  "password": "securepass123"
}

Başarılı Yanıt:

{
  "access_token": "...",
  "refresh_token": "...",
  "user_id": "...",
  "username": "johndoe",
  "email": "john@example.com",
  "avatar": "",
  "roles": [...]
}

OAuth (Google/GitHub) ile Kayıt

OAuth sağlayıcıları email'i zaten doğruladığı için, bu kullanıcılar otomatik olarak email_verified: true olarak kaydedilir.

GET /v1/auth/google
GET /v1/auth/github

OAuth callback'ten sonra kullanıcı otomatik olarak login edilir ve token'lar döndürülür.

Veritabanı Yapısı

Users Tablosu

CREATE TABLE users (
  id UUID PRIMARY KEY,
  user_name TEXT NOT NULL,
  email VARCHAR(255) UNIQUE NOT NULL,
  password TEXT,
  avatar VARCHAR(500),
  email_verified BOOLEAN DEFAULT false,
  email_verify_token TEXT,
  email_verified_at TIMESTAMP,
  created_at TIMESTAMP,
  updated_at TIMESTAMP,
  deleted_at TIMESTAMP  -- Soft delete için
);

Email Verification Alanları

• email_verified: Boolean - Email doğrulandı mı? (Email/password için false, OAuth için true)
• email_verify_token: String - Doğrulama token'ı (email/password kayıt için)
• email_verified_at: Timestamp - Email ne zaman doğrulandı?

Admin Kullanıcı Yönetimi

Kullanıcı Silme

Soft Delete (Varsayılan)

DELETE /v1/admin/users/{user_id}

Kullanıcı deleted_at timestamp'i ile işaretlenir, veritabanından silinmez.

Hard Delete (Kalıcı Silme)

DELETE /v1/admin/users/{user_id}?hard=true

Kullanıcı ve tüm ilişkili kayıtları (user_roles, social_accounts) kalıcı olarak silinir.

Not: Kendi hesabınızı silemezsiniz.

Email Ayarları

Email gönderimi için .env dosyasındaki ayarları yapılandırın:

# Email Settings (Mailpit - Development)
EMAIL_HOST=212.64.215.243
EMAIL_PORT=1025
EMAIL_HOST_USER=""
EMAIL_HOST_PASSWORD=""
EMAIL_USE_TLS=false
EMAIL_USE_SSL=false
EMAIL_FROM=noreply@gauth.local

Güvenlik Notları

1. Verification Token: 32 byte güvenli rastgele token oluşturulur
2. Token Süresi: Şu anda token'ların süresi dolmuyor (ileride eklenebilir)
3. Rate Limiting: Register endpoint'i için rate limit aktif
4. Password Hashing: bcrypt kullanılarak güvenli şekilde hash'lenir

Geliştirme Notları

Migration

Email verification özelliği sonradan eklendiği için, mevcut kullanıcılar otomatik olarak email_verified: true olarak işaretlenmiştir. Yeni kayıtlar email_verified: false ile başlar.

Migration fonksiyonu internal/database/db.go dosyasında devre dışı bırakılmıştır.

Model Değişiklikleri

User model'de EmailVerified alanı *bool (pointer) olarak tanımlanmıştır. Bu, GORM'un false değerlerini doğru şekilde işlemesini sağlar.

type User struct {
    // ...
    EmailVerified    *bool      `gorm:"default:false" json:"email_verified"`
    EmailVerifyToken string     `gorm:"index" json:"-"`
    EmailVerifiedAt  *time.Time `json:"email_verified_at,omitempty"`
    // ...
}

Test Senaryosu

# 1. Yeni kullanıcı kaydı
curl -X POST http://localhost:8080/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "email": "test@example.com",
    "password": "password123"
  }'

# 2. Email doğrulanmadan login dene (BAŞARISIZ)
curl -X POST http://localhost:8080/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "password123"
  }'
# Yanıt: {"error": "email not verified"}

# 3. Email'i doğrula
curl -X GET "http://localhost:8080/v1/auth/verify-email?token=VERIFICATION_TOKEN"

# 4. Login (BAŞARILI)
curl -X POST http://localhost:8080/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "password123"
  }'
# Yanıt: access_token, refresh_token, user bilgileri

Özet

✅ Email/password ile kayıt olanlar email doğrulaması yapmalı ✅ Email doğrulanmadan login yapılamaz ✅ OAuth ile giriş yapanlar otomatik doğrulanmış kabul edilir ✅ Soft delete varsayılan, hard delete ?hard=true ile yapılır ✅ Email doğrulama sistemi tam çalışır durumda