fraud-sim 0.2.0 → 0.5.1

package/src/utils/random.js

@@ -8,34 +8,18 @@
  * 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.
+ *
+ * Every helper here is built on exactly three primitives — `randomInt`,
+ * `pickOne` and `alphanumeric` — and all three draw from the run-scoped source
+ * in `random-source.js`. Seed a run and every value below replays identically.
+ * A helper that reaches for `Math.random()` directly would silently opt itself
+ * out of that, so none of them do.
  */
 
-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',
-];
+import { randomFloat, currentLocale } from './random-source.js';
+import { resolveLocale } from '../locales/index.js';
 
-const LAST_NAMES = [
-  'Adeyemi', 'Okonkwo', 'Ibrahim', 'Nwosu', 'Bello', 'Eze', 'Yusuf', 'Okoye',
-  'Lawal', 'Obi', 'Musa', 'Achebe', 'Akin', 'Adamu', 'Ojo', 'Chukwu',
-  'Smith', 'Brown', 'Williams', 'Johnson',
-];
+const ALPHANUM = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
 
 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',
@@ -52,14 +36,14 @@ const USER_AGENTS = [
  * Random integer in [min, max] inclusive.
  */
 export function randomInt(min, max) {
-  return Math.floor(Math.random() * (max - min + 1)) + min;
+  return Math.floor(randomFloat() * (max - min + 1)) + min;
 }
 
 /**
  * Pick one element from an array.
  */
 export function pickOne(arr) {
-  return arr[Math.floor(Math.random() * arr.length)];
+  return arr[Math.floor(randomFloat() * arr.length)];
 }
 
 /**
@@ -68,47 +52,276 @@ export function pickOne(arr) {
 export function alphanumeric(length) {
   let out = '';
   for (let i = 0; i < length; i++) {
-    out += ALPHANUM.charAt(Math.floor(Math.random() * ALPHANUM.length));
+    out += ALPHANUM.charAt(Math.floor(randomFloat() * ALPHANUM.length));
   }
   return out;
 }
 
 /**
- * Generate a synthetic IPv4 address.
- * Not from any real range — purely synthetic for testing.
+ * IPv4 ranges that are reserved, private, or otherwise never routed on the
+ * public internet. A generator that emits these produces addresses that no
+ * IP-intelligence provider can resolve — which silently disables every
+ * geo/reputation rule on the target being tested. We skip them.
+ *
+ * @param {number} a - first octet
+ * @param {number} b - second octet
+ * @returns {boolean}
+ */
+function isReservedIpv4(a, b) {
+  if (a === 0 || a === 10 || a === 127) return true;      // this-network, private, loopback
+  if (a >= 224) return true;                               // multicast + reserved + broadcast
+  if (a === 100 && b >= 64 && b <= 127) return true;       // CGNAT   100.64.0.0/10
+  if (a === 169 && b === 254) return true;                 // link-local
+  if (a === 172 && b >= 16 && b <= 31) return true;        // private 172.16.0.0/12
+  if (a === 192 && b === 168) return true;                 // private
+  if (a === 192 && b === 0) return true;                   // 192.0.0.0/24 + TEST-NET-1
+  if (a === 192 && b === 88) return true;                  // 6to4 relay anycast
+  if (a === 198 && (b === 18 || b === 19)) return true;     // benchmarking
+  if (a === 198 && b === 51) return true;                  // TEST-NET-2
+  if (a === 203 && b === 0) return true;                   // TEST-NET-3
+  return false;
+}
+
+/**
+ * Generate a synthetic but *publicly routable* IPv4 address.
+ *
+ * Deliberately excludes private, loopback, CGNAT, link-local, multicast and
+ * documentation ranges. Addresses from those blocks cannot be resolved by any
+ * geo/reputation provider, so a target that scores them will fall back to
+ * neutral intel and never fire its proxy, abuse-score, or geo rules — making a
+ * defence look weaker than it is.
+ *
+ * These addresses are used only as payload field values. `fraud-sim` never
+ * connects to them.
+ *
+ * For a stable, pre-seedable set with known geolocation, use
+ * {@link DEMO_IP_POOL} / {@link pickDemoIp} instead.
  */
 export function randomIp() {
-  return `${randomInt(1, 254)}.${randomInt(0, 255)}.${randomInt(0, 255)}.${randomInt(1, 254)}`;
+  let a, b;
+  do {
+    a = randomInt(1, 223);
+    b = randomInt(0, 255);
+  } while (isReservedIpv4(a, b));
+  return `${a}.${b}.${randomInt(0, 255)}.${randomInt(1, 254)}`;
 }
 
 /**
- * Pick a realistic user agent string.
+ * A fixed pool of attacker IPs with known, declared geolocation and
+ * reputation metadata.
+ *
+ * Why this exists: most fraud systems resolve IP intelligence *asynchronously*
+ * and fall back to neutral values on a cache miss. In a short simulation every
+ * IP is seen for the first time, so geo and reputation rules never fire and the
+ * run under-reports what the defence can actually catch. Because this pool is
+ * fixed and its metadata is declared here, the system under test can pre-warm
+ * its IP-intel cache from `DEMO_IP_POOL` before a run — no live lookups, no
+ * third-party rate limits, and reproducible results.
+ *
+ * Addresses are drawn from the RFC 5737 documentation ranges (192.0.2.0/24,
+ * 198.51.100.0/24, 203.0.113.0/24). They are reserved for documentation, are
+ * never routed, and belong to no real network — so attack traffic in a
+ * simulation is never attributed to a real operator. The geolocation and
+ * reputation fields are synthetic labels chosen to exercise distinct rule
+ * paths, not claims about these addresses.
+ *
+ * Personas covered:
+ *   - `domestic` residential  → the victim's home country; the quiet baseline
+ *   - `hosting`               → datacenter ranges; should fire hosting rules
+ *   - `proxy`                 → VPN/proxy exits; should fire proxy rules
+ *   - `foreign` residential   → new-country and impossible-travel paths
+ *
+ * @type {ReadonlyArray<{ip: string, countryCode: string, country: string,
+ *   lat: number, lon: number, proxy: boolean, hosting: boolean,
+ *   abuseScore: number, isp: string, persona: string}>}
  */
-export function randomUserAgent() {
-  return pickOne(USER_AGENTS);
+const FOREIGN_POOL = Object.freeze([
+  // ── Datacenter / hosting — bot traffic rarely comes from a living room
+  f('198.51.100.20', 'NL', 'Netherlands', 52.3676, 4.9041, false, true, 78, 'Simulated Cloud Hosting (Amsterdam)', 'hosting'),
+  f('198.51.100.21', 'DE', 'Germany', 50.1109, 8.6821, false, true, 84, 'Simulated Cloud Hosting (Frankfurt)', 'hosting'),
+  f('198.51.100.22', 'US', 'United States', 39.0438, -77.4874, false, true, 91, 'Simulated Cloud Hosting (Ashburn)', 'hosting'),
+  f('198.51.100.23', 'SG', 'Singapore', 1.3521, 103.8198, false, true, 66, 'Simulated Cloud Hosting (Singapore)', 'hosting'),
+
+  // ── Proxy / VPN exits — the usual answer to a blocked datacenter range
+  f('203.0.113.30', 'RU', 'Russia', 55.7558, 37.6173, true, false, 72, 'Simulated VPN Exit (Moscow)', 'proxy'),
+  f('203.0.113.31', 'UA', 'Ukraine', 50.4501, 30.5234, true, false, 58, 'Simulated VPN Exit (Kyiv)', 'proxy'),
+  f('203.0.113.32', 'CN', 'China', 22.5431, 114.0579, true, false, 69, 'Simulated Proxy Exit (Shenzhen)', 'proxy'),
+
+  // ── Foreign residential — new country + impossible travel, low reputation signal
+  f('203.0.113.40', 'BR', 'Brazil', -23.5505, -46.6333, false, false, 12, 'Simulated Residential ISP (Sao Paulo)', 'foreign'),
+  f('203.0.113.41', 'IN', 'India', 19.076, 72.8777, false, false, 8, 'Simulated Residential ISP (Mumbai)', 'foreign'),
+]);
+
+/**
+ * Domestic entries for the active market.
+ *
+ * "Domestic" only means anything relative to a market: an address in Lagos is
+ * the quiet baseline for a Nigerian bank and a new-country signal for a British
+ * one. These are generated from the locale's cities so the pool means the same
+ * thing wherever the tool is pointed.
+ */
+function domesticEntries(locale) {
+  return locale.cities.map((place, i) =>
+    f(
+      `192.0.2.${10 + i}`,
+      locale.id,
+      locale.name,
+      place.lat,
+      place.lon,
+      false,
+      false,
+      0,
+      `Simulated Residential ISP (${place.city})`,
+      'domestic'
+    )
+  );
 }
 
 /**
- * Generate a synthetic Nigerian-style account number (10 digits).
+ * The attacker IP pool for the run's market: domestic entries from the active
+ * locale, plus the fixed set of hosting, proxy and foreign exits.
+ *
+ * Exposed as a getter so it tracks the locale in scope without callers having
+ * to pass one. `demoIpPool()` is the explicit form.
  */
-export function randomAccountNumber() {
-  let out = '';
-  for (let i = 0; i < 10; i++) {
-    out += randomInt(0, 9).toString();
+export function demoIpPool(locale) {
+  return Object.freeze([
+    ...domesticEntries(locale ?? currentLocale()),
+    ...FOREIGN_POOL,
+  ]);
+}
+
+/** Compact constructor for DEMO_IP_POOL rows — keeps the table above readable. */
+function f(ip, countryCode, country, lat, lon, proxy, hosting, abuseScore, isp, persona) {
+  return Object.freeze({ ip, countryCode, country, lat, lon, proxy, hosting, abuseScore, isp, persona });
+}
+
+/**
+ * Pick an entry from {@link DEMO_IP_POOL}, optionally filtered by persona.
+ *
+ * @param {'any'|'domestic'|'hosting'|'proxy'|'foreign'} [persona='any']
+ * @returns {(typeof DEMO_IP_POOL)[number]}
+ */
+export function pickDemoIp(persona = 'any') {
+  const pool = demoIpPool();
+  if (persona === 'any') return pickOne(pool);
+  const matches = pool.filter((entry) => entry.persona === persona);
+  if (matches.length === 0) {
+    throw new Error(
+      `Unknown IP persona: "${persona}". Expected one of: any, domestic, hosting, proxy, foreign.`
+    );
   }
+  return pickOne(matches);
+}
+
+/**
+ * Publicly documented test BIN prefixes.
+ *
+ * These are the card prefixes every payment processor publishes for sandbox
+ * use. `fraud-sim` deliberately does NOT generate Luhn-valid card numbers and
+ * never emits a full PAN — a fraud API receives a token, a BIN, and the last
+ * four digits, so that is all a scenario produces. Anything more would make the
+ * library useful for something other than testing your own defences.
+ */
+const TEST_CARD_BINS = [
+  '411111', // Visa
+  '400000', // Visa
+  '555555', // Mastercard
+  '510510', // Mastercard
+  '601111', // Discover
+  '371449', // Amex
+];
+
+/** Pick one of the published test BINs. */
+export function randomCardBin() {
+  return pickOne(TEST_CARD_BINS);
+}
+
+/** All test BINs, for scenarios that need to walk a BIN range deliberately. */
+export function cardBins() {
+  return [...TEST_CARD_BINS];
+}
+
+/** Four synthetic trailing digits. Not derived from any real card. */
+export function randomLast4() {
+  let out = '';
+  for (let i = 0; i < 4; i++) out += randomInt(0, 9).toString();
   return out;
 }
 
+/** An opaque card token, the way a processor would hand one to a risk API. */
+export function newCardToken() {
+  return `tok_sim_${alphanumeric(24)}`;
+}
+
 /**
- * Pick a Nigerian bank name.
+ * Generate an IP inside the same /24 as `ip`.
+ *
+ * Promo-abuse and other single-actor attacks look like many users, but the
+ * addresses cluster. Subnet clustering is usually the signal that catches them.
  */
-export function randomBank() {
-  return pickOne(NIGERIAN_BANKS);
+export function ipInSameSubnet(ip) {
+  const octets = String(ip).split('.');
+  if (octets.length !== 4) {
+    throw new Error(`ipInSameSubnet: "${ip}" is not a dotted-quad IPv4 address`);
+  }
+  return `${octets[0]}.${octets[1]}.${octets[2]}.${randomInt(1, 254)}`;
+}
+
+/** A subscriber number in the active market's format. */
+export function randomPhoneNumber() {
+  return currentLocale().phoneNumber(randomFloat);
 }
 
 /**
- * Generate a random full name.
+ * Pick a realistic user agent string.
  */
+export function randomUserAgent() {
+  return pickOne(USER_AGENTS);
+}
+
+/**
+ * A real browser's user agent — never a tool. For legitimate traffic, where a
+ * `curl` agent would be a false positive the simulator manufactured.
+ */
+export function randomBrowserUserAgent() {
+  return pickOne(USER_AGENTS.filter((ua) => ua.startsWith('Mozilla/')));
+}
+
+/**
+ * An account identifier shaped like the active market's — 10 digits in Nigeria,
+ * 8 in the UK, a variable length in the US. Format matters: a target that
+ * validates account numbers rejects a wrongly-shaped one before it ever scores
+ * it, and a run full of validation errors measures nothing.
+ */
+export function randomAccountNumber() {
+  return currentLocale().accountNumber(randomFloat);
+}
+
+/** A bank from the active market. */
+export function randomBank() {
+  return pickOne(currentLocale().banks);
+}
+
+/** A plausible name for the active market. Synthetic; nobody real. */
 export function randomFullName() {
-  return `${pickOne(FIRST_NAMES)} ${pickOne(LAST_NAMES)}`;
+  const locale = currentLocale();
+  return `${pickOne(locale.firstNames)} ${pickOne(locale.lastNames)}`;
 }
+
+/**
+ * A float in [0, 1) from the run's random source.
+ *
+ * Custom scenarios should use this rather than `Math.random()` — anything that
+ * bypasses it will not replay when the run is seeded.
+ */
+export { randomFloat } from './random-source.js';
+
+/**
+ * The pool for the market currently in scope.
+ *
+ * Retained as a named export because callers pre-date `demoIpPool()`; it is a
+ * snapshot of the default market rather than a live view, so a target
+ * pre-seeding intel for a non-default locale should call `demoIpPool()`.
+ */
+export const DEMO_IP_POOL = demoIpPool(resolveLocale());

package/src/utils/results.js

@@ -0,0 +1,84 @@
+/**
+ * Shared decision tallying.
+ *
+ * Every scenario counts the same four outcomes and emits the same
+ * attempt/response event pair around each call to the target. Centralising it
+ * keeps the counts consistent and means a scenario file contains only the
+ * attack logic.
+ */
+
+/** A fresh tally. */
+export function newResults(extra = {}) {
+  return { attempts: 0, blocked: 0, stepUp: 0, allowed: 0, errors: 0, ...extra };
+}
+
+/**
+ * Record one decision against a tally. Anything that isn't a recognised
+ * decision counts as an error rather than being silently dropped.
+ */
+export function countDecision(results, decision) {
+  if (decision === 'BLOCK') results.blocked++;
+  else if (decision === 'STEP_UP') results.stepUp++;
+  else if (decision === 'ALLOW') results.allowed++;
+  else results.errors++;
+  return decision;
+}
+
+/**
+ * Call one of the target's scoring methods, emitting the attempt/response
+ * events and updating the tally.
+ *
+ * Returns the target's response, or `null` if the call threw — callers decide
+ * whether a failed call ends the scenario or is skipped. A throw is counted as
+ * an error but does NOT increment `attempts`, because nothing was scored.
+ *
+ * @param {object} args
+ * @param {object} args.ctx      - The scenario context ({ target, emit }).
+ * @param {string} args.method   - 'scoreLogin' | 'scoreWithdrawal' | 'scoreAction'
+ * @param {object} args.payload  - The payload to send.
+ * @param {object} args.results  - Tally from `newResults()`.
+ * @param {string} [args.stage]  - Optional label carried on both events.
+ * @param {object} [args.ipIntel] - Declared intel for the payload's IP, if known.
+ * @returns {Promise<object|null>}
+ */
+export async function scoreAndCount({ ctx, method, payload, results, stage, ipIntel }) {
+  const { target, emit } = ctx;
+
+  if (typeof target?.[method] !== 'function') {
+    throw new Error(
+      `This scenario needs target.${method}(), which the adapter does not implement. ` +
+        'httpAdapter supports it — map it to your endpoint via the `endpoints` option.'
+    );
+  }
+
+  const round = results.attempts;
+  const t0 = Date.now();
+  emit({ type: 'attempt', round, payload, stage, ipIntel, timestamp: t0 });
+
+  let response;
+  try {
+    response = await target[method](payload);
+  } catch (err) {
+    results.errors++;
+    emit({
+      type: 'error',
+      message: `${stage ?? method} failed: ${err.message}`,
+      round,
+      timestamp: Date.now(),
+    });
+    return null;
+  }
+
+  emit({
+    type: 'response',
+    round,
+    response,
+    stage,
+    latencyMs: Date.now() - t0,
+    timestamp: Date.now(),
+  });
+
+  results.attempts++;
+  countDecision(results, response?.decision ?? 'ERROR');
+  return response;
+}

package/src/utils/rng.js

@@ -1,10 +1,9 @@
 /**
  * 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.
+ * Backs both seeded runs (installed as the run's random source by the runner —
+ * see `random-source.js`) and the deterministic LLM provider, which needs the
+ * same seed to produce the same strategy for the same history.
  *
  * Algorithm is mulberry32 — small, fast, and good enough for synthetic data.
  * It is NOT cryptographically secure and must never be used for anything that

package/src/utils/throttle.js

@@ -0,0 +1,127 @@
+/**
+ * Outbound request rate limiting.
+ *
+ * `fraud-sim` generates attack traffic, so the difference between a useful
+ * simulation and a denial-of-service against your own staging environment is
+ * one mistyped `delayMs`. Per-scenario pacing is a convention; this is the
+ * guard rail that holds when the convention is ignored.
+ *
+ * The limiter wraps the *target adapter* rather than living inside scenarios,
+ * so every call from every scenario passes through it — including scenarios
+ * written by users, which cannot be expected to police themselves.
+ *
+ * It is a sliding window, not a fixed one: a run cannot spend its whole budget
+ * in the first 50ms of each second and call the average acceptable.
+ */
+
+const SCORING_METHODS = ['scoreLogin', 'scoreWithdrawal', 'scoreAction', 'reportEvent'];
+
+/**
+ * Wrap a target adapter so its outbound calls never exceed `maxPerSecond`.
+ *
+ * Passing `Infinity` (or a non-finite value) returns the target untouched —
+ * useful in tests, and for users who have their own pacing and mean it.
+ *
+ * @param {object} target - Any TargetAdapter.
+ * @param {number} maxPerSecond
+ * @param {{ onThrottle?: (waitMs: number) => void, signal?: AbortSignal }} [hooks]
+ * @returns {object} A adapter with the same shape as `target`.
+ */
+export function throttleTarget(target, maxPerSecond, hooks = {}) {
+  if (!Number.isFinite(maxPerSecond)) return target;
+  if (maxPerSecond <= 0) {
+    throw new Error(`maxRequestsPerSecond must be greater than 0, received: ${maxPerSecond}`);
+  }
+
+  return applyLimiter(target, rateLimiter(maxPerSecond, hooks));
+}
+
+/**
+ * Wrap a target with an already-constructed limiter.
+ *
+ * Separate from `throttleTarget` because several concurrent runs need to share
+ * a single limiter instance: one limiter per run would let the effective rate
+ * scale with the concurrency, which is the opposite of what a ceiling is for.
+ *
+ * @param {object} target
+ * @param {() => Promise<void>} limiter - From `rateLimiter()`.
+ * @param {(waitMs: number) => void} [onThrottle] - Per-run accounting.
+ * @returns {object}
+ */
+export function applyLimiter(target, limiter, onThrottle) {
+  const wrapped = Object.create(Object.getPrototypeOf(target) ?? Object.prototype);
+
+  // Copy anything the adapter exposes that we are not wrapping — test helpers
+  // like mockAdapter's `_calls` have to survive the wrapping.
+  for (const key of allKeys(target)) {
+    const value = target[key];
+    wrapped[key] = typeof value === 'function' ? value.bind(target) : value;
+  }
+
+  for (const method of SCORING_METHODS) {
+    if (typeof target[method] !== 'function') continue;
+    wrapped[method] = async (...args) => {
+      const t0 = Date.now();
+      await limiter();
+      const waited = Date.now() - t0;
+      if (waited > 0) onThrottle?.(waited);
+      return target[method](...args);
+    };
+  }
+
+  return wrapped;
+}
+
+/**
+ * A sliding-window limiter. Resolves immediately while under the limit;
+ * otherwise waits until the oldest request in the window ages out.
+ */
+export function rateLimiter(maxPerSecond, hooks = {}) {
+  const windowMs = 1000;
+  /** @type {number[]} timestamps of recent requests, oldest first */
+  const recent = [];
+
+  return async function acquire() {
+    for (;;) {
+      const now = Date.now();
+
+      // Drop anything that has aged out of the window.
+      while (recent.length > 0 && now - recent[0] >= windowMs) recent.shift();
+
+      if (recent.length < maxPerSecond) {
+        recent.push(now);
+        return;
+      }
+
+      const waitMs = windowMs - (now - recent[0]);
+      hooks.onThrottle?.(waitMs);
+      await delay(waitMs, hooks.signal);
+    }
+  };
+}
+
+function delay(ms, signal) {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve) => {
+    const timer = setTimeout(finish, ms);
+    function finish() {
+      clearTimeout(timer);
+      signal?.removeEventListener?.('abort', finish);
+      resolve();
+    }
+    // An aborted run should stop waiting on a rate limit immediately; the
+    // scenario's own abort check is what ends the loop.
+    signal?.addEventListener?.('abort', finish, { once: true });
+  });
+}
+
+/** Own and inherited enumerable keys, so adapters built either way survive. */
+function allKeys(target) {
+  const keys = new Set();
+  for (let obj = target; obj && obj !== Object.prototype; obj = Object.getPrototypeOf(obj)) {
+    for (const key of Object.getOwnPropertyNames(obj)) {
+      if (key !== 'constructor') keys.add(key);
+    }
+  }
+  return keys;
+}

package/types/adapters/http.d.ts

@@ -0,0 +1,6 @@
+export function httpAdapter(config: any): {
+    scoreLogin(payload: any): Promise<any>;
+    scoreWithdrawal(payload: any): Promise<any>;
+    scoreAction(payload: any): Promise<any>;
+    reportEvent(eventType: any, data: any): Promise<void>;
+};

package/types/adapters/index.d.ts

@@ -0,0 +1,3 @@
+export { httpAdapter } from "./http.js";
+export { mockAdapter } from "./mock.js";
+export { loggingAdapter } from "./logging.js";

package/types/adapters/logging.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Logging adapter — logs payloads to a logger without sending anywhere.
+ *
+ * Used to inspect what a scenario produces before pointing at a real target.
+ * Returns ALLOW for every call by default.
+ *
+ * @example
+ *   import { loggingAdapter } from 'fraud-sim/adapters';
+ *
+ *   const target = loggingAdapter();
+ *   await run('credential-stuffing', { target, options: { ... } });
+ *   // → All payloads are printed to stdout; nothing is sent to the network
+ */
+export function loggingAdapter(config?: {}): {
+    scoreLogin(payload: any): Promise<any>;
+    scoreWithdrawal(payload: any): Promise<any>;
+    scoreAction(payload: any): Promise<any>;
+    reportEvent(eventType: any, data: any): Promise<void>;
+};

package/types/adapters/mock.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Mock adapter — returns predetermined responses in sequence.
+ *
+ * Primary use case: unit testing scenarios. Lets a test verify that a
+ * scenario behaves correctly given a known sequence of target responses.
+ *
+ * @example
+ *   const target = mockAdapter({
+ *     scoreLogin: [
+ *       { decision: 'ALLOW' },
+ *       { decision: 'STEP_UP', riskScore: 0.5 },
+ *       { decision: 'BLOCK',   riskScore: 0.9, reasons: [{ code: 'NEW_DEVICE' }] },
+ *     ],
+ *   });
+ *
+ * After the queue is exhausted, the adapter returns the last response repeatedly,
+ * unless `defaultResponse` is provided.
+ */
+export function mockAdapter(config?: {}): {
+    scoreLogin(payload: any): Promise<any>;
+    scoreWithdrawal(payload: any): Promise<any>;
+    scoreAction(payload: any): Promise<any>;
+    reportEvent(eventType: any, data: any): Promise<void>;
+    /**
+     * Test helper: return all payloads received by a given endpoint.
+     */
+    _calls(name: any): any;
+    /**
+     * Test helper: return all reported events.
+     */
+    _reportedEvents(): any[];
+};