fraud-sim 0.2.0 → 0.5.0

package/types/scenarios/index.d.ts

@@ -0,0 +1,261 @@
+export const scenarios: ({
+    id: string;
+    name: string;
+    traffic: string;
+    description: string;
+    defaultOptions: {
+        targetUserIds: any;
+        warmupLogins: number;
+        sessionsPerUser: number;
+        sessionGapHours: number;
+        withdrawalRate: number;
+        newDeviceRate: number;
+        travelRate: number;
+        newPayeeRate: number;
+        amountMinor: number;
+        delayMs: number;
+    };
+    run(ctx: any): Promise<{
+        customers: number;
+        customersBlocked: number;
+        falsePositiveRate: number;
+        frictionRate: number;
+        valueBlockedMinor: number;
+        byStage: {
+            [k: string]: {
+                events: number;
+                allowed: number;
+                stepUp: number;
+                blocked: number;
+            };
+        };
+        falsePositiveReasons: any;
+        warmup: {
+            attempts: number;
+            blocked: number;
+            stepUp: number;
+            allowed: number;
+            errors: number;
+        };
+        simulatedTime: boolean;
+        simulatedSpan: string;
+        attempts: number;
+        blocked: number;
+        stepUp: number;
+        allowed: number;
+        errors: number;
+    }>;
+} | {
+    id: string;
+    name: string;
+    description: string;
+    defaultOptions: {
+        targetUserIds: any;
+        targetUserId: any;
+        attackerCount: number;
+        attemptsPerIp: number;
+        delayMs: number;
+        maxTotalAttempts: number;
+        ipPersona: string;
+    };
+    run(ctx: any): Promise<{
+        attempts: number;
+        blocked: number;
+        stepUp: number;
+        allowed: number;
+        errors: number;
+        accountsTargeted: number;
+    }>;
+} | {
+    id: string;
+    name: string;
+    description: string;
+    defaultOptions: {
+        targetUserId: any;
+        attackerIp: any;
+        withdrawalCount: number;
+        amountMinor: number;
+        delayBetweenWithdrawalsMs: number;
+        postLoginPauseMs: number;
+        skipPasswordChange: boolean;
+    };
+    run(ctx: any): Promise<{
+        attempts: any;
+        blocked: any;
+        stepUp: any;
+        allowed: any;
+        errors: any;
+        loginDecision: any;
+        withdrawalDecisions: any;
+        attackerSucceeded: any;
+    }>;
+} | {
+    id: string;
+    name: string;
+    description: string;
+    defaultOptions: {
+        targetUserId: any;
+        maxRounds: number;
+        baselineIp: string;
+        delayMs: number;
+    };
+    run(ctx: any): Promise<{
+        attempts: number;
+        blocked: number;
+        stepUp: number;
+        allowed: number;
+        errors: number;
+        rounds: number;
+        outcome: string;
+        strategyHistory: any[];
+    }>;
+} | {
+    id: string;
+    name: string;
+    description: string;
+    defaultOptions: {
+        attackerUserId: string;
+        cardCount: number;
+        binCount: number;
+        microAmountMinor: number;
+        largeAmountMinor: number;
+        escalateAfter: number;
+        delayMs: number;
+        maxTotalAttempts: number;
+        ipPersona: string;
+        reuseIp: boolean;
+    };
+    run(ctx: any): Promise<{
+        estimatedLossKobo: number;
+        attackerSucceeded: boolean;
+        binsUsed: string[];
+        attempts: number;
+        blocked: number;
+        stepUp: number;
+        allowed: number;
+        errors: number;
+    }>;
+} | {
+    id: string;
+    name: string;
+    description: string;
+    defaultOptions: {
+        accountCount: number;
+        bonusMinor: number;
+        deviceCount: number;
+        subnetCount: number;
+        sharedPayoutAccount: any;
+        claimBonus: boolean;
+        delayMs: number;
+        maxTotalAttempts: number;
+    };
+    run(ctx: any): Promise<{
+        estimatedLossKobo: number;
+        attackerSucceeded: boolean;
+        sharedPayoutAccount: any;
+        devicesUsed: number;
+        subnetsUsed: number;
+        attempts: number;
+        blocked: number;
+        stepUp: number;
+        allowed: number;
+        errors: number;
+    }>;
+} | {
+    id: string;
+    name: string;
+    description: string;
+    defaultOptions: {
+        sourceUserId: any;
+        muleCount: number;
+        amountPerMuleMinor: number;
+        retentionRatio: number;
+        finalDestinationAccount: any;
+        forwardDelayMinutes: number;
+        delayMs: number;
+        maxTotalAttempts: number;
+    };
+    run(ctx: any): Promise<any>;
+} | {
+    id: string;
+    name: string;
+    description: string;
+    defaultOptions: {
+        targetUserId: any;
+        withdrawalCount: number;
+        amountMinor: number;
+        amountJitterMinor: number;
+        intervalMinutes: number;
+        sameDevice: boolean;
+        delayMs: number;
+        maxTotalAttempts: number;
+    };
+    run(ctx: any): Promise<{
+        estimatedLossKobo: any;
+        attackerSucceeded: boolean;
+        simulatedTime: boolean;
+        simulatedSpan: string;
+        drainedBeforeFirstBlockMinor: any;
+        attempts: number;
+        blocked: number;
+        stepUp: number;
+        allowed: number;
+        errors: number;
+    }>;
+} | {
+    id: string;
+    name: string;
+    description: string;
+    defaultOptions: {
+        targetUserId: any;
+        benignActionsBeforeHijack: number;
+        amountMinor: number;
+        withdrawAfterHijack: boolean;
+        hijackFromPersona: string;
+        delayMs: number;
+    };
+    run(ctx: any): Promise<any>;
+} | {
+    id: string;
+    name: string;
+    description: string;
+    defaultOptions: {
+        targetUserId: any;
+        minutesSincePort: number;
+        amountMinor: number;
+        reportPortEvent: boolean;
+        attemptPasswordReset: boolean;
+        ipPersona: string;
+        delayMs: number;
+    };
+    run(ctx: any): Promise<any>;
+} | {
+    id: string;
+    name: string;
+    description: string;
+    defaultOptions: {
+        targetUserId: any;
+        attemptCount: number;
+        assumedLimit: number;
+        assumedWindowSeconds: number;
+        safetyMargin: number;
+        jitterRatio: number;
+        rotateDevice: boolean;
+        ipPersona: string;
+        delayMs: number;
+        maxTotalAttempts: number;
+    };
+    run(ctx: any): Promise<{
+        attackerSucceeded: any;
+        pacingMs: number;
+        effectiveRatePerWindow: number;
+        assumedLimit: any;
+        simulatedTime: boolean;
+        simulatedSpan: string;
+        attempts: number;
+        blocked: number;
+        stepUp: number;
+        allowed: number;
+        errors: number;
+    }>;
+})[];

package/types/scenarios/legitimate-users.d.ts

@@ -0,0 +1,49 @@
+declare namespace _default {
+    let id: string;
+    let name: string;
+    let traffic: string;
+    let description: string;
+    namespace defaultOptions {
+        let targetUserIds: any;
+        let warmupLogins: number;
+        let sessionsPerUser: number;
+        let sessionGapHours: number;
+        let withdrawalRate: number;
+        let newDeviceRate: number;
+        let travelRate: number;
+        let newPayeeRate: number;
+        let amountMinor: number;
+        let delayMs: number;
+    }
+    function run(ctx: any): Promise<{
+        customers: number;
+        customersBlocked: number;
+        falsePositiveRate: number;
+        frictionRate: number;
+        valueBlockedMinor: number;
+        byStage: {
+            [k: string]: {
+                events: number;
+                allowed: number;
+                stepUp: number;
+                blocked: number;
+            };
+        };
+        falsePositiveReasons: any;
+        warmup: {
+            attempts: number;
+            blocked: number;
+            stepUp: number;
+            allowed: number;
+            errors: number;
+        };
+        simulatedTime: boolean;
+        simulatedSpan: string;
+        attempts: number;
+        blocked: number;
+        stepUp: number;
+        allowed: number;
+        errors: number;
+    }>;
+}
+export default _default;

package/types/scenarios/mule-network.d.ts

@@ -0,0 +1,17 @@
+declare namespace _default {
+    let id: string;
+    let name: string;
+    let description: string;
+    namespace defaultOptions {
+        let sourceUserId: any;
+        let muleCount: number;
+        let amountPerMuleMinor: number;
+        let retentionRatio: number;
+        let finalDestinationAccount: any;
+        let forwardDelayMinutes: number;
+        let delayMs: number;
+        let maxTotalAttempts: number;
+    }
+    function run(ctx: any): Promise<any>;
+}
+export default _default;

package/types/scenarios/promo-abuse.d.ts

@@ -0,0 +1,28 @@
+declare namespace _default {
+    let id: string;
+    let name: string;
+    let description: string;
+    namespace defaultOptions {
+        let accountCount: number;
+        let bonusMinor: number;
+        let deviceCount: number;
+        let subnetCount: number;
+        let sharedPayoutAccount: any;
+        let claimBonus: boolean;
+        let delayMs: number;
+        let maxTotalAttempts: number;
+    }
+    function run(ctx: any): Promise<{
+        estimatedLossKobo: number;
+        attackerSucceeded: boolean;
+        sharedPayoutAccount: any;
+        devicesUsed: number;
+        subnetsUsed: number;
+        attempts: number;
+        blocked: number;
+        stepUp: number;
+        allowed: number;
+        errors: number;
+    }>;
+}
+export default _default;

package/types/scenarios/session-hijack.d.ts

@@ -0,0 +1,15 @@
+declare namespace _default {
+    let id: string;
+    let name: string;
+    let description: string;
+    namespace defaultOptions {
+        let targetUserId: any;
+        let benignActionsBeforeHijack: number;
+        let amountMinor: number;
+        let withdrawAfterHijack: boolean;
+        let hijackFromPersona: string;
+        let delayMs: number;
+    }
+    function run(ctx: any): Promise<any>;
+}
+export default _default;

package/types/scenarios/sim-swap-takeover.d.ts

@@ -0,0 +1,16 @@
+declare namespace _default {
+    let id: string;
+    let name: string;
+    let description: string;
+    namespace defaultOptions {
+        let targetUserId: any;
+        let minutesSincePort: number;
+        let amountMinor: number;
+        let reportPortEvent: boolean;
+        let attemptPasswordReset: boolean;
+        let ipPersona: string;
+        let delayMs: number;
+    }
+    function run(ctx: any): Promise<any>;
+}
+export default _default;

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

@@ -0,0 +1,28 @@
+declare namespace _default {
+    let id: string;
+    let name: string;
+    let description: string;
+    namespace defaultOptions {
+        let targetUserId: any;
+        let withdrawalCount: number;
+        let amountMinor: number;
+        let amountJitterMinor: number;
+        let intervalMinutes: number;
+        let sameDevice: boolean;
+        let delayMs: number;
+        let maxTotalAttempts: number;
+    }
+    function run(ctx: any): Promise<{
+        estimatedLossKobo: any;
+        attackerSucceeded: boolean;
+        simulatedTime: boolean;
+        simulatedSpan: string;
+        drainedBeforeFirstBlockMinor: any;
+        attempts: number;
+        blocked: number;
+        stepUp: number;
+        allowed: number;
+        errors: number;
+    }>;
+}
+export default _default;

package/types/scenarios/velocity-evasion.d.ts

@@ -0,0 +1,31 @@
+declare namespace _default {
+    let id: string;
+    let name: string;
+    let description: string;
+    namespace defaultOptions {
+        let targetUserId: any;
+        let attemptCount: number;
+        let assumedLimit: number;
+        let assumedWindowSeconds: number;
+        let safetyMargin: number;
+        let jitterRatio: number;
+        let rotateDevice: boolean;
+        let ipPersona: string;
+        let delayMs: number;
+        let maxTotalAttempts: number;
+    }
+    function run(ctx: any): Promise<{
+        attackerSucceeded: any;
+        pacingMs: number;
+        effectiveRatePerWindow: number;
+        assumedLimit: any;
+        simulatedTime: boolean;
+        simulatedSpan: string;
+        attempts: number;
+        blocked: number;
+        stepUp: number;
+        allowed: number;
+        errors: number;
+    }>;
+}
+export default _default;

package/types/streaming/index.d.ts

@@ -0,0 +1 @@
+export { sseStream } from "./sse.js";

package/types/streaming/sse.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Server-Sent Events streaming helper.
+ *
+ * Wraps an Express-style response object to stream simulation events to a
+ * browser dashboard as they happen, instead of waiting for the full report.
+ *
+ * @example
+ *   import { sseStream } from 'fraud-sim/streaming';
+ *
+ *   app.get('/simulate/:scenario/stream', async (req, res) => {
+ *     const stream = sseStream(res);
+ *     await run(req.params.scenario, {
+ *       target,
+ *       onEvent: (event) => stream.send(event),
+ *     });
+ *     stream.close();
+ *   });
+ */
+/**
+ * Set up SSE headers on `res` and return a `{ send, close }` handle.
+ *
+ * Handles backpressure: if `res.write` reports the internal buffer is full
+ * (returns `false`), further events queue in memory until the response
+ * emits `drain`, then flush in order.
+ *
+ * @param {object} res - Any Express-style response with `write`, `end`,
+ *   `writeHead` (or settable `.statusCode`/`.setHeader`), and an
+ *   EventEmitter-style `on('drain', ...)`.
+ * @returns {{ send: (event: object) => void, close: () => void }}
+ */
+export function sseStream(res: object): {
+    send: (event: object) => void;
+    close: () => void;
+};

package/types/types.d.ts

@@ -0,0 +1,191 @@
+/**
+ * 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.
+ */
+export type TargetResponse = {
+    decision: "ALLOW" | "STEP_UP" | "BLOCK" | "ERROR" | string;
+    riskScore?: number | null;
+    reasons?: Array<{
+        code: string;
+        label?: string;
+        weight?: number;
+    }>;
+    /**
+     * - The target's unmapped response body.
+     */
+    raw?: object;
+    httpStatus?: number;
+    /**
+     * - True when the call failed rather than
+     * being scored: rate limiting, a 5xx, a timeout. Excluded from block rates.
+     */
+    infraError?: boolean;
+    retryAfter?: string | null;
+};
+/**
+ * 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.
+ */
+export type TargetAdapter = {
+    scoreLogin?: (payload: object) => Promise<TargetResponse>;
+    scoreWithdrawal?: (payload: object) => Promise<TargetResponse>;
+    scoreAction?: (payload: object) => Promise<TargetResponse>;
+    reportEvent?: (eventType: string, data: object) => Promise<void>;
+};
+/**
+ * One thing that happened during a run.
+ */
+export type ScenarioEvent = {
+    type: "attempt" | "response" | "milestone" | "warning" | "error" | "summary" | "attacker_adapts" | string;
+    timestamp: number;
+    round?: number;
+    /**
+     * - Which phase of a multi-stage attack this belongs to.
+     */
+    stage?: string;
+    payload?: object;
+    response?: TargetResponse;
+    latencyMs?: number;
+    message?: string;
+    /**
+     * - Declared geo/reputation for the payload's IP,
+     * present only for pool-backed addresses.
+     */
+    ipIntel?: object;
+};
+/**
+ * What the runner provides to a scenario.
+ */
+export type ScenarioContext = {
+    /**
+     * - Defaults merged with the caller's options.
+     */
+    options: object;
+    /**
+     * - Already wrapped with the run's rate limit.
+     */
+    target: TargetAdapter;
+    /**
+     * - Present only for scenarios that use one.
+     */
+    llm?: object;
+    emit: (event: ScenarioEvent) => void;
+    signal: AbortSignal;
+};
+/**
+ * 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.
+ */
+export type Scenario = {
+    id: string;
+    name: string;
+    description: string;
+    defaultOptions?: object;
+    run: (ctx: ScenarioContext) => Promise<object>;
+};
+/**
+ * Scenario metadata, as returned by `listScenarios()`.
+ */
+export type ScenarioMetadata = {
+    id: string;
+    name: string;
+    description: string;
+    defaultOptions?: object;
+};
+/**
+ * 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.
+ */
+export type ScenarioReport = {
+    scenarioId: string;
+    scenarioName: string;
+    startedAt: number;
+    completedAt: number;
+    durationMs: number;
+    /**
+     * - Everything the scenario tried.
+     */
+    attempts: number;
+    /**
+     * - Attempts that came back with a decision.
+     */
+    scoredAttempts: number;
+    blocked: number;
+    stepUp: number;
+    allowed: number;
+    /**
+     * - Attempts that never reached a decision.
+     */
+    errors: number;
+    /**
+     * - `blocked / scoredAttempts`.
+     */
+    blockRate: number;
+    /**
+     * - `stepUp / scoredAttempts`.
+     */
+    stepUpRate: number;
+    /**
+     * - `errors / attempts`.
+     */
+    errorRate: number;
+    /**
+     * - Present only when the run was seeded.
+     */
+    seed?: number;
+    /**
+     * - True when the scenario advanced
+     * timestamps rather than sleeping; results are only faithful if the target
+     * derives its windows from the event timestamp.
+     */
+    simulatedTime?: boolean;
+    simulatedSpan?: string;
+    attackerSucceeded?: boolean;
+    estimatedLossKobo?: number;
+};
+/**
+ * Totals across a suite. Same denominator rule as a single run.
+ */
+export type SuiteAggregate = {
+    attempts: number;
+    scoredAttempts: number;
+    blocked: number;
+    stepUp: number;
+    allowed: number;
+    errors: number;
+    blockRate: number;
+    stepUpRate: number;
+    errorRate: number;
+};
+/**
+ * The result of `runSuite()`.
+ */
+export type SuiteReport = {
+    suiteName: string;
+    startedAt: string;
+    completedAt: string;
+    /**
+     * - How many scenarios ran at once.
+     */
+    concurrency: number;
+    scenarioReports: ScenarioReport[];
+    aggregate: SuiteAggregate;
+};