fraud-sim 0.2.0

package/src/streaming/sse.js

@@ -0,0 +1,105 @@
+/**
+ * Server-Sent Events streaming helper.
+ *
+ * Wraps an Express-style response object to stream simulation events to a
+ * browser dashboard as they happen, instead of waiting for the full report.
+ *
+ * @example
+ *   import { sseStream } from 'fraud-sim/streaming';
+ *
+ *   app.get('/simulate/:scenario/stream', async (req, res) => {
+ *     const stream = sseStream(res);
+ *     await run(req.params.scenario, {
+ *       target,
+ *       onEvent: (event) => stream.send(event),
+ *     });
+ *     stream.close();
+ *   });
+ */
+
+/**
+ * Set up SSE headers on `res` and return a `{ send, close }` handle.
+ *
+ * Handles backpressure: if `res.write` reports the internal buffer is full
+ * (returns `false`), further events queue in memory until the response
+ * emits `drain`, then flush in order.
+ *
+ * @param {object} res - Any Express-style response with `write`, `end`,
+ *   `writeHead` (or settable `.statusCode`/`.setHeader`), and an
+ *   EventEmitter-style `on('drain', ...)`.
+ * @returns {{ send: (event: object) => void, close: () => void }}
+ */
+export function sseStream(res) {
+  if (typeof res?.write !== 'function' || typeof res?.end !== 'function') {
+    throw new Error('sseStream(res) requires a response object with write() and end() methods');
+  }
+
+  if (typeof res.writeHead === 'function') {
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+    });
+  } else {
+    res.statusCode = 200;
+    res.setHeader?.('Content-Type', 'text/event-stream');
+    res.setHeader?.('Cache-Control', 'no-cache');
+    res.setHeader?.('Connection', 'keep-alive');
+  }
+
+  const queue = [];
+  let draining = false;
+  let closed = false;
+  let closing = false;
+
+  function frame(event) {
+    return `data: ${JSON.stringify(event)}\n\n`;
+  }
+
+  function flush() {
+    while (queue.length > 0) {
+      // write() sends the chunk regardless of its return value — a `false`
+      // return just signals "the internal buffer is full, pause before
+      // writing more", matching Node's own Writable stream contract. So the
+      // chunk is dequeued either way; only further writes wait for drain.
+      const next = queue.shift();
+      const ok = res.write(next);
+      if (!ok) {
+        if (!draining) {
+          draining = true;
+          res.once?.('drain', () => {
+            draining = false;
+            flush();
+          });
+        }
+        return;
+      }
+    }
+    // Everything queued so far has been flushed — safe to end now.
+    if (closing && !closed) {
+      closed = true;
+      res.end();
+    }
+  }
+
+  function write(raw) {
+    if (closed || closing) return;
+    queue.push(raw);
+    if (!draining) flush();
+  }
+
+  return {
+    /** Send one event to the client as an SSE `data:` frame. */
+    send(event) {
+      write(frame(event));
+    },
+
+    /** Send the done sentinel, flush any pending backpressure, then end. */
+    close() {
+      if (closing || closed) return;
+      queue.push(frame({ type: 'done' }));
+      closing = true;
+      if (!draining) flush();
+    },
+  };
+}

package/src/utils/faker-helpers.js

@@ -0,0 +1,76 @@
+/**
+ * Shared payload builders. Centralised here so all scenarios produce
+ * structurally consistent payloads — and so adding a field to all
+ * scenarios at once is a one-line change.
+ *
+ * Uses the internal `random.js` utilities to avoid a faker dependency.
+ */
+
+import {
+  alphanumeric,
+  randomIp,
+  randomUserAgent,
+  randomAccountNumber,
+  randomBank,
+  randomFullName,
+  randomInt,
+  pickOne,
+} from './random.js';
+
+export function newSessionId(prefix = 'sim') {
+  return `${prefix}_${alphanumeric(10)}`;
+}
+
+export function newDeviceFingerprint() {
+  return alphanumeric(32);
+}
+
+export function newReference() {
+  return `TXN_${Date.now()}_${alphanumeric(6)}`;
+}
+
+export function newPayee() {
+  return {
+    payee_account: randomAccountNumber(),
+    payee_bank: randomBank(),
+    payee_name: randomFullName(),
+  };
+}
+
+export function buildLoginPayload(userId, overrides = {}) {
+  return {
+    user_id: userId,
+    session_id: newSessionId(),
+    ip_address: randomIp(),
+    user_agent: randomUserAgent(),
+    device_fingerprint: newDeviceFingerprint(),
+    timestamp: new Date().toISOString(),
+    metadata: {
+      login_method: 'password',
+      platform: pickOne(['web', 'android', 'ios']),
+      _simulated: true,
+    },
+    ...overrides,
+  };
+}
+
+export function buildWithdrawalPayload(userId, transaction = {}, overrides = {}) {
+  const payee = newPayee();
+  return {
+    user_id: userId,
+    session_id: newSessionId(),
+    ip_address: randomIp(),
+    device_fingerprint: newDeviceFingerprint(),
+    timestamp: new Date().toISOString(),
+    transaction: {
+      amount: randomInt(100000, 5000000),
+      currency: 'NGN',
+      ...payee,
+      is_new_payee: true,
+      reference: newReference(),
+      ...transaction,
+    },
+    metadata: { _simulated: true },
+    ...overrides,
+  };
+}

package/src/utils/random.js

@@ -0,0 +1,114 @@
+/**
+ * Internal random data utilities.
+ *
+ * fraud-sim deliberately does not depend on a faker library. We need a handful
+ * of synthetic data generators and the simpler the dependency graph, the safer
+ * the library is to adopt. This module provides everything we use.
+ *
+ * If you need richer fake data in your own scenarios (real-looking names,
+ * locale-specific data, etc.), import @faker-js/faker in your scenario file —
+ * it is not bundled with fraud-sim, but you can use it freely alongside it.
+ */
+
+const ALPHANUM = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+
+const NIGERIAN_BANKS = [
+  'GTBank',
+  'UBA',
+  'Access',
+  'Zenith',
+  'First Bank',
+  'FCMB',
+  'Sterling',
+  'Stanbic IBTC',
+  'Fidelity',
+  'Wema',
+];
+
+const FIRST_NAMES = [
+  'Adaeze', 'Chinedu', 'Folake', 'Tunde', 'Aisha', 'Emeka', 'Nkechi', 'Bayo',
+  'Ngozi', 'Olumide', 'Funmi', 'Kayode', 'Hauwa', 'Ifeanyi', 'Toyin', 'Segun',
+  'James', 'Mary', 'David', 'Sarah', 'Michael', 'Grace', 'John', 'Esther',
+];
+
+const LAST_NAMES = [
+  'Adeyemi', 'Okonkwo', 'Ibrahim', 'Nwosu', 'Bello', 'Eze', 'Yusuf', 'Okoye',
+  'Lawal', 'Obi', 'Musa', 'Achebe', 'Akin', 'Adamu', 'Ojo', 'Chukwu',
+  'Smith', 'Brown', 'Williams', 'Johnson',
+];
+
+const USER_AGENTS = [
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+  'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+  'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+  'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1',
+  'Mozilla/5.0 (Linux; Android 13; SM-A546B) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Mobile Safari/537.36',
+  'Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Mobile Safari/537.36',
+  'curl/8.4.0',
+  'python-requests/2.31.0',
+];
+
+/**
+ * Random integer in [min, max] inclusive.
+ */
+export function randomInt(min, max) {
+  return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+/**
+ * Pick one element from an array.
+ */
+export function pickOne(arr) {
+  return arr[Math.floor(Math.random() * arr.length)];
+}
+
+/**
+ * Generate a random alphanumeric string of the given length.
+ */
+export function alphanumeric(length) {
+  let out = '';
+  for (let i = 0; i < length; i++) {
+    out += ALPHANUM.charAt(Math.floor(Math.random() * ALPHANUM.length));
+  }
+  return out;
+}
+
+/**
+ * Generate a synthetic IPv4 address.
+ * Not from any real range — purely synthetic for testing.
+ */
+export function randomIp() {
+  return `${randomInt(1, 254)}.${randomInt(0, 255)}.${randomInt(0, 255)}.${randomInt(1, 254)}`;
+}
+
+/**
+ * Pick a realistic user agent string.
+ */
+export function randomUserAgent() {
+  return pickOne(USER_AGENTS);
+}
+
+/**
+ * Generate a synthetic Nigerian-style account number (10 digits).
+ */
+export function randomAccountNumber() {
+  let out = '';
+  for (let i = 0; i < 10; i++) {
+    out += randomInt(0, 9).toString();
+  }
+  return out;
+}
+
+/**
+ * Pick a Nigerian bank name.
+ */
+export function randomBank() {
+  return pickOne(NIGERIAN_BANKS);
+}
+
+/**
+ * Generate a random full name.
+ */
+export function randomFullName() {
+  return `${pickOne(FIRST_NAMES)} ${pickOne(LAST_NAMES)}`;
+}

package/src/utils/rng.js

@@ -0,0 +1,76 @@
+/**
+ * Seeded pseudo-random number generator.
+ *
+ * `random.js` uses `Math.random()`, which is fine for generating attack traffic
+ * but useless when a run has to be reproducible. The deterministic LLM provider
+ * needs the same seed to produce the same strategy for the same history, so it
+ * uses this instead.
+ *
+ * Algorithm is mulberry32 — small, fast, and good enough for synthetic data.
+ * It is NOT cryptographically secure and must never be used for anything that
+ * needs real randomness.
+ */
+
+const ALPHANUM = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+
+export class DeterministicRng {
+  /**
+   * @param {number} [seed] - Any integer. The same seed always replays the same sequence.
+   */
+  constructor(seed = 1) {
+    // Coerce to a 32-bit integer so string/float seeds don't silently misbehave.
+    this.state = Math.trunc(seed) >>> 0;
+  }
+
+  /**
+   * Next float in [0, 1).
+   * @returns {number}
+   */
+  next() {
+    this.state = (this.state + 0x6d2b79f5) >>> 0;
+    let t = this.state;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  }
+
+  /**
+   * Integer in [min, max] inclusive.
+   * @param {number} min
+   * @param {number} max
+   * @returns {number}
+   */
+  int(min, max) {
+    return Math.floor(this.next() * (max - min + 1)) + min;
+  }
+
+  /**
+   * Pick one element from an array.
+   * @param {Array} arr
+   * @returns {*}
+   */
+  pick(arr) {
+    return arr[Math.floor(this.next() * arr.length)];
+  }
+
+  /**
+   * Random alphanumeric string of the given length.
+   * @param {number} length
+   * @returns {string}
+   */
+  alphanumeric(length) {
+    let out = '';
+    for (let i = 0; i < length; i++) {
+      out += ALPHANUM.charAt(Math.floor(this.next() * ALPHANUM.length));
+    }
+    return out;
+  }
+
+  /**
+   * Synthetic IPv4 address.
+   * @returns {string}
+   */
+  ip() {
+    return `${this.int(1, 254)}.${this.int(0, 255)}.${this.int(0, 255)}.${this.int(1, 254)}`;
+  }
+}

package/src/utils/sleep.js

@@ -0,0 +1,32 @@
+/**
+ * Sleep utility — abort-aware.
+ *
+ * Used by scenarios to space out attack attempts. Respects AbortSignal
+ * so scenarios cancel promptly when the user aborts.
+ */
+
+export function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new Error('Aborted'));
+      return;
+    }
+
+    const timer = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, ms);
+
+    const onAbort = () => {
+      cleanup();
+      reject(new Error('Aborted'));
+    };
+
+    const cleanup = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener?.('abort', onAbort);
+    };
+
+    signal?.addEventListener?.('abort', onAbort, { once: true });
+  });
+}