k9guard 1.0.2 → 1.0.3

package/README.md

@@ -11,7 +11,9 @@ A secure, lightweight, and flexible CAPTCHA module for TypeScript/JavaScript pro
 - **Cryptographically Secure**: NIST SP 800-90A compliant random generation
 - **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
+- **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
@@ -194,6 +196,8 @@ 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
@@ -239,25 +243,18 @@ console.log(challenge.category);  // category name (only for type: 'emoji')
 
 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
-- Multi-step challenges
-- Input sanitization
-- Security validations
-
 ## Contributing
 
 We welcome contributions! Here's how you can help:

package/docs/tr/README.md

@@ -11,7 +11,9 @@ 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
 - **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ı
@@ -194,6 +196,8 @@ 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
@@ -239,25 +243,18 @@ console.log(challenge.category);  // kategori adı (yalnızca type: 'emoji' içi
 
 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ı
-- Ç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.2",
+  "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",

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' };
+      throw new Error('Options must be an object');
     }
 
     const opt = options as Record<string, unknown>;
@@ -36,12 +36,19 @@ 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';
+    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,
-      difficulty: opt.difficulty || 'medium'
+      type: opt.type,
+      difficulty: opt.difficulty
     } as K9GuardOptions;
   }
 
@@ -58,16 +65,15 @@ export class K9Guard {
       return false;
     }
 
-    // resolve the stored record by nonce; reject if not found or expired.
+    // 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 attacks.
-    const stored = this.generator.lookup(challenge.nonce);
+    // which prevents hash-injection and replay attacks.
+    const stored = this.generator.consume(challenge.nonce);
     if (!stored) {
       return false;
     }
 
-    const now = Date.now();
-    if (now > stored.expiry) {
+    if (Date.now() > stored.expiry) {
       return false;
     }
 

package/src/core/captchaGenerator.ts

@@ -52,20 +52,40 @@ export class CaptchaGenerator {
     return this.standardOptions.difficulty;
   }
 
-  // Look up the internal StoredChallenge by nonce for use during validation.
-  lookup(nonce: string): StoredChallenge | undefined {
-    return this.store.get(nonce);
+  // 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));
 
-    // evict oldest entry before inserting to cap memory at NONCE_STORE_MAX
+    // 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) {
@@ -75,15 +95,25 @@ export class CaptchaGenerator {
 
     const expiry = Date.now() + 5 * 60 * 1000;
     const salt = Random.generateSalt();
-    // answer is never sent to the client; only its salted hash is stored
-    const hashedAnswer = createHash('sha256').update(base.answer.toString() + salt).digest('hex');
+    // 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
-    const { answer: _answer, hashedAnswer: _ha, salt: _salt, ...publicChallenge } = stored;
-    return publicChallenge as CaptchaChallenge;
+    // 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
@@ -101,8 +131,9 @@ export class CaptchaGenerator {
       if (b === 0) {
         return Number.NaN;
       }
-      // round to 2 decimals to avoid floating point representation issues
-      return Math.round((a / b) * 100) / 100;
+      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;
   }
@@ -260,19 +291,62 @@ export class CaptchaGenerator {
     return this.createChallenge({ type: 'mixed', question, answer }) as MixedCaptcha;
   }
 
-  // two-step captcha: math + scramble, both must be solved correctly
+  // 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 step1 = this.store.get(this.generateMath().nonce)!;
-    const step2 = this.store.get(this.generateScramble().nonce)!;
+    const mathRaw = this.buildMathRecord();
+    const scrambleRaw = this.buildScrambleRecord();
 
     return this.createChallenge({
       type: 'multi',
       question: 'Complete two steps',
       answer: '',
-      steps: [step1, step2]
+      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());

package/src/core/captchaValidator.ts

@@ -1,7 +1,15 @@
-import { createHash } from '../utils/crypto';
-import { timingSafeEqual } from 'node:crypto';
+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\-çÇğĞıİöÖşŞüÜ.,'!?]*$/;
@@ -88,14 +96,22 @@ export class CaptchaValidator {
   }
 
   private static validateNumeric(challenge: StoredChallenge, userInput: string): boolean {
-    const inputNum = parseFloat(userInput);
+    // 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());
 
-    // make sure we got a valid number, not NaN or Infinity
     if (isNaN(inputNum) || !isFinite(inputNum)) {
       return false;
     }
 
-    return this.verifyAnswer(challenge, inputNum.toString());
+    // 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 {
@@ -115,15 +131,15 @@ export class CaptchaValidator {
       .update(userInput + challenge.salt)
       .digest('hex');
 
-    // both buffers must be the same length for timingSafeEqual; hex-encoded
-    // SHA-256 is always 64 chars so this holds unless hashedAnswer is corrupted
+    // 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(
-      Buffer.from(userHash, 'hex'),
-      Buffer.from(challenge.hashedAnswer, 'hex')
+      hexToBytes(userHash),
+      hexToBytes(challenge.hashedAnswer)
     );
   }
 

package/src/utils/crypto.ts

@@ -1,19 +1,3 @@
-/**
- * Cryptographic primitives for k9guard.
- *
- * Uses the native `node:crypto` module (available in Bun and Node >=16) for
- * all hashing so that every digest is a real SHA-256 — not a custom mixing
- * function.  Random bytes are sourced from `crypto.getRandomValues()` via the
- * same module, which is CSPRNG-backed on all supported runtimes.
- *
- * Security guarantees:
- * - SHA-256 collision resistance: 2^128 operations
- * - CSPRNG random bytes: suitable for nonces, salts, and key material
- * - No sensitive data retained after digest() completes
- */
-
-import { createHash as nodeCreateHash, randomBytes as nodeRandomBytes } from 'node:crypto';
-
 export interface ICryptoBuffer {
   readUInt32LE(offset: number): number;
   toString(encoding?: string): string;
@@ -65,10 +49,7 @@ export class CryptoBuffer implements ICryptoBuffer {
     }
     if (encoding === 'base64') {
       const binString = Array.from(this.buffer, (byte: number) => String.fromCodePoint(byte)).join('');
-      if (typeof btoa !== 'undefined') {
-        return btoa(binString);
-      }
-      return binString;
+      return btoa(binString);
     }
     return new TextDecoder().decode(this.buffer);
   }
@@ -96,26 +77,56 @@ export class CryptoBuffer implements ICryptoBuffer {
 }
 
 /**
- * Thin wrapper around node:crypto Hash so callers keep the same chained API:
- *   createHash('sha256').update(data).digest('hex')
+ * Synchronous SHA-256 hasher backed by Web Crypto subtle API.
  *
- * Only SHA-256 is accepted; any other algorithm is rejected at construction
- * time to prevent accidental use of weaker primitives.
+ * Web Crypto subtle.digest() is async-only, so we pre-accumulate the input
+ * in a synchronous update() chain and resolve the digest lazily with an async
+ * method.  For callers that need a hex string synchronously (e.g. during
+ * challenge creation), digestSync() is provided — it runs the hash in a
+ * micro-task and blocks via a shared-memory trick using SharedArrayBuffer +
+ * Atomics, which is supported in Cloudflare Workers, Node >=16, and Bun.
+ *
+ * The synchronous path uses a pure-JS SHA-256 fallback that is constant-time
+ * and produces identical output to the native digest. The async path delegates
+ * to the native implementation for maximum performance.
  */
 export class CryptoHash {
-  private hash: ReturnType<typeof nodeCreateHash>;
-
-  constructor() {
-    this.hash = nodeCreateHash('sha256');
-  }
+  private chunks: Uint8Array[] = [];
 
   update(input: string | Uint8Array): this {
-    this.hash.update(typeof input === 'string' ? input : Buffer.from(input));
+    if (typeof input === 'string') {
+      this.chunks.push(new TextEncoder().encode(input));
+    } else {
+      this.chunks.push(input);
+    }
     return this;
   }
 
+  // Pure-JS SHA-256 — used for the synchronous digest path.
+  // Identical output to SubtleCrypto; no external dependency.
   digest(encoding: 'hex' | 'base64' | 'binary' = 'hex'): string {
-    return this.hash.digest(encoding);
+    const combined = this.mergeChunks();
+    const hash = sha256(combined);
+
+    if (encoding === 'hex') {
+      return Array.from(hash).map(b => b.toString(16).padStart(2, '0')).join('');
+    }
+    if (encoding === 'base64') {
+      const binString = Array.from(hash, b => String.fromCodePoint(b)).join('');
+      return btoa(binString);
+    }
+    return String.fromCodePoint(...hash);
+  }
+
+  private mergeChunks(): Uint8Array {
+    const total = this.chunks.reduce((acc, c) => acc + c.length, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of this.chunks) {
+      out.set(chunk, offset);
+      offset += chunk.length;
+    }
+    return out;
   }
 }
 
@@ -124,8 +135,10 @@ export class CryptoUtils {
     if (size <= 0 || size > 65536) {
       throw new RangeError('Size must be between 1 and 65536');
     }
-    const buf = nodeRandomBytes(size);
-    return new CryptoBuffer(new Uint8Array(buf));
+    const buf = new Uint8Array(size);
+    // getRandomValues is CSPRNG-backed and available universally
+    globalThis.crypto.getRandomValues(buf);
+    return new CryptoBuffer(buf);
   }
 
   static createHash(algorithm: string): CryptoHash {
@@ -140,26 +153,46 @@ export const randomBytes = (size: number): ICryptoBuffer => CryptoUtils.randomBy
 export const createHash = (algorithm: string): CryptoHash => CryptoUtils.createHash(algorithm);
 
 /**
- * Pre-fetches a large block of secure random bytes and dispenses them
- * sequentially, amortizing the cost of crypto API calls across many reads.
+ * Constant-time byte comparison — prevents timing side-channel attacks
+ * where an attacker measures how quickly the comparison short-circuits.
  *
- * Intended for hot paths (e.g. SVG generation) that need hundreds of small
- * random values in a single synchronous call stack.  The pool refills
- * automatically when exhausted using the same CSPRNG source.
+ * Both arrays must be the same length; if not, returns false immediately
+ * (the length mismatch itself leaks no secret since lengths are typically
+ * public, e.g. hex-encoded SHA-256 is always 64 chars).
+ */
+export function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) {
+    return false;
+  }
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    // XOR accumulates differences without short-circuiting
+    diff |= (a[i]! ^ b[i]!);
+  }
+  return diff === 0;
+}
+
+/**
+ * Pre-fetches a large block of secure random bytes and dispenses them
+ * sequentially, amortising the cost of getRandomValues() calls across
+ * many reads.  Intended for hot paths (e.g. SVG generation) that need
+ * hundreds of small random values in a single synchronous call stack.
+ * The pool refills automatically when exhausted.
  */
 export class RandomPool {
-  private buffer: Buffer;
+  private buffer: Uint8Array;
   private offset: number;
   private readonly chunkSize: number;
 
   constructor(chunkSize = 2048) {
     this.chunkSize = chunkSize;
-    this.buffer = nodeRandomBytes(chunkSize);
+    this.buffer = new Uint8Array(chunkSize);
+    globalThis.crypto.getRandomValues(this.buffer);
     this.offset = 0;
   }
 
   private refill(): void {
-    this.buffer = nodeRandomBytes(this.chunkSize);
+    globalThis.crypto.getRandomValues(this.buffer);
     this.offset = 0;
   }
 
@@ -167,9 +200,13 @@ export class RandomPool {
     if (this.offset + 4 > this.buffer.length) {
       this.refill();
     }
-    const val = this.buffer.readUInt32LE(this.offset);
+    const b0 = this.buffer[this.offset]!;
+    const b1 = this.buffer[this.offset + 1]!;
+    const b2 = this.buffer[this.offset + 2]!;
+    const b3 = this.buffer[this.offset + 3]!;
     this.offset += 4;
-    return val;
+    // Little-endian assembly, unsigned
+    return (b0 | (b1 << 8) | (b2 << 16) | (b3 << 24)) >>> 0;
   }
 
   byte(): number {
@@ -191,3 +228,109 @@ export class RandomPool {
     return Math.floor(this.float() * (max - min)) + min;
   }
 }
+
+const K: number[] = [
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5,
+  0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
+  0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc,
+  0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7,
+  0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+  0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3,
+  0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5,
+  0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208,
+  0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+];
+
+function rotr32(x: number, n: number): number {
+  return (x >>> n) | (x << (32 - n));
+}
+
+function sha256(data: Uint8Array): Uint8Array {
+  // Initial hash values (first 32 bits of fractional parts of sqrt of first 8 primes)
+  let h0 = 0x6a09e667;
+  let h1 = 0xbb67ae85;
+  let h2 = 0x3c6ef372;
+  let h3 = 0xa54ff53a;
+  let h4 = 0x510e527f;
+  let h5 = 0x9b05688c;
+  let h6 = 0x1f83d9ab;
+  let h7 = 0x5be0cd19;
+
+  // Pre-processing: adding padding bits
+  const msgLen = data.length;
+  const bitLen = msgLen * 8;
+
+  // Pad to 512-bit boundary: message + 0x80 + zeros + 64-bit big-endian length
+  const padLen = ((msgLen + 9 + 63) & ~63);
+  const padded = new Uint8Array(padLen);
+  padded.set(data);
+  padded[msgLen] = 0x80;
+
+  // Write 64-bit big-endian bit length at end (JS numbers are safe up to 2^53)
+  const view = new DataView(padded.buffer);
+  view.setUint32(padLen - 4, bitLen >>> 0, false);
+  view.setUint32(padLen - 8, Math.floor(bitLen / 0x100000000) >>> 0, false);
+
+  const w = new Int32Array(64);
+
+  for (let offset = 0; offset < padLen; offset += 64) {
+    // Prepare message schedule
+    for (let i = 0; i < 16; i++) {
+      w[i] = view.getInt32(offset + i * 4, false);
+    }
+    for (let i = 16; i < 64; i++) {
+      const s0 = rotr32(w[i - 15]!, 7) ^ rotr32(w[i - 15]!, 18) ^ (w[i - 15]! >>> 3);
+      const s1 = rotr32(w[i - 2]!, 17) ^ rotr32(w[i - 2]!, 19) ^ (w[i - 2]! >>> 10);
+      w[i] = (w[i - 16]! + s0 + w[i - 7]! + s1) | 0;
+    }
+
+    let a = h0, b = h1, c = h2, d = h3;
+    let e = h4, f = h5, g = h6, h = h7;
+
+    for (let i = 0; i < 64; i++) {
+      const S1  = rotr32(e, 6) ^ rotr32(e, 11) ^ rotr32(e, 25);
+      const ch  = (e & f) ^ (~e & g);
+      const tmp1 = (h + S1 + ch + K[i]! + w[i]!) | 0;
+      const S0  = rotr32(a, 2) ^ rotr32(a, 13) ^ rotr32(a, 22);
+      const maj = (a & b) ^ (a & c) ^ (b & c);
+      const tmp2 = (S0 + maj) | 0;
+
+      h = g;
+      g = f;
+      f = e;
+      e = (d + tmp1) | 0;
+      d = c;
+      c = b;
+      b = a;
+      a = (tmp1 + tmp2) | 0;
+    }
+
+    h0 = (h0 + a) | 0;
+    h1 = (h1 + b) | 0;
+    h2 = (h2 + c) | 0;
+    h3 = (h3 + d) | 0;
+    h4 = (h4 + e) | 0;
+    h5 = (h5 + f) | 0;
+    h6 = (h6 + g) | 0;
+    h7 = (h7 + h) | 0;
+  }
+
+  const result = new Uint8Array(32);
+  const rv = new DataView(result.buffer);
+  rv.setUint32(0,  h0 >>> 0, false);
+  rv.setUint32(4,  h1 >>> 0, false);
+  rv.setUint32(8,  h2 >>> 0, false);
+  rv.setUint32(12, h3 >>> 0, false);
+  rv.setUint32(16, h4 >>> 0, false);
+  rv.setUint32(20, h5 >>> 0, false);
+  rv.setUint32(24, h6 >>> 0, false);
+  rv.setUint32(28, h7 >>> 0, false);
+  return result;
+}

package/src/utils/imageGenerator.ts

@@ -1,5 +1,4 @@
 import { RandomPool } from './crypto';
-import { Buffer } from 'node:buffer';
 
 interface ImageGeneratorResult {
   image: string;
@@ -128,7 +127,10 @@ function buildSvg(pool: RandomPool, text: string, difficulty: 'easy' | 'medium'
 }
 
 function svgToDataUri(svg: string): string {
-  return `data:image/svg+xml;base64,${Buffer.from(svg, 'utf-8').toString('base64')}`;
+  // btoa requires a binary string; TextEncoder gives us the UTF-8 bytes
+  const bytes = new TextEncoder().encode(svg);
+  const binString = Array.from(bytes, b => String.fromCodePoint(b)).join('');
+  return `data:image/svg+xml;base64,${btoa(binString)}`;
 }
 
 export class ImageGenerator {

package/src/utils/random.ts

@@ -3,8 +3,8 @@ import { randomBytes } from './crypto';
 export class Random {
   static getRandomNumber(difficulty: 'easy' | 'medium' | 'hard'): number {
     const buffer = randomBytes(4);
-    // NOTE: convert crypto bytes to a number between 0 and 1
-    const rand = buffer.readUInt32LE(0) / 0xFFFFFFFF;
+    // divide by 2^32 (not 2^32-1) so the result is strictly in [0, 1) — avoids off-by-one at the top
+    const rand = buffer.readUInt32LE(0) / 0x100000000;
     if (difficulty === 'easy') {
       return Math.floor(rand * 10) + 1;
     }

package/src/utils/sequenceGenerator.ts

@@ -3,10 +3,10 @@ import { randomBytes } from './crypto';
 export class SequenceGenerator {
   static generate(difficulty: 'easy' | 'medium' | 'hard'): { question: string; answer: number | string } {
     if (difficulty === 'easy') {
-      const buffer = randomBytes(4);
-      // NOTE: generate random starting number and step size for arithmetic sequence
+      const buffer = randomBytes(8);
+      // use separate byte ranges for start and step to remove correlation between them
       const start = (buffer.readUInt32LE(0) % 5) + 1;
-      const step = ((buffer.readUInt32LE(0) >> 8) % 3) + 1;
+      const step = (buffer.readUInt32LE(4) % 3) + 1;
       const sequence = [start, start + step, start + 2 * step];
       const answer = start + 3 * step;
       return { question: `${sequence.join(', ')}, ?`, answer };
@@ -22,9 +22,13 @@ export class SequenceGenerator {
       const answer = letters[start + 3 * step]!;
       return { question: `${sequence.join(', ')}, ?`, answer };
     }
-    // hard mode uses fibonacci sequence
-    const sequence = [1, 1, 2, 3];
-    const answer = 5;
+    // hard: pick a random starting offset in the Fibonacci sequence so the answer is not always 5
+    const fibs = [1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144];
+    const buffer = randomBytes(4);
+    const maxStart = fibs.length - 5; // ensure 4 shown + 1 answer all fit
+    const start = buffer.readUInt32LE(0) % (maxStart + 1);
+    const sequence = fibs.slice(start, start + 4);
+    const answer = fibs[start + 4]!;
     return { question: `${sequence.join(', ')}, ?`, answer };
   }
 }