fraud-sim 0.2.0 → 0.5.0

package/types/utils/clock.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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?: {
+    start?: number;
+    stepMs?: number;
+}): {
+    iso: () => string;
+    epoch: () => number;
+    advance: (ms?: number) => void;
+    elapsedMs: () => number;
+};
+/** Format a millisecond span as a short human string, for milestone messages. */
+export function humaniseMs(ms: any): string;

package/types/utils/faker-helpers.d.ts

@@ -0,0 +1,114 @@
+export function newSessionId(prefix?: string): string;
+export function newDeviceFingerprint(): string;
+export function newReference(): string;
+export function newPayee(): {
+    payee_account: any;
+    payee_bank: any;
+    payee_name: string;
+};
+export function buildLoginPayload(userId: any, overrides?: {}): {
+    user_id: any;
+    session_id: string;
+    ip_address: string;
+    user_agent: any;
+    device_fingerprint: string;
+    timestamp: string;
+    metadata: {
+        login_method: string;
+        platform: any;
+        _simulated: boolean;
+    };
+};
+export function buildWithdrawalPayload(userId: any, transaction?: {}, overrides?: {}): {
+    user_id: any;
+    session_id: string;
+    ip_address: string;
+    device_fingerprint: string;
+    timestamp: string;
+    transaction: {
+        is_new_payee: boolean;
+        reference: string;
+        payee_account: any;
+        payee_bank: any;
+        payee_name: string;
+        amount: any;
+        currency: any;
+    };
+    metadata: {
+        _simulated: boolean;
+    };
+};
+/**
+ * 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: any, actionType: any, details?: {}, overrides?: {}): {
+    details: any;
+    user_id: any;
+    session_id: string;
+    action_type: any;
+    ip_address: string;
+    user_agent: any;
+    device_fingerprint: string;
+    timestamp: string;
+    metadata: {
+        _simulated: boolean;
+    };
+};
+/** A new-account signup, as promo abuse would generate it. */
+export function buildSignupPayload(userId: any, overrides?: {}): {
+    details: any;
+    user_id: any;
+    session_id: string;
+    action_type: any;
+    ip_address: string;
+    user_agent: any;
+    device_fingerprint: string;
+    timestamp: string;
+    metadata: {
+        _simulated: boolean;
+    };
+};
+/**
+ * A card authorisation attempt.
+ *
+ * Carries a token, BIN and last four — never a full card number. See
+ * `randomCardBin` for why.
+ */
+export function buildCardAuthPayload(userId: any, card?: {}, amountMinor?: number, overrides?: {}): {
+    details: any;
+    user_id: any;
+    session_id: string;
+    action_type: any;
+    ip_address: string;
+    user_agent: any;
+    device_fingerprint: string;
+    timestamp: string;
+    metadata: {
+        _simulated: boolean;
+    };
+};
+/**
+ * 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: any, destinationAccount: any, amountMinor: any, overrides?: {}): {
+    user_id: any;
+    session_id: string;
+    ip_address: string;
+    device_fingerprint: string;
+    timestamp: string;
+    transaction: {
+        is_new_payee: boolean;
+        reference: string;
+        payee_account: any;
+        payee_bank: any;
+        payee_name: string;
+        amount: any;
+        currency: any;
+    };
+    metadata: {
+        _simulated: boolean;
+    };
+};

package/types/utils/index.d.ts

@@ -0,0 +1,8 @@
+export { sleep } from "./sleep.js";
+export { DeterministicRng } from "./rng.js";
+export { simulatedClock, humaniseMs } from "./clock.js";
+export { newResults, countDecision, scoreAndCount } from "./results.js";
+export { buildLoginPayload, buildWithdrawalPayload, buildActionPayload, buildSignupPayload, buildCardAuthPayload, buildTransferPayload, newSessionId, newDeviceFingerprint, newReference, newPayee } from "./faker-helpers.js";
+export { randomFloat, randomInt, pickOne, alphanumeric, randomIp, ipInSameSubnet, randomUserAgent, randomAccountNumber, randomBank, randomFullName, randomPhoneNumber, randomCardBin, cardBins, randomLast4, newCardToken, DEMO_IP_POOL, demoIpPool, pickDemoIp } from "./random.js";
+export { withSeed, isSeeded, withLocale, currentLocale } from "./random-source.js";
+export { LOCALES, localeIds, resolveLocale, DEFAULT_LOCALE } from "../locales/index.js";

package/types/utils/random-source.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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(): {
+    next: () => number;
+};
+/** A float in [0, 1) from the current source. */
+export function randomFloat(): number;
+/**
+ * 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<T>(seed: number, fn: () => T): T;
+/** True when a seeded generator is currently in scope. */
+export function isSeeded(): boolean;
+/** The locale pack in scope, or the default when a run did not name one. */
+export function currentLocale(): any;
+/**
+ * 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<T>(locale: string | object, fn: () => T): T;

package/types/utils/random.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Random integer in [min, max] inclusive.
+ */
+export function randomInt(min: any, max: any): any;
+/**
+ * Pick one element from an array.
+ */
+export function pickOne(arr: any): any;
+/**
+ * Generate a random alphanumeric string of the given length.
+ */
+export function alphanumeric(length: any): string;
+/**
+ * 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(): string;
+/**
+ * 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 demoIpPool(locale: any): readonly any[];
+/**
+ * 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" | "domestic" | "hosting" | "proxy" | "foreign"): (typeof DEMO_IP_POOL)[number];
+/** Pick one of the published test BINs. */
+export function randomCardBin(): any;
+/** All test BINs, for scenarios that need to walk a BIN range deliberately. */
+export function cardBins(): string[];
+/** Four synthetic trailing digits. Not derived from any real card. */
+export function randomLast4(): string;
+/** An opaque card token, the way a processor would hand one to a risk API. */
+export function newCardToken(): string;
+/**
+ * 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 ipInSameSubnet(ip: any): string;
+/** A subscriber number in the active market's format. */
+export function randomPhoneNumber(): any;
+/**
+ * Pick a realistic user agent string.
+ */
+export function randomUserAgent(): any;
+/**
+ * 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(): any;
+/**
+ * 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(): any;
+/** A bank from the active market. */
+export function randomBank(): any;
+/** A plausible name for the active market. Synthetic; nobody real. */
+export function randomFullName(): string;
+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: readonly any[];

package/types/utils/results.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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?: {}): {
+    attempts: number;
+    blocked: number;
+    stepUp: number;
+    allowed: number;
+    errors: number;
+};
+/**
+ * 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: any, decision: any): any;
+/**
+ * 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 function scoreAndCount({ ctx, method, payload, results, stage, ipIntel }: {
+    ctx: object;
+    method: string;
+    payload: object;
+    results: object;
+    stage?: string;
+    ipIntel?: object;
+}): Promise<object | null>;

package/types/utils/rng.d.ts

@@ -0,0 +1,36 @@
+export class DeterministicRng {
+    /**
+     * @param {number} [seed] - Any integer. The same seed always replays the same sequence.
+     */
+    constructor(seed?: number);
+    state: number;
+    /**
+     * Next float in [0, 1).
+     * @returns {number}
+     */
+    next(): number;
+    /**
+     * Integer in [min, max] inclusive.
+     * @param {number} min
+     * @param {number} max
+     * @returns {number}
+     */
+    int(min: number, max: number): number;
+    /**
+     * Pick one element from an array.
+     * @param {Array} arr
+     * @returns {*}
+     */
+    pick(arr: any[]): any;
+    /**
+     * Random alphanumeric string of the given length.
+     * @param {number} length
+     * @returns {string}
+     */
+    alphanumeric(length: number): string;
+    /**
+     * Synthetic IPv4 address.
+     * @returns {string}
+     */
+    ip(): string;
+}

package/types/utils/sleep.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Sleep utility — abort-aware.
+ *
+ * Used by scenarios to space out attack attempts. Respects AbortSignal
+ * so scenarios cancel promptly when the user aborts.
+ */
+export function sleep(ms: any, signal: any): Promise<any>;

package/types/utils/throttle.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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: object, maxPerSecond: number, hooks?: {
+    onThrottle?: (waitMs: number) => void;
+    signal?: AbortSignal;
+}): object;
+/**
+ * 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: object, limiter: () => Promise<void>, onThrottle?: (waitMs: number) => void): object;
+/**
+ * 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: any, hooks?: {}): () => Promise<void>;