fraud-sim 0.2.0 → 0.5.0

package/types/index.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Run a single scenario against a target.
+ *
+ * @param {string} scenarioId - The ID of a registered scenario
+ * @param {object} config
+ * @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 function run(scenarioId: string, config?: {
+    target: TargetAdapter;
+    options?: object;
+    onEvent?: Function;
+    signal?: AbortSignal;
+    seed?: number;
+    maxRequestsPerSecond?: number;
+}): Promise<ScenarioReport>;
+/**
+ * Run a suite of scenarios as a benchmark.
+ *
+ * @param {object} config
+ * @param {string} config.name - Human-readable suite name
+ * @param {Array<{id: string, options?: object}>} config.scenarios
+ * @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 function runSuite(config?: {
+    name: string;
+    scenarios: Array<{
+        id: string;
+        options?: object;
+    }>;
+    target: TargetAdapter;
+    onEvent?: Function;
+    signal?: AbortSignal;
+    seed?: number;
+    maxRequestsPerSecond?: number;
+    concurrency?: number;
+}): Promise<SuiteReport>;
+/**
+ * Returns metadata for all registered scenarios.
+ * @returns {Array<ScenarioMetadata>}
+ */
+export function listScenarios(): Array<ScenarioMetadata>;
+/**
+ * Register a custom scenario. Useful for users extending the library
+ * or for testing internal scenarios in isolation.
+ *
+ * @param {Scenario} scenario
+ */
+export function registerScenario(scenario: Scenario): void;
+/**
+ * Remove a scenario from the registry. Primarily for testing.
+ * @param {string} scenarioId
+ */
+export function unregisterScenario(scenarioId: string): void;
+export type Scenario = import("./types.js").Scenario;
+export type ScenarioMetadata = import("./types.js").ScenarioMetadata;
+export type ScenarioReport = import("./types.js").ScenarioReport;
+export type SuiteReport = import("./types.js").SuiteReport;
+export type TargetAdapter = import("./types.js").TargetAdapter;
+export { DEMO_IP_POOL, demoIpPool, pickDemoIp } from "./utils/random.js";
+export { LOCALES, localeIds, resolveLocale, DEFAULT_LOCALE } from "./locales/index.js";

package/types/llm/anthropic.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @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?: {
+    apiKey: string;
+    model?: string;
+    maxTokens?: number;
+    fetch?: Function;
+}): {
+    name: string;
+    generateStrategy: Function;
+};

package/types/llm/deterministic.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @param {object} [config]
+ * @param {number} [config.seed=1] - Seed for reproducible strategies.
+ * @returns {{ name: string, generateStrategy: function }}
+ */
+export function deterministic(config?: {
+    seed?: number;
+}): {
+    name: string;
+    generateStrategy: Function;
+};

package/types/llm/index.d.ts

@@ -0,0 +1,3 @@
+export { deterministic } from "./deterministic.js";
+export { openai } from "./openai.js";
+export { anthropic } from "./anthropic.js";

package/types/llm/openai.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @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?: {
+    apiKey: string;
+    model?: string;
+    temperature?: number;
+    fetch?: Function;
+}): {
+    name: string;
+    generateStrategy: Function;
+};

package/types/locales/index.d.ts

@@ -0,0 +1,146 @@
+/**
+ * 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?: string | Locale): Locale;
+/** Ids of the bundled packs. */
+export function localeIds(): string[];
+export namespace LOCALES {
+    namespace NG {
+        let id: string;
+        let name: string;
+        let currency: string;
+        let minorUnits: number;
+        let banks: string[];
+        let firstNames: string[];
+        let lastNames: string[];
+        function accountNumber(rand: any): string;
+        function phoneNumber(rand: any): string;
+        let cities: {
+            city: string;
+            lat: number;
+            lon: number;
+        }[];
+    }
+    namespace US {
+        let id_1: string;
+        export { id_1 as id };
+        let name_1: string;
+        export { name_1 as name };
+        let currency_1: string;
+        export { currency_1 as currency };
+        let minorUnits_1: number;
+        export { minorUnits_1 as minorUnits };
+        let banks_1: string[];
+        export { banks_1 as banks };
+        let firstNames_1: string[];
+        export { firstNames_1 as firstNames };
+        let lastNames_1: string[];
+        export { lastNames_1 as lastNames };
+        export function accountNumber_1(rand: any): string;
+        export { accountNumber_1 as accountNumber };
+        export function phoneNumber_1(rand: any): string;
+        export { phoneNumber_1 as phoneNumber };
+        let cities_1: {
+            city: string;
+            lat: number;
+            lon: number;
+        }[];
+        export { cities_1 as cities };
+    }
+    namespace GB {
+        let id_2: string;
+        export { id_2 as id };
+        let name_2: string;
+        export { name_2 as name };
+        let currency_2: string;
+        export { currency_2 as currency };
+        let minorUnits_2: number;
+        export { minorUnits_2 as minorUnits };
+        let banks_2: string[];
+        export { banks_2 as banks };
+        let firstNames_2: string[];
+        export { firstNames_2 as firstNames };
+        let lastNames_2: string[];
+        export { lastNames_2 as lastNames };
+        export function accountNumber_2(rand: any): string;
+        export { accountNumber_2 as accountNumber };
+        export function phoneNumber_2(rand: any): string;
+        export { phoneNumber_2 as phoneNumber };
+        let cities_2: {
+            city: string;
+            lat: number;
+            lon: number;
+        }[];
+        export { cities_2 as cities };
+    }
+    namespace KE {
+        let id_3: string;
+        export { id_3 as id };
+        let name_3: string;
+        export { name_3 as name };
+        let currency_3: string;
+        export { currency_3 as currency };
+        let minorUnits_3: number;
+        export { minorUnits_3 as minorUnits };
+        let banks_3: string[];
+        export { banks_3 as banks };
+        let firstNames_3: string[];
+        export { firstNames_3 as firstNames };
+        let lastNames_3: string[];
+        export { lastNames_3 as lastNames };
+        export function accountNumber_3(rand: any): string;
+        export { accountNumber_3 as accountNumber };
+        export function phoneNumber_3(rand: any): string;
+        export { phoneNumber_3 as phoneNumber };
+        let cities_3: {
+            city: string;
+            lat: number;
+            lon: number;
+        }[];
+        export { cities_3 as cities };
+    }
+}
+/** The market used when a run does not name one. */
+export const DEFAULT_LOCALE: "US";
+export type Locale = {
+    /**
+     * - ISO 3166-1 alpha-2 country code.
+     */
+    id: string;
+    name: string;
+    /**
+     * - ISO 4217 code.
+     */
+    currency: string;
+    /**
+     * - Minor units per major unit (100 for most).
+     */
+    minorUnits: number;
+    banks: string[];
+    firstNames: string[];
+    lastNames: string[];
+    /**
+     * - Market-shaped account identifier.
+     */
+    accountNumber: () => string;
+    /**
+     * - Market-shaped subscriber number.
+     */
+    phoneNumber: () => string;
+    /**
+     * - Domestic
+     * locations for the IP pool's "this looks like home" entries.
+     */
+    cities: Array<{
+        city: string;
+        lat: number;
+        lon: number;
+    }>;
+};

package/types/reporting/aggregate.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Turning raw run data into the things a report needs to say.
+ *
+ * Kept separate from rendering so every output format — HTML, JUnit, JSON —
+ * agrees on the numbers. A format that computed its own totals would eventually
+ * disagree with another one, and a report that contradicts itself is worse than
+ * no report.
+ */
+/** Accepts a single ScenarioReport, an array of them, or a SuiteReport. */
+export function normaliseInput(result: any): {
+    name: any;
+    reports: any;
+};
+/** True for traffic a defence should let through — see legitimate-users. */
+export function isLegitimate(report: any): boolean;
+/**
+ * Totals across every attack scenario, using the same denominator rule as a
+ * single run: rates are over attempts that actually received a decision.
+ *
+ * Legitimate traffic is kept out of these figures and summarised under
+ * `legitimate` instead. A blocked customer added to the block rate would make
+ * a defence look better the more good customers it refused.
+ */
+export function totalsFor(reports: any): {
+    scoredAttempts: number;
+    blockRate: number;
+    stepUpRate: number;
+    allowRate: number;
+    errorRate: number;
+    scenarios: any;
+    attacksSucceeded: any;
+    estimatedLossMinor: any;
+    estimatedLossKobo: any;
+    legitimate: {
+        scoredAttempts: number;
+        falsePositiveRate: number;
+        frictionRate: number;
+        errorRate: number;
+        customers: number;
+        customersBlocked: number;
+        valueBlockedMinor: number;
+        attempts: number;
+        blocked: number;
+        stepUp: number;
+        allowed: number;
+        errors: number;
+    };
+    attempts: number;
+    blocked: number;
+    stepUp: number;
+    allowed: number;
+    errors: number;
+};
+/**
+ * What the defence cost ordinary customers, or `null` when the run included
+ * no legitimate traffic — absent is different from zero, and a report should
+ * never claim "no false positives" for a run that could not have seen any.
+ */
+export function legitimateTotalsFor(reports: any): {
+    scoredAttempts: number;
+    falsePositiveRate: number;
+    frictionRate: number;
+    errorRate: number;
+    customers: number;
+    customersBlocked: number;
+    valueBlockedMinor: number;
+    attempts: number;
+    blocked: number;
+    stepUp: number;
+    allowed: number;
+    errors: number;
+};
+/** Reason codes across the whole run, most frequent first. */
+export function reasonFrequency(reports: any): [any, any][];
+/** Latency across the whole run — merged samples, not an average of averages. */
+export function latencyFor(reports: any): {
+    count: number;
+    p50: any;
+    p95: any;
+    p99: any;
+    max: any;
+    approximate?: undefined;
+} | {
+    count: any;
+    p50: number;
+    p95: number;
+    p99: number;
+    max: number;
+    approximate: boolean;
+};
+/**
+ * Classify what a scenario's run actually means, which is not the same as its
+ * block rate. Order matters: reaching money outranks everything, and a result
+ * we cannot trust must never be reported as a pass.
+ */
+/**
+ * A scenario's extracted value, in the currency's minor unit.
+ *
+ * Amounts are minor-unit integers throughout — kobo, cents, the same thing
+ * structurally — so nothing here is currency-specific. `estimatedLossKobo`
+ * is the original naira-flavoured name, kept working.
+ */
+export function lossOf(report: any): any;
+export function outcomeFor(report: any): {
+    kind: string;
+    label: string;
+    severity: string;
+};
+/**
+ * The findings list, worst first.
+ *
+ * Deliberately conservative: it reports what the data supports and does not
+ * guess at causes. A generated finding that speculates is a finding a reader
+ * will eventually catch being wrong.
+ */
+export function findingsFor(reports: any, options?: {}): {
+    severity: string;
+    scenario: any;
+    title: string;
+    detail: string;
+    stats: any[][];
+}[];
+export function pct(n: any): string;
+/** @deprecated Use `formatMoney` from ./money.js — kept for compatibility. */
+export function fmtNaira(kobo: any): string;
+export function fmtMs(ms: any): string;

package/types/reporting/html.d.ts

@@ -0,0 +1 @@
+export function renderHtml(result: any, options?: {}): string;

package/types/reporting/index.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Render a run as a shareable report.
+ *
+ * Synchronous and pure — it returns a string and touches no filesystem, so the
+ * caller decides where output goes and nothing surprising happens on import.
+ *
+ * @param {object} result - A ScenarioReport, an array of them, or a SuiteReport.
+ * @param {object} [options]
+ * @param {'html'|'junit'|'json'|'text'} [options.format='html']
+ * @param {string} [options.title]
+ * @param {string} [options.targetName]
+ * @param {string} [options.version]
+ * @param {number} [options.failUnder] - Block rate below which a scenario is a
+ *   CI failure. Used by the junit and text formats.
+ * @param {number} [options.maxFalsePositiveRate] - Share of legitimate
+ *   customer events that may be blocked before the run fails. Used by the
+ *   junit and text formats.
+ * @param {string} [options.currency='NGN'] - Display currency. Amounts are
+ *   minor-unit integers, so this changes presentation only.
+ * @param {string} [options.locale] - Defaults to a locale for the currency.
+ * @returns {string}
+ */
+export function generateReport(result: object, options?: {
+    format?: "html" | "junit" | "json" | "text";
+    title?: string;
+    targetName?: string;
+    version?: string;
+    failUnder?: number;
+    maxFalsePositiveRate?: number;
+    currency?: string;
+    locale?: string;
+}): string;
+/**
+ * The structured summary behind every format. Useful on its own when you want
+ * to assert on a run in CI without parsing a rendered document.
+ */
+export function summarise(result: any, options?: {}): {
+    name: any;
+    generatedAt: any;
+    totals: {
+        scoredAttempts: number;
+        blockRate: number;
+        stepUpRate: number;
+        allowRate: number;
+        errorRate: number;
+        scenarios: any;
+        attacksSucceeded: any;
+        estimatedLossMinor: any;
+        estimatedLossKobo: any;
+        legitimate: {
+            scoredAttempts: number;
+            falsePositiveRate: number;
+            frictionRate: number;
+            errorRate: number;
+            customers: number;
+            customersBlocked: number;
+            valueBlockedMinor: number;
+            attempts: number;
+            blocked: number;
+            stepUp: number;
+            allowed: number;
+            errors: number;
+        };
+        attempts: number;
+        blocked: number;
+        stepUp: number;
+        allowed: number;
+        errors: number;
+    };
+    latency: {
+        count: number;
+        p50: any;
+        p95: any;
+        p99: any;
+        max: any;
+        approximate?: undefined;
+    } | {
+        count: any;
+        p50: number;
+        p95: number;
+        p99: number;
+        max: number;
+        approximate: boolean;
+    };
+    findings: {
+        severity: string;
+        scenario: any;
+        title: string;
+        detail: string;
+        stats: any[][];
+    }[];
+    reasonCounts: any;
+    scenarios: any;
+};
+import { renderHtml } from './html.js';
+import { renderJUnit } from './junit.js';
+export { renderHtml, renderJUnit };
+export { formatMoney, currencySymbol } from "./money.js";
+export { normaliseInput, totalsFor, legitimateTotalsFor, isLegitimate, reasonFrequency, latencyFor, findingsFor, outcomeFor } from "./aggregate.js";

package/types/reporting/junit.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @param {object} result - A ScenarioReport, an array of them, or a SuiteReport.
+ * @param {object} [options]
+ * @param {number} [options.failUnder] - Minimum acceptable block rate per scenario.
+ * @param {number} [options.maxFalsePositiveRate] - Maximum acceptable share of
+ *   legitimate customer events blocked.
+ * @param {string} [options.suiteName]
+ */
+export function renderJUnit(result: object, options?: {
+    failUnder?: number;
+    maxFalsePositiveRate?: number;
+    suiteName?: string;
+}): string;

package/types/reporting/money.d.ts

@@ -0,0 +1,20 @@
+/**
+ * How many minor units make one major unit of this currency.
+ * 100 for most, 1 for JPY and KRW, 1000 for a few Gulf currencies.
+ */
+export function minorUnitsPerMajor(currency: any, locale: any): number;
+/**
+ * Render an integer number of minor units as money.
+ *
+ * @param {number} minorUnits - e.g. 60000000 kobo, or 6060000 cents
+ * @param {object} [options]
+ * @param {string} [options.currency='NGN']
+ * @param {string} [options.locale] - Defaults to a sensible locale for the currency.
+ * @returns {string}
+ */
+export function formatMoney(minorUnits: number, options?: {
+    currency?: string;
+    locale?: string;
+}): string;
+/** The currency's symbol on its own, for compact labels like a stat tile. */
+export function currencySymbol(currency: string, locale: any): any;

package/types/runner.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Ceiling on outbound requests per second, applied to every scenario unless
+ * overridden. High enough that the shipped scenarios never touch it, low
+ * enough that a `delayMs: 0` typo against a real host stays a simulation
+ * rather than becoming a denial-of-service. Pass `Infinity` to disable.
+ */
+export const DEFAULT_MAX_REQUESTS_PER_SECOND: 25;
+export class Runner {
+    run(scenario: any, config: any): Promise<any>;
+}

package/types/scenarios/account-drain.d.ts

@@ -0,0 +1,25 @@
+declare namespace _default {
+    let id: string;
+    let name: string;
+    let description: string;
+    namespace defaultOptions {
+        let targetUserId: any;
+        let attackerIp: any;
+        let withdrawalCount: number;
+        let amountMinor: number;
+        let delayBetweenWithdrawalsMs: number;
+        let postLoginPauseMs: number;
+        let skipPasswordChange: boolean;
+    }
+    function run(ctx: any): Promise<{
+        attempts: any;
+        blocked: any;
+        stepUp: any;
+        allowed: any;
+        errors: any;
+        loginDecision: any;
+        withdrawalDecisions: any;
+        attackerSucceeded: any;
+    }>;
+}
+export default _default;

package/types/scenarios/adaptive-attacker.d.ts

@@ -0,0 +1,22 @@
+declare namespace _default {
+    let id: string;
+    let name: string;
+    let description: string;
+    namespace defaultOptions {
+        let targetUserId: any;
+        let maxRounds: number;
+        let baselineIp: string;
+        let delayMs: number;
+    }
+    function run(ctx: any): Promise<{
+        attempts: number;
+        blocked: number;
+        stepUp: number;
+        allowed: number;
+        errors: number;
+        rounds: number;
+        outcome: string;
+        strategyHistory: any[];
+    }>;
+}
+export default _default;

package/types/scenarios/card-testing.d.ts

@@ -0,0 +1,28 @@
+declare namespace _default {
+    let id: string;
+    let name: string;
+    let description: string;
+    namespace defaultOptions {
+        let attackerUserId: string;
+        let cardCount: number;
+        let binCount: number;
+        let microAmountMinor: number;
+        let largeAmountMinor: number;
+        let escalateAfter: number;
+        let delayMs: number;
+        let maxTotalAttempts: number;
+        let ipPersona: string;
+        let reuseIp: boolean;
+    }
+    function run(ctx: any): Promise<{
+        estimatedLossKobo: number;
+        attackerSucceeded: boolean;
+        binsUsed: string[];
+        attempts: number;
+        blocked: number;
+        stepUp: number;
+        allowed: number;
+        errors: number;
+    }>;
+}
+export default _default;

package/types/scenarios/credential-stuffing.d.ts

@@ -0,0 +1,23 @@
+declare namespace _default {
+    let id: string;
+    let name: string;
+    let description: string;
+    namespace defaultOptions {
+        let targetUserIds: any;
+        let targetUserId: any;
+        let attackerCount: number;
+        let attemptsPerIp: number;
+        let delayMs: number;
+        let maxTotalAttempts: number;
+        let ipPersona: string;
+    }
+    function run(ctx: any): Promise<{
+        attempts: number;
+        blocked: number;
+        stepUp: number;
+        allowed: number;
+        errors: number;
+        accountsTargeted: number;
+    }>;
+}
+export default _default;