k9guard 1.0.2 → 1.0.4

package/docs/tr/README.md

@@ -10,11 +10,14 @@ TypeScript/JavaScript projeleri için kriptografik güvenlik sunan güvenli, haf
 
 - **Kriptografik Güvenlik**: NIST SP 800-90A standardına uyumluluk sağlanmıştır
 - **10 CAPTCHA Türü**: Matematik, metin, dizi, karıştırma, ters çevirme, karma, çok adımlı, görsel, emoji ve özel doğrulama yöntemleri
+- **Adaptif Zorluk**: Kullanıcı başarı oranına göre zorluk seviyesini otomatik ayarlar
 - **Güvenlik Odaklı**: SHA-256 tuzlu hash algoritması, sunucu taraflı challenge deposu, nonce tabanlı oturum yönetimi ve 5 dakikalık geçerlilik süresi
-- **Girdi Doğrulama**: Enjeksiyon saldırılarını önlemek için uzunluk sınırlamaları, tip kontrolü ve sanitizasyon
+- **Tek Kullanımlık Challenge**: Her nonce, `validate()` çağrısında — doğru ya da yanlış fark etmeksizin — tüketilir; replay ve brute-force saldırıları engellenir
+- **Katı Yapılandırma**: Geçersiz `type` veya `difficulty` değerleri anında hata fırlatır; sessiz fallback yoktur
+- **Girdi Doğrulama**: Enjeksiyon saldırılarını önlemek için uzunluk sınırlamaları, katı sayısal ayrıştırma, tip kontrolü ve sanitizasyon
 - **Özel Sorular**: Doğrulama ve sanitizasyon ile kendi sorularınızı tanımlama desteği
 - **Sıfır Bağımlılık**: Harici bağımlılık gerektirmeyen hafif yapı
-- **Kapsamlı Test Edilmiş**: Uç durumlar ve güvenlik senaryoları dahil olmak üzere geniş test kapsama alanı
+- **Kapsamlı Test Edilmiş**: 228+ test ile birim, entegrasyon, güvenlik, uç durum ve benchmark senaryoları
 - **OWASP Uyumlu**: OWASP Top 10 güvenlik yönergelerine uygun geliştirme
 - **Gizlilik Uyumlu**: Kişisel veri saklamayan GDPR/KVKK uyumlu mimari
 
@@ -190,16 +193,114 @@ const challenge = captcha.generate();
 const isValid = captcha.validate(challenge, "ankara");
 ```
 
+### Adaptif Zorluk
+
+Adaptif zorluk, kullanıcının başarı oranına göre zorluk seviyesini otomatik olarak ayarlar. Bu sayede zorlanan kullanıcılara kolay, hızlı çözen kullanıcılara ise daha zor challenge'lar sunulur.
+
+#### Nasıl Çalışır?
+
+- Oturum başına son 10 denemeyi takip eder (kayan pencere)
+- **%80+ başarı oranı** — zorluk artar (easy -> medium -> hard)
+- **%40 ve altı başarı oranı** — zorluk düşer (hard -> medium -> easy)
+- **%40-80 arası** — zorluk sabit kalır
+- Herhangi bir ayarlama öncesinde minimum 3 deneme gerekli (histerezis)
+- Oturumlar 30 dakika hareketsizlik sonra otomatik sona erer
+- Maksimum 10.000 eş zamanlı oturum (en eski otomatik temizlenir)
+
+#### Seçenek 1: Constructor'da Session ID
+
+```typescript
+const captcha = new K9Guard({
+  type: 'math',
+  difficulty: 'adaptive',
+  sessionId: 'user-123'  // herhangi benzersiz string (kullanıcı ID, oturum token'ı, IP vb.)
+});
+
+const challenge = captcha.generate();  // user-123'ün mevcut zorluğunu kullanır
+const isValid = captcha.validate(challenge, userAnswer);  // sonucu otomatik kaydeder
+```
+
+#### Seçenek 2: Parametre Olarak Session ID
+
+```typescript
+const captcha = new K9Guard({ type: 'math', difficulty: 'adaptive' });
+
+// her çağrıda sessionId geçir
+const challenge = captcha.generate('user-123');
+const isValid = captcha.validate(challenge, userAnswer, 'user-123');
+```
+
+#### Seçenek 3: Esnek (Her İkisi)
+
+Constructor'daki `sessionId` varsayılan olarak kullanılır. Parametre olarak verilen `sessionId` onu override eder.
+
+```typescript
+const captcha = new K9Guard({
+  type: 'math',
+  difficulty: 'adaptive',
+  sessionId: 'varsayilan-kullanici'
+});
+
+captcha.generate();                // 'varsayilan-kullanici' kullanır
+captcha.generate('diger-kullanici'); // 'diger-kullanici' kullanır (override)
+```
+
+#### Oturum Yönetimi
+
+```typescript
+// oturumun mevcut zorluğunu öğren
+const difficulty = captcha.getSessionDifficulty('user-123'); // 'easy' | 'medium' | 'hard' | null
+
+// belirli bir oturumu temizle (zorluk 'medium' olarak sıfırlanır)
+captcha.clearSession('user-123');
+
+// tüm oturumları temizle
+captcha.clearAllSessions();
+```
+
+#### Tüm CAPTCHA Türleriyle Uyumlu
+
+```typescript
+// adaptif zorluk herhangi bir captcha türüyle çalışır
+const captcha = new K9Guard({ type: 'image', difficulty: 'adaptive', sessionId: 'user-1' });
+const captcha = new K9Guard({ type: 'emoji', difficulty: 'adaptive', sessionId: 'user-1' });
+const captcha = new K9Guard({ type: 'reverse', difficulty: 'adaptive', sessionId: 'user-1' });
+// ... ve diğerleri
+```
+
+#### Express.js Örneği
+
+```typescript
+import express from 'express';
+import K9Guard from 'k9guard';
+
+const app = express();
+const captcha = new K9Guard({ type: 'math', difficulty: 'adaptive' });
+
+app.get('/captcha', (req, res) => {
+  const challenge = captcha.generate(req.sessionID);
+  res.json(challenge);
+});
+
+app.post('/verify', (req, res) => {
+  const isValid = captcha.validate(req.body.challenge, req.body.answer, req.sessionID);
+  res.json({ valid: isValid });
+});
+```
+
 ## API Referansı
 
 ### Yapıcı Metod Seçenekleri
 
+`type` ve `difficulty` alanları **zorunludur** ve katı şekilde doğrulanır. Geçersiz bir değer iletildiğinde constructor anında hata fırlatır.
+
 #### Standart CAPTCHA Seçenekleri
 
 ```typescript
 interface K9GuardOptions {
   type: 'math' | 'text' | 'sequence' | 'scramble' | 'reverse' | 'mixed' | 'multi' | 'image' | 'emoji';
-  difficulty: 'easy' | 'medium' | 'hard';
+  difficulty: 'easy' | 'medium' | 'hard' | 'adaptive';
+  sessionId?: string;  // opsiyonel, difficulty 'adaptive' iken gerekli
 }
 ```
 
@@ -209,6 +310,7 @@ interface K9GuardOptions {
 interface K9GuardCustomOptions {
   type: 'custom';
   questions: CustomQuestion[];
+  sessionId?: string;
 }
 
 interface CustomQuestion {
@@ -220,10 +322,12 @@ interface CustomQuestion {
 
 ### Metotlar
 
-#### `generate(): CaptchaChallenge`
+#### `generate(sessionId?: string): CaptchaChallenge`
 
 İstemciye gönderilmesi güvenli bir **public** nesne döndürür — `answer`, `hashedAnswer` ve `salt` çıkarılarak `nonce` ile anahtarlanmış şekilde sunucu tarafında saklanır.
 
+`difficulty` `'adaptive'` olduğunda, `sessionId` parametresi kullanıcının mevcut zorluk seviyesini belirlemek için kullanılır. Constructor'da `sessionId` verilmişse varsayılan olarak kullanılır.
+
 ```typescript
 const challenge = captcha.generate();
 console.log(challenge.question);  // kullanıcıya gösterilecek soru
@@ -235,28 +339,112 @@ console.log(challenge.category);  // kategori adı (yalnızca type: 'emoji' içi
 // challenge.answer / .hashedAnswer / .salt — MEVCUT DEĞİL; istemciye hiç gönderilmez
 ```
 
-#### `validate(challenge: CaptchaChallenge, userInput: string): boolean`
+#### `validate(challenge: CaptchaChallenge, userInput: string, sessionId?: string): boolean`
 
 Kullanıcı girdisini `challenge.nonce` üzerinden bulunan sunucu taraflı kayıtla karşılaştırır. Doğruysa `true`, yanlışsa `false` döndürür. Public challenge nesnesindeki `hashedAnswer` veya `salt` değiştirme girişimlerinin hiçbir etkisi yoktur.
 
+`difficulty` `'adaptive'` olduğunda, doğrulama sonucu otomatik olarak oturuma kaydedilir ve zorluk buna göre ayarlanır.
+
+> **⚠️ Tek kullanımlık semantik:** `validate()`, **ilk çağrıda** — cevap doğru ya da yanlış olsun fark etmeksizin — nonce'u tüketir. Her doğrulama denemesinden sonra challenge geçersiz hale gelir. Kullanıcıya yeni bir challenge sunmadan önce mutlaka `generate()` yeniden çağrılmalıdır.
+
 ```typescript
 const isValid = captcha.validate(challenge, userAnswer);
+
+// validate() çağrısından sonra challenge tüketilir.
+// Yeniden deneme için yeni bir challenge üretilmeli:
+if (!isValid) {
+  const newChallenge = captcha.generate();
+}
+```
+
+#### `getSessionDifficulty(sessionId: string): Difficulty | null`
+
+Oturumun mevcut adaptif zorluk seviyesini döndürür. Instance adaptif modda değilse `null` döndürür.
+
+```typescript
+const difficulty = captcha.getSessionDifficulty('user-123');
+// 'easy' | 'medium' | 'hard' | null
+```
+
+#### `clearSession(sessionId: string): boolean`
+
+Belirli bir adaptif oturumu temizler. Oturum mevcutsa `true`, değilse `false` döndürür.
+
+```typescript
+captcha.clearSession('user-123');
+```
+
+#### `clearAllSessions(): void`
+
+Tüm adaptif oturumları temizler.
+
+```typescript
+captcha.clearAllSessions();
+```
+
+### Dışa Aktarılan Yardımcılar
+
+```typescript
+import K9Guard, { AdaptiveTracker, CustomQuestionValidator, CustomQuestionGenerator } from 'k9guard';
+```
+
+| Export | Açıklama |
+|--------|----------|
+| `K9Guard` (varsayılan) | Ana CAPTCHA sınıfı |
+| `AdaptiveTracker` | Bağımsız adaptif zorluk takipçisi (özel entegrasyonlar için) |
+| `CustomQuestionValidator` | Özel soru dizilerini doğrula ve sanitize et |
+| `CustomQuestionGenerator` | Özel soru havuzlarından üretim |
+
+### Tip Exportları
+
+```typescript
+import type {
+  K9GuardOptions,
+  K9GuardCustomOptions,
+  CaptchaChallenge,
+  CustomQuestion,
+  Difficulty,
+  AdaptiveSession,
+  AdaptiveAttempt,
+  StoredChallenge,
+  ImageCaptcha,
+  MathCaptcha,
+  TextCaptcha,
+  SequenceCaptcha,
+  ScrambleCaptcha,
+  ReverseCaptcha,
+  MixedCaptcha,
+  CustomCaptcha,
+  EmojiCaptcha,
+} from 'k9guard';
 ```
 
-## Test Etme
+## Testler
+
+K9Guard, `bun:test` kullanarak 228+ test ile birim, entegrasyon, güvenlik, uç durum ve benchmark senaryolarını kapsar.
 
-Dahil edilen test paketini çalıştırın:
+### Testleri Çalıştırma
 
 ```bash
-bun run src/test.ts
+# tüm testleri çalıştır
+bun test
+
+# izleme modunda çalıştır
+bun run test:watch
+
+# kapsam ile çalıştır
+bun run test:coverage
 ```
 
-Testler şunları içerir:
-- Tüm CAPTCHA türleri için doğru/yanlış/uç durum girdileri
-- Özel soru doğrulama senaryoları
-- Çok adımlı doğrulamalar
-- Girdi sanitizasyonu
-- Güvenlik doğrulamaları
+### Test Kategorileri
+
+| Kategori | Kapsam |
+|----------|--------|
+| **Birim** | Her modül bağımsız olarak doğru çıktılar ve uç durumlarla test edilir |
+| **Entegrasyon** | Tüm 10 captcha türü + adaptif mod için tam generate-validate akışı |
+| **Güvenlik** | Timing saldırısı direnci, nonce replay önleme, hash enjeksiyonu, girdi sanitizasyonu, SVG enjeksiyonu |
+| **Uç Durumlar** | Sıfıra bölme, unicode karakterler, eş zamanlı üreteçler, geçersiz girdiler |
+| **Benchmark** | Tüm captcha türleri için performans garantileri (generate < 5ms, validate < 5ms) |
 
 ## Katkıda Bulunma
 
@@ -265,7 +453,7 @@ Katkılarınızı memnuniyetle karşılıyoruz! Nasıl yardımcı olabilirsiniz:
 1. **Depoyu fork edin**
 2. **Özellik dalı oluşturun**: `git checkout -b feature/harika-ozellik`
 3. **Değişiklikleriniz için testler ekleyin**
-4. **Testleri çalıştırın**: `bun run src/test.ts`
+4. **Testleri çalıştırın**: `bun test`
 5. **Değişikliklerinizi commit edin**: `git commit -m 'feat: harika özellik eklendi'`
 6. **Dalınıza push edin**: `git push origin feature/harika-ozellik`
 7. **Pull Request oluşturun**

package/package.json

@@ -1,11 +1,29 @@
 {
   "name": "k9guard",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "A secure, lightweight, and flexible CAPTCHA module for TypeScript/JavaScript projects with cryptographic security and multi-language support",
-  "main": "index.ts",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "tsup",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage",
+    "prepublishOnly": "bun run build"
   },
   "keywords": [
     "captcha",
@@ -42,20 +60,24 @@
     "url": "https://github.com/K9Crypt/k9guard/issues"
   },
   "homepage": "https://github.com/K9Crypt/k9guard#readme",
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE",
+    "docs/"
+  ],
   "engines": {
     "node": ">=16.0.0"
   },
   "devDependencies": {
-    "@types/bun": "latest",
-    "@types/node": "^20.19.33",
-    "@typescript-eslint/eslint-plugin": "^6.21.0",
-    "@typescript-eslint/parser": "^6.21.0",
-    "eslint": "^8.57.1",
-    "tsx": "^4.21.0",
-    "typescript": "^5.9.3"
-  },
-  "peerDependencies": {
-    "typescript": "^5"
+    "@types/bun": "^1.3.14",
+    "@types/node": "^25.9.1",
+    "@typescript-eslint/eslint-plugin": "^8.59.4",
+    "@typescript-eslint/parser": "^8.59.4",
+    "eslint": "^10.4.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.22.3",
+    "typescript": "^6.0.3"
   },
   "publishConfig": {
     "access": "public",

package/index.ts

@@ -1,4 +0,0 @@
-export { K9Guard as default } from './src/K9Guard';
-export * from './src/types';
-export { CustomQuestionValidator } from './src/validators/customQuestionValidator';
-export { CustomQuestionGenerator } from './src/utils/customQuestionGenerator';

package/src/K9Guard.ts

@@ -1,91 +0,0 @@
-import type { K9GuardOptions, K9GuardCustomOptions, CaptchaChallenge, CustomQuestion } from './types';
-import { CaptchaGenerator } from './core/captchaGenerator';
-import { CaptchaValidator } from './core/captchaValidator';
-import { CustomQuestionValidator } from './validators/customQuestionValidator';
-
-export class K9Guard {
-  private options: K9GuardOptions | K9GuardCustomOptions;
-  private generator: CaptchaGenerator;
-
-  constructor(options: K9GuardOptions | K9GuardCustomOptions | { type: 'custom'; questions: CustomQuestion[] } = { type: 'math', difficulty: 'medium' }) {
-    const processedOptions = this.processOptions(options);
-    this.generator = new CaptchaGenerator(processedOptions);
-    this.options = processedOptions;
-  }
-
-  private processOptions(options: unknown): K9GuardOptions | K9GuardCustomOptions {
-    if (typeof options !== 'object' || options === null) {
-      return { type: 'math', difficulty: 'medium' };
-    }
-
-    const opt = options as Record<string, unknown>;
-
-    if (opt.type === 'custom') {
-      if (!Array.isArray(opt.questions)) {
-        throw new Error('Custom type requires questions array');
-      }
-
-      const validation = CustomQuestionValidator.validate(opt.questions);
-      if (!validation.valid) {
-        throw new Error(`Invalid custom questions: ${validation.error}`);
-      }
-
-      return {
-        type: 'custom',
-        questions: CustomQuestionValidator.sanitize(opt.questions as CustomQuestion[])
-      } as K9GuardCustomOptions;
-    }
-
-    const validTypes = ['math', 'text', 'sequence', 'scramble', 'reverse', 'mixed', 'multi', 'image', 'emoji'];
-    const type = validTypes.includes(opt.type as string) ? opt.type : 'math';
-
-    return {
-      type,
-      difficulty: opt.difficulty || 'medium'
-    } as K9GuardOptions;
-  }
-
-  generate(): CaptchaChallenge {
-    return this.generator.generate();
-  }
-
-  validate(challenge: CaptchaChallenge, userInput: string): boolean {
-    if (!this.isValidChallenge(challenge)) {
-      return false;
-    }
-
-    if (typeof userInput !== 'string') {
-      return false;
-    }
-
-    // resolve the stored record by nonce; reject if not found or expired.
-    // hashedAnswer and salt come from the server-side store, never from the client,
-    // which prevents hash-injection attacks.
-    const stored = this.generator.lookup(challenge.nonce);
-    if (!stored) {
-      return false;
-    }
-
-    const now = Date.now();
-    if (now > stored.expiry) {
-      return false;
-    }
-
-    return CaptchaValidator.validate(stored, userInput);
-  }
-
-  private isValidChallenge(challenge: unknown): boolean {
-    if (typeof challenge !== 'object' || challenge === null) {
-      return false;
-    }
-
-    const c = challenge as Record<string, unknown>;
-
-    return (
-      typeof c.type === 'string' &&
-      typeof c.question === 'string' &&
-      typeof c.nonce === 'string' && c.nonce.length > 0 &&
-      typeof c.expiry === 'number'
-    );
-  }
-}