k9guard 1.0.1 → 1.0.2

package/src/core/captchaGenerator.ts

@@ -1,19 +1,25 @@
 import { createHash, randomBytes } from '../utils/crypto';
 import { Random } from '../utils/random';
-import { RiddleBank } from '../utils/riddleBank';
 import { SequenceGenerator } from '../utils/sequenceGenerator';
 import { ScrambleGenerator } from '../utils/scrambleGenerator';
-import { LogicGenerator } from '../utils/logicGenerator';
 import { ReverseGenerator } from '../utils/reverseGenerator';
 import { CustomQuestionGenerator } from '../utils/customQuestionGenerator';
 import { CustomQuestionValidator } from '../validators/customQuestionValidator';
-import type { K9GuardOptions, K9GuardCustomOptions, CaptchaChallenge, MathCaptcha, TextCaptcha, RiddleCaptcha, SequenceCaptcha, ScrambleCaptcha, LogicCaptcha, ReverseCaptcha, MixedCaptcha, CustomCaptcha, CustomQuestion } from '../types';
+import { ImageGenerator } from '../utils/imageGenerator';
+import { EmojiGenerator } from '../utils/emojiGenerator';
+import type { K9GuardOptions, K9GuardCustomOptions, CaptchaChallenge, StoredChallenge, MathCaptcha, TextCaptcha, SequenceCaptcha, ScrambleCaptcha, ReverseCaptcha, MixedCaptcha, CustomCaptcha, ImageCaptcha, EmojiCaptcha, CustomQuestion } from '../types';
+
+// Bounded nonce store: evicts the oldest entry once capacity is reached to
+// prevent unbounded memory growth while still blocking same-process replays.
+const NONCE_STORE_MAX = 10_000;
 
 export class CaptchaGenerator {
   private standardOptions: K9GuardOptions | null = null;
   private customOptions: K9GuardCustomOptions | null = null;
   private customGenerator: CustomQuestionGenerator | null = null;
-  private usedNonces: Set<string> = new Set();
+  // Keyed by nonce; stores the full server-side record including answer hash and salt.
+  // answer, hashedAnswer and salt are never included in the public CaptchaChallenge.
+  private store: Map<string, StoredChallenge> = new Map();
 
   // set up the generator and check custom questions if they exist
   constructor(options: K9GuardOptions | K9GuardCustomOptions) {
@@ -46,39 +52,41 @@ export class CaptchaGenerator {
     return this.standardOptions.difficulty;
   }
 
-  private getLocale(): 'en' | 'tr' {
-    if (!this.standardOptions) {
-      return 'en';
-    }
-    return this.standardOptions.locale || 'en';
+  // Look up the internal StoredChallenge by nonce for use during validation.
+  lookup(nonce: string): StoredChallenge | undefined {
+    return this.store.get(nonce);
   }
 
-  // add security stuff to the challenge like unique nonce, expiry time, and hashed answer
-  private createChallenge(base: Omit<CaptchaChallenge, 'nonce' | 'expiry' | 'hashedAnswer' | 'salt'>): CaptchaChallenge {
+  // Stores the full record server-side; returns a public CaptchaChallenge
+  // that is safe to send to the client (no answer, hashedAnswer or salt).
+  private createChallenge(base: Omit<StoredChallenge, 'nonce' | 'expiry' | 'hashedAnswer' | 'salt'>): CaptchaChallenge {
     let nonce: string;
     do {
-      // NOTE: make sure each nonce is unique to stop replay attacks
       nonce = Random.generateNonce();
-    } while (this.usedNonces.has(nonce));
+    } while (this.store.has(nonce));
 
-    this.usedNonces.add(nonce);
+    // evict oldest entry before inserting to cap memory at NONCE_STORE_MAX
+    if (this.store.size >= NONCE_STORE_MAX) {
+      const oldest = this.store.keys().next().value;
+      if (oldest !== undefined) {
+        this.store.delete(oldest);
+      }
+    }
 
-    // challenge will expire in 5 minutes
     const expiry = Date.now() + 5 * 60 * 1000;
     const salt = Random.generateSalt();
-    // never save the real answer, only the hash for checking later
+    // answer is never sent to the client; only its salted hash is stored
     const hashedAnswer = createHash('sha256').update(base.answer.toString() + salt).digest('hex');
 
-    return {
-      ...base,
-      nonce,
-      expiry,
-      hashedAnswer,
-      salt
-    };
+    const stored: StoredChallenge = { ...base, nonce, expiry, hashedAnswer, salt };
+    this.store.set(nonce, stored);
+
+    // strip sensitive fields before returning to caller
+    const { answer: _answer, hashedAnswer: _ha, salt: _salt, ...publicChallenge } = stored;
+    return publicChallenge as CaptchaChallenge;
   }
 
-  // do the math based on which operator we got
+  // evaluate arithmetic expression for the math captcha type
   private calculateMath(a: number, op: string, b: number): number {
     if (op === '+') {
       return a + b;
@@ -91,16 +99,15 @@ export class CaptchaGenerator {
     }
     if (op === '/') {
       if (b === 0) {
-        // can't divide by zero, return NaN
         return Number.NaN;
       }
-      // round to 2 decimals to avoid weird floating point numbers
+      // round to 2 decimals to avoid floating point representation issues
       return Math.round((a / b) * 100) / 100;
     }
     return 0;
   }
 
-  // main function that picks the right generator for the captcha type
+  // dispatch to the correct generator based on configured captcha type
   generate(): CaptchaChallenge {
     if (this.customOptions) {
       return this.generateCustom();
@@ -118,24 +125,24 @@ export class CaptchaGenerator {
     if (captchaType === 'text') {
       return this.generateText();
     }
-    if (captchaType === 'riddle') {
-      return this.generateRiddle();
-    }
     if (captchaType === 'sequence') {
       return this.generateSequence();
     }
     if (captchaType === 'scramble') {
       return this.generateScramble();
     }
-    if (captchaType === 'logic') {
-      return this.generateLogic();
-    }
     if (captchaType === 'reverse') {
       return this.generateReverse();
     }
     if (captchaType === 'multi') {
       return this.generateMulti();
     }
+    if (captchaType === 'image') {
+      return this.generateImage();
+    }
+    if (captchaType === 'emoji') {
+      return this.generateEmoji();
+    }
     return this.generateMixed();
   }
 
@@ -145,26 +152,42 @@ export class CaptchaGenerator {
     }
 
     const custom = this.customGenerator.generate();
+
+    // an empty answer would allow bypass with any blank input; reject early
+    if (!custom.question || !custom.answer) {
+      throw new Error('Custom question pool returned an empty question or answer');
+    }
+
     return this.createChallenge({ type: 'custom', question: custom.question, answer: custom.answer }) as CustomCaptcha;
   }
 
   private generateMath(): MathCaptcha {
-    let num1 = Random.getRandomNumber(this.getDifficulty());
-    let num2 = Random.getRandomNumber(this.getDifficulty());
+    const difficulty = this.getDifficulty();
+    let num1 = Random.getRandomNumber(difficulty);
+    let num2 = Random.getRandomNumber(difficulty);
     const operator = Random.getRandomOperator();
 
+    // guarantee non-zero divisor; add 1 so the result is always >= 1
     if (operator === '/' && num2 === 0) {
-      num2 = Random.getRandomNumber(this.getDifficulty()) + 1;
+      num2 = Random.getRandomNumber(difficulty) + 1;
     }
 
-    const question = `${num1} ${operator} ${num2}`;
     const answer = this.calculateMath(num1, operator, num2);
 
-    if (isNaN(answer)) {
-      return this.generateMath();
+    // calculateMath only returns NaN for division by zero, which is already
+    // prevented above — but guard here avoids any future regression without
+    // unbounded recursion: iterate instead of recurse
+    if (isNaN(answer) || !isFinite(answer)) {
+      num1 = Random.getRandomNumber(difficulty);
+      num2 = Random.getRandomNumber(difficulty) + 1;
+      return this.createChallenge({
+        type: 'math',
+        question: `${num1} + ${num2}`,
+        answer: num1 + num2
+      }) as MathCaptcha;
     }
 
-    return this.createChallenge({ type: 'math', question, answer }) as MathCaptcha;
+    return this.createChallenge({ type: 'math', question: `${num1} ${operator} ${num2}`, answer }) as MathCaptcha;
   }
 
   private generateText(): TextCaptcha {
@@ -172,11 +195,6 @@ export class CaptchaGenerator {
     return this.createChallenge({ type: 'text', question: text, answer: text }) as TextCaptcha;
   }
 
-  private generateRiddle(): RiddleCaptcha {
-    const riddle = RiddleBank.getRandom(this.getLocale(), this.getDifficulty());
-    return this.createChallenge({ type: 'riddle', question: riddle.question, answer: riddle.answer }) as RiddleCaptcha;
-  }
-
   private generateSequence(): SequenceCaptcha {
     const seq = SequenceGenerator.generate(this.getDifficulty());
     return this.createChallenge({ type: 'sequence', question: seq.question, answer: seq.answer }) as SequenceCaptcha;
@@ -187,41 +205,65 @@ export class CaptchaGenerator {
     return this.createChallenge({ type: 'scramble', question: scr.question, answer: scr.answer }) as ScrambleCaptcha;
   }
 
-  private generateLogic(): LogicCaptcha {
-    const logic = LogicGenerator.getRandom(this.getLocale(), this.getDifficulty());
-    return this.createChallenge({ type: 'logic', question: logic.question, answer: logic.answer }) as LogicCaptcha;
-  }
-
   private generateReverse(): ReverseCaptcha {
     const rev = ReverseGenerator.generate(this.getDifficulty());
     return this.createChallenge({ type: 'reverse', question: rev.question, answer: rev.answer }) as ReverseCaptcha;
   }
 
-  // generates a mixed captcha by randomly selecting a type and generating accordingly
+  // randomly selects one of the available non-compound types
   private generateMixed(): MixedCaptcha {
-    const types: ('math' | 'text' | 'riddle' | 'sequence' | 'scramble' | 'logic' | 'reverse')[] = ['math', 'text', 'riddle', 'sequence', 'scramble', 'logic', 'reverse'];
+    const types = ['math', 'text', 'sequence', 'scramble', 'reverse'] as const;
     const buffer = randomBytes(1) as any;
     const randomType = types[buffer[0]! % types.length]!;
 
-    const previousType = this.standardOptions?.type;
-    if (this.standardOptions) {
-      // NOTE: change the type temporarily so we can call generate() again
-      this.standardOptions.type = randomType;
-    }
-
-    const challenge = this.generate();
-    if (this.standardOptions && previousType) {
-      // put back the old type when done
-      this.standardOptions.type = previousType;
+    // resolve the raw answer directly so we can pass it to createChallenge;
+    // avoids mutating this.standardOptions and prevents race conditions
+    let question: string;
+    let answer: string | number;
+
+    if (randomType === 'math') {
+      const difficulty = this.getDifficulty();
+      let num1 = Random.getRandomNumber(difficulty);
+      let num2 = Random.getRandomNumber(difficulty);
+      const operator = Random.getRandomOperator();
+      if (operator === '/' && num2 === 0) {
+        num2 = Random.getRandomNumber(difficulty) + 1;
+      }
+      const result = this.calculateMath(num1, operator, num2);
+      if (isNaN(result) || !isFinite(result)) {
+        num1 = Random.getRandomNumber(difficulty);
+        num2 = Random.getRandomNumber(difficulty) + 1;
+        question = `${num1} + ${num2}`;
+        answer = num1 + num2;
+      } else {
+        question = `${num1} ${operator} ${num2}`;
+        answer = result;
+      }
+    } else if (randomType === 'text') {
+      const text = Random.generateRandomString(this.getDifficulty());
+      question = text;
+      answer = text;
+    } else if (randomType === 'sequence') {
+      const seq = SequenceGenerator.generate(this.getDifficulty());
+      question = seq.question;
+      answer = seq.answer;
+    } else if (randomType === 'scramble') {
+      const scr = ScrambleGenerator.generate(this.getDifficulty());
+      question = scr.question;
+      answer = scr.answer;
+    } else {
+      const rev = ReverseGenerator.generate(this.getDifficulty());
+      question = rev.question;
+      answer = rev.answer;
     }
 
-    return this.createChallenge({ ...challenge, type: 'mixed' }) as MixedCaptcha;
+    return this.createChallenge({ type: 'mixed', question, answer }) as MixedCaptcha;
   }
 
-  // make a two-step captcha with math and riddle
+  // two-step captcha: math + scramble, both must be solved correctly
   private generateMulti(): CaptchaChallenge {
-    const step1 = this.generateMath();
-    const step2 = this.generateRiddle();
+    const step1 = this.store.get(this.generateMath().nonce)!;
+    const step2 = this.store.get(this.generateScramble().nonce)!;
 
     return this.createChallenge({
       type: 'multi',
@@ -230,4 +272,27 @@ export class CaptchaGenerator {
       steps: [step1, step2]
     });
   }
+
+  // generates an SVG-based visual CAPTCHA immune to trivial OCR attacks
+  private generateImage(): ImageCaptcha {
+    const result = ImageGenerator.generate(this.getDifficulty());
+    return this.createChallenge({
+      type: 'image',
+      question: result.question,
+      answer: result.answer,
+      image: result.image
+    }) as ImageCaptcha;
+  }
+
+  // generates an emoji selection CAPTCHA: user picks all emojis from a given category
+  private generateEmoji(): EmojiCaptcha {
+    const result = EmojiGenerator.generate(this.getDifficulty());
+    return this.createChallenge({
+      type: 'emoji',
+      question: result.question,
+      answer: result.answer,
+      emojis: result.emojis,
+      category: result.category
+    }) as EmojiCaptcha;
+  }
 }

package/src/core/captchaValidator.ts

@@ -1,12 +1,13 @@
 import { createHash } from '../utils/crypto';
-import type { CaptchaChallenge } from '../types';
+import { timingSafeEqual } from 'node:crypto';
+import type { StoredChallenge } from '../types';
 
 export class CaptchaValidator {
   private static readonly MAX_INPUT_LENGTH = 1000;
   private static readonly VALID_CHAR_REGEX = /^[a-zA-Z0-9\s\-çÇğĞıİöÖşŞüÜ.,'!?]*$/;
 
   // main validation entry point, routes to the correct validator based on challenge type
-  static validate(challenge: CaptchaChallenge, userInput: string): boolean {
+  static validate(challenge: StoredChallenge, userInput: string): boolean {
     if (!this.isValidInput(userInput)) {
       return false;
     }
@@ -19,6 +20,14 @@ export class CaptchaValidator {
       return this.validateCustom(challenge, userInput);
     }
 
+    if (challenge.type === 'image') {
+      return this.validateImage(challenge, userInput);
+    }
+
+    if (challenge.type === 'emoji') {
+      return this.validateEmoji(challenge, userInput);
+    }
+
     if (this.isNumericChallenge(challenge)) {
       return this.validateNumeric(challenge, userInput);
     }
@@ -37,7 +46,7 @@ export class CaptchaValidator {
   }
 
   // validates multi step captchas by checking each step individually
-  private static validateMulti(challenge: CaptchaChallenge, userInput: string): boolean {
+  private static validateMulti(challenge: StoredChallenge, userInput: string): boolean {
     if (!challenge.steps || challenge.steps.length === 0) {
       return false;
     }
@@ -71,11 +80,14 @@ export class CaptchaValidator {
     return true;
   }
 
-  private static isNumericChallenge(challenge: CaptchaChallenge): boolean {
-    return challenge.type === 'math' || challenge.type === 'sequence' || (challenge.type === 'mixed' && typeof challenge.answer === 'number');
+  private static isNumericChallenge(challenge: StoredChallenge): boolean {
+    // sequence can return string answers (e.g. letters for medium difficulty), so check the actual answer type
+    return challenge.type === 'math' ||
+      (challenge.type === 'sequence' && typeof challenge.answer === 'number') ||
+      (challenge.type === 'mixed' && typeof challenge.answer === 'number');
   }
 
-  private static validateNumeric(challenge: CaptchaChallenge, userInput: string): boolean {
+  private static validateNumeric(challenge: StoredChallenge, userInput: string): boolean {
     const inputNum = parseFloat(userInput);
 
     // make sure we got a valid number, not NaN or Infinity
@@ -86,7 +98,7 @@ export class CaptchaValidator {
     return this.verifyAnswer(challenge, inputNum.toString());
   }
 
-  private static validateText(challenge: CaptchaChallenge, userInput: string): boolean {
+  private static validateText(challenge: StoredChallenge, userInput: string): boolean {
     const sanitized = userInput.trim();
 
     if (!this.VALID_CHAR_REGEX.test(sanitized)) {
@@ -96,16 +108,26 @@ export class CaptchaValidator {
     return this.verifyAnswer(challenge, sanitized);
   }
 
-  // NOTE: hash the user input with same salt and compare to stored hash
-  private static verifyAnswer(challenge: CaptchaChallenge, userInput: string): boolean {
+  // hash the user input with the same salt and compare using a constant-time
+  // equality check to eliminate timing side-channels
+  private static verifyAnswer(challenge: StoredChallenge, userInput: string): boolean {
     const userHash = createHash('sha256')
       .update(userInput + challenge.salt)
       .digest('hex');
 
-    return userHash === challenge.hashedAnswer;
+    // both buffers must be the same length for timingSafeEqual; hex-encoded
+    // SHA-256 is always 64 chars so this holds unless hashedAnswer is corrupted
+    if (userHash.length !== challenge.hashedAnswer.length) {
+      return false;
+    }
+
+    return timingSafeEqual(
+      Buffer.from(userHash, 'hex'),
+      Buffer.from(challenge.hashedAnswer, 'hex')
+    );
   }
 
-  private static validateCustom(challenge: CaptchaChallenge, userInput: string): boolean {
+  private static validateCustom(challenge: StoredChallenge, userInput: string): boolean {
     const sanitized = userInput.trim();
 
     if (!this.VALID_CHAR_REGEX.test(sanitized)) {
@@ -114,4 +136,47 @@ export class CaptchaValidator {
 
     return this.verifyAnswer(challenge, sanitized);
   }
+
+  // image answers are case-insensitive; only alphanumeric chars are accepted
+  private static validateImage(challenge: StoredChallenge, userInput: string): boolean {
+    const sanitized = userInput.trim().toLowerCase();
+
+    if (!/^[a-z0-9]+$/.test(sanitized)) {
+      return false;
+    }
+
+    if (sanitized.length < 1 || sanitized.length > 20) {
+      return false;
+    }
+
+    return this.verifyAnswer(challenge, sanitized);
+  }
+
+  // emoji answers: comma-separated zero-based indices e.g. "0,2,4"
+  // parsed, deduplicated, sorted numerically then re-joined to produce the canonical form
+  private static validateEmoji(challenge: StoredChallenge, userInput: string): boolean {
+    const trimmed = userInput.trim();
+
+    // only digits and commas are valid; reject anything else to prevent injection
+    if (!/^[0-9,]+$/.test(trimmed)) {
+      return false;
+    }
+
+    const parts = trimmed.split(',').filter(s => s.length > 0);
+
+    if (parts.length === 0 || parts.length > 20) {
+      return false;
+    }
+
+    const indices = parts.map(Number);
+
+    if (indices.some(n => isNaN(n) || n < 0 || !Number.isInteger(n))) {
+      return false;
+    }
+
+    // canonical form matches what EmojiGenerator stored: sorted unique indices
+    const normalized = [...new Set(indices)].sort((a, b) => a - b).join(',');
+
+    return this.verifyAnswer(challenge, normalized);
+  }
 }

package/src/types/index.ts

@@ -1,7 +1,6 @@
 export 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';
 }
 
 export interface CustomQuestion {
@@ -15,58 +14,71 @@ export interface K9GuardCustomOptions {
   questions: CustomQuestion[];
 }
 
-export interface CaptchaChallenge {
-  type: 'math' | 'text' | 'riddle' | 'sequence' | 'scramble' | 'logic' | 'reverse' | 'mixed' | 'multi' | 'custom';
+// Internal: full challenge record kept server-side only.
+// answer, hashedAnswer and salt must never leave the server.
+export interface StoredChallenge {
+  type: 'math' | 'text' | 'sequence' | 'scramble' | 'reverse' | 'mixed' | 'multi' | 'custom' | 'image' | 'emoji';
   question: string;
   answer: string | number;
   nonce: string;
   expiry: number;
   hashedAnswer: string;
   salt: string;
+  steps?: StoredChallenge[];
+  image?: string;
+  emojis?: string[];
+  category?: string;
+}
+
+// Public: safe subset sent to the client.
+// answer, hashedAnswer and salt are intentionally omitted to prevent
+// hash-injection attacks where an attacker forges hashedAnswer on the client.
+export interface CaptchaChallenge {
+  type: StoredChallenge['type'];
+  question: string;
+  nonce: string;
+  expiry: number;
   steps?: CaptchaChallenge[];
+  image?: string;
+  emojis?: string[];
+  category?: string;
+}
+
+export interface ImageCaptcha extends CaptchaChallenge {
+  type: 'image';
+  image: string;
 }
 
 export interface MathCaptcha extends CaptchaChallenge {
   type: 'math';
-  answer: number;
 }
 
 export interface TextCaptcha extends CaptchaChallenge {
   type: 'text';
-  answer: string;
-}
-
-export interface RiddleCaptcha extends CaptchaChallenge {
-  type: 'riddle';
-  answer: string;
 }
 
 export interface SequenceCaptcha extends CaptchaChallenge {
   type: 'sequence';
-  answer: string | number;
 }
 
 export interface ScrambleCaptcha extends CaptchaChallenge {
   type: 'scramble';
-  answer: string;
-}
-
-export interface LogicCaptcha extends CaptchaChallenge {
-  type: 'logic';
-  answer: string;
 }
 
 export interface ReverseCaptcha extends CaptchaChallenge {
   type: 'reverse';
-  answer: string;
 }
 
 export interface MixedCaptcha extends CaptchaChallenge {
   type: 'mixed';
-  answer: string | number;
 }
 
 export interface CustomCaptcha extends CaptchaChallenge {
   type: 'custom';
-  answer: string;
-}
+}
+
+export interface EmojiCaptcha extends CaptchaChallenge {
+  type: 'emoji';
+  emojis: string[];
+  category: string;
+}