k9guard 1.0.1 → 1.0.3

package/src/utils/crypto.ts

@@ -1,31 +1,3 @@
-/**
- * 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.
- *
- * 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
- *
- * 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
- */
-
-declare const window: any;
-declare const self: any;
-
-/**
- * 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 +6,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 +24,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 +37,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,11 +49,7 @@ 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);
-      }
-      return binString;
+      return btoa(binString);
     }
     return new TextDecoder().decode(this.buffer);
   }
@@ -197,14 +58,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 +77,260 @@ export class CryptoBuffer implements ICryptoBuffer {
 }
 
 /**
- * Incremental hash computation class
+ * Synchronous SHA-256 hasher backed by Web Crypto subtle API.
+ *
+ * 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.
  *
- * Provides Node.js crypto.createHash() compatible interface.
- * Supports incremental updates for large data processing.
- * Uses custom hash algorithm optimized for browser compatibility.
+ * 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 dataChunks: Uint8Array[] = [];
-
-  /**
-   * 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;
+  private chunks: Uint8Array[] = [];
 
-    this.dataChunks.push(inputBytes);
+  update(input: string | Uint8Array): this {
+    if (typeof input === 'string') {
+      this.chunks.push(new TextEncoder().encode(input));
+    } else {
+      this.chunks.push(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;
+  // Pure-JS SHA-256 — used for the synchronous digest path.
+  // Identical output to SubtleCrypto; no external dependency.
+  digest(encoding: 'hex' | 'base64' | 'binary' = 'hex'): string {
+    const combined = this.mergeChunks();
+    const hash = sha256(combined);
 
-    for (const chunk of this.dataChunks) {
-      combined.set(chunk, offset);
-      offset += chunk.length;
+    if (encoding === 'hex') {
+      return Array.from(hash).map(b => b.toString(16).padStart(2, '0')).join('');
     }
-
-    return combined;
+    if (encoding === 'base64') {
+      const binString = Array.from(hash, b => String.fromCodePoint(b)).join('');
+      return btoa(binString);
+    }
+    return String.fromCodePoint(...hash);
   }
 
-  /**
-   * 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);
+  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;
+  }
+}
 
-    if (encoding === 'hex') {
-      return Array.from(hashArray)
-        .map(b => b.toString(16).padStart(2, '0'))
-        .join('');
+export class CryptoUtils {
+  static randomBytes(size: number): ICryptoBuffer {
+    if (size <= 0 || size > 65536) {
+      throw new RangeError('Size must be between 1 and 65536');
     }
-    if (encoding === 'base64') {
-      const binString = Array.from(hashArray, (byte: number) => String.fromCodePoint(byte)).join('');
-      if (typeof btoa !== 'undefined') {
-        return btoa(binString);
-      }
-      return binString;
+    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 {
+    if (algorithm.toLowerCase() !== 'sha256') {
+      throw new Error('Only SHA-256 is supported');
     }
+    return new CryptoHash();
+  }
+}
+
+export const randomBytes = (size: number): ICryptoBuffer => CryptoUtils.randomBytes(size);
+export const createHash = (algorithm: string): CryptoHash => CryptoUtils.createHash(algorithm);
 
-    return new TextDecoder().decode(hashArray);
+/**
+ * Constant-time byte comparison — prevents timing side-channel attacks
+ * where an attacker measures how quickly the comparison short-circuits.
+ *
+ * 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;
+}
 
-  /**
-   * 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
-
-      const val1 = simpleHash[idx1];
-      const val2 = simpleHash[idx2];
-
-      if (val1 !== undefined) {
-        simpleHash[idx1] = val1 ^ byteVal;
-      }
+/**
+ * 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: Uint8Array;
+  private offset: number;
+  private readonly chunkSize: number;
+
+  constructor(chunkSize = 2048) {
+    this.chunkSize = chunkSize;
+    this.buffer = new Uint8Array(chunkSize);
+    globalThis.crypto.getRandomValues(this.buffer);
+    this.offset = 0;
+  }
 
-      if (val2 !== undefined) {
-        simpleHash[idx2] = ((val2 + byteVal) * 31) & 0xFF; // NOTE: 31 is prime for avalanche effect
-      }
+  private refill(): void {
+    globalThis.crypto.getRandomValues(this.buffer);
+    this.offset = 0;
+  }
+
+  uint32(): number {
+    if (this.offset + 4 > this.buffer.length) {
+      this.refill();
     }
+    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;
+    // Little-endian assembly, unsigned
+    return (b0 | (b1 << 8) | (b2 << 16) | (b3 << 24)) >>> 0;
+  }
 
-    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)
+  byte(): number {
+    if (this.offset >= this.buffer.length) {
+      this.refill();
+    }
+    const val = this.buffer[this.offset]!;
+    this.offset += 1;
+    return val;
+  }
 
-        const prev = simpleHash[prevIdx];
-        const curr = simpleHash[i];
-        const next = simpleHash[nextIdx];
+  // uniform float in [0, 1)
+  float(): number {
+    return this.uint32() / 0xffffffff;
+  }
 
-        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;
-        }
-      }
+  // uniform integer in [min, max)
+  int(min: number, max: number): number {
+    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;
     }
 
-    return simpleHash;
+    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;
   }
-}
 
-export const randomBytes = (size: number): ICryptoBuffer => CryptoUtils.randomBytes(size);
-export const createHash = (algorithm: string): CryptoHash => CryptoUtils.createHash(algorithm);
+  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/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)`
+    };
+  }
+}