k9guard 1.0.1 → 1.0.3

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,15 +4,16 @@
 
 # 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
-- **Input Validation**: Length limits, type checking, and sanitization to prevent injection attacks
+- **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
+- **Single-Use Challenges**: Every nonce is consumed on the first `validate()` call — success or failure — preventing replay and brute-force attacks
+- **Strict Configuration**: Invalid `type` or `difficulty` values throw immediately; no silent fallbacks
+- **Input Validation**: Length limits, strict numeric parsing, 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
 - **Well Tested**: Comprehensive test coverage including edge cases and security scenarios
@@ -32,8 +33,7 @@ import K9Guard from "k9guard";
 
 const captcha = new K9Guard({
   type: 'math',
-  difficulty: 'medium',
-  locale: 'en'
+  difficulty: 'medium'
 });
 
 // generate a challenge
@@ -69,15 +69,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 +87,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 +169,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);
 }
 ```
@@ -156,13 +196,14 @@ const isValid = captcha.validate(challenge, "paris");
 
 ### Constructor Options
 
+Both `type` and `difficulty` are **required** and strictly validated. Passing an invalid value throws an error immediately.
+
 #### Standard CAPTCHA Options
 
 ```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,39 +226,35 @@ 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.
+
+> **⚠️ Single-use semantics:** `validate()` consumes the nonce on the **first call**, regardless of whether the answer is correct or not. After any validation attempt, the challenge is invalidated. Always call `generate()` again before presenting a new challenge to the user.
 
 ```typescript
 const isValid = captcha.validate(challenge, userAnswer);
-```
 
-## Testing
-
-Run the included test suite:
-
-```bash
-bun run src/test.ts
+// After validate(), the challenge is consumed.
+// For a retry, generate a fresh challenge:
+if (!isValid) {
+  const newChallenge = captcha.generate();
+}
 ```
 
-Tests include:
-- All CAPTCHA types with correct/incorrect/edge case inputs
-- Custom question validation
-- Locale switching
-- Multi-step challenges
-- Input sanitization
-- Security validations
-
 ## Contributing
 
 We welcome contributions! Here's how you can help:

package/docs/tr/README.md

@@ -4,15 +4,16 @@
 
 # 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
-- **Girdi Doğrulama**: Enjeksiyon saldırılarını önlemek için uzunluk sınırlamaları, tip kontrolü ve sanitizasyon
+- **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
+- **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ı
@@ -32,8 +33,7 @@ import K9Guard from "k9guard";
 
 const captcha = new K9Guard({
   type: 'math',
-  difficulty: 'medium',
-  locale: 'tr'
+  difficulty: 'medium'
 });
 
 // doğrulama sorusu oluştur
@@ -69,15 +69,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 +83,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 +169,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);
 }
 ```
@@ -156,13 +196,14 @@ const isValid = captcha.validate(challenge, "ankara");
 
 ### 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' | '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,39 +226,35 @@ 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.
+
+> **⚠️ 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);
-```
 
-## Test Etme
-
-Dahil edilen test paketini çalıştırın:
-
-```bash
-bun run src/test.ts
+// validate() çağrısından sonra challenge tüketilir.
+// Yeniden deneme için yeni bir challenge üretilmeli:
+if (!isValid) {
+  const newChallenge = captcha.generate();
+}
 ```
 
-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ı
-
 ## Katkıda Bulunma
 
 Katkılarınızı memnuniyetle karşılıyoruz! Nasıl yardımcı olabilirsiniz:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "k9guard",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "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

@@ -7,7 +7,7 @@ export class K9Guard {
   private options: K9GuardOptions | K9GuardCustomOptions;
   private generator: CaptchaGenerator;
 
-  constructor(options: K9GuardOptions | K9GuardCustomOptions | { type: 'custom'; questions: CustomQuestion[] } = { type: 'math', difficulty: 'medium' }) {
+  constructor(options: K9GuardOptions | K9GuardCustomOptions | { type: 'custom'; questions: CustomQuestion[] }) {
     const processedOptions = this.processOptions(options);
     this.generator = new CaptchaGenerator(processedOptions);
     this.options = processedOptions;
@@ -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' };
+      throw new Error('Options must be an object');
     }
 
     const opt = options as Record<string, unknown>;
@@ -36,10 +36,19 @@ export class K9Guard {
       } as K9GuardCustomOptions;
     }
 
+    const validTypes = ['math', 'text', 'sequence', 'scramble', 'reverse', 'mixed', 'multi', 'image', 'emoji'] as const;
+    if (!validTypes.includes(opt.type as any)) {
+      throw new Error(`Invalid type. Must be one of: ${validTypes.join(', ')}`);
+    }
+
+    const validDifficulties = ['easy', 'medium', 'hard'] as const;
+    if (!validDifficulties.includes(opt.difficulty as any)) {
+      throw new Error(`Invalid difficulty. Must be one of: ${validDifficulties.join(', ')}`);
+    }
+
     return {
-      type: opt.type || 'math',
-      difficulty: opt.difficulty || 'medium',
-      locale: opt.locale || 'en'
+      type: opt.type,
+      difficulty: opt.difficulty
     } as K9GuardOptions;
   }
 
@@ -56,12 +65,19 @@ export class K9Guard {
       return false;
     }
 
-    const now = Date.now();
-    if (now > challenge.expiry) {
+    // consume() atomically removes the nonce from the store — single-use semantics.
+    // hashedAnswer and salt come from the server-side store, never from the client,
+    // which prevents hash-injection and replay attacks.
+    const stored = this.generator.consume(challenge.nonce);
+    if (!stored) {
+      return false;
+    }
+
+    if (Date.now() > stored.expiry) {
       return false;
     }
 
-    return CaptchaValidator.validate(challenge, userInput);
+    return CaptchaValidator.validate(stored, userInput);
   }
 
   private isValidChallenge(challenge: unknown): boolean {
@@ -74,10 +90,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'
     );
   }
 }