fraud-sim 0.2.0

package/src/adapters/mock.js

@@ -0,0 +1,80 @@
+/**
+ * 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 = {}) {
+  const state = {
+    scoreLogin: queueFrom(config.scoreLogin),
+    scoreWithdrawal: queueFrom(config.scoreWithdrawal),
+    scoreAction: queueFrom(config.scoreAction),
+    reportedEvents: [],
+  };
+
+  const defaultResponse = config.defaultResponse ?? {
+    decision: 'ALLOW',
+    riskScore: 0,
+    reasons: [],
+  };
+
+  function dequeue(name) {
+    const queue = state[name];
+    if (queue.length === 0) return defaultResponse;
+    return queue.length === 1 ? queue[0] : queue.shift();
+  }
+
+  return {
+    async scoreLogin(payload) {
+      state.scoreLogin._calls.push(payload);
+      return dequeue('scoreLogin');
+    },
+
+    async scoreWithdrawal(payload) {
+      state.scoreWithdrawal._calls.push(payload);
+      return dequeue('scoreWithdrawal');
+    },
+
+    async scoreAction(payload) {
+      state.scoreAction._calls.push(payload);
+      return dequeue('scoreAction');
+    },
+
+    async reportEvent(eventType, data) {
+      state.reportedEvents.push({ type: eventType, data });
+    },
+
+    /**
+     * Test helper: return all payloads received by a given endpoint.
+     */
+    _calls(name) {
+      return state[name]?._calls ?? [];
+    },
+
+    /**
+     * Test helper: return all reported events.
+     */
+    _reportedEvents() {
+      return state.reportedEvents;
+    },
+  };
+}
+
+function queueFrom(responses) {
+  const arr = Array.isArray(responses) ? [...responses] : [];
+  arr._calls = [];
+  return arr;
+}

package/src/index.js

@@ -0,0 +1,155 @@
+/**
+ * fraud-sim — public API surface
+ *
+ * Realistic synthetic attack traffic for testing fintech fraud detection systems.
+ *
+ * Usage:
+ *   import { run, runSuite, listScenarios, registerScenario } from 'fraud-sim';
+ *   import { httpAdapter } from 'fraud-sim/adapters';
+ *
+ *   const report = await run('credential-stuffing', { target, options: {...} });
+ */
+
+import { Runner } from './runner.js';
+import { scenarios as builtInScenarios } from './scenarios/index.js';
+
+// Module-level registry — extensible via registerScenario()
+const registry = new Map();
+for (const scenario of builtInScenarios) {
+  registry.set(scenario.id, scenario);
+}
+
+/**
+ * Run a single scenario against a target.
+ *
+ * @param {string} scenarioId - The ID of a registered scenario
+ * @param {object} config
+ * @param {object} config.target - A TargetAdapter
+ * @param {object} [config.options] - Scenario-specific options (merged with defaults)
+ * @param {function} [config.onEvent] - Event callback (event) => void
+ * @param {AbortSignal} [config.signal] - For cancellation
+ * @returns {Promise<ScenarioReport>}
+ */
+export async function run(scenarioId, config = {}) {
+  const scenario = registry.get(scenarioId);
+  if (!scenario) {
+    const available = [...registry.keys()].join(', ');
+    throw new Error(`Unknown scenario: "${scenarioId}". Available: ${available}`);
+  }
+
+  if (!config.target) {
+    throw new Error('A target adapter is required. Use httpAdapter() or mockAdapter().');
+  }
+
+  const runner = new Runner();
+  return runner.run(scenario, config);
+}
+
+/**
+ * Run a suite of scenarios as a benchmark.
+ *
+ * v0.1 — runs sequentially. v0.4 will add parallel execution and full reporting.
+ *
+ * @param {object} config
+ * @param {string} config.name - Human-readable suite name
+ * @param {Array<{id: string, options?: object}>} config.scenarios
+ * @param {object} config.target
+ * @param {function} [config.onEvent]
+ * @returns {Promise<SuiteReport>}
+ */
+export async function runSuite(config = {}) {
+  if (!config.scenarios || config.scenarios.length === 0) {
+    throw new Error('A suite requires at least one scenario.');
+  }
+
+  const startedAt = new Date().toISOString();
+  const scenarioReports = [];
+
+  for (const entry of config.scenarios) {
+    const report = await run(entry.id, {
+      target: config.target,
+      options: entry.options ?? {},
+      onEvent: config.onEvent,
+    });
+    scenarioReports.push(report);
+  }
+
+  return {
+    suiteName: config.name ?? 'unnamed-suite',
+    startedAt,
+    completedAt: new Date().toISOString(),
+    scenarioReports,
+    aggregate: aggregateReports(scenarioReports),
+  };
+}
+
+/**
+ * Returns metadata for all registered scenarios.
+ * @returns {Array<ScenarioMetadata>}
+ */
+export function listScenarios() {
+  return [...registry.values()].map((s) => ({
+    id: s.id,
+    name: s.name,
+    description: s.description,
+    defaultOptions: s.defaultOptions,
+  }));
+}
+
+/**
+ * Register a custom scenario. Useful for users extending the library
+ * or for testing internal scenarios in isolation.
+ *
+ * @param {Scenario} scenario
+ */
+export function registerScenario(scenario) {
+  validateScenario(scenario);
+  registry.set(scenario.id, scenario);
+}
+
+/**
+ * Remove a scenario from the registry. Primarily for testing.
+ * @param {string} scenarioId
+ */
+export function unregisterScenario(scenarioId) {
+  registry.delete(scenarioId);
+}
+
+// ── internals ───────────────────────────────────────────────────────────
+
+function validateScenario(scenario) {
+  if (!scenario || typeof scenario !== 'object') {
+    throw new Error('Scenario must be an object.');
+  }
+  for (const field of ['id', 'name', 'description', 'run']) {
+    if (!scenario[field]) {
+      throw new Error(`Scenario is missing required field: "${field}".`);
+    }
+  }
+  if (typeof scenario.run !== 'function') {
+    throw new Error('Scenario.run must be a function.');
+  }
+  if (scenario.defaultOptions && typeof scenario.defaultOptions !== 'object') {
+    throw new Error('Scenario.defaultOptions must be an object.');
+  }
+}
+
+function aggregateReports(reports) {
+  const totals = {
+    attempts: 0,
+    blocked: 0,
+    stepUp: 0,
+    allowed: 0,
+  };
+  for (const r of reports) {
+    totals.attempts += r.attempts ?? 0;
+    totals.blocked += r.blocked ?? 0;
+    totals.stepUp += r.stepUp ?? 0;
+    totals.allowed += r.allowed ?? 0;
+  }
+  return {
+    ...totals,
+    blockRate: totals.attempts > 0 ? totals.blocked / totals.attempts : 0,
+    stepUpRate: totals.attempts > 0 ? totals.stepUp / totals.attempts : 0,
+  };
+}

package/src/llm/anthropic.js

@@ -0,0 +1,129 @@
+/**
+ * Anthropic-backed LLM provider.
+ *
+ * Same contract as the OpenAI provider (src/llm/openai.js) but built on the
+ * Anthropic Messages API. Owns prompt construction and response parsing, falls
+ * back to a randomised strategy on any error, and never throws.
+ *
+ * @example
+ *   import { anthropic } from 'fraud-sim/llm';
+ *
+ *   const provider = anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+ *   await run('adaptive-attacker', { target, llm: provider, options: { targetUserId: 'u1' } });
+ */
+
+import { deterministic } from './deterministic.js';
+
+const ENDPOINT = 'https://api.anthropic.com/v1/messages';
+const API_VERSION = '2023-06-01';
+const TIMEOUT_MS = 10000;
+const DEFAULT_MAX_TOKENS = 1024;
+
+const SYSTEM_PROMPT = `You are simulating a fraud actor probing a fintech security system.
+You can only observe API responses — you cannot see the rules.
+Your goal: based on the attack history, decide what to change for the next attempt.
+Respond ONLY with valid JSON: { "reasoning": "...", "parameters": {...} }`;
+
+/**
+ * @param {object} config
+ * @param {string} config.apiKey - Anthropic API key.
+ * @param {string} [config.model='claude-sonnet-5']
+ * @param {number} [config.maxTokens=1024]
+ * @param {function} [config.fetch] - Injectable fetch, for testing.
+ * @returns {{ name: string, generateStrategy: function }}
+ */
+export function anthropic(config = {}) {
+  const { apiKey, model = 'claude-sonnet-5', maxTokens = DEFAULT_MAX_TOKENS } = config;
+  const fetchImpl = config.fetch ?? globalThis.fetch;
+  const fallback = deterministic({ seed: config.seed ?? 1 });
+
+  return {
+    name: 'anthropic',
+
+    async generateStrategy(input) {
+      const { scenarioId, history = [], round = 1, maxRound = 10 } = input ?? {};
+
+      const userMessage = `Scenario: ${scenarioId}
+Round: ${round} of ${maxRound}
+History: ${JSON.stringify(history)}
+
+What is your next strategy?`;
+
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+
+      try {
+        const res = await fetchImpl(ENDPOINT, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'x-api-key': apiKey,
+            'anthropic-version': API_VERSION,
+          },
+          body: JSON.stringify({
+            model,
+            max_tokens: maxTokens,
+            system: SYSTEM_PROMPT,
+            messages: [{ role: 'user', content: userMessage }],
+          }),
+          signal: controller.signal,
+        });
+
+        if (!res.ok) {
+          return fallback.generateStrategy(input);
+        }
+
+        const body = await res.json();
+        // Messages API returns content as an array of blocks; we want the text.
+        const content = extractText(body);
+        const parsed = parseStrategy(content);
+        if (!parsed) {
+          return fallback.generateStrategy(input);
+        }
+        return parsed;
+      } catch {
+        return fallback.generateStrategy(input);
+      } finally {
+        clearTimeout(timer);
+      }
+    },
+  };
+}
+
+function extractText(body) {
+  const blocks = body?.content;
+  if (!Array.isArray(blocks)) return null;
+  const textBlock = blocks.find((b) => b?.type === 'text' && typeof b.text === 'string');
+  return textBlock ? textBlock.text : null;
+}
+
+/**
+ * Parse a strategy from raw model text. Tolerates prose around the JSON by
+ * extracting the first {...} block if a bare parse fails.
+ * @returns {{ reasoning: string, parameters: object } | null}
+ */
+function parseStrategy(content) {
+  if (typeof content !== 'string') return null;
+  const obj = tryParse(content) ?? tryParse(extractJsonObject(content));
+  if (!obj || typeof obj !== 'object') return null;
+  const reasoning = typeof obj.reasoning === 'string' ? obj.reasoning : '';
+  const parameters =
+    obj.parameters && typeof obj.parameters === 'object' ? obj.parameters : {};
+  return { reasoning, parameters };
+}
+
+function tryParse(str) {
+  if (typeof str !== 'string') return null;
+  try {
+    return JSON.parse(str);
+  } catch {
+    return null;
+  }
+}
+
+function extractJsonObject(str) {
+  const start = str.indexOf('{');
+  const end = str.lastIndexOf('}');
+  if (start === -1 || end === -1 || end <= start) return null;
+  return str.slice(start, end + 1);
+}

package/src/llm/deterministic.js

@@ -0,0 +1,125 @@
+/**
+ * Deterministic LLM provider — a no-API attacker heuristic.
+ *
+ * fraud-sim's headline feature is an attacker that adapts based on what gets
+ * blocked. The real thing calls an LLM; this is the fallback for when there's
+ * no API key — CI, air-gapped machines, contributors without funds. It plays
+ * the same role in the interface without any network calls.
+ *
+ * The "logic" is simple: look at why the last attempt was blocked and change
+ * the thing that most likely caused it. It's seeded so a given history always
+ * produces the same strategy — reproducibility matters more than cleverness.
+ *
+ * @example
+ *   import { deterministic } from 'fraud-sim/llm';
+ *
+ *   const provider = deterministic({ seed: 42 });
+ *   const strategy = await provider.generateStrategy({
+ *     scenarioId: 'adaptive-attacker',
+ *     history: [{ round: 1, decision: 'BLOCK', reasons: [{ code: 'IP_REPUTATION' }] }],
+ *     round: 2,
+ *     maxRound: 10,
+ *   });
+ *   // → { reasoning: '...', parameters: { ip: '...', ... } }
+ */
+
+import { DeterministicRng } from '../utils/rng.js';
+
+// Substrings we look for in block-reason codes to decide what to change.
+// Matched case-insensitively against each reason's `code`.
+const IP_SIGNALS = ['IP', 'GEO', 'PROXY', 'VPN', 'SUBNET'];
+const DEVICE_SIGNALS = ['DEVICE', 'FINGERPRINT', 'SESSION'];
+const VELOCITY_SIGNALS = ['VELOCITY', 'RATE', 'FREQUENCY', 'BURST'];
+
+const COMMON_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 (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 14; Pixel 8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Mobile Safari/537.36',
+];
+
+/**
+ * @param {object} [config]
+ * @param {number} [config.seed=1] - Seed for reproducible strategies.
+ * @returns {{ name: string, generateStrategy: function }}
+ */
+export function deterministic(config = {}) {
+  const seed = config.seed ?? 1;
+
+  return {
+    name: 'deterministic',
+
+    /**
+     * @param {object} input
+     * @param {string} input.scenarioId
+     * @param {Array} input.history - Prior rounds: { round, parameters?, decision, reasons? }
+     * @param {number} input.round
+     * @param {number} input.maxRound
+     * @returns {Promise<{ reasoning: string, parameters: object }>}
+     */
+    async generateStrategy({ history = [], round = 1 } = {}) {
+      // Seed off (seed, round) so each round is deterministic yet distinct —
+      // otherwise "randomise everything" would return the same values forever.
+      const rng = new DeterministicRng(seed + round);
+
+      const lastAttempt = history.length > 0 ? history[history.length - 1] : null;
+      const reasonCodes = extractReasonCodes(lastAttempt);
+      const category = classify(reasonCodes);
+
+      const parameters = {
+        ip: rng.ip(),
+        deviceFingerprint: rng.alphanumeric(32),
+        userAgent: rng.pick(COMMON_USER_AGENTS),
+        delayMs: rng.int(500, 3000),
+      };
+
+      let reasoning;
+      switch (category) {
+        case 'ip':
+          reasoning = `Last attempt was blocked on an IP-related reason (${reasonCodes.join(', ')}). Rotating to a fresh IP address.`;
+          break;
+        case 'device':
+          reasoning = `Last attempt was blocked on a device-related reason (${reasonCodes.join(', ')}). Rotating the device fingerprint and user agent.`;
+          break;
+        case 'velocity':
+          // Velocity blocks: slow down AND change IP to dodge rate limits.
+          parameters.delayMs = rng.int(5000, 15000);
+          reasoning = `Last attempt was blocked on a velocity-related reason (${reasonCodes.join(', ')}). Waiting longer between attempts and changing IP.`;
+          break;
+        case 'none':
+          reasoning =
+            round === 1
+              ? 'First round — establishing a residential-looking baseline before adapting.'
+              : 'No clear block pattern to react to. Randomising all attributes to probe for gaps.';
+          break;
+        default:
+          reasoning = `Blocked for an unrecognised reason (${reasonCodes.join(', ')}). Randomising all attributes.`;
+      }
+
+      return { reasoning, parameters };
+    },
+  };
+}
+
+function extractReasonCodes(attempt) {
+  if (!attempt || !Array.isArray(attempt.reasons)) return [];
+  return attempt.reasons
+    .map((r) => (typeof r === 'string' ? r : r?.code))
+    .filter((code) => typeof code === 'string');
+}
+
+function classify(reasonCodes) {
+  if (reasonCodes.length === 0) return 'none';
+  const matches = (signals) =>
+    reasonCodes.some((code) => {
+      const upper = code.toUpperCase();
+      return signals.some((sig) => upper.includes(sig));
+    });
+
+  // Velocity and device are checked before IP because velocity codes can also
+  // mention IP (e.g. IP_VELOCITY) and the velocity response is the stronger one.
+  if (matches(VELOCITY_SIGNALS)) return 'velocity';
+  if (matches(DEVICE_SIGNALS)) return 'device';
+  if (matches(IP_SIGNALS)) return 'ip';
+  return 'unknown';
+}

package/src/llm/index.js

@@ -0,0 +1,19 @@
+/**
+ * LLM providers — pluggable strategy generators for the adaptive attacker.
+ *
+ * All providers share one interface:
+ *   {
+ *     name: string,
+ *     async generateStrategy({ scenarioId, history, round, maxRound }) => {
+ *       return { reasoning: string, parameters: object };
+ *     }
+ *   }
+ *
+ * `deterministic` needs no API and is the fallback used when no `llm` is passed
+ * to a scenario. `openai` and `anthropic` call their respective APIs and fall
+ * back to randomised behaviour on any error.
+ */
+
+export { deterministic } from './deterministic.js';
+export { openai } from './openai.js';
+export { anthropic } from './anthropic.js';

package/src/llm/openai.js

@@ -0,0 +1,112 @@
+/**
+ * OpenAI-backed LLM provider.
+ *
+ * Uses the OpenAI Chat Completions API to drive the adaptive attacker. The
+ * provider owns prompt construction and response parsing. It is defensive by
+ * design: any failure — network error, timeout, malformed JSON — falls back to
+ * a randomised strategy rather than crashing the scenario. It never throws.
+ *
+ * @example
+ *   import { openai } from 'fraud-sim/llm';
+ *
+ *   const provider = openai({ apiKey: process.env.OPENAI_API_KEY });
+ *   await run('adaptive-attacker', { target, llm: provider, options: { targetUserId: 'u1' } });
+ */
+
+import { deterministic } from './deterministic.js';
+
+const ENDPOINT = 'https://api.openai.com/v1/chat/completions';
+const TIMEOUT_MS = 10000;
+
+const SYSTEM_PROMPT = `You are simulating a fraud actor probing a fintech security system.
+You can only observe API responses — you cannot see the rules.
+Your goal: based on the attack history, decide what to change for the next attempt.
+Respond ONLY with valid JSON: { "reasoning": "...", "parameters": {...} }`;
+
+/**
+ * @param {object} config
+ * @param {string} config.apiKey - OpenAI API key.
+ * @param {string} [config.model='gpt-4o']
+ * @param {number} [config.temperature=0.7]
+ * @param {function} [config.fetch] - Injectable fetch, for testing.
+ * @returns {{ name: string, generateStrategy: function }}
+ */
+export function openai(config = {}) {
+  const { apiKey, model = 'gpt-4o', temperature = 0.7 } = config;
+  const fetchImpl = config.fetch ?? globalThis.fetch;
+  // A seeded fallback so error paths are still deterministic.
+  const fallback = deterministic({ seed: config.seed ?? 1 });
+
+  return {
+    name: 'openai',
+
+    async generateStrategy(input) {
+      const { scenarioId, history = [], round = 1, maxRound = 10 } = input ?? {};
+
+      const userMessage = `Scenario: ${scenarioId}
+Round: ${round} of ${maxRound}
+History: ${JSON.stringify(history)}
+
+What is your next strategy?`;
+
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+
+      try {
+        const res = await fetchImpl(ENDPOINT, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${apiKey}`,
+          },
+          body: JSON.stringify({
+            model,
+            temperature,
+            messages: [
+              { role: 'system', content: SYSTEM_PROMPT },
+              { role: 'user', content: userMessage },
+            ],
+            response_format: { type: 'json_object' },
+          }),
+          signal: controller.signal,
+        });
+
+        if (!res.ok) {
+          return fallback.generateStrategy(input);
+        }
+
+        const body = await res.json();
+        const content = body?.choices?.[0]?.message?.content;
+        const parsed = parseStrategy(content);
+        if (!parsed) {
+          return fallback.generateStrategy(input);
+        }
+        return parsed;
+      } catch {
+        // Network error, timeout/abort, or JSON body error — fall back.
+        return fallback.generateStrategy(input);
+      } finally {
+        clearTimeout(timer);
+      }
+    },
+  };
+}
+
+/**
+ * Parse and validate a strategy from raw model output.
+ * @returns {{ reasoning: string, parameters: object } | null}
+ */
+function parseStrategy(content) {
+  if (typeof content !== 'string') return null;
+  let obj;
+  try {
+    obj = JSON.parse(content);
+  } catch {
+    return null;
+  }
+  if (!obj || typeof obj !== 'object') return null;
+  const reasoning = typeof obj.reasoning === 'string' ? obj.reasoning : '';
+  const parameters =
+    obj.parameters && typeof obj.parameters === 'object' ? obj.parameters : {};
+  return { reasoning, parameters };
+}