Kurumsal Düzeyde NestJS Kimlik Doğrulama, RBAC ve Görev Yönetimi Şablonu (Boilerplate)

JWT (Access + Refresh Token Rotation), Rol Tabanlı Yetkilendirme (RBAC), Throttling, Account Lockout ve Audit Logging ile Güvenli Üretim Mimarisi.

Geliştirici Portföyü • Mimari Akış • Güvenlik Standartları • Kurulum & API

---

1. Sistem Mimarisi ve Güvenlik Akışı

Bu proje; kurumsal ölçekte backend uygulamaları için yüksek güvenlik, tip güvenliği ve modüler mikroservis standartlarına uygun olarak tasarlanmış bir NestJS + Prisma + PostgreSQL Boilerplate mimarisidir.

Kimlik doğrulama süreçlerinde endüstri standardı olan Token Rotation, brute-force saldırılarına karşı Account Lockout, IP tabanlı Audit Logging ve rol tabanlı erişim kontrolü (RBAC) mekanizmaları uçtan uca uygulanmıştır.

┌────────────────────────────────────────────────────────┐
│                   İstemci / Web / Mobil                 │
└───────────────────────────┬────────────────────────────┘
                            │
                            ▼ HTTPS / Authorization: Bearer <Token>
┌────────────────────────────────────────────────────────┐
│             NestJS Gateway / Guards & Middleware       │
│  • ThrottlerGuard: IP bazlı Rate Limiting (Koruması)   │
│  • AccountLockoutGuard: 5 hatalı denemede 15dk kilitleme│
│  • JwtAuthGuard: Access Token doğrulama (Kısa ömürlü)  │
│  • RolesGuard: RBAC (ADMIN vs. USER hiyerarşisi)       │
└───────────────────────────┬────────────────────────────┘
                            │
                            ▼
┌────────────────────────────────────────────────────────┐
│            Servis Katmanı & İş Mantığı                 │
│  • AuthService: Bcrypt hashleme, Token Rotation        │
│  • AuditService: IP & User-Agent işlem kaydı           │
│  • Tasks/Users Service: CRUD operasyonları             │
└───────────────────────────┬────────────────────────────┘
                            │
                            ▼
┌────────────────────────────────────────────────────────┐
│           Prisma ORM & PostgreSQL Veritabanı           │
│  • UUID birincil anahtarlar, snake_case isimlendirme   │
│  • AuditLog, User, Task, RefreshToken tabloları        │
└────────────────────────────────────────────────────────┘

---

2. Güvenlik ve Kimlik Doğrulama Standartları

• JWT Token Rotation & Refresh Tokens: Access token süresi dolduğunda, tek kullanımlık refresh token ile yeni çift üretilir. Eski refresh token geçersiz kılınarak token çalınma riskleri engellenir.
• Rol Tabanlı Erişim Kontrolü (RBAC): @Roles('ADMIN') dekoratörleri ile hassas uç noktalar ve metrik dashboard'ları sınırlandırılmıştır.
• Brute-Force & Hesap Kilitleme (Account Lockout): 5 ardışık hatalı şifre denemesinde hesap otomatik olarak 15 dakika boyunca kilitlenir.
• İstek Sınırlama (Rate Limiting / Throttling): @nestjs/throttler ile DDoS ve spam isteklerine karşı IP bazlı hız sınırlandırması uygulanır.
• Denetim Günlüğü (Audit Logging): Tüm oturum açma, çıkış yapma, parola sıfırlama ve kritik değişiklikler istemci IP adresi ve User-Agent bilgisiyle kalıcı olarak loglanır.
• Bcrypt Parola Güvenliği: Salt round parametreleriyle güvenli şifre özetleme.

---

3. Hızlı Kurulum ve Çalıştırma

Gereksinimler

• Node.js 20+
• Docker & Docker Compose

1. Docker ile Tek Komutta Başlatma (Önerilen)

docker-compose up -d

Bu komut PostgreSQL veritabanını kaldırır, Prisma migrationlarını çalıştırır ve NestJS uygulamasını ayağa kaldırır:

• API Adresi: http://localhost:3000
• Swagger UI Dokümantasyonu: http://localhost:3000/api
• Sistem Sağlık Kontrolü: http://localhost:3000/health

2. Yerel Geliştirme (Local Development)

# Bağımlılıkları kurun
npm install

# Ortam değişkenlerini hazırlayın
cp .env.example .env.development

# Yalnızca PostgreSQL veritabanını kaldırın
docker-compose up -d postgres

# Veritabanı şemasını uygulayın
npx prisma migrate dev

# Geliştirme sunucusunu başlatın
npm run start:dev

---

4. Temel API Uç Noktaları

Metot	Uç Nokta	Yetki	Açıklama
POST	/auth/register	Public	Yeni kullanıcı kaydı
POST	/auth/login	Public	Oturum açma (Access + Refresh Token)
POST	/auth/refresh	Bearer Token	Token Rotation ile yeni token çifti alma
POST	/auth/logout	Bearer Token	Oturumu sonlandırma ve token iptali
GET	/admin/metrics	ADMIN	Sistem metrikleri ve denetim kayıtları
GET	/tasks	Authenticated	Kullanıcı görev listesi
GET	/health	Public	Sunucu ve veritabanı sağlık kontrolü

---

5. Kullanılan Teknolojiler

Katman	Teknoloji	Fonksiyon
Framework	NestJS v10	Kurumsal seviye TypeScript mimarisi
Veritabanı & ORM	PostgreSQL 16, Prisma ORM	Tip güvenli veri erişimi ve migration yönetimi
Kimlik Doğrulama	Passport.js, JWT, Bcrypt	Güvenli kimlik doğrulama ve hashleme
Konteynerizasyon	Docker, Docker Compose, Nginx	Taşınabilir mikroservis dağıtımı
Dokümantasyon	Swagger / OpenAPI	Otomatik interaktif API kılavuzu

---

6. Geliştirici ve İletişim

Muhammet Atmaca

• Web Sitesi: muhammetatmaca.com.tr
• GitHub: @muhammetatmaca
• E-posta: info@muhammetatmaca.com.tr

---

7. Lisans

Bu proje MIT lisansı altında sunulmaktadır.