🔐 Secure Crypto Auth

Modern, güvenli ve yüksek performanslı şifre hash'leme ve kullanıcı kimlik doğrulama kütüphanesi. Argon2-inspired algoritma kullanarak enterprise-grade güvenlik sağlar.

✨ Özellikler

• 🛡️ Güvenli Şifre Hash'leme: Argon2-inspired algoritma ile memory-hard fonksiyonlar
• ⚡ Paralel İşleme: Multi-threaded hash işleme desteği
• 🧂 Salt & Pepper: Otomatik salt üretimi ve isteğe bağlı pepper desteği
• 🔑 Kimlik Doğrulama Sistemi: Tam kapsamlı kullanıcı yönetimi
• 📊 Benchmark Araçları: Performans optimizasyonu için otomatik benchmark
• 🔒 Session Yönetimi: Güvenli oturum token'ları
• ⚙️ Esnek Konfigürasyon: Tamamen özelleştirilebilir parametreler
• 🔍 Debug Modu: Geliştirme için detaylı loglama

🚀 Kurulum

npm install secure-crypto-auth

📚 Hızlı Başlangıç

Temel Şifre Hash'leme

import { SecureCrypto } from 'secure-crypto-auth';

const crypto = new SecureCrypto();

// Şifreyi hash'le
const hashResult = crypto.hash("MySecurePassword123!");
console.log(hashResult);
// {
//   hash: "base64-encoded-hash",
//   version: "2.0.0", 
//   algorithm: "SECURE-ARGON2"
// }

// Şifreyi doğrula
const isValid = crypto.verify("MySecurePassword123!", hashResult.hash);
console.log(isValid); // true

Kullanıcı Kimlik Doğrulama

import { UserAuth } from 'secure-crypto-auth';

const auth = new UserAuth();

// Kullanıcı kaydı
const registerResult = await auth.register({
    email: "[email protected]",
    password: "SecurePassword123!"
});

if (registerResult.success) {
    console.log("Kayıt başarılı:", registerResult.user);
    console.log("Session token:", registerResult.sessionToken);
}

// Giriş yapma
const loginResult = await auth.login({
    email: "[email protected]", 
    password: "SecurePassword123!"
});

if (loginResult.success) {
    console.log("Giriş başarılı:", loginResult.user);
}

⚙️ Konfigürasyon

SecureCrypto Konfigürasyonu

const crypto = new SecureCrypto({
    memoryCost: 65536,      // Memory kullanımı (KB)
    timeCost: 3,            // İterasyon sayısı
    parallelism: 4,         // Paralel işleme thread'i
    hashLength: 64,         // Hash uzunluğu (bytes)
    saltLength: 32,         // Salt uzunluğu (bytes)
    pepper: "secret-key",   // İsteğe bağlı pepper
    requirePepper: true,    // Pepper zorunluluğu
    debugMode: false,       // Debug modunu aktifleştir
    authKeyContext: "MyApp-v1.0" // Uygulama bağlamı
});

Environment Variables

# .env dosyası
SECURE_CRYPTO_PEPPER=your-secret-pepper-here
SECURE_CRYPTO_CONTEXT=YourApp-v1.0
NODE_ENV=production

🛠️ API Referansı

SecureCrypto Class

Constructor

new SecureCrypto(config?: Partial<CryptoConfig>)

Methods

hash(password: string): HashResult

Şifreyi güvenli şekilde hash'ler.

Parametreler:

• password: Hash'lenecek şifre

Döndürür: HashResult objesi

verify(password: string, hash: string | HashResult): boolean

Şifreyi hash ile karşılaştırır.

Parametreler:

• password: Doğrulanacak şifre
• hash: Hash string'i veya HashResult objesi

Döndürür: boolean - doğrulama sonucu

getConfig(): CryptoConfig

Mevcut konfigürasyonu döndürür.

static benchmark(targetTime: number, pepper?: string): CryptoConfig

Belirtilen süre için optimal konfigürasyon bulur.

Parametreler:

• targetTime: Hedef süre (ms)
• pepper: Opsiyonel pepper

UserAuth Class

Constructor

new UserAuth(cryptoConfig?: Partial<CryptoConfig>)

Methods

register(data: RegistrationData): Promise<AuthResult>

Yeni kullanıcı kaydeder.

login(data: LoginData): Promise<AuthResult>

Kullanıcı girişi yapar.

logout(sessionToken: string): boolean

Kullanıcıyı çıkış yapar.

validateSession(sessionToken: string): { valid: boolean; user?: User }

Session token'ını doğrular.

changePassword(sessionToken: string, oldPassword: string, newPassword: string): AuthResult

Kullanıcı şifresini değiştirir.

getUserStats(): { totalUsers: number; activeSessions: number }

Kullanıcı istatistiklerini döndürür.

🎯 Performans Optimizasyonu

Otomatik Benchmark

// 1 saniye hedef süre için optimal konfigürasyon
const optimalConfig = SecureCrypto.benchmark(1000);
const crypto = new SecureCrypto(optimalConfig);

Manuel Optimizasyon

// Düşük güvenlik, yüksek hız
const fastConfig = {
    memoryCost: 8192,
    timeCost: 1,
    parallelism: 2
};

// Yüksek güvenlik, düşük hız  
const secureConfig = {
    memoryCost: 131072,
    timeCost: 5,
    parallelism: 8
};

🔒 Güvenlik Özellikleri

Memory-Hard Fonksiyon

• Argon2-inspired algoritma
• Paralel memory erişimi
• Timing attack koruması

Salt & Pepper

• Otomatik 32-byte rastgele salt
• İsteğe bağlı pepper desteği
• Hash collision koruması

Authentication Tags

• HMAC-SHA512 tabanlı doğrulama
• Hash integrity kontrolü
• Tampering detection

Session Güvenliği

• 256-bit rastgele session token'ları
• Otomatik token expiration
• Session hijacking koruması

🧪 Test ve Örnek Kullanım

Örnek kullanım için:

npm run build
npx ts-node example.ts

📋 Gereksinimler

• Node.js >= 16.0.0
• TypeScript >= 4.0.0

📦 Proje Yapısı

secure-crypto-auth/
├── src/
│   ├── index.ts        # Ana export dosyası
│   ├── crypto.ts       # SecureCrypto sınıfı
│   └── auth.ts         # UserAuth sınıfı
├── dist/               # Derlenmiş JavaScript dosyaları
├── example.ts          # Örnek kullanım dosyası
├── package.json        # NPM package konfigürasyonu
├── tsconfig.json       # TypeScript konfigürasyonu
└── README.md          # Bu dosya

🔧 Geliştirme

Build

npm run build

Örnek Çalıştırma

npx ts-node example.ts

🎛️ Yapılandırma Örnekleri

Production Ortamı

const prodCrypto = new SecureCrypto({
    memoryCost: 65536,      // 64MB memory
    timeCost: 3,            // 3 iterasyon
    parallelism: 4,         // 4 paralel thread
    pepper: process.env.CRYPTO_PEPPER,
    requirePepper: true,
    debugMode: false
});

Development Ortamı

const devCrypto = new SecureCrypto({
    memoryCost: 16384,      // 16MB memory (daha hızlı)
    timeCost: 1,            // 1 iterasyon
    parallelism: 2,         // 2 paralel thread
    requirePepper: false,   // Pepper zorunlu değil
    debugMode: true         // Debug açık
});

Test Ortamı

const testCrypto = new SecureCrypto({
    memoryCost: 4096,       // 4MB memory (en hızlı)
    timeCost: 1,
    parallelism: 1,
    requirePepper: false,
    debugMode: false
});

🚨 Önemli Güvenlik Notları

1. Pepper Kullanımı: Production ortamında mutlaka pepper kullanın
2. Environment Variables: Pepper'ı environment variable olarak saklayın
3. Session Management: Session token'ları güvenli şekilde saklayın
4. Memory Limits: Üretim ortamında memory cost'u sisteminize göre ayarlayın
5. Regular Updates: Kütüphaneyi düzenli olarak güncelleyin

🔄 Migration Guide

v1.x'den v2.x'e Geçiş

// Eski versiyon (v1.x)
const oldHash = crypto.hash("password");

// Yeni versiyon (v2.x) - geriye uyumlu
const isValid = crypto.verify("password", oldHash);

🐛 Sorun Giderme

Yaygın Sorunlar

1. "Pepper is required" Hatası

   // Çözüm: Pepper ekleyin veya requirePepper'ı false yapın
   const crypto = new SecureCrypto({ requirePepper: false });

2. Yavaş Hash İşlemi

   // Çözüm: Memory cost'u azaltın
   const crypto = new SecureCrypto({ memoryCost: 16384 });

3. Memory Hatası

   // Çözüm: Parallelism'i azaltın
   const crypto = new SecureCrypto({ parallelism: 1 });

📈 Roadmap

• [ ] Database adaptör desteği (MongoDB, PostgreSQL)
• [ ] Rate limiting entegrasyonu
• [ ] Multi-factor authentication (MFA)
• [ ] Password policy konfigürasyonu
• [ ] Audit logging sistemi
• [ ] WebAssembly optimizasyonu
• [ ] React/Vue.js frontend helpers
• [ ] JWT token entegrasyonu

🤝 Katkıda Bulunma

1. Projeyi fork edin
2. Feature branch oluşturun (git checkout -b feature/amazing-feature)
3. Değişikliklerinizi commit edin (git commit -m 'Add amazing feature')
4. Branch'i push edin (git push origin feature/amazing-feature)
5. Pull Request oluşturun

📄 Lisans

Bu proje MIT lisansı altında lisanslanmıştır. Detaylar için LICENSE dosyasına bakın.

📞 İletişim

• GitHub Issues: Sorun bildir
• Email: [email protected]

🙏 Teşekkürler

Bu proje aşağıdaki teknolojilerden ilham almıştır:

• Argon2 - Password hashing standard
• bcrypt - Classic password hashing
• scrypt - Alternative key derivation

⚡ Secure Crypto Auth - Enterprise-grade güvenlik, developer-friendly API