k9guard 1.0.1 → 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 K9Crypt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,14 +4,13 @@
 
 # K9Guard
 
-A secure, lightweight, and flexible CAPTCHA module for TypeScript/JavaScript projects with cryptographic security and multi-language support.
+A secure, lightweight, and flexible CAPTCHA module for TypeScript/JavaScript projects with cryptographic security.
 
 ## Features
 
 - **Cryptographically Secure**: NIST SP 800-90A compliant random generation
-- **Multi-Language Support**: English and Turkish locales for riddles and logic questions
-- **9 CAPTCHA Types**: Math, text, riddle, sequence, scramble, logic, reverse, mixed, and multi-step challenges
-- **Security First**: SHA-256 salted hashing, nonce-based session management, and 5-minute expiry
+- **10 CAPTCHA Types**: Math, text, sequence, scramble, reverse, mixed, multi-step, image, emoji, and custom challenges
+- **Security First**: SHA-256 salted hashing, server-side challenge store, nonce-based session management, and 5-minute expiry
 - **Input Validation**: Length limits, type checking, and sanitization to prevent injection attacks
 - **Custom Questions**: Support for your own questions with validation and sanitization
 - **Zero Dependencies**: Lightweight with no external dependencies
@@ -32,8 +31,7 @@ import K9Guard from "k9guard";
 
 const captcha = new K9Guard({
   type: 'math',
-  difficulty: 'medium',
-  locale: 'en'
+  difficulty: 'medium'
 });
 
 // generate a challenge
@@ -69,15 +67,6 @@ const challenge = captcha.generate();
 // Answer: "aB2xY9"
 ```
 
-### Riddle CAPTCHA
-
-```typescript
-const captcha = new K9Guard({ type: 'riddle', difficulty: 'easy', locale: 'en' });
-const challenge = captcha.generate();
-// Output: "What has keys but can't open locks?"
-// Answer: "piano"
-```
-
 ### Sequence CAPTCHA
 
 ```typescript
@@ -96,24 +85,73 @@ const challenge = captcha.generate();
 // Answer: "cat"
 ```
 
-### Logic CAPTCHA
+### Reverse CAPTCHA
 
 ```typescript
-const captcha = new K9Guard({ type: 'logic', difficulty: 'easy', locale: 'en' });
+const captcha = new K9Guard({ type: 'reverse', difficulty: 'easy' });
 const challenge = captcha.generate();
-// Output: "Water is dry. True or False?"
-// Answer: "false"
+// Output: "god"
+// Answer: "dog"
 ```
 
-### Reverse CAPTCHA
+### Image CAPTCHA
 
 ```typescript
-const captcha = new K9Guard({ type: 'reverse', difficulty: 'easy' });
+const captcha = new K9Guard({ type: 'image', difficulty: 'medium' });
 const challenge = captcha.generate();
-// Output: "god"
-// Answer: "dog"
+
+// challenge.image — base64 SVG data URI, render it directly in an <img> tag
+// challenge.question — "Type the characters shown in the image"
+console.log(challenge.image); // "data:image/svg+xml;base64,..."
+
+// validate user input (case-insensitive)
+const isValid = captcha.validate(challenge, "aB3z");
+if (isValid) {
+  console.log("Access granted!");
+} else {
+  console.log("Wrong answer!");
+}
+```
+
+The image is a distorted SVG with:
+- **Rotated & offset characters** per-glyph, randomized color and size
+- **Sinusoidal wave overlays** proportional to difficulty
+- **Noise lines and dots** that break simple segmentation attacks
+- **Case-insensitive validation** — user may type upper or lowercase
+- **No external dependencies** — pure SVG generated server-side
+
+### Emoji CAPTCHA
+
+```typescript
+const captcha = new K9Guard({ type: 'emoji', difficulty: 'medium' });
+const challenge = captcha.generate();
+
+// challenge.emojis — array of emojis to display (6 for medium)
+// challenge.category — the target category name (e.g. "animals")
+// challenge.question — "Select all animals from the list (6 emojis, 3 correct)"
+console.log(challenge.emojis);   // ["🐶", "🍎", "🚗", "🐱", "🌸", "🏀"]
+console.log(challenge.category); // "animals"
+
+// user submits sorted comma-separated zero-based indices of the correct emojis
+// e.g. if emojis[0] and emojis[3] are animals: "0,3"
+const isValid = captcha.validate(challenge, "0,3");
+if (isValid) {
+  console.log("Access granted!");
+} else {
+  console.log("Wrong answer!");
+}
 ```
 
+Difficulty controls the number of emojis shown and correct answers required:
+
+| Difficulty | Total emojis | Correct to select |
+|------------|-------------|-------------------|
+| easy       | 4           | 2                 |
+| medium     | 6           | 3                 |
+| hard       | 8           | 4                 |
+
+There are 5 categories (animals, food, vehicles, nature, sports) with 20 emojis each. Distractors are drawn from all other categories. Answer format: sorted comma-separated zero-based indices, e.g. `"0,2,4"`.
+
 ### Mixed CAPTCHA
 
 ```typescript
@@ -129,9 +167,9 @@ const captcha = new K9Guard({ type: 'multi', difficulty: 'easy' });
 const challenge = captcha.generate();
 
 if (challenge.steps) {
-  // user must solve both steps
-  const answers = challenge.steps.map(step => step.answer.toString());
-  const userInput = JSON.stringify(answers);
+  // user must solve both steps; steps expose only question/nonce/expiry — not the answer
+  // answers are submitted as a JSON array of strings
+  const userInput = JSON.stringify(["22", "typescript"]);
   const isValid = captcha.validate(challenge, userInput);
 }
 ```
@@ -160,9 +198,8 @@ const isValid = captcha.validate(challenge, "paris");
 
 ```typescript
 interface K9GuardOptions {
-  type: 'math' | 'text' | 'riddle' | 'sequence' | 'scramble' | 'logic' | 'reverse' | 'mixed' | 'multi';
+  type: 'math' | 'text' | 'sequence' | 'scramble' | 'reverse' | 'mixed' | 'multi' | 'image' | 'emoji';
   difficulty: 'easy' | 'medium' | 'hard';
-  locale?: 'en' | 'tr'; // default: 'en'
 }
 ```
 
@@ -185,18 +222,22 @@ interface CustomQuestion {
 
 #### `generate(): CaptchaChallenge`
 
-Generates a new CAPTCHA challenge with unique nonce, expiry time, and hashed answer.
+Generates a new CAPTCHA challenge. Returns a **public** object safe to send to the client — `answer`, `hashedAnswer` and `salt` are stripped and stored server-side, keyed by `nonce`.
 
 ```typescript
 const challenge = captcha.generate();
-console.log(challenge.question); // the question to show user
-console.log(challenge.nonce); // unique session identifier
-console.log(challenge.expiry); // timestamp when challenge expires
+console.log(challenge.question);  // the question to show the user
+console.log(challenge.nonce);     // unique session identifier (pass back on validate)
+console.log(challenge.expiry);    // Unix ms timestamp when challenge expires
+console.log(challenge.image);     // base64 SVG data URI (only for type: 'image')
+console.log(challenge.emojis);    // emoji array (only for type: 'emoji')
+console.log(challenge.category);  // category name (only for type: 'emoji')
+// challenge.answer / .hashedAnswer / .salt — NOT present; never sent to client
 ```
 
 #### `validate(challenge: CaptchaChallenge, userInput: string): boolean`
 
-Validates user input against the challenge. Returns `true` if correct, `false` otherwise.
+Validates user input against the stored server-side record (looked up by `challenge.nonce`). Returns `true` if correct, `false` otherwise. Tampered `hashedAnswer` or `salt` on the public challenge object have no effect.
 
 ```typescript
 const isValid = captcha.validate(challenge, userAnswer);
@@ -213,7 +254,6 @@ bun run src/test.ts
 Tests include:
 - All CAPTCHA types with correct/incorrect/edge case inputs
 - Custom question validation
-- Locale switching
 - Multi-step challenges
 - Input sanitization
 - Security validations

package/docs/tr/README.md

@@ -4,14 +4,13 @@
 
 # K9Guard
 
-TypeScript/JavaScript projeleri için kriptografik güvenlik ve çok dilli destek sunan güvenli, hafif ve esnek bir CAPTCHA modülü.
+TypeScript/JavaScript projeleri için kriptografik güvenlik sunan güvenli, hafif ve esnek bir CAPTCHA modülü.
 
 ## Özellikler
 
 - **Kriptografik Güvenlik**: NIST SP 800-90A standardına uyumluluk sağlanmıştır
-- **Çok Dilli Destek**: Bulmaca ve mantık soruları için İngilizce ve Türkçe dil desteği mevcuttur
-- **9 CAPTCHA Türü**: Matematik, metin, bulmaca, dizi, karıştırma, mantık, ters çevirme, karma ve çok adımlı doğrulama yöntemleri
-- **Güvenlik Odaklı**: SHA-256 tuzlu hash algoritması, nonce tabanlı oturum yönetimi ve 5 dakikalık geçerlilik süresi
+- **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
+- **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
 - **Ö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ı
@@ -32,8 +31,7 @@ import K9Guard from "k9guard";
 
 const captcha = new K9Guard({
   type: 'math',
-  difficulty: 'medium',
-  locale: 'tr'
+  difficulty: 'medium'
 });
 
 // doğrulama sorusu oluştur
@@ -69,15 +67,6 @@ const challenge = captcha.generate();
 // Cevap: "aB2xY9"
 ```
 
-### Bulmaca CAPTCHA
-
-```typescript
-const captcha = new K9Guard({ type: 'riddle', difficulty: 'easy', locale: 'tr' });
-const challenge = captcha.generate();
-// Çıktı: "Tuşları vardır ama kilit açamaz. Nedir?"
-// Cevap: "piyano"
-```
-
 ### Dizi CAPTCHA
 
 ```typescript
@@ -92,28 +81,77 @@ const challenge = captcha.generate();
 ```typescript
 const captcha = new K9Guard({ type: 'scramble', difficulty: 'easy' });
 const challenge = captcha.generate();
-// Çıktı: "iked"
-// Cevap: "kedi"
+// Çıktı: "tac"
+// Cevap: "cat"
 ```
 
-### Mantık CAPTCHA
+### Ters Çevirme CAPTCHA
 
 ```typescript
-const captcha = new K9Guard({ type: 'logic', difficulty: 'easy', locale: 'tr' });
+const captcha = new K9Guard({ type: 'reverse', difficulty: 'easy' });
 const challenge = captcha.generate();
-// Çıktı: "Su kuru bir maddedir. Doğru mu Yanlış mı?"
-// Cevap: "yanlış"
+// Çıktı: "god"
+// Cevap: "dog"
 ```
 
-### Ters Çevirme CAPTCHA
+### Görsel CAPTCHA
 
 ```typescript
-const captcha = new K9Guard({ type: 'reverse', difficulty: 'easy' });
+const captcha = new K9Guard({ type: 'image', difficulty: 'medium' });
+const challenge = captcha.generate();
+
+// challenge.image — doğrudan <img> etiketinde kullanılabilecek base64 SVG data URI
+// challenge.question — "Type the characters shown in the image"
+console.log(challenge.image); // "data:image/svg+xml;base64,..."
+
+// kullanıcı yanıtını doğrula (büyük/küçük harf duyarsız)
+const isValid = captcha.validate(challenge, "aB3z");
+if (isValid) {
+  console.log("Erişim izni verildi!");
+} else {
+  console.log("Yanlış cevap!");
+}
+```
+
+Görsel CAPTCHA'nın güvenlik özellikleri:
+- **Karakter başına rotasyon ve offset** — rastgele renk ve boyutla OCR direnci
+- **Sinüzoidal dalga katmanları** — zorluk seviyesine orantılı üst üste bindirilir
+- **Gürültü çizgileri ve noktaları** — basit segmentasyon saldırılarını engeller
+- **Büyük/küçük harf duyarsız doğrulama** — kullanıcı hem büyük hem küçük harf girebilir
+- **Sıfır dış bağımlılık** — tamamen sunucu tarafında saf SVG ile üretilir
+
+### Emoji CAPTCHA
+
+```typescript
+const captcha = new K9Guard({ type: 'emoji', difficulty: 'medium' });
 const challenge = captcha.generate();
-// Çıktı: "köpek"
-// Cevap: "kepök"
+
+// challenge.emojis — gösterilecek emoji dizisi (medium için 6 adet)
+// challenge.category — hedef kategori adı (örn. "animals")
+// challenge.question — "Select all animals from the list (6 emojis, 3 correct)"
+console.log(challenge.emojis);   // ["🐶", "🍎", "🚗", "🐱", "🌸", "🏀"]
+console.log(challenge.category); // "animals"
+
+// kullanıcı, doğru emojilerin sıfır tabanlı indekslerini virgülle ayırarak gönderir
+// örn. emojis[0] ve emojis[3] hayvan ise: "0,3"
+const isValid = captcha.validate(challenge, "0,3");
+if (isValid) {
+  console.log("Erişim izni verildi!");
+} else {
+  console.log("Yanlış cevap!");
+}
 ```
 
+Zorluk seviyesi gösterilen emoji sayısını ve doğru seçilmesi gereken emoji sayısını belirler:
+
+| Zorluk  | Toplam emoji | Seçilmesi gereken |
+|---------|-------------|-------------------|
+| easy    | 4           | 2                 |
+| medium  | 6           | 3                 |
+| hard    | 8           | 4                 |
+
+5 kategori mevcuttur (animals, food, vehicles, nature, sports), her birinde 20 emoji bulunur. Yanıltıcı emojiler diğer kategorilerden seçilir. Cevap formatı: sıralanmış, virgülle ayrılmış sıfır tabanlı indeksler; örn. `"0,2,4"`.
+
 ### Karma CAPTCHA
 
 ```typescript
@@ -129,9 +167,9 @@ const captcha = new K9Guard({ type: 'multi', difficulty: 'easy' });
 const challenge = captcha.generate();
 
 if (challenge.steps) {
-  // kullanıcı her iki adımı da çözmelidir
-  const answers = challenge.steps.map(step => step.answer.toString());
-  const userInput = JSON.stringify(answers);
+  // kullanıcı her iki adımı da çözmelidir; steps yalnızca question/nonce/expiry içerir
+  // cevaplar JSON dizisi olarak gönderilir
+  const userInput = JSON.stringify(["22", "typescript"]);
   const isValid = captcha.validate(challenge, userInput);
 }
 ```
@@ -160,9 +198,8 @@ const isValid = captcha.validate(challenge, "ankara");
 
 ```typescript
 interface K9GuardOptions {
-  type: 'math' | 'text' | 'riddle' | 'sequence' | 'scramble' | 'logic' | 'reverse' | 'mixed' | 'multi';
+  type: 'math' | 'text' | 'sequence' | 'scramble' | 'reverse' | 'mixed' | 'multi' | 'image' | 'emoji';
   difficulty: 'easy' | 'medium' | 'hard';
-  locale?: 'en' | 'tr'; // varsayılan: 'en'
 }
 ```
 
@@ -185,18 +222,22 @@ interface CustomQuestion {
 
 #### `generate(): CaptchaChallenge`
 
-Benzersiz nonce, geçerlilik süresi ve hash'lenmiş cevap içeren yeni bir CAPTCHA doğrulaması oluşturur.
+İ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.
 
 ```typescript
 const challenge = captcha.generate();
-console.log(challenge.question); // kullanıcıya gösterilecek soru
-console.log(challenge.nonce); // benzersiz oturum tanımlayıcısı
-console.log(challenge.expiry); // doğrulamanın geçerlilik süresi sona erme zamanı
+console.log(challenge.question);  // kullanıcıya gösterilecek soru
+console.log(challenge.nonce);     // benzersiz oturum tanımlayıcısı (validate'e geri gönderilir)
+console.log(challenge.expiry);    // Unix ms cinsinden geçerlilik bitiş zamanı
+console.log(challenge.image);     // base64 SVG data URI (yalnızca type: 'image' için)
+console.log(challenge.emojis);    // emoji dizisi (yalnızca type: 'emoji' için)
+console.log(challenge.category);  // kategori adı (yalnızca type: 'emoji' için)
+// challenge.answer / .hashedAnswer / .salt — MEVCUT DEĞİL; istemciye hiç gönderilmez
 ```
 
 #### `validate(challenge: CaptchaChallenge, userInput: string): boolean`
 
-Kullanıcı girdisini doğrulama ile karşılaştırır. Doğruysa `true`, yanlışsa `false` değeri döndürür.
+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.
 
 ```typescript
 const isValid = captcha.validate(challenge, userAnswer);
@@ -213,7 +254,6 @@ bun run src/test.ts
 Testler şunları içerir:
 - Tüm CAPTCHA türleri için doğru/yanlış/uç durum girdileri
 - Özel soru doğrulama senaryoları
-- Dil değiştirme işlemleri
 - Çok adımlı doğrulamalar
 - Girdi sanitizasyonu
 - Güvenlik doğrulamaları

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "k9guard",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "A secure, lightweight, and flexible CAPTCHA module for TypeScript/JavaScript projects with cryptographic security and multi-language support",
   "main": "index.ts",
   "type": "module",
@@ -47,12 +47,12 @@
   },
   "devDependencies": {
     "@types/bun": "latest",
-    "@types/node": "^20.0.0",
-    "@typescript-eslint/eslint-plugin": "^6.0.0",
-    "@typescript-eslint/parser": "^6.0.0",
-    "eslint": "^8.0.0",
-    "tsx": "^4.0.0",
-    "typescript": "^5.0.0"
+    "@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"

package/src/K9Guard.ts

@@ -15,7 +15,7 @@ export class K9Guard {
 
   private processOptions(options: unknown): K9GuardOptions | K9GuardCustomOptions {
     if (typeof options !== 'object' || options === null) {
-      return { type: 'math', difficulty: 'medium', locale: 'en' };
+      return { type: 'math', difficulty: 'medium' };
     }
 
     const opt = options as Record<string, unknown>;
@@ -36,10 +36,12 @@ export class K9Guard {
       } 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: opt.type || 'math',
-      difficulty: opt.difficulty || 'medium',
-      locale: opt.locale || 'en'
+      type,
+      difficulty: opt.difficulty || 'medium'
     } as K9GuardOptions;
   }
 
@@ -56,12 +58,20 @@ export class K9Guard {
       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 > challenge.expiry) {
+    if (now > stored.expiry) {
       return false;
     }
 
-    return CaptchaValidator.validate(challenge, userInput);
+    return CaptchaValidator.validate(stored, userInput);
   }
 
   private isValidChallenge(challenge: unknown): boolean {
@@ -74,10 +84,8 @@ export class K9Guard {
     return (
       typeof c.type === 'string' &&
       typeof c.question === 'string' &&
-      typeof c.nonce === 'string' &&
-      typeof c.expiry === 'number' &&
-      typeof c.hashedAnswer === 'string' &&
-      typeof c.salt === 'string'
+      typeof c.nonce === 'string' && c.nonce.length > 0 &&
+      typeof c.expiry === 'number'
     );
   }
 }