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ı
```bash
POST /v1/auth/register
{
  "username": "johndoe",
  "email": "john@example.com",
  "password": "securepass123"
}
```

**Yanıt:**
```json
{
  "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:

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

**Yanıt:**
```json
{
  "message": "Email verified successfully"
}
```

### 3. Login Denemesi (Email Doğrulanmadan)

Email doğrulanmadan login yapılamaz:

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

**Hata Yanıtı:**
```json
{
  "error": "email not verified"
}
```

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

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

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

**Başarılı Yanıt:**
```json
{
  "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.

```bash
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

```sql
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)
```bash
DELETE /v1/admin/users/{user_id}
```

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

#### Hard Delete (Kalıcı Silme)
```bash
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:

```env
# 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.

```go
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

```bash
# 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