k9guard 1.0.1 → 1.0.2

package/src/utils/crypto.ts

@@ -1,31 +1,19 @@
 /**
- * This module provides Node.js crypto API compatibility for web browsers using the Web Crypto API.
- * It implements secure random number generation and hashing functions that work in both browser
- * and server environments, eliminating the need for Node.js crypto module in web applications.
+ * Cryptographic primitives for k9guard.
  *
- * Key features:
- * - Web Crypto API integration with fallback detection
- * - Secure random bytes generation
- * - SHA-256 hashing with incremental updates
- * - Buffer-like interface for compatibility
- * - TypeScript support with proper type safety
+ * 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 Notes:
- * - Uses cryptographically secure random number generation
- * - Implements deterministic hashing for consistent results
- * - No sensitive data is stored or logged
- * - All operations are performed in-memory only
+ * 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
  */
 
-declare const window: any;
-declare const self: any;
+import { createHash as nodeCreateHash, randomBytes as nodeRandomBytes } from 'node:crypto';
 
-/**
- * Interface for crypto buffer operations
- *
- * Provides Node.js Buffer-like functionality for cryptographic operations.
- * Supports array-like access, encoding conversions, and binary data manipulation.
- */
 export interface ICryptoBuffer {
   readUInt32LE(offset: number): number;
   toString(encoding?: string): string;
@@ -34,97 +22,13 @@ export interface ICryptoBuffer {
   [Symbol.iterator](): Iterator<number>;
 }
 
-/**
- * Core cryptographic utilities class
- *
- * Provides access to Web Crypto API with automatic environment detection.
- * Handles browser compatibility and secure random number generation.
- */
-export class CryptoUtils {
-  /**
-   * Detect and return available Web Crypto API instance
-   *
-   * Checks multiple global objects to find crypto API in different environments:
-   * - globalThis (modern browsers/Node.js)
-   * - window (browser main thread)
-   * - self (Web Workers/Service Workers)
-   *
-   * @throws Error if Web Crypto API is not available
-   */
-  private static getWebCrypto(): Crypto {
-    if (typeof globalThis !== 'undefined' && globalThis.crypto) {
-      return globalThis.crypto;
-    }
-    if (typeof window !== 'undefined' && window.crypto) {
-      return window.crypto;
-    }
-    if (typeof self !== 'undefined' && self.crypto) {
-      return self.crypto;
-    }
-    throw new Error('Web Crypto API not available');
-  }
-
-  /**
-   * Generate cryptographically secure random bytes
-   *
-   * Uses Web Crypto API's getRandomValues() for secure random number generation.
-   * This is suitable for cryptographic purposes and provides better entropy than Math.random().
-   *
-   * @param size - Number of random bytes to generate (1-65536)
-   * @returns CryptoBuffer containing random bytes
-   * @throws RangeError if size is invalid
-   */
-  static randomBytes(size: number): ICryptoBuffer {
-    if (size <= 0 || size > 65536) {
-      throw new RangeError('Size must be between 1 and 65536');
-    }
-
-    const crypto = this.getWebCrypto();
-    const buffer = new Uint8Array(size);
-    crypto.getRandomValues(buffer);
-
-    return new CryptoBuffer(buffer);
-  }
-
-  /**
-   * Create a new hash instance
-   *
-   * Currently supports only SHA-256 for security and compatibility reasons.
-   * SHA-256 provides strong cryptographic hashing suitable for most applications.
-   *
-   * @param algorithm - Hash algorithm (currently only 'sha256' supported)
-   * @returns New CryptoHash instance
-   * @throws Error if unsupported algorithm is requested
-   */
-  static createHash(algorithm: string): CryptoHash {
-    if (algorithm.toLowerCase() !== 'sha256') {
-      throw new Error('Only SHA-256 is supported');
-    }
-
-    return new CryptoHash();
-  }
-}
-
-/**
- * Buffer implementation for cryptographic data
- *
- * Provides Node.js Buffer-compatible interface using Uint8Array internally.
- * Uses Proxy pattern to enable array-like access (buffer[0], buffer[1], etc.)
- * while maintaining type safety and compatibility.
- */
 export class CryptoBuffer implements ICryptoBuffer {
   private buffer: Uint8Array;
   [index: number]: number | undefined;
 
-  /**
-   * Create a new crypto buffer
-   *
-   * @param buffer - Underlying Uint8Array data
-   */
   constructor(buffer: Uint8Array) {
     this.buffer = buffer;
-    // NOTE: Using Proxy to enable array-like access while maintaining encapsulation
-    // This allows buffer[0], buffer[1] syntax while keeping internal buffer private
+    // Proxy enables numeric index access (buffer[0]) while keeping internal state private
     const proxy = new Proxy(this, {
       get(target, prop) {
         if (typeof prop === 'string' && !isNaN(Number(prop))) {
@@ -136,17 +40,6 @@ export class CryptoBuffer implements ICryptoBuffer {
     return proxy as any;
   }
 
-  /**
-   * Read 32-bit unsigned integer in little-endian format
-   *
-   * Reads 4 bytes starting at offset and interprets them as a little-endian
-   * unsigned 32-bit integer. Used for cryptographic operations requiring
-   * specific byte ordering.
-   *
-   * @param offset - Starting position in buffer
-   * @returns 32-bit unsigned integer value
-   * @throws RangeError if offset is out of bounds
-   */
   readUInt32LE(offset: number): number {
     if (offset < 0 || offset + 4 > this.buffer.length) {
       throw new RangeError('Offset out of bounds');
@@ -160,22 +53,10 @@ export class CryptoBuffer implements ICryptoBuffer {
       throw new RangeError('Buffer read error');
     }
 
-    // NOTE: Little-endian byte order: least significant byte first
-    // b0 is LSB, b3 is MSB. Using unsigned right shift to ensure positive result
+    // Little-endian: b0 is LSB, unsigned right-shift keeps result in [0, 2^32)
     return (b0 | (b1 << 8) | (b2 << 16) | (b3 << 24)) >>> 0;
   }
 
-  /**
-   * Convert buffer to string with specified encoding
-   *
-   * Supports multiple encodings for compatibility with different use cases:
-   * - 'hex': Hexadecimal representation (2 chars per byte)
-   * - 'base64': Base64 encoding using browser's btoa() or fallback
-   * - default: UTF-8 text decoding
-   *
-   * @param encoding - Output encoding ('hex', 'base64', or undefined for UTF-8)
-   * @returns Encoded string representation
-   */
   toString(encoding?: string): string {
     if (encoding === 'hex') {
       return Array.from(this.buffer)
@@ -184,7 +65,6 @@ export class CryptoBuffer implements ICryptoBuffer {
     }
     if (encoding === 'base64') {
       const binString = Array.from(this.buffer, (byte: number) => String.fromCodePoint(byte)).join('');
-      // NOTE: btoa() is browser-specific, fallback to raw binary string in Node.js
       if (typeof btoa !== 'undefined') {
         return btoa(binString);
       }
@@ -197,14 +77,6 @@ export class CryptoBuffer implements ICryptoBuffer {
     return this.buffer.length;
   }
 
-  /**
-   * Iterator implementation for for...of loops and spread operator
-   *
-   * Allows the buffer to be used in modern JavaScript iteration constructs.
-   * Provides sequential access to individual bytes.
-   *
-   * @returns Iterator yielding individual byte values
-   */
   [Symbol.iterator](): Iterator<number> {
     let index = 0;
     const buffer = this.buffer;
@@ -224,137 +96,98 @@ export class CryptoBuffer implements ICryptoBuffer {
 }
 
 /**
- * Incremental hash computation class
+ * Thin wrapper around node:crypto Hash so callers keep the same chained API:
+ *   createHash('sha256').update(data).digest('hex')
  *
- * Provides Node.js crypto.createHash() compatible interface.
- * Supports incremental updates for large data processing.
- * Uses custom hash algorithm optimized for browser compatibility.
+ * Only SHA-256 is accepted; any other algorithm is rejected at construction
+ * time to prevent accidental use of weaker primitives.
  */
 export class CryptoHash {
-  private dataChunks: Uint8Array[] = [];
+  private hash: ReturnType<typeof nodeCreateHash>;
 
-  /**
-   * Add data to the hash computation
-   *
-   * Can be called multiple times to hash large or streaming data.
-   * Data is accumulated internally until digest() is called.
-   *
-   * @param input - Data to hash (string or Uint8Array)
-   * @returns This instance for method chaining
-   */
-  update(input: string | Uint8Array): this {
-    const inputBytes = typeof input === 'string'
-      ? new TextEncoder().encode(input)
-      : input;
+  constructor() {
+    this.hash = nodeCreateHash('sha256');
+  }
 
-    this.dataChunks.push(inputBytes);
+  update(input: string | Uint8Array): this {
+    this.hash.update(typeof input === 'string' ? input : Buffer.from(input));
     return this;
   }
 
-  /**
-   * Combine all accumulated data chunks into a single buffer
-   *
-   * Internal method used before hash computation.
-   * Efficiently concatenates all chunks into contiguous memory.
-   *
-   * @returns Combined Uint8Array of all input data
-   */
-  private getCombinedData(): Uint8Array {
-    const totalLength = this.dataChunks.reduce((sum, chunk) => sum + chunk.length, 0);
-    const combined = new Uint8Array(totalLength);
-    let offset = 0;
+  digest(encoding: 'hex' | 'base64' | 'binary' = 'hex'): string {
+    return this.hash.digest(encoding);
+  }
+}
 
-    for (const chunk of this.dataChunks) {
-      combined.set(chunk, offset);
-      offset += chunk.length;
+export class CryptoUtils {
+  static randomBytes(size: number): ICryptoBuffer {
+    if (size <= 0 || size > 65536) {
+      throw new RangeError('Size must be between 1 and 65536');
     }
-
-    return combined;
+    const buf = nodeRandomBytes(size);
+    return new CryptoBuffer(new Uint8Array(buf));
   }
 
-  /**
-   * Finalize hash computation and return result
-   *
-   * Computes the hash of all accumulated data and returns it in the specified encoding.
-   * After calling digest(), the hash instance should not be used for further updates.
-   *
-   * @param encoding - Output encoding ('hex', 'base64', or undefined for binary)
-   * @returns Hash digest as encoded string
-   */
-  digest(encoding?: string): string {
-    const combined = this.getCombinedData();
-    const hashArray = this.computeHashSync(combined);
-
-    if (encoding === 'hex') {
-      return Array.from(hashArray)
-        .map(b => b.toString(16).padStart(2, '0'))
-        .join('');
-    }
-    if (encoding === 'base64') {
-      const binString = Array.from(hashArray, (byte: number) => String.fromCodePoint(byte)).join('');
-      if (typeof btoa !== 'undefined') {
-        return btoa(binString);
-      }
-      return binString;
+  static createHash(algorithm: string): CryptoHash {
+    if (algorithm.toLowerCase() !== 'sha256') {
+      throw new Error('Only SHA-256 is supported');
     }
-
-    return new TextDecoder().decode(hashArray);
+    return new CryptoHash();
   }
+}
 
-  /**
-   * Compute hash using custom synchronous algorithm
-   *
-   * Implements a deterministic hash function optimized for browser compatibility.
-   * Uses multiple rounds of mixing operations to ensure good distribution.
-   *
-   * Algorithm overview:
-   * 1. Initial distribution: XOR and multiply operations
-   * 2. Diffusion rounds: Neighbor-based mixing with round constants
-   *
-   * @param data - Input data to hash
-   * @returns 32-byte hash array
-   */
-  private computeHashSync(data: Uint8Array): Uint8Array {
-    const simpleHash = new Uint8Array(32);
-
-    for (let i = 0; i < data.length; i++) {
-      const byteVal = data[i];
-      if (byteVal === undefined) continue;
-
-      const idx1 = i % 32;
-      const idx2 = (i * 7) % 32; // NOTE: Prime multiplier for better distribution
+export const randomBytes = (size: number): ICryptoBuffer => CryptoUtils.randomBytes(size);
+export const createHash = (algorithm: string): CryptoHash => CryptoUtils.createHash(algorithm);
 
-      const val1 = simpleHash[idx1];
-      const val2 = simpleHash[idx2];
+/**
+ * Pre-fetches a large block of secure random bytes and dispenses them
+ * sequentially, amortizing the cost of crypto API 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 using the same CSPRNG source.
+ */
+export class RandomPool {
+  private buffer: Buffer;
+  private offset: number;
+  private readonly chunkSize: number;
+
+  constructor(chunkSize = 2048) {
+    this.chunkSize = chunkSize;
+    this.buffer = nodeRandomBytes(chunkSize);
+    this.offset = 0;
+  }
 
-      if (val1 !== undefined) {
-        simpleHash[idx1] = val1 ^ byteVal;
-      }
+  private refill(): void {
+    this.buffer = nodeRandomBytes(this.chunkSize);
+    this.offset = 0;
+  }
 
-      if (val2 !== undefined) {
-        simpleHash[idx2] = ((val2 + byteVal) * 31) & 0xFF; // NOTE: 31 is prime for avalanche effect
-      }
+  uint32(): number {
+    if (this.offset + 4 > this.buffer.length) {
+      this.refill();
     }
+    const val = this.buffer.readUInt32LE(this.offset);
+    this.offset += 4;
+    return val;
+  }
 
-    for (let round = 0; round < 16; round++) {
-      for (let i = 0; i < 32; i++) {
-        const prevIdx = (i + 31) % 32; // Previous element (wrap around)
-        const nextIdx = (i + 1) % 32;  // Next element (wrap around)
-
-        const prev = simpleHash[prevIdx];
-        const curr = simpleHash[i];
-        const next = simpleHash[nextIdx];
-
-        if (prev !== undefined && curr !== undefined && next !== undefined) {
-          // NOTE: Complex mixing function combining neighbors with round constant
-          simpleHash[i] = ((prev + curr * 2 + next) * 7 + round) & 0xFF;
-        }
-      }
+  byte(): number {
+    if (this.offset >= this.buffer.length) {
+      this.refill();
     }
+    const val = this.buffer[this.offset]!;
+    this.offset += 1;
+    return val;
+  }
 
-    return simpleHash;
+  // uniform float in [0, 1)
+  float(): number {
+    return this.uint32() / 0xffffffff;
   }
-}
 
-export const randomBytes = (size: number): ICryptoBuffer => CryptoUtils.randomBytes(size);
-export const createHash = (algorithm: string): CryptoHash => CryptoUtils.createHash(algorithm);
+  // uniform integer in [min, max)
+  int(min: number, max: number): number {
+    return Math.floor(this.float() * (max - min)) + min;
+  }
+}

package/src/utils/emojiGenerator.ts

@@ -0,0 +1,88 @@
+import { randomBytes } from './crypto';
+
+export interface EmojiGeneratorResult {
+  emojis: string[];
+  category: string;
+  answer: string;
+  question: string;
+}
+
+// each category has >= 20 entries to ensure unique sampling without replacement
+const CATEGORIES: Record<string, string[]> = {
+  animals:  ['🐶','🐱','🐭','🐹','🐰','🦊','🐻','🐼','🐨','🐯','🦁','🐮','🐷','🐸','🐵','🦒','🦓','🐘','🐧','🦅'],
+  food:     ['🍎','🍊','🍋','🍇','🍓','🍔','🍕','🍜','🍣','🍩','🎂','🥦','🥕','🥑','🧀','🍦','🍫','🥐','🌮','🍱'],
+  vehicles: ['🚗','🚕','🚙','🚌','🚑','🚒','🚓','🚜','🏎','🚂','🚁','🛩','🚀','🛸','🚢','⛵','🚲','🛵','🏍','🚛'],
+  nature:   ['🌸','🌺','🌻','🌹','🌷','🍀','🌿','🌱','🌲','🌳','🍁','🍂','🌊','🌙','⭐','🌈','🌞','🌋','🏔','🌾'],
+  sports:   ['⚽','🏀','🏈','⚾','🎾','🏐','🏉','🎱','🏓','🏸','🥊','🎿','🛷','⛷','🤸','🚴','🏊','🤺','🥋','🎯'],
+};
+
+const CATEGORY_KEYS = Object.keys(CATEGORIES);
+
+// crypto-safe index in [0, max)
+function secureIndex(max: number): number {
+  const buf = randomBytes(4);
+  return buf.readUInt32LE(0) % max;
+}
+
+// pick `count` unique items from pool without replacement
+function pickUnique(pool: string[], count: number): string[] {
+  const available = pool.slice();
+  const result: string[] = [];
+  for (let i = 0; i < count && available.length > 0; i++) {
+    const idx = secureIndex(available.length);
+    result.push(available.splice(idx, 1)[0]!);
+  }
+  return result;
+}
+
+// Fisher-Yates in-place shuffle with crypto random
+function shuffleInPlace(arr: string[]): void {
+  const batchBuf = randomBytes(arr.length * 4);
+  for (let i = arr.length - 1; i > 0; i--) {
+    const j = batchBuf.readUInt32LE((arr.length - 1 - i) * 4) % (i + 1);
+    [arr[i]!, arr[j]!] = [arr[j]!, arr[i]!];
+  }
+}
+
+export class EmojiGenerator {
+  static generate(difficulty: 'easy' | 'medium' | 'hard'): EmojiGeneratorResult {
+    const targetCount     = difficulty === 'easy' ? 2 : difficulty === 'medium' ? 3 : 4;
+    const distractorCount = difficulty === 'easy' ? 2 : difficulty === 'medium' ? 3 : 4;
+    const totalCount      = targetCount + distractorCount;
+
+    const categoryKey = CATEGORY_KEYS[secureIndex(CATEGORY_KEYS.length)]!;
+    const targetPool  = CATEGORIES[categoryKey]!;
+
+    // collect distractor emojis from all categories except the target
+    const distractorPool: string[] = [];
+    for (const key of CATEGORY_KEYS) {
+      if (key !== categoryKey) {
+        distractorPool.push(...CATEGORIES[key]!);
+      }
+    }
+
+    const targets     = pickUnique(targetPool, targetCount);
+    const distractors = pickUnique(distractorPool, distractorCount);
+
+    // combine then shuffle; track indices after shuffle
+    const combined = [...targets, ...distractors];
+    shuffleInPlace(combined);
+
+    // mark which positions ended up containing target emojis
+    const targetSet = new Set(targets);
+    const targetIndices = combined
+      .map((e, i) => (targetSet.has(e) ? i : -1))
+      .filter(i => i !== -1)
+      .sort((a, b) => a - b);
+
+    // canonical answer: sorted comma-separated zero-based indices e.g. "0,2,4"
+    const answer = targetIndices.join(',');
+
+    return {
+      emojis: combined,
+      category: categoryKey,
+      answer,
+      question: `Select all ${categoryKey} from the list (${totalCount} emojis, ${targetCount} correct)`
+    };
+  }
+}

package/src/utils/imageGenerator.ts

@@ -0,0 +1,152 @@
+import { RandomPool } from './crypto';
+import { Buffer } from 'node:buffer';
+
+interface ImageGeneratorResult {
+  image: string;
+  answer: string;
+  question: string;
+}
+
+const CHAR_POOL_EASY   = 'ABCDEFGHJKLMNPQRSTUVWXYZ';
+const CHAR_POOL_MEDIUM = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
+const CHAR_POOL_HARD   = 'ABCDEFGHJKLMNPQRSTUVWXYZabcdefghjkmnpqrstuvwxyz23456789';
+
+const SVG_WIDTH  = 200;
+const SVG_HEIGHT = 70;
+
+// prevents XML injection via user-controlled strings embedded in SVG
+function escapeXml(str: string): string {
+  return str
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function generateText(pool: RandomPool, charPool: string, length: number): string {
+  let result = '';
+  for (let i = 0; i < length; i++) {
+    result += charPool[pool.byte() % charPool.length]!;
+  }
+  return result;
+}
+
+// each character is rendered individually with rotation and offset to resist OCR
+function renderChar(pool: RandomPool, char: string, x: number, baseY: number, colorHex: string): string {
+  const rotate  = pool.int(-25, 25);
+  const offsetY = pool.int(-6, 6);
+  const fontSize = pool.int(22, 30);
+  const opacity  = (pool.float() * 0.25 + 0.75).toFixed(2);
+
+  return `<text x="${x}" y="${baseY + offsetY}" transform="rotate(${rotate},${x},${baseY + offsetY})" font-size="${fontSize}" font-family="monospace" font-weight="bold" fill="${colorHex}" opacity="${opacity}" letter-spacing="2">${escapeXml(char)}</text>`;
+}
+
+function grayColor(pool: RandomPool): string {
+  const v = pool.int(100, 200);
+  return `rgb(${v},${v},${v})`;
+}
+
+function darkColor(pool: RandomPool): string {
+  const r = pool.int(20, 150);
+  const g = pool.int(20, 150);
+  const b = pool.int(20, 150);
+  return `rgb(${r},${g},${b})`;
+}
+
+// interference lines make automated segment extraction harder
+function renderNoiseLines(pool: RandomPool, count: number): string {
+  let lines = '';
+  for (let i = 0; i < count; i++) {
+    const x1 = pool.int(0, SVG_WIDTH);
+    const y1 = pool.int(0, SVG_HEIGHT);
+    const x2 = pool.int(0, SVG_WIDTH);
+    const y2 = pool.int(0, SVG_HEIGHT);
+    const strokeWidth = (pool.float() * 1.5 + 0.5).toFixed(1);
+    const color   = grayColor(pool);
+    const opacity = (pool.float() * 0.4 + 0.2).toFixed(2);
+    lines += `<line x1="${x1}" y1="${y1}" x2="${x2}" y2="${y2}" stroke="${color}" stroke-width="${strokeWidth}" opacity="${opacity}"/>`;
+  }
+  return lines;
+}
+
+// noise dots add pixel-level entropy that defeats simple segmentation
+function renderNoiseDots(pool: RandomPool, count: number): string {
+  let dots = '';
+  for (let i = 0; i < count; i++) {
+    const cx      = pool.int(0, SVG_WIDTH);
+    const cy      = pool.int(0, SVG_HEIGHT);
+    const r       = pool.int(1, 3);
+    const color   = grayColor(pool);
+    const opacity = (pool.float() * 0.5 + 0.1).toFixed(2);
+    dots += `<circle cx="${cx}" cy="${cy}" r="${r}" fill="${color}" opacity="${opacity}"/>`;
+  }
+  return dots;
+}
+
+// sinusoidal wave distortion applied as a path overlay
+function renderWavePath(pool: RandomPool): string {
+  const amplitude  = pool.int(3, 8);
+  const frequency  = pool.float() * 0.08 + 0.04;
+  const phaseShift = pool.float() * Math.PI * 2;
+  const strokeColor = grayColor(pool);
+
+  let d = `M 0 ${SVG_HEIGHT / 2}`;
+  for (let x = 1; x <= SVG_WIDTH; x += 2) {
+    const y = SVG_HEIGHT / 2 + amplitude * Math.sin(frequency * x + phaseShift);
+    d += ` L ${x} ${y.toFixed(2)}`;
+  }
+
+  return `<path d="${d}" stroke="${strokeColor}" stroke-width="1.5" fill="none" opacity="0.35"/>`;
+}
+
+function buildSvg(pool: RandomPool, text: string, difficulty: 'easy' | 'medium' | 'hard'): string {
+  const charCount = text.length;
+  const spacing   = SVG_WIDTH / (charCount + 1);
+  const baseY     = SVG_HEIGHT / 2 + 8;
+
+  const noiseLineCount = difficulty === 'easy' ? 4  : difficulty === 'medium' ? 7  : 10;
+  const noiseDotCount  = difficulty === 'easy' ? 20 : difficulty === 'medium' ? 40 : 60;
+  const waveCount      = difficulty === 'easy' ? 1  : difficulty === 'medium' ? 2  : 3;
+
+  const bgGray = pool.int(235, 250);
+  const background = `<rect width="${SVG_WIDTH}" height="${SVG_HEIGHT}" fill="rgb(${bgGray},${bgGray},${bgGray})" rx="6"/>`;
+
+  let chars = '';
+  for (let i = 0; i < charCount; i++) {
+    const x     = Math.round(spacing * (i + 1));
+    const color = darkColor(pool);
+    chars += renderChar(pool, text[i]!, x, baseY, color);
+  }
+
+  let waves = '';
+  for (let i = 0; i < waveCount; i++) {
+    waves += renderWavePath(pool);
+  }
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${SVG_WIDTH}" height="${SVG_HEIGHT}" viewBox="0 0 ${SVG_WIDTH} ${SVG_HEIGHT}">${background}${renderNoiseDots(pool, noiseDotCount)}${renderNoiseLines(pool, noiseLineCount)}${waves}${chars}</svg>`;
+}
+
+function svgToDataUri(svg: string): string {
+  return `data:image/svg+xml;base64,${Buffer.from(svg, 'utf-8').toString('base64')}`;
+}
+
+export class ImageGenerator {
+  static generate(difficulty: 'easy' | 'medium' | 'hard'): ImageGeneratorResult {
+    // single pool allocation covers all random needs for this image — ~1 crypto
+    // call instead of the ~500 individual randomBytes(4) calls it replaced
+    const pool = new RandomPool(2048);
+
+    const charPool = difficulty === 'easy' ? CHAR_POOL_EASY : difficulty === 'medium' ? CHAR_POOL_MEDIUM : CHAR_POOL_HARD;
+    const length   = difficulty === 'easy' ? 4 : difficulty === 'medium' ? 5 : 6;
+    const answer   = generateText(pool, charPool, length);
+    const svg      = buildSvg(pool, answer, difficulty);
+    const image    = svgToDataUri(svg);
+
+    return {
+      image,
+      answer: answer.toLowerCase(),
+      question: 'Type the characters shown in the image'
+    };
+  }
+}

package/src/utils/reverseGenerator.ts

@@ -1,3 +1,5 @@
+import { randomBytes } from './crypto';
+
 export class ReverseGenerator {
   private static readonly easyWords = [
     'cat', 'dog', 'sun', 'moon', 'star', 'fish', 'bird', 'tree',
@@ -42,7 +44,9 @@ export class ReverseGenerator {
       wordPool = this.hardWords;
     }
     
-    const text = wordPool![Math.floor(Math.random() * wordPool!.length)]!;
+    const buf = randomBytes(4);
+    const rand = buf.readUInt32LE(0) / 0xFFFFFFFF;
+    const text = wordPool![Math.floor(rand * wordPool!.length)]!;
     const reversed = text.split('').reverse().join('');
     
     return { question: reversed, answer: text };