fraud-sim 0.2.0 → 0.5.0

package/src/adapters/http.js

@@ -3,8 +3,8 @@
  *
  * Configurable for any target's response shape via the `responseMap` function.
  * This is the key flexibility point that keeps fraud-sim target-agnostic:
- * a user testing against Stripe Radar writes a different responseMap than
- * one testing against an in-house system.
+ * a target that answers `{ action: 'deny' }` writes a different responseMap
+ * than one that answers `{ decision: 'BLOCK' }`.
  *
  * @example
  *   const target = httpAdapter({
@@ -20,7 +20,17 @@
  *       reasons:   raw.reasons,
  *       raw,
  *     }),
+ *     // Only if your API signals a genuine block with an HTTP status:
+ *     blockOnStatus: [403],
  *   });
+ *
+ * ── On HTTP failures ──────────────────────────────────────────────────
+ * A non-2xx response is treated as an infrastructure error, NOT as a block,
+ * unless its status is listed in `blockOnStatus`. This matters: if a 429 or a
+ * 503 counted as a BLOCK, then rate-limiting the simulator or crashing the
+ * target under load would *raise* its measured block rate. A benchmark that
+ * rewards a target for falling over is measuring the opposite of what it
+ * claims, so errors are reported as errors and excluded from the block rate.
  */
 
 const DEFAULT_ENDPOINTS = {
@@ -52,6 +62,10 @@ export function httpAdapter(config) {
   const endpoints = { ...DEFAULT_ENDPOINTS, ...(config.endpoints ?? {}) };
   const responseMap = config.responseMap ?? DEFAULT_RESPONSE_MAP;
   const timeoutMs = config.timeoutMs ?? 5000;
+  // Statuses this specific API uses to signal a real block. Empty by default:
+  // no standard HTTP status means "the fraud engine decided to block", and
+  // guessing is how an outage gets scored as a successful defence.
+  const blockOnStatus = new Set(config.blockOnStatus ?? []);
   const fetchImpl = config.fetch ?? globalThis.fetch;
 
   if (!fetchImpl) {
@@ -76,14 +90,29 @@ export function httpAdapter(config) {
       const raw = await res.json().catch(() => ({}));
 
       if (!res.ok) {
-        // Non-2xx response — fraud detection systems often return 4xx/5xx
-        // for hard blocks. We surface this in the response, not as an error.
+        // Only statuses the caller has explicitly declared as blocks count as
+        // blocks. Everything else is infrastructure trouble and is reported as
+        // such — see the note at the top of this file.
+        if (blockOnStatus.has(res.status)) {
+          return {
+            decision: raw.decision ?? 'BLOCK',
+            riskScore: raw.risk_score ?? 1.0,
+            reasons: raw.reasons ?? [{ code: 'HTTP_BLOCK', label: `HTTP ${res.status}` }],
+            raw,
+            httpStatus: res.status,
+          };
+        }
+
         return {
-          decision: raw.decision ?? 'BLOCK',
-          riskScore: raw.risk_score ?? 1.0,
-          reasons: raw.reasons ?? [{ code: 'HTTP_ERROR', label: `HTTP ${res.status}` }],
+          decision: 'ERROR',
+          riskScore: null,
+          reasons: [{ code: errorCodeFor(res.status), label: `HTTP ${res.status}` }],
           raw,
           httpStatus: res.status,
+          // Scenarios and the runner key off this to keep infrastructure
+          // failures out of the block rate.
+          infraError: true,
+          retryAfter: res.headers?.get?.('retry-after') ?? null,
         };
       }
 
@@ -97,6 +126,7 @@ export function httpAdapter(config) {
         riskScore: null,
         reasons: [{ code: 'NETWORK_ERROR', label: err.message }],
         raw: { error: err.message },
+        infraError: true,
       };
     } finally {
       clearTimeout(timer);
@@ -130,3 +160,15 @@ export function httpAdapter(config) {
     },
   };
 }
+
+/**
+ * Name the failure so a report says why a run is unreliable, not just that it
+ * is. Rate limiting and server errors have very different remedies.
+ */
+function errorCodeFor(status) {
+  if (status === 429) return 'RATE_LIMITED';
+  if (status >= 500) return 'SERVER_ERROR';
+  if (status === 401 || status === 403) return 'AUTH_ERROR';
+  if (status === 404) return 'ENDPOINT_NOT_FOUND';
+  return 'HTTP_ERROR';
+}

package/src/index.js

@@ -10,8 +10,33 @@
  *   const report = await run('credential-stuffing', { target, options: {...} });
  */
 
-import { Runner } from './runner.js';
+/**
+ * @typedef {import('./types.js').Scenario} Scenario
+ * @typedef {import('./types.js').ScenarioMetadata} ScenarioMetadata
+ * @typedef {import('./types.js').ScenarioReport} ScenarioReport
+ * @typedef {import('./types.js').SuiteReport} SuiteReport
+ * @typedef {import('./types.js').TargetAdapter} TargetAdapter
+ */
+
+import { Runner, DEFAULT_MAX_REQUESTS_PER_SECOND } from './runner.js';
 import { scenarios as builtInScenarios } from './scenarios/index.js';
+import { rateLimiter } from './utils/throttle.js';
+import { legitimateTotalsFor } from './reporting/aggregate.js';
+
+/**
+ * The fixed attacker IP pool, with declared geolocation and reputation.
+ *
+ * Re-exported here so a system under test can pre-warm its IP-intelligence
+ * cache before a run. Most fraud engines resolve IP intel asynchronously and
+ * fall back to neutral values on a cache miss — in a short simulation every IP
+ * is new, so proxy, abuse-score, and geo rules never fire and the run
+ * understates what the defence catches. Seeding from this pool removes that
+ * blind spot, along with any dependency on a third-party lookup during a run.
+ *
+ * Used by scenarios when `options.ipPersona` is anything other than 'random'.
+ */
+export { DEMO_IP_POOL, demoIpPool, pickDemoIp } from './utils/random.js';
+export { LOCALES, localeIds, resolveLocale, DEFAULT_LOCALE } from './locales/index.js';
 
 // Module-level registry — extensible via registerScenario()
 const registry = new Map();
@@ -24,10 +49,15 @@ for (const scenario of builtInScenarios) {
  *
  * @param {string} scenarioId - The ID of a registered scenario
  * @param {object} config
- * @param {object} config.target - A TargetAdapter
+ * @param {TargetAdapter} 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
+ * @param {number} [config.seed] - Seed the run's randomness so it replays
+ *   identically. Controls every generated value (IPs, devices, amounts,
+ *   ordering) but not wall-clock timestamps.
+ * @param {number} [config.maxRequestsPerSecond=25] - Ceiling on outbound
+ *   requests. `Infinity` disables it.
  * @returns {Promise<ScenarioReport>}
  */
 export async function run(scenarioId, config = {}) {
@@ -48,13 +78,19 @@ export async function run(scenarioId, 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 {TargetAdapter} config.target
  * @param {function} [config.onEvent]
+ * @param {AbortSignal} [config.signal]
+ * @param {number} [config.seed] - Seeds the suite. Each scenario gets a
+ *   distinct derived seed, so the suite replays as a whole without every
+ *   scenario drawing the same values.
+ * @param {number} [config.maxRequestsPerSecond=25] - Shared across the whole
+ *   suite, including when scenarios run concurrently.
+ * @param {number} [config.concurrency=1] - How many scenarios run at once.
+ *   See the note below before raising it.
  * @returns {Promise<SuiteReport>}
  */
 export async function runSuite(config = {}) {
@@ -62,27 +98,85 @@ export async function runSuite(config = {}) {
     throw new Error('A suite requires at least one scenario.');
   }
 
+  const concurrency = config.concurrency ?? 1;
+  if (!Number.isInteger(concurrency) || concurrency < 1) {
+    throw new Error(`concurrency must be a positive integer, received: ${config.concurrency}`);
+  }
+
   const startedAt = new Date().toISOString();
-  const scenarioReports = [];
+  const maxRequestsPerSecond =
+    config.maxRequestsPerSecond ?? DEFAULT_MAX_REQUESTS_PER_SECOND;
+
+  // One limiter for the whole suite. A limiter per run would let the effective
+  // request ceiling scale with the concurrency — the opposite of a ceiling.
+  const limiter = Number.isFinite(maxRequestsPerSecond)
+    ? rateLimiter(maxRequestsPerSecond, { signal: config.signal })
+    : null;
 
-  for (const entry of config.scenarios) {
-    const report = await run(entry.id, {
+  const runOne = (entry, index) =>
+    run(entry.id, {
       target: config.target,
       options: entry.options ?? {},
       onEvent: config.onEvent,
+      signal: config.signal,
+      llm: entry.llm ?? config.llm,
+      ...(config.seed != null ? { seed: config.seed + index } : {}),
+      ...(config.locale != null ? { locale: config.locale } : {}),
+      maxRequestsPerSecond,
+      ...(limiter ? { limiter } : {}),
     });
-    scenarioReports.push(report);
-  }
+
+  const scenarioReports =
+    concurrency === 1
+      ? await runSequentially(config.scenarios, runOne)
+      : await runPooled(config.scenarios, runOne, concurrency);
 
   return {
     suiteName: config.name ?? 'unnamed-suite',
     startedAt,
     completedAt: new Date().toISOString(),
+    concurrency,
     scenarioReports,
     aggregate: aggregateReports(scenarioReports),
   };
 }
 
+async function runSequentially(entries, runOne) {
+  const out = [];
+  for (const [index, entry] of entries.entries()) {
+    out.push(await runOne(entry, index));
+  }
+  return out;
+}
+
+/**
+ * Run up to `limit` scenarios at once, preserving input order in the results.
+ *
+ * ── Before raising concurrency ────────────────────────────────────────
+ * Scenarios sharing a target interleave their traffic, and most fraud engines
+ * keep per-user and per-IP state. Two scenarios touching the same account at
+ * once will influence each other's decisions, so a parallel suite measures a
+ * *combined* attack rather than each attack independently. That is realistic —
+ * real systems face concurrent attackers — but it is a different question from
+ * "does this scenario get caught", and results will not match a sequential run.
+ * Use distinct users per scenario if you want both speed and isolation.
+ */
+async function runPooled(entries, runOne, limit) {
+  const results = new Array(entries.length);
+  let cursor = 0;
+
+  const workers = Array.from({ length: Math.min(limit, entries.length) }, async () => {
+    for (;;) {
+      const index = cursor++;
+      if (index >= entries.length) return;
+      results[index] = await runOne(entries[index], index);
+    }
+  });
+
+  await Promise.all(workers);
+  return results;
+}
+
 /**
  * Returns metadata for all registered scenarios.
  * @returns {Array<ScenarioMetadata>}
@@ -92,6 +186,7 @@ export function listScenarios() {
     id: s.id,
     name: s.name,
     description: s.description,
+    traffic: s.traffic ?? 'attack',
     defaultOptions: s.defaultOptions,
   }));
 }
@@ -132,24 +227,42 @@ function validateScenario(scenario) {
   if (scenario.defaultOptions && typeof scenario.defaultOptions !== 'object') {
     throw new Error('Scenario.defaultOptions must be an object.');
   }
+  if (scenario.traffic != null && !['attack', 'legitimate'].includes(scenario.traffic)) {
+    throw new Error(`Scenario.traffic must be "attack" or "legitimate", received: "${scenario.traffic}".`);
+  }
 }
 
 function aggregateReports(reports) {
+  // Attack and legitimate traffic answer opposite questions — a block is a
+  // catch on one and a false positive on the other — so they are never summed.
+  const attacks = reports.filter((r) => r.traffic !== 'legitimate');
+
   const totals = {
     attempts: 0,
     blocked: 0,
     stepUp: 0,
     allowed: 0,
+    errors: 0,
   };
-  for (const r of reports) {
+  for (const r of attacks) {
     totals.attempts += r.attempts ?? 0;
     totals.blocked += r.blocked ?? 0;
     totals.stepUp += r.stepUp ?? 0;
     totals.allowed += r.allowed ?? 0;
+    totals.errors += r.errors ?? 0;
   }
+
+  // Same rule as a single run: attempts that never received a decision are not
+  // evidence about the defence, so they are excluded from the rates rather than
+  // being credited to it. See Runner.run.
+  const scoredAttempts = Math.max(0, totals.attempts - totals.errors);
+
   return {
     ...totals,
-    blockRate: totals.attempts > 0 ? totals.blocked / totals.attempts : 0,
-    stepUpRate: totals.attempts > 0 ? totals.stepUp / totals.attempts : 0,
+    scoredAttempts,
+    blockRate: scoredAttempts > 0 ? totals.blocked / scoredAttempts : 0,
+    stepUpRate: scoredAttempts > 0 ? totals.stepUp / scoredAttempts : 0,
+    errorRate: totals.attempts > 0 ? totals.errors / totals.attempts : 0,
+    legitimate: legitimateTotalsFor(reports),
   };
 }

package/src/llm/anthropic.js

@@ -22,6 +22,13 @@ 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.
+Each history entry shows the exact parameters sent that round and the decision returned.
+You control these parameters:
+  "ip"                - source IPv4 address
+  "userAgent"         - browser user agent string
+  "deviceFingerprint" - device fingerprint; reuse one from history to replay that device
+  "delayMs"           - how long you would wait before the next attempt
+Omit a parameter to keep its previous value.
 Respond ONLY with valid JSON: { "reasoning": "...", "parameters": {...} }`;
 
 /**

package/src/llm/deterministic.js

@@ -66,6 +66,11 @@ export function deterministic(config = {}) {
       const reasonCodes = extractReasonCodes(lastAttempt);
       const category = classify(reasonCodes);
 
+      // A step-up is not a block, and saying so matters: the reasoning is read
+      // by a human in a report, and an attacker that mis-describes what just
+      // happened to it does not look like it is reasoning at all.
+      const outcome = lastAttempt?.decision === 'STEP_UP' ? 'challenged' : 'blocked';
+
       const parameters = {
         ip: rng.ip(),
         deviceFingerprint: rng.alphanumeric(32),
@@ -76,15 +81,15 @@ export function deterministic(config = {}) {
       let reasoning;
       switch (category) {
         case 'ip':
-          reasoning = `Last attempt was blocked on an IP-related reason (${reasonCodes.join(', ')}). Rotating to a fresh IP address.`;
+          reasoning = `Last attempt was ${outcome} 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.`;
+          reasoning = `Last attempt was ${outcome} 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.`;
+          reasoning = `Last attempt was ${outcome} on a velocity-related reason (${reasonCodes.join(', ')}). Waiting longer between attempts and changing IP.`;
           break;
         case 'none':
           reasoning =
@@ -93,7 +98,7 @@ export function deterministic(config = {}) {
               : '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.`;
+          reasoning = `${outcome === 'challenged' ? 'Challenged' : 'Blocked'} for an unrecognised reason (${reasonCodes.join(', ')}). Randomising all attributes.`;
       }
 
       return { reasoning, parameters };
@@ -116,10 +121,19 @@ function classify(reasonCodes) {
       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.
+  // Order is by how *actionable* the signal is, not how severe it looks.
+  //
+  // Velocity first: those codes often also mention IP (IP_VELOCITY), and the
+  // velocity response — slow down — is the stronger move.
+  //
+  // Then IP before device. A defence that reports NEW_DEVICE alongside an IP
+  // reason is not telling the attacker anything it can act on: the device is
+  // unrecognised *because* the attacker rotated it, and it will be unrecognised
+  // again next round no matter what. The IP is the part that can actually be
+  // changed for the better. Checking device first made the attacker announce it
+  // was rotating a fingerprint while the thing blocking it was the address.
   if (matches(VELOCITY_SIGNALS)) return 'velocity';
-  if (matches(DEVICE_SIGNALS)) return 'device';
   if (matches(IP_SIGNALS)) return 'ip';
+  if (matches(DEVICE_SIGNALS)) return 'device';
   return 'unknown';
 }

package/src/llm/openai.js

@@ -21,6 +21,13 @@ 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.
+Each history entry shows the exact parameters sent that round and the decision returned.
+You control these parameters:
+  "ip"                - source IPv4 address
+  "userAgent"         - browser user agent string
+  "deviceFingerprint" - device fingerprint; reuse one from history to replay that device
+  "delayMs"           - how long you would wait before the next attempt
+Omit a parameter to keep its previous value.
 Respond ONLY with valid JSON: { "reasoning": "...", "parameters": {...} }`;
 
 /**

package/src/locales/index.js

@@ -0,0 +1,193 @@
+/**
+ * Locale packs — the market a simulation pretends to be in.
+ *
+ * A fraud system is fed by data that looks like its market: account numbers of
+ * the right length, banks that exist, phone numbers in the right format, amounts
+ * in the right currency. Sending Nigerian-shaped payloads at a US processor
+ * produces validation errors, not fraud decisions — and a run full of 400s
+ * measures nothing.
+ *
+ * So the market is a parameter. `run()` and `runSuite()` take a `locale`, and
+ * every generator draws from it — the same way `seed` works, and scoped the same
+ * way, so no builder needs an extra argument threaded through it.
+ *
+ * ── What a pack is not ────────────────────────────────────────────────
+ * It is not a claim about a country. The banks and names here are a small,
+ * plausible sample chosen so generated payloads pass format validation; they are
+ * not a directory, and no real customer, account or number is represented. Every
+ * value is synthetic.
+ *
+ * @example
+ *   await run('account-drain', { target, locale: 'US', options: { ... } });
+ *
+ * Adding a market is a pull request against this file: fill the same fields,
+ * keeping the data synthetic and the formats real.
+ */
+
+/**
+ * @typedef {object} Locale
+ * @property {string} id - ISO 3166-1 alpha-2 country code.
+ * @property {string} name
+ * @property {string} currency - ISO 4217 code.
+ * @property {number} minorUnits - Minor units per major unit (100 for most).
+ * @property {string[]} banks
+ * @property {string[]} firstNames
+ * @property {string[]} lastNames
+ * @property {() => string} accountNumber - Market-shaped account identifier.
+ * @property {() => string} phoneNumber - Market-shaped subscriber number.
+ * @property {Array<{city: string, lat: number, lon: number}>} cities - Domestic
+ *   locations for the IP pool's "this looks like home" entries.
+ */
+
+/** Digits helper shared by the packs; takes the run's RNG so output stays seeded. */
+const digits = (rand, n) => {
+  let out = '';
+  for (let i = 0; i < n; i++) out += Math.floor(rand() * 10).toString();
+  return out;
+};
+
+const pick = (rand, arr) => arr[Math.floor(rand() * arr.length)];
+
+export const LOCALES = {
+  NG: {
+    id: 'NG',
+    name: 'Nigeria',
+    currency: 'NGN',
+    minorUnits: 100,
+    banks: [
+      'GTBank', 'UBA', 'Access', 'Zenith', 'First Bank',
+      'FCMB', 'Sterling', 'Stanbic IBTC', 'Fidelity', 'Wema',
+    ],
+    firstNames: [
+      'Adaeze', 'Chinedu', 'Folake', 'Tunde', 'Aisha', 'Emeka', 'Nkechi',
+      'Bayo', 'Ngozi', 'Olumide', 'Funmi', 'Kayode', 'Hauwa', 'Ifeanyi',
+    ],
+    lastNames: [
+      'Adeyemi', 'Okonkwo', 'Ibrahim', 'Nwosu', 'Bello', 'Eze', 'Yusuf',
+      'Okoye', 'Lawal', 'Obi', 'Musa', 'Achebe', 'Adamu', 'Chukwu',
+    ],
+    // NUBAN: 10 digits.
+    accountNumber: (rand) => digits(rand, 10),
+    phoneNumber: (rand) =>
+      pick(rand, ['0803', '0806', '0703', '0705', '0813', '0816', '0906', '0913']) +
+      digits(rand, 7),
+    cities: [
+      { city: 'Lagos', lat: 6.5244, lon: 3.3792 },
+      { city: 'Abuja', lat: 9.0765, lon: 7.3986 },
+      { city: 'Port Harcourt', lat: 4.8156, lon: 7.0498 },
+    ],
+  },
+
+  US: {
+    id: 'US',
+    name: 'United States',
+    currency: 'USD',
+    minorUnits: 100,
+    banks: [
+      'Chase', 'Bank of America', 'Wells Fargo', 'Citibank', 'US Bank',
+      'PNC', 'Truist', 'Capital One', 'TD Bank', 'Fifth Third',
+    ],
+    firstNames: [
+      'James', 'Mary', 'Robert', 'Patricia', 'Michael', 'Jennifer', 'David',
+      'Linda', 'William', 'Elizabeth', 'Maria', 'Jose', 'Aisha', 'Wei',
+    ],
+    lastNames: [
+      'Smith', 'Johnson', 'Williams', 'Brown', 'Jones', 'Garcia', 'Miller',
+      'Davis', 'Rodriguez', 'Martinez', 'Nguyen', 'Kim', 'Patel', 'Cohen',
+    ],
+    // ACH account numbers vary; 8-12 digits is the common range.
+    accountNumber: (rand) => digits(rand, 8 + Math.floor(rand() * 5)),
+    // NANP, avoiding reserved 555 exchange codes being the only option.
+    phoneNumber: (rand) =>
+      `+1${pick(rand, ['212', '312', '415', '469', '512', '646', '702', '917'])}${digits(rand, 7)}`,
+    cities: [
+      { city: 'New York', lat: 40.7128, lon: -74.006 },
+      { city: 'Chicago', lat: 41.8781, lon: -87.6298 },
+      { city: 'Austin', lat: 30.2672, lon: -97.7431 },
+    ],
+  },
+
+  GB: {
+    id: 'GB',
+    name: 'United Kingdom',
+    currency: 'GBP',
+    minorUnits: 100,
+    banks: [
+      'Barclays', 'HSBC', 'Lloyds', 'NatWest', 'Santander UK',
+      'Halifax', 'Nationwide', 'Monzo', 'Starling', 'TSB',
+    ],
+    firstNames: [
+      'Oliver', 'Amelia', 'Harry', 'Isla', 'George', 'Ava', 'Noah',
+      'Freya', 'Priya', 'Mohammed', 'Sophie', 'Jack', 'Chloe', 'Adam',
+    ],
+    lastNames: [
+      'Smith', 'Jones', 'Taylor', 'Brown', 'Williams', 'Wilson', 'Davies',
+      'Patel', 'Evans', 'Thomas', 'Khan', 'Roberts', 'Walker', 'Wright',
+    ],
+    // UK account numbers are 8 digits (sort code is separate).
+    accountNumber: (rand) => digits(rand, 8),
+    phoneNumber: (rand) => `+447${digits(rand, 9)}`,
+    cities: [
+      { city: 'London', lat: 51.5072, lon: -0.1276 },
+      { city: 'Manchester', lat: 53.4808, lon: -2.2426 },
+      { city: 'Edinburgh', lat: 55.9533, lon: -3.1883 },
+    ],
+  },
+
+  KE: {
+    id: 'KE',
+    name: 'Kenya',
+    currency: 'KES',
+    minorUnits: 100,
+    banks: [
+      'Equity Bank', 'KCB', 'Co-operative Bank', 'Absa Kenya', 'Standard Chartered',
+      'NCBA', 'DTB', 'Stanbic Kenya', 'I&M Bank', 'Family Bank',
+    ],
+    firstNames: [
+      'Wanjiku', 'Otieno', 'Achieng', 'Kamau', 'Njeri', 'Mwangi', 'Akinyi',
+      'Kipchoge', 'Wafula', 'Chebet', 'Omondi', 'Nyambura', 'Barasa', 'Amina',
+    ],
+    lastNames: [
+      'Kariuki', 'Ochieng', 'Mutiso', 'Wanjala', 'Kimani', 'Odhiambo',
+      'Njoroge', 'Mutua', 'Cheruiyot', 'Maina', 'Owino', 'Githinji',
+    ],
+    accountNumber: (rand) => digits(rand, 12),
+    phoneNumber: (rand) => `+2547${digits(rand, 8)}`,
+    cities: [
+      { city: 'Nairobi', lat: -1.2864, lon: 36.8172 },
+      { city: 'Mombasa', lat: -4.0435, lon: 39.6682 },
+      { city: 'Kisumu', lat: -0.0917, lon: 34.768 },
+    ],
+  },
+};
+
+/** The market used when a run does not name one. */
+export const DEFAULT_LOCALE = 'US';
+
+/**
+ * Resolve a locale id to its pack.
+ *
+ * Unknown ids throw rather than falling back: silently generating US-shaped
+ * data for a run that asked for `DE` would produce a result that looks valid
+ * and measures the wrong market.
+ *
+ * @param {string|Locale} [id]
+ * @returns {Locale}
+ */
+export function resolveLocale(id = DEFAULT_LOCALE) {
+  if (id && typeof id === 'object') return id;
+
+  const pack = LOCALES[String(id).toUpperCase()];
+  if (!pack) {
+    throw new Error(
+      `Unknown locale: "${id}". Available: ${Object.keys(LOCALES).join(', ')}. ` +
+        'Pass a locale object to use a market that is not bundled.'
+    );
+  }
+  return pack;
+}
+
+/** Ids of the bundled packs. */
+export function localeIds() {
+  return Object.keys(LOCALES);
+}