fraud-sim 0.2.0 → 0.5.0

package/src/scenarios/velocity-evasion.js

@@ -0,0 +1,179 @@
+/**
+ * Scenario: velocity-evasion
+ *
+ * An attacker who has already probed the target and learned roughly where its
+ * rate limits sit, and now paces attempts to stay just underneath them. Not a
+ * botnet — one attacker, being deliberately patient.
+ *
+ * This is a direct test of a specific weakness: a counter with a fixed
+ * threshold is a line, and any line can be stayed under. The scenario
+ * parameterises the attacker's *belief* about the limit and derives its pacing
+ * from that, so you can also run it with a deliberately wrong belief to see how
+ * much margin your thresholds actually have.
+ *
+ * Defensive systems should catch this via:
+ *   - Adaptive thresholds keyed to the user's own baseline
+ *   - Multi-window counters (staying under an hourly limit still breaks a daily one)
+ *   - Statistical anomaly detection on inter-arrival times — perfectly spaced
+ *     attempts are themselves unnatural
+ *   - Device and network novelty, which pacing does nothing to hide
+ *
+ * ── On simulated time ─────────────────────────────────────────────────
+ * Evasion is defined by spacing, so this scenario advances the `timestamp`
+ * field rather than sleeping for hours. That is faithful only if the target
+ * derives its windows from the event timestamp; a system stamping server-side
+ * arrival time will see a burst and block it, which tells you nothing about
+ * evasion. `simulatedTime: true` is set on the report.
+ */
+
+import { sleep } from '../utils/sleep.js';
+import {
+  buildLoginPayload,
+  newDeviceFingerprint,
+} from '../utils/faker-helpers.js';
+import { newResults, scoreAndCount } from '../utils/results.js';
+import { simulatedClock, humaniseMs } from '../utils/clock.js';
+import { randomIp, randomInt, pickDemoIp } from '../utils/random.js';
+
+export default {
+  id: 'velocity-evasion',
+  name: 'Velocity evasion',
+  description:
+    'An attacker who has learned where the rate limits sit and paces attempts to stay just under them.',
+
+  defaultOptions: {
+    targetUserId: null, // required
+    attemptCount: 24,
+    assumedLimit: 5, // attempts the attacker believes are allowed...
+    assumedWindowSeconds: 600, // ...within this window
+    safetyMargin: 1.25, // how far under the limit they stay (1.0 = exactly at it)
+    jitterRatio: 0.15, // randomise spacing — perfect regularity is its own signal
+    rotateDevice: true, // pacing hides volume, not novelty
+    ipPersona: 'random',
+    delayMs: 50, // wall-clock pacing only
+    maxTotalAttempts: 200,
+  },
+
+  async run(ctx) {
+    const { options, emit, signal } = ctx;
+
+    if (!options.targetUserId) {
+      throw new Error('velocity-evasion requires options.targetUserId');
+    }
+    if (options.assumedLimit < 1) {
+      throw new Error('velocity-evasion requires options.assumedLimit >= 1');
+    }
+    if (options.safetyMargin <= 0) {
+      throw new Error('velocity-evasion requires options.safetyMargin > 0');
+    }
+
+    // To stay under `limit` attempts per `window`, space them at least
+    // window/limit apart, times a margin the attacker keeps for safety.
+    const baseSpacingMs =
+      ((options.assumedWindowSeconds * 1000) / options.assumedLimit) * options.safetyMargin;
+
+    const results = newResults({
+      attemptsMade: 0,
+      firstNonAllowAtAttempt: null,
+      evaded: false,
+    });
+
+    const clock = simulatedClock({ start: Date.now() });
+    const fixedDevice = options.rotateDevice ? null : newDeviceFingerprint();
+    const fixedIp = options.ipPersona === 'random' ? randomIp() : null;
+
+    const effectiveRate = (options.assumedWindowSeconds * 1000) / baseSpacingMs;
+
+    emit({
+      type: 'milestone',
+      message:
+        `Pacing at one attempt every ${humaniseMs(baseSpacingMs)} — ` +
+        `${effectiveRate.toFixed(1)} per ${options.assumedWindowSeconds}s window, ` +
+        `against an assumed limit of ${options.assumedLimit}`,
+      timestamp: Date.now(),
+    });
+
+    emit({
+      type: 'milestone',
+      message:
+        'Timestamps are simulated. If the target uses server arrival time for its windows, ' +
+        'this run measures a burst rather than an evasion attempt.',
+      timestamp: Date.now(),
+    });
+
+    for (let i = 0; i < options.attemptCount; i++) {
+      if (signal.aborted) break;
+      if (results.attempts >= options.maxTotalAttempts) break;
+
+      const ip = fixedIp ?? pickIp(options.ipPersona);
+      const overrides = {
+        timestamp: clock.iso(),
+        ip_address: typeof ip === 'string' ? ip : ip.ip,
+      };
+      if (fixedDevice) overrides.device_fingerprint = fixedDevice;
+
+      const response = await scoreAndCount({
+        ctx,
+        method: 'scoreLogin',
+        payload: buildLoginPayload(options.targetUserId, overrides),
+        results,
+        stage: 'paced-attempt',
+        ipIntel: typeof ip === 'string' ? undefined : ip.intel,
+      });
+
+      results.attemptsMade++;
+
+      if (response && response.decision !== 'ALLOW' && results.firstNonAllowAtAttempt == null) {
+        results.firstNonAllowAtAttempt = i + 1;
+        emit({
+          type: 'milestone',
+          message:
+            `Pushback at attempt ${i + 1} (${response.decision}) after ` +
+            `${humaniseMs(clock.elapsedMs())} of simulated time — pacing did not save them`,
+          timestamp: Date.now(),
+        });
+      }
+
+      // Jitter the spacing. A perfectly regular interval is itself detectable.
+      const jitter = options.jitterRatio
+        ? randomInt(-baseSpacingMs * options.jitterRatio, baseSpacingMs * options.jitterRatio)
+        : 0;
+      clock.advance(Math.max(1, Math.round(baseSpacingMs + jitter)));
+
+      try {
+        await sleep(options.delayMs, signal);
+      } catch {
+        break;
+      }
+    }
+
+    results.evaded = results.firstNonAllowAtAttempt == null && results.attemptsMade > 0;
+
+    if (results.evaded) {
+      emit({
+        type: 'milestone',
+        message:
+          `All ${results.attemptsMade} attempts allowed across ${humaniseMs(clock.elapsedMs())}. ` +
+          'Fixed-threshold counters can be paced under; a baseline-aware model is what catches this.',
+        timestamp: Date.now(),
+      });
+    }
+
+    return {
+      ...results,
+      attackerSucceeded: results.evaded,
+      pacingMs: Math.round(baseSpacingMs),
+      effectiveRatePerWindow: Math.round(effectiveRate * 100) / 100,
+      assumedLimit: options.assumedLimit,
+      simulatedTime: true,
+      simulatedSpan: humaniseMs(clock.elapsedMs()),
+    };
+  },
+};
+
+function pickIp(persona) {
+  if (!persona || persona === 'random') return { ip: randomIp(), intel: undefined };
+  const resolved = persona === 'mixed' ? 'proxy' : persona;
+  const { ip, ...intel } = pickDemoIp(resolved);
+  return { ip, intel };
+}

package/src/types.js

@@ -0,0 +1,160 @@
+/**
+ * Shared type definitions.
+ *
+ * `fraud-sim` is plain JavaScript; these JSDoc typedefs are the single source
+ * of truth for its public shapes, and `npm run build:types` compiles them into
+ * the `.d.ts` files consumers actually see. Names referenced from JSDoc
+ * elsewhere in the codebase resolve here.
+ *
+ * This module exports no runtime values.
+ */
+
+/**
+ * What a target says about one scored event.
+ *
+ * `decision` is deliberately typed loosely: a target may return a value outside
+ * the three canonical ones, and a scenario counts anything unrecognised as an
+ * error rather than guessing. `'ERROR'` is produced by the adapters themselves
+ * for failures that never reached a decision.
+ *
+ * @typedef {object} TargetResponse
+ * @property {'ALLOW'|'STEP_UP'|'BLOCK'|'ERROR'|string} decision
+ * @property {number|null} [riskScore]
+ * @property {Array<{code: string, label?: string, weight?: number}>} [reasons]
+ * @property {object} [raw] - The target's unmapped response body.
+ * @property {number} [httpStatus]
+ * @property {boolean} [infraError] - True when the call failed rather than
+ *   being scored: rate limiting, a 5xx, a timeout. Excluded from block rates.
+ * @property {string|null} [retryAfter]
+ */
+
+/**
+ * The bridge between scenarios and the system under test.
+ *
+ * Not every target implements every method. A scenario that needs one you have
+ * not provided fails with a message naming it, rather than silently skipping
+ * that part of the attack.
+ *
+ * @typedef {object} TargetAdapter
+ * @property {(payload: object) => Promise<TargetResponse>} [scoreLogin]
+ * @property {(payload: object) => Promise<TargetResponse>} [scoreWithdrawal]
+ * @property {(payload: object) => Promise<TargetResponse>} [scoreAction]
+ * @property {(eventType: string, data: object) => Promise<void>} [reportEvent]
+ */
+
+/**
+ * One thing that happened during a run.
+ *
+ * @typedef {object} ScenarioEvent
+ * @property {'attempt'|'response'|'milestone'|'warning'|'error'|'summary'|'attacker_adapts'|string} type
+ * @property {number} timestamp
+ * @property {number} [round]
+ * @property {string} [stage] - Which phase of a multi-stage attack this belongs to.
+ * @property {object} [payload]
+ * @property {TargetResponse} [response]
+ * @property {number} [latencyMs]
+ * @property {string} [message]
+ * @property {object} [ipIntel] - Declared geo/reputation for the payload's IP,
+ *   present only for pool-backed addresses.
+ */
+
+/**
+ * What the runner provides to a scenario.
+ *
+ * @typedef {object} ScenarioContext
+ * @property {object} options - Defaults merged with the caller's options.
+ * @property {TargetAdapter} target - Already wrapped with the run's rate limit.
+ * @property {object} [llm] - Present only for scenarios that use one.
+ * @property {(event: ScenarioEvent) => void} emit
+ * @property {AbortSignal} signal
+ */
+
+/**
+ * An attack. Everything concrete about how traffic is generated lives here.
+ *
+ * `defaultOptions` is not documentation — it is the scenario's option surface.
+ * The runner rejects any option key it does not declare, so a typo fails
+ * loudly rather than silently falling back to a default.
+ *
+ * @typedef {object} Scenario
+ * @property {string} id
+ * @property {string} name
+ * @property {string} description
+ * @property {object} [defaultOptions]
+ * @property {(ctx: ScenarioContext) => Promise<object>} run
+ */
+
+/**
+ * Scenario metadata, as returned by `listScenarios()`.
+ *
+ * @typedef {object} ScenarioMetadata
+ * @property {string} id
+ * @property {string} name
+ * @property {string} description
+ * @property {object} [defaultOptions]
+ */
+
+/**
+ * The result of one run.
+ *
+ * Note the denominators. `blockRate` and `stepUpRate` are computed over
+ * `scoredAttempts`, not `attempts`: an attempt that failed before reaching a
+ * decision is not evidence about the defence either way, so counting it as a
+ * block would let a target look better the more it fell over. Check
+ * `errorRate` before reading anything into a run.
+ *
+ * Scenarios add their own fields — `attackerSucceeded`, `estimatedLossKobo`,
+ * `blockedAtStage` and so on — which is why this is not a closed shape.
+ *
+ * @typedef {object} ScenarioReport
+ * @property {string} scenarioId
+ * @property {string} scenarioName
+ * @property {number} startedAt
+ * @property {number} completedAt
+ * @property {number} durationMs
+ * @property {number} attempts - Everything the scenario tried.
+ * @property {number} scoredAttempts - Attempts that came back with a decision.
+ * @property {number} blocked
+ * @property {number} stepUp
+ * @property {number} allowed
+ * @property {number} errors - Attempts that never reached a decision.
+ * @property {number} blockRate - `blocked / scoredAttempts`.
+ * @property {number} stepUpRate - `stepUp / scoredAttempts`.
+ * @property {number} errorRate - `errors / attempts`.
+ * @property {number} [seed] - Present only when the run was seeded.
+ * @property {boolean} [simulatedTime] - True when the scenario advanced
+ *   timestamps rather than sleeping; results are only faithful if the target
+ *   derives its windows from the event timestamp.
+ * @property {string} [simulatedSpan]
+ * @property {boolean} [attackerSucceeded]
+ * @property {number} [estimatedLossKobo]
+ */
+
+/**
+ * Totals across a suite. Same denominator rule as a single run.
+ *
+ * @typedef {object} SuiteAggregate
+ * @property {number} attempts
+ * @property {number} scoredAttempts
+ * @property {number} blocked
+ * @property {number} stepUp
+ * @property {number} allowed
+ * @property {number} errors
+ * @property {number} blockRate
+ * @property {number} stepUpRate
+ * @property {number} errorRate
+ */
+
+/**
+ * The result of `runSuite()`.
+ *
+ * @typedef {object} SuiteReport
+ * @property {string} suiteName
+ * @property {string} startedAt
+ * @property {string} completedAt
+ * @property {number} concurrency - How many scenarios ran at once.
+ * @property {ScenarioReport[]} scenarioReports
+ * @property {SuiteAggregate} aggregate
+ */
+
+export {};

package/src/utils/clock.js

@@ -0,0 +1,77 @@
+/**
+ * Simulated clock.
+ *
+ * Some attacks are defined by their *timing* rather than their volume. A slow
+ * drain spreads withdrawals over days; a velocity-evading attacker paces
+ * attempts just under a rolling limit. Reproducing those in wall-clock time
+ * would make a single run take days, so instead we advance the `timestamp`
+ * field the target receives while sleeping only briefly — or not at all.
+ *
+ * This is honest as long as the target derives its windows from the event
+ * timestamp. A system that stamps arrival time server-side will see the whole
+ * run compressed into seconds and will (correctly) treat it as a burst. When
+ * that happens the scenario is measuring the wrong thing, so scenarios using a
+ * simulated clock say so in their report via `simulatedTime: true` and emit a
+ * milestone explaining it.
+ *
+ * @example
+ *   const clock = simulatedClock({ stepMs: 90 * 60 * 1000 }); // 90 minutes
+ *   payload.timestamp = clock.iso();
+ *   clock.advance();
+ */
+
+/**
+ * @param {object} [config]
+ * @param {number} [config.start] - Epoch ms to start from. Defaults to now.
+ * @param {number} [config.stepMs] - Default advance applied by `advance()`.
+ * @returns {{iso: () => string, epoch: () => number, advance: (ms?: number) => void,
+ *   elapsedMs: () => number}}
+ */
+export function simulatedClock(config = {}) {
+  const start = config.start ?? Date.now();
+  const stepMs = config.stepMs ?? 0;
+
+  if (!Number.isFinite(start)) {
+    throw new Error('simulatedClock: start must be a finite epoch in milliseconds');
+  }
+  if (!Number.isFinite(stepMs) || stepMs < 0) {
+    throw new Error('simulatedClock: stepMs must be a non-negative number');
+  }
+
+  let now = start;
+
+  return {
+    /** Current simulated time as an ISO-8601 string, for payload timestamps. */
+    iso() {
+      return new Date(now).toISOString();
+    },
+
+    /** Current simulated time in epoch milliseconds. */
+    epoch() {
+      return now;
+    },
+
+    /** Move the clock forward. Defaults to the configured step. */
+    advance(ms) {
+      const delta = ms ?? stepMs;
+      if (!Number.isFinite(delta) || delta < 0) {
+        throw new Error('simulatedClock.advance: expected a non-negative number of milliseconds');
+      }
+      now += delta;
+    },
+
+    /** How much simulated time has passed since the start. */
+    elapsedMs() {
+      return now - start;
+    },
+  };
+}
+
+/** Format a millisecond span as a short human string, for milestone messages. */
+export function humaniseMs(ms) {
+  const minutes = ms / 60000;
+  if (minutes < 60) return `${Math.round(minutes)} min`;
+  const hours = minutes / 60;
+  if (hours < 48) return `${hours.toFixed(1)} hours`;
+  return `${(hours / 24).toFixed(1)} days`;
+}

package/src/utils/faker-helpers.js

@@ -14,8 +14,13 @@ import {
   randomBank,
   randomFullName,
   randomInt,
+  randomCardBin,
+  randomLast4,
+  newCardToken,
+  randomPhoneNumber,
   pickOne,
 } from './random.js';
+import { currentLocale } from './random-source.js';
 
 export function newSessionId(prefix = 'sim') {
   return `${prefix}_${alphanumeric(10)}`;
@@ -63,8 +68,11 @@ export function buildWithdrawalPayload(userId, transaction = {}, overrides = {})
     device_fingerprint: newDeviceFingerprint(),
     timestamp: new Date().toISOString(),
     transaction: {
-      amount: randomInt(100000, 5000000),
-      currency: 'NGN',
+      // 50,000 - 250,000 major units, expressed in minor units. An earlier
+      // ceiling sat exactly on the "new payee, high amount" threshold most
+      // engines ship with, and those rules compare with `>`, so it never fired.
+      amount: randomInt(5000000, 25000000),
+      currency: currentLocale().currency,
       ...payee,
       is_new_payee: true,
       reference: newReference(),
@@ -74,3 +82,80 @@ export function buildWithdrawalPayload(userId, transaction = {}, overrides = {})
     ...overrides,
   };
 }
+
+/**
+ * Generic non-login, non-withdrawal event, sent to the target's `scoreAction`
+ * endpoint. Signups, promo claims, card authorisations and profile changes all
+ * ride on this shape so a target only has to map one extra endpoint.
+ */
+export function buildActionPayload(userId, actionType, details = {}, overrides = {}) {
+  // `details` is merged, not replaced. Spreading `overrides` wholesale would
+  // let a caller adding one detail field silently drop every other one —
+  // which is how a card payload can lose its BIN and still look well-formed.
+  const { details: detailOverrides, ...topLevel } = overrides;
+
+  return {
+    user_id: userId,
+    session_id: newSessionId(),
+    action_type: actionType,
+    ip_address: randomIp(),
+    user_agent: randomUserAgent(),
+    device_fingerprint: newDeviceFingerprint(),
+    timestamp: new Date().toISOString(),
+    metadata: { _simulated: true },
+    ...topLevel,
+    details: { ...details, ...(detailOverrides ?? {}) },
+  };
+}
+
+/** A new-account signup, as promo abuse would generate it. */
+export function buildSignupPayload(userId, overrides = {}) {
+  return buildActionPayload(
+    userId,
+    'signup',
+    {
+      email: `${userId}@example.invalid`,
+      phone: randomPhoneNumber(),
+      full_name: randomFullName(),
+    },
+    overrides
+  );
+}
+
+/**
+ * A card authorisation attempt.
+ *
+ * Carries a token, BIN and last four — never a full card number. See
+ * `randomCardBin` for why.
+ */
+export function buildCardAuthPayload(userId, card = {}, amountMinor = 5000, overrides = {}) {
+  return buildActionPayload(
+    userId,
+    'card_auth',
+    {
+      card_token: card.token ?? newCardToken(),
+      card_bin: card.bin ?? randomCardBin(),
+      card_last4: card.last4 ?? randomLast4(),
+      amount: amountMinor,
+      currency: currentLocale().currency,
+      entry_mode: 'card_not_present',
+    },
+    overrides
+  );
+}
+
+/**
+ * An account-to-account transfer. Structurally a withdrawal, but names the
+ * destination account explicitly so mule-network runs can be traced.
+ */
+export function buildTransferPayload(userId, destinationAccount, amountMinor, overrides = {}) {
+  return buildWithdrawalPayload(
+    userId,
+    {
+      amount: amountMinor,
+      payee_account: destinationAccount,
+      is_new_payee: overrides.isNewPayee ?? true,
+    },
+    overrides
+  );
+}

package/src/utils/index.js

@@ -0,0 +1,69 @@
+/**
+ * Scenario-authoring toolkit — `fraud-sim/utils`.
+ *
+ * Everything the built-in scenarios use to construct an attack. Custom
+ * scenarios should build on these rather than hand-rolling equivalents, for
+ * two reasons that are easy to get wrong:
+ *
+ *   - **Randomness.** Every generator here draws from the run's random source,
+ *     so a seeded run replays your scenario too. A scenario calling
+ *     `Math.random()` directly silently opts out of that.
+ *   - **Address realism.** `randomIp()` avoids private, loopback, CGNAT and
+ *     documentation ranges. Addresses in those blocks resolve at no IP-intel
+ *     provider, so a target scoring them falls back to neutral values and its
+ *     geo and reputation rules never fire — the attack looks harmless because
+ *     the defence was never given anything to look at.
+ *
+ * @example
+ *   import { buildLoginPayload, randomIp, sleep } from 'fraud-sim/utils';
+ */
+
+// ── pacing ──────────────────────────────────────────────────────────────
+export { sleep } from './sleep.js';
+export { simulatedClock, humaniseMs } from './clock.js';
+
+// ── decision tallying ───────────────────────────────────────────────────
+export { newResults, countDecision, scoreAndCount } from './results.js';
+
+// ── payload builders ────────────────────────────────────────────────────
+export {
+  buildLoginPayload,
+  buildWithdrawalPayload,
+  buildActionPayload,
+  buildSignupPayload,
+  buildCardAuthPayload,
+  buildTransferPayload,
+  newSessionId,
+  newDeviceFingerprint,
+  newReference,
+  newPayee,
+} from './faker-helpers.js';
+
+// ── synthetic data ──────────────────────────────────────────────────────
+export {
+  randomFloat,
+  randomInt,
+  pickOne,
+  alphanumeric,
+  randomIp,
+  ipInSameSubnet,
+  randomUserAgent,
+  randomAccountNumber,
+  randomBank,
+  randomFullName,
+  randomPhoneNumber,
+  randomCardBin,
+  cardBins,
+  randomLast4,
+  newCardToken,
+  DEMO_IP_POOL,
+  demoIpPool,
+  pickDemoIp,
+} from './random.js';
+
+// ── reproducibility ─────────────────────────────────────────────────────
+// `withSeed` is exported for tooling that needs to seed something outside a
+// scenario run; inside a run the runner has already installed the source.
+export { withSeed, isSeeded, withLocale, currentLocale } from './random-source.js';
+export { LOCALES, localeIds, resolveLocale, DEFAULT_LOCALE } from '../locales/index.js';
+export { DeterministicRng } from './rng.js';

package/src/utils/random-source.js

@@ -0,0 +1,104 @@
+/**
+ * Run-scoped source of randomness.
+ *
+ * Every synthetic value `fraud-sim` produces — IPs, device fingerprints,
+ * amounts, jitter, pool ordering — ultimately comes from one function here.
+ * That indirection is what makes a run reproducible: seed it, and the same
+ * attack replays choice for choice.
+ *
+ * ── Why AsyncLocalStorage rather than a module-level variable ──────────
+ * A mutable module global would work for one run at a time, and would silently
+ * corrupt two. Runs share this module, so a second run starting while a first
+ * is awaiting would swap the generator underneath it and both would lose
+ * reproducibility — with no error to say so. `AsyncLocalStorage` scopes the
+ * generator to one async execution context instead, so concurrent runs stay
+ * independent and no helper needs an extra parameter threaded through it.
+ *
+ * ── What seeding does and does not fix ────────────────────────────────
+ * Seeding controls the *choices*: which IP, which device, which amount, in
+ * which order. It does not control wall-clock time — payload timestamps still
+ * come from the real clock (or a scenario's simulated one), so two seeded runs
+ * are identical in shape but not byte-identical. That is enough to replay an
+ * attack and to keep a CI block rate stable; it is not a byte-for-byte record.
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+import { DeterministicRng } from './rng.js';
+import { resolveLocale, DEFAULT_LOCALE } from '../locales/index.js';
+
+const storage = new AsyncLocalStorage();
+
+/**
+ * The market in scope for the current run.
+ *
+ * Scoped exactly like the random source, and for the same reason: a module-level
+ * variable would work for one run and silently corrupt two concurrent ones,
+ * generating one market's payloads inside another market's run with no error to
+ * show for it.
+ */
+const localeStorage = new AsyncLocalStorage();
+
+/**
+ * The default, unseeded source. Fine for generating attack traffic; useless
+ * for replaying it.
+ */
+const systemSource = { next: () => Math.random() };
+
+/**
+ * The generator in scope right now — a seeded one inside `withSeed`, the
+ * system one otherwise.
+ *
+ * Consumers only ever need `next()`, so any object with that method works.
+ * Keeping the interface to a single function means a seeded run and an
+ * unseeded one draw from identical distributions.
+ *
+ * @returns {{ next: () => number }}
+ */
+export function currentSource() {
+  return storage.getStore() ?? systemSource;
+}
+
+/** A float in [0, 1) from the current source. */
+export function randomFloat() {
+  return currentSource().next();
+}
+
+/**
+ * Run `fn` with a seeded generator in scope. Everything it does — including
+ * across `await` boundaries — draws from that generator.
+ *
+ * @param {number} seed - Any integer. The same seed replays the same sequence.
+ * @param {() => T} fn
+ * @returns {T}
+ * @template T
+ */
+export function withSeed(seed, fn) {
+  if (!Number.isFinite(seed)) {
+    throw new Error(`seed must be a finite number, received: ${JSON.stringify(seed)}`);
+  }
+  return storage.run(new DeterministicRng(seed), fn);
+}
+
+/** True when a seeded generator is currently in scope. */
+export function isSeeded() {
+  return storage.getStore() !== undefined;
+}
+
+/** The locale pack in scope, or the default when a run did not name one. */
+export function currentLocale() {
+  return localeStorage.getStore() ?? resolveLocale(DEFAULT_LOCALE);
+}
+
+/**
+ * Run `fn` with a market in scope. Every generator inside it — account numbers,
+ * banks, names, phone numbers, payload currency — draws from that pack.
+ *
+ * @param {string|object} locale - A bundled locale id, or a locale object.
+ * @param {() => T} fn
+ * @returns {T}
+ * @template T
+ */
+export function withLocale(locale, fn) {
+  return localeStorage.run(resolveLocale(locale), fn);
+}