k9guard 1.0.3 → 1.0.4

package/src/core/captchaGenerator.ts

@@ -1,372 +0,0 @@
-import { createHash, randomBytes } from '../utils/crypto';
-import { Random } from '../utils/random';
-import { SequenceGenerator } from '../utils/sequenceGenerator';
-import { ScrambleGenerator } from '../utils/scrambleGenerator';
-import { ReverseGenerator } from '../utils/reverseGenerator';
-import { CustomQuestionGenerator } from '../utils/customQuestionGenerator';
-import { CustomQuestionValidator } from '../validators/customQuestionValidator';
-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;
-  // 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) {
-    if (this.isCustomOptions(options)) {
-      this.customOptions = options;
-      const validation = CustomQuestionValidator.validate(options.questions);
-      if (!validation.valid) {
-        throw new Error(`Invalid custom questions: ${validation.error}`);
-      }
-      const sanitized = CustomQuestionValidator.sanitize(options.questions);
-      this.customGenerator = new CustomQuestionGenerator(sanitized);
-    } else {
-      this.standardOptions = options;
-    }
-  }
-
-  // check if we got custom captcha options
-  private isCustomOptions(options: unknown): options is K9GuardCustomOptions {
-    if (typeof options !== 'object' || options === null) {
-      return false;
-    }
-    const opt = options as Record<string, unknown>;
-    return opt.type === 'custom' && Array.isArray(opt.questions);
-  }
-
-  private getDifficulty(): 'easy' | 'medium' | 'hard' {
-    if (!this.standardOptions) {
-      return 'easy';
-    }
-    return this.standardOptions.difficulty;
-  }
-
-  // Atomically fetches and removes the stored challenge by nonce.
-  // Single-use semantics: the challenge is invalidated on the first attempt (success or failure).
-  // Callers must re-generate a new challenge after any validation attempt.
-  consume(nonce: string): StoredChallenge | undefined {
-    const record = this.store.get(nonce);
-    if (record !== undefined) {
-      this.store.delete(nonce);
-    }
-    return record;
-  }
-
-  // Removes all entries whose expiry has passed to free memory proactively.
-  // Called on every generate() to prevent the store from filling with stale records.
-  private pruneExpired(): void {
-    const now = Date.now();
-    for (const [key, record] of this.store) {
-      if (now > record.expiry) {
-        this.store.delete(key);
-      }
-    }
-  }
-
-  // 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 {
-    // prune stale entries first so expired records do not displace valid active ones
-    this.pruneExpired();
-
-    let nonce: string;
-    do {
-      nonce = Random.generateNonce();
-    } while (this.store.has(nonce));
-
-    // hard cap: if still full after pruning, evict the oldest entry
-    if (this.store.size >= NONCE_STORE_MAX) {
-      const oldest = this.store.keys().next().value;
-      if (oldest !== undefined) {
-        this.store.delete(oldest);
-      }
-    }
-
-    const expiry = Date.now() + 5 * 60 * 1000;
-    const salt = Random.generateSalt();
-    // canonical string for numeric answers: integers as-is, floats at fixed 2 decimal places
-    const answerStr = typeof base.answer === 'number'
-      ? (Number.isInteger(base.answer) ? base.answer.toString() : base.answer.toFixed(2))
-      : base.answer.toString();
-    const hashedAnswer = createHash('sha256').update(answerStr + salt).digest('hex');
-
-    const stored: StoredChallenge = { ...base, nonce, expiry, hashedAnswer, salt };
-    this.store.set(nonce, stored);
-
-    // strip sensitive fields before returning to caller; also sanitize nested steps
-    const { answer: _answer, hashedAnswer: _ha, salt: _salt, steps: rawSteps, ...rest } = stored;
-    const publicChallenge: CaptchaChallenge = { ...rest };
-
-    if (rawSteps && rawSteps.length > 0) {
-      // steps are StoredChallenge objects; only public fields must reach the client
-      publicChallenge.steps = rawSteps.map(({ answer: _a, hashedAnswer: _h, salt: _s, steps: _nested, ...pub }) => pub as CaptchaChallenge);
-    }
-
-    return publicChallenge;
-  }
-
-  // evaluate arithmetic expression for the math captcha type
-  private calculateMath(a: number, op: string, b: number): number {
-    if (op === '+') {
-      return a + b;
-    }
-    if (op === '-') {
-      return a - b;
-    }
-    if (op === '*') {
-      return a * b;
-    }
-    if (op === '/') {
-      if (b === 0) {
-        return Number.NaN;
-      }
-      const raw = a / b;
-      // use parseFloat(toFixed(2)) so the stored value is the same canonical string the validator will see
-      return parseFloat(raw.toFixed(2));
-    }
-    return 0;
-  }
-
-  // dispatch to the correct generator based on configured captcha type
-  generate(): CaptchaChallenge {
-    if (this.customOptions) {
-      return this.generateCustom();
-    }
-
-    if (!this.standardOptions) {
-      throw new Error('Generator not properly initialized');
-    }
-
-    const captchaType = this.standardOptions.type;
-
-    if (captchaType === 'math') {
-      return this.generateMath();
-    }
-    if (captchaType === 'text') {
-      return this.generateText();
-    }
-    if (captchaType === 'sequence') {
-      return this.generateSequence();
-    }
-    if (captchaType === 'scramble') {
-      return this.generateScramble();
-    }
-    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();
-  }
-
-  private generateCustom(): CustomCaptcha {
-    if (!this.customGenerator) {
-      throw new Error('Custom generator not initialized');
-    }
-
-    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 {
-    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(difficulty) + 1;
-    }
-
-    const answer = this.calculateMath(num1, operator, num2);
-
-    // 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: `${num1} ${operator} ${num2}`, answer }) as MathCaptcha;
-  }
-
-  private generateText(): TextCaptcha {
-    const text = Random.generateRandomString(this.getDifficulty());
-    return this.createChallenge({ type: 'text', question: text, answer: text }) as TextCaptcha;
-  }
-
-  private generateSequence(): SequenceCaptcha {
-    const seq = SequenceGenerator.generate(this.getDifficulty());
-    return this.createChallenge({ type: 'sequence', question: seq.question, answer: seq.answer }) as SequenceCaptcha;
-  }
-
-  private generateScramble(): ScrambleCaptcha {
-    const scr = ScrambleGenerator.generate(this.getDifficulty());
-    return this.createChallenge({ type: 'scramble', question: scr.question, answer: scr.answer }) as ScrambleCaptcha;
-  }
-
-  private generateReverse(): ReverseCaptcha {
-    const rev = ReverseGenerator.generate(this.getDifficulty());
-    return this.createChallenge({ type: 'reverse', question: rev.question, answer: rev.answer }) as ReverseCaptcha;
-  }
-
-  // randomly selects one of the available non-compound types
-  private generateMixed(): MixedCaptcha {
-    const types = ['math', 'text', 'sequence', 'scramble', 'reverse'] as const;
-    const buffer = randomBytes(1) as any;
-    const randomType = types[buffer[0]! % types.length]!;
-
-    // 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({ type: 'mixed', question, answer }) as MixedCaptcha;
-  }
-
-  // two-step captcha: math + scramble, both must be solved correctly.
-  // Child challenges are built via the same salt/hash pipeline but are NOT inserted into the
-  // nonce store independently, so they cannot be validated as standalone challenges.
-  private generateMulti(): CaptchaChallenge {
-    const mathRaw = this.buildMathRecord();
-    const scrambleRaw = this.buildScrambleRecord();
-
-    return this.createChallenge({
-      type: 'multi',
-      question: 'Complete two steps',
-      answer: '',
-      steps: [mathRaw, scrambleRaw]
-    });
-  }
-
-  // Builds a StoredChallenge for a math question WITHOUT registering it in the nonce store.
-  private buildMathRecord(): StoredChallenge {
-    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;
-    }
-
-    let answer = this.calculateMath(num1, operator, num2);
-
-    if (isNaN(answer) || !isFinite(answer)) {
-      num1 = Random.getRandomNumber(difficulty);
-      num2 = Random.getRandomNumber(difficulty) + 1;
-      answer = num1 + num2;
-    }
-
-    return this.buildStoredRecord({ type: 'math', question: `${num1} ${operator} ${num2}`, answer });
-  }
-
-  // Builds a StoredChallenge for a scramble question WITHOUT registering it in the nonce store.
-  private buildScrambleRecord(): StoredChallenge {
-    const scr = ScrambleGenerator.generate(this.getDifficulty());
-    return this.buildStoredRecord({ type: 'scramble', question: scr.question, answer: scr.answer });
-  }
-
-  // Hashes and packages a challenge record but does NOT add it to the nonce store.
-  // Used for child steps that must not be independently redeemable.
-  private buildStoredRecord(base: Omit<StoredChallenge, 'nonce' | 'expiry' | 'hashedAnswer' | 'salt'>): StoredChallenge {
-    const nonce = Random.generateNonce();
-    const expiry = Date.now() + 5 * 60 * 1000;
-    const salt = Random.generateSalt();
-    const answerStr = typeof base.answer === 'number'
-      ? (Number.isInteger(base.answer) ? base.answer.toString() : base.answer.toFixed(2))
-      : base.answer.toString();
-    const hashedAnswer = createHash('sha256').update(answerStr + salt).digest('hex');
-    return { ...base, nonce, expiry, hashedAnswer, salt };
-  }
-
-  // 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,198 +0,0 @@
-import { createHash, timingSafeEqual } from '../utils/crypto';
-import type { StoredChallenge } from '../types';
-
-// decodes a hex string to raw bytes without relying on Buffer
-function hexToBytes(hex: string): Uint8Array {
-  const bytes = new Uint8Array(hex.length / 2);
-  for (let i = 0; i < bytes.length; i++) {
-    bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
-  }
-  return bytes;
-}
-
-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: StoredChallenge, userInput: string): boolean {
-    if (!this.isValidInput(userInput)) {
-      return false;
-    }
-
-    if (challenge.type === 'multi') {
-      return this.validateMulti(challenge, userInput);
-    }
-
-    if (challenge.type === 'custom') {
-      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);
-    }
-
-    return this.validateText(challenge, userInput);
-  }
-
-  private static isValidInput(input: unknown): boolean {
-    if (typeof input !== 'string') {
-      return false;
-    }
-    if (input.length === 0 || input.length > this.MAX_INPUT_LENGTH) {
-      return false;
-    }
-    return true;
-  }
-
-  // validates multi step captchas by checking each step individually
-  private static validateMulti(challenge: StoredChallenge, userInput: string): boolean {
-    if (!challenge.steps || challenge.steps.length === 0) {
-      return false;
-    }
-
-    let parsed: unknown;
-    try {
-      // NOTE: user input should be a JSON array of answers
-      parsed = JSON.parse(userInput);
-    } catch {
-      return false;
-    }
-
-    if (!Array.isArray(parsed) || parsed.length !== challenge.steps.length) {
-      return false;
-    }
-
-    // check each step answer matches its challenge
-    for (let i = 0; i < challenge.steps.length; i++) {
-      const step = challenge.steps[i];
-      const input = parsed[i];
-      
-      if (!step || typeof input !== 'string') {
-        return false;
-      }
-      
-      if (!this.validate(step, input)) {
-        return false;
-      }
-    }
-
-    return true;
-  }
-
-  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: StoredChallenge, userInput: string): boolean {
-    // strict: only an optional minus, digits, and an optional single decimal point
-    // rejects scientific notation, leading zeros, and partial-parse tricks like "10abc"
-    if (!/^-?(\d+(\.\d+)?|\.\d+)$/.test(userInput.trim())) {
-      return false;
-    }
-
-    const inputNum = parseFloat(userInput.trim());
-
-    if (isNaN(inputNum) || !isFinite(inputNum)) {
-      return false;
-    }
-
-    // normalize to the same canonical form used at generation time (2 decimal places for floats)
-    const canonical = Number.isInteger(inputNum) ? inputNum.toString() : inputNum.toFixed(2);
-
-    return this.verifyAnswer(challenge, canonical);
-  }
-
-  private static validateText(challenge: StoredChallenge, userInput: string): boolean {
-    const sanitized = userInput.trim();
-
-    if (!this.VALID_CHAR_REGEX.test(sanitized)) {
-      return false;
-    }
-
-    return this.verifyAnswer(challenge, sanitized);
-  }
-
-  // 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');
-
-    // both hex strings must be equal length before byte comparison;
-    // SHA-256 hex is always 64 chars so this only fails on corruption
-    if (userHash.length !== challenge.hashedAnswer.length) {
-      return false;
-    }
-
-    return timingSafeEqual(
-      hexToBytes(userHash),
-      hexToBytes(challenge.hashedAnswer)
-    );
-  }
-
-  private static validateCustom(challenge: StoredChallenge, userInput: string): boolean {
-    const sanitized = userInput.trim();
-
-    if (!this.VALID_CHAR_REGEX.test(sanitized)) {
-      return false;
-    }
-
-    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,84 +0,0 @@
-export interface K9GuardOptions {
-  type: 'math' | 'text' | 'sequence' | 'scramble' | 'reverse' | 'mixed' | 'multi' | 'image' | 'emoji';
-  difficulty: 'easy' | 'medium' | 'hard';
-}
-
-export interface CustomQuestion {
-  question: string;
-  answer: string;
-  difficulty: 'easy' | 'medium' | 'hard';
-}
-
-export interface K9GuardCustomOptions {
-  type: 'custom';
-  questions: CustomQuestion[];
-}
-
-// 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';
-}
-
-export interface TextCaptcha extends CaptchaChallenge {
-  type: 'text';
-}
-
-export interface SequenceCaptcha extends CaptchaChallenge {
-  type: 'sequence';
-}
-
-export interface ScrambleCaptcha extends CaptchaChallenge {
-  type: 'scramble';
-}
-
-export interface ReverseCaptcha extends CaptchaChallenge {
-  type: 'reverse';
-}
-
-export interface MixedCaptcha extends CaptchaChallenge {
-  type: 'mixed';
-}
-
-export interface CustomCaptcha extends CaptchaChallenge {
-  type: 'custom';
-}
-
-export interface EmojiCaptcha extends CaptchaChallenge {
-  type: 'emoji';
-  emojis: string[];
-  category: string;
-}