@mnemopay/sdk 0.3.0 → 0.4.0

package/dist/fraud.d.ts

@@ -0,0 +1,212 @@
+/**
+ * MnemoPay Fraud Guard — velocity checks, anomaly detection, risk scoring,
+ * dispute resolution, and platform fee collection.
+ *
+ * Plugs into MnemoPayLite.charge/settle/refund to enforce security rules
+ * before any money moves.
+ */
+import { IsolationForest, TransactionGraph, BehaviorProfile } from "./fraud-ml.js";
+import type { CollusionSignal, BehaviorSnapshot } from "./fraud-ml.js";
+export interface FraudConfig {
+    /** Platform fee rate on settle (0.03 = 3%). Default 0.03 */
+    platformFeeRate: number;
+    /** Max charges per minute per agent. Default 5 */
+    maxChargesPerMinute: number;
+    /** Max charges per hour per agent. Default 30 */
+    maxChargesPerHour: number;
+    /** Max charges per day per agent. Default 100 */
+    maxChargesPerDay: number;
+    /** Max daily charge volume in USD. Default 5000 */
+    maxDailyVolume: number;
+    /** Standard deviations for amount anomaly detection. Default 2.5 */
+    anomalyStdDevThreshold: number;
+    /** Minutes before settled funds can be withdrawn (hold period). Default 30 */
+    settlementHoldMinutes: number;
+    /** Minutes after settlement during which dispute can be filed. Default 1440 (24h) */
+    disputeWindowMinutes: number;
+    /** Risk score 0-1 above which transaction is blocked. Default 0.75 */
+    blockThreshold: number;
+    /** Risk score 0-1 above which transaction is flagged. Default 0.45 */
+    flagThreshold: number;
+    /** Minimum account age in minutes before charges are allowed. Default 0 */
+    minAccountAgeMinutes: number;
+    /** Max pending (unsettled) transactions at once. Default 10 */
+    maxPendingTransactions: number;
+    /** Enable IP/geo tracking (MCP server only). Default true */
+    enableGeoCheck: boolean;
+    /** Blocked country ISO codes. Default empty */
+    blockedCountries: string[];
+    /** Enable ML fraud detection (Isolation Forest, graph analysis, behavioral fingerprinting). Default false */
+    ml: boolean;
+}
+export declare const DEFAULT_FRAUD_CONFIG: FraudConfig;
+export interface FraudSignal {
+    type: string;
+    severity: "low" | "medium" | "high" | "critical";
+    description: string;
+    /** Risk weight 0-1 */
+    weight: number;
+}
+export interface RiskAssessment {
+    /** Composite risk score 0-1 */
+    score: number;
+    /** Risk level derived from score */
+    level: "safe" | "low" | "medium" | "high" | "blocked";
+    /** Detected fraud signals */
+    signals: FraudSignal[];
+    /** Whether the action should proceed */
+    allowed: boolean;
+    /** Human-readable reason if blocked */
+    reason?: string;
+    /** Whether flagged for review (allowed but suspicious) */
+    flagged: boolean;
+}
+export interface Dispute {
+    id: string;
+    txId: string;
+    agentId: string;
+    reason: string;
+    status: "open" | "resolved_refunded" | "resolved_upheld" | "expired";
+    createdAt: Date;
+    resolvedAt?: Date;
+    evidence: string[];
+}
+export interface PlatformFeeRecord {
+    txId: string;
+    agentId: string;
+    grossAmount: number;
+    feeRate: number;
+    feeAmount: number;
+    netAmount: number;
+    createdAt: Date;
+}
+/** IP/geo context passed from MCP server */
+export interface RequestContext {
+    ip?: string;
+    country?: string;
+    userAgent?: string;
+    sessionId?: string;
+}
+export declare class FraudGuard {
+    readonly config: FraudConfig;
+    /** Sliding window of recent charges per agent */
+    private chargeHistory;
+    /** Running stats per agent: sum, sumSq, count for online std-dev */
+    private agentStats;
+    /** Active disputes */
+    private disputes;
+    /** Platform fee ledger */
+    private feeLedger;
+    /** Total platform fees collected */
+    private _platformFeesCollected;
+    /** Known IPs per agent for consistency checks */
+    private agentIps;
+    /** Flagged agents (soft block — allowed but monitored) */
+    private flaggedAgents;
+    /** Hard-blocked agents */
+    private blockedAgents;
+    /** ML anomaly detection — only loaded when ml: true */
+    readonly isolationForest: IsolationForest | null;
+    /** Transaction graph — only loaded when ml: true */
+    readonly transactionGraph: TransactionGraph | null;
+    /** Behavioral fingerprinting — only loaded when ml: true */
+    readonly behaviorProfile: BehaviorProfile | null;
+    constructor(config?: Partial<FraudConfig>);
+    /**
+     * Assess risk for a charge attempt. Returns a RiskAssessment
+     * that includes whether the charge should proceed.
+     */
+    assessCharge(agentId: string, amount: number, reputation: number, accountCreatedAt: Date, pendingCount: number, ctx?: RequestContext): RiskAssessment;
+    /**
+     * Record a successful charge for velocity tracking and stats.
+     * Call AFTER charge is approved.
+     */
+    recordCharge(agentId: string, amount: number, ctx?: RequestContext): void;
+    /** Record a non-payment event (memory ops) for behavioral profiling */
+    recordEvent(agentId: string, type: "remember" | "recall" | "settle" | "refund"): void;
+    /** Record a transaction between agents for graph analysis */
+    recordTransfer(fromAgent: string, toAgent: string, amount: number, txId: string): void;
+    /** Run collusion detection across the transaction graph (requires ml: true) */
+    detectCollusion(): CollusionSignal[];
+    /** Get an agent's behavioral baseline (requires ml: true) */
+    getAgentBaseline(agentId: string): BehaviorSnapshot | undefined;
+    /**
+     * Calculate and record platform fee for a settlement.
+     * Returns { grossAmount, feeAmount, netAmount }.
+     */
+    applyPlatformFee(txId: string, agentId: string, grossAmount: number): PlatformFeeRecord;
+    /** Total platform fees collected */
+    get platformFeesCollected(): number;
+    /** Get platform fee ledger */
+    getFeeLedger(limit?: number): PlatformFeeRecord[];
+    /**
+     * File a dispute against a settled transaction.
+     * Returns the dispute if within the dispute window.
+     */
+    fileDispute(txId: string, agentId: string, reason: string, txCompletedAt: Date, evidence?: string[]): Dispute;
+    /**
+     * Resolve a dispute. Either refund the transaction or uphold it.
+     */
+    resolveDispute(disputeId: string, outcome: "refund" | "uphold"): Dispute;
+    /** Get all disputes for an agent */
+    getDisputes(agentId?: string): Dispute[];
+    /** Get a specific dispute */
+    getDispute(disputeId: string): Dispute | undefined;
+    /**
+     * Check if a transaction is within the settlement hold period.
+     * Returns true if the transaction is still held and cannot be withdrawn.
+     */
+    isWithinHoldPeriod(settledAt: Date): boolean;
+    /** Check if a transaction is still within the dispute window */
+    isWithinDisputeWindow(settledAt: Date): boolean;
+    /** Block an agent from making any charges */
+    blockAgent(agentId: string): void;
+    /** Unblock a previously blocked agent */
+    unblockAgent(agentId: string): void;
+    /** Check if an agent is blocked */
+    isBlocked(agentId: string): boolean;
+    /** Check if an agent is flagged */
+    isFlagged(agentId: string): boolean;
+    /** Get fraud stats summary */
+    stats(): {
+        totalChargesTracked: number;
+        agentsTracked: number;
+        agentsFlagged: number;
+        agentsBlocked: number;
+        openDisputes: number;
+        platformFeesCollected: number;
+    };
+    serialize(): string;
+    static deserialize(json: string, config?: Partial<FraudConfig>): FraudGuard;
+}
+export interface RateLimitConfig {
+    /** Max requests per window. Default 60 */
+    maxRequests: number;
+    /** Window size in milliseconds. Default 60000 (1 minute) */
+    windowMs: number;
+    /** Max requests for payment operations (charge/settle/refund). Default 10 */
+    maxPaymentRequests: number;
+    /** Payment operations window in ms. Default 60000 */
+    paymentWindowMs: number;
+}
+export declare const DEFAULT_RATE_LIMIT: RateLimitConfig;
+export declare class RateLimiter {
+    private config;
+    /** IP → timestamps of recent requests */
+    private requests;
+    /** IP → timestamps of recent payment operations */
+    private paymentRequests;
+    constructor(config?: Partial<RateLimitConfig>);
+    /**
+     * Check if a request should be allowed.
+     * Returns { allowed, remaining, retryAfterMs? }
+     */
+    check(key: string, isPayment?: boolean): {
+        allowed: boolean;
+        remaining: number;
+        retryAfterMs?: number;
+    };
+    /** Clean up old entries (call periodically) */
+    cleanup(): void;
+}
+//# sourceMappingURL=fraud.d.ts.map

package/dist/fraud.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fraud.d.ts","sourceRoot":"","sources":["../src/fraud.ts"],"names":[],"mappings":"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"}