baileys-antiban 3.1.0 → 3.2.0

package/CHANGELOG.md

@@ -5,6 +5,65 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.2.0] — 2026-04-26
+
+### New Features
+- **deviceFingerprint** — Randomizes appVersion, osVersion, and deviceModel to prevent Meta's clientPayload fingerprinting (the #1 gap in anti-ban coverage per GapHunter analysis)
+  - Randomizes appVersion patch number within safe range (e.g. 2.24.5.18 → 2.24.5.[15-22])
+  - Randomizes osVersion (Android versions 10-14)
+  - Randomizes deviceModel from pool of 12 real-world devices (Pixel, Galaxy, Xiaomi, OnePlus, etc.)
+  - Deterministic PRNG seeded from sessionId for stable fingerprints per session
+  - `generateFingerprint()` creates unique fingerprint per session
+  - `applyFingerprint()` applies to Baileys SocketConfig before makeWASocket()
+  - User-configurable pools for custom device/OS combinations
+  - Master switch: `enabled: false` to disable all randomization
+- **credsSnapshot** — Atomic credentials backup to prevent code-500 corruption loop
+  - `take()` creates atomic snapshot of creds.json before risky operations
+  - `restoreLatest()` recovers from most recent snapshot
+  - Automatic rotation keeps only N newest snapshots (default: 3)
+  - Atomic file operations (write to .tmp, rename) prevent partial writes
+  - Graceful handling of missing creds file (no crashes)
+- **readReceiptVariance** — Randomizes read receipt timing to avoid instant-read bot signals
+  - Gaussian-jittered delay before sending read receipts (mean: 1500ms, stdDev: 800ms)
+  - Configurable min/max clamps (default: 200-8000ms)
+  - Skips variance for backlog messages (older than 60s by default)
+  - `wrap()` proxies sock.readMessages with transparent delay injection
+  - `delayMs()` for manual delay computation in custom receipt logic
+  - Box-Muller transform for realistic human timing variance
+  - `stop()` cancels all pending timers on disconnect
+
+### Why v3.2
+Per GapHunter analysis, device fingerprint randomization is the single highest-ROI ban-prevention upgrade. Baileys ships identical clientPayload for every instance — Meta literally fingerprints it. This release closes that gap plus two critical operational gaps (creds corruption, instant-read bot detection).
+
+### Usage
+```ts
+import { generateFingerprint, applyFingerprint, credsSnapshot, readReceiptVariance } from 'baileys-antiban';
+
+// 1. Device fingerprint randomization
+const fp = generateFingerprint({ seed: 'my-session-123' });
+const sock = makeWASocket(applyFingerprint(socketConfig, fp));
+
+// 2. Atomic creds snapshot
+const snapshot = credsSnapshot({ credsPath: './auth/creds.json', keep: 5 });
+await snapshot.take(); // Before risky reconnect
+// ... on code-500 corruption:
+await snapshot.restoreLatest();
+
+// 3. Read receipt variance
+const variance = readReceiptVariance({ meanMs: 2000, stdDevMs: 1000 });
+const wrappedSock = variance.wrap(sock);
+// Now all readMessages() calls have human-like delays
+```
+
+### Technical Details
+- Zero runtime dependencies (Box-Muller in pure JS, fs from Node stdlib)
+- TypeScript strict mode compliant
+- Deterministic PRNG (mulberry32) for reproducible testing
+- Atomic file operations prevent corruption on crash
+- All modules are standalone and can be used independently
+
+---
+
 ## [3.1.0] — 2026-04-25
 
 ### New Features

package/dist/credsSnapshot.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Atomic Credentials Snapshot
+ *
+ * Pre-reconnect backup to kill code-500 corruption loop.
+ * Take snapshots before risky operations, restore on corruption.
+ *
+ * @author Kobus Wentzel <kobie@pop.co.za>
+ * @license MIT
+ */
+export interface CredsSnapshotConfig {
+    /** Path to creds file (e.g. './auth/creds.json') */
+    credsPath: string;
+    /** Snapshot dir (default: same dir, .snapshots/ subfolder) */
+    snapshotDir?: string;
+    /** How many snapshots to keep (rotation) */
+    keep?: number;
+    /** Logger */
+    logger?: {
+        info?: Function;
+        warn?: Function;
+        error?: Function;
+    };
+}
+export interface CredsSnapshot {
+    /** Take an atomic snapshot of creds.json. Returns snapshot path or null on failure. */
+    take(): Promise<string | null>;
+    /** Restore from most recent snapshot */
+    restoreLatest(): Promise<boolean>;
+    /** Restore from specific snapshot path */
+    restore(snapshotPath: string): Promise<boolean>;
+    /** List available snapshots, newest first */
+    list(): Promise<{
+        path: string;
+        takenAt: Date;
+        size: number;
+    }[]>;
+}
+export declare function credsSnapshot(config: CredsSnapshotConfig): CredsSnapshot;

package/dist/credsSnapshot.js

@@ -0,0 +1,121 @@
+/**
+ * Atomic Credentials Snapshot
+ *
+ * Pre-reconnect backup to kill code-500 corruption loop.
+ * Take snapshots before risky operations, restore on corruption.
+ *
+ * @author Kobus Wentzel <kobie@pop.co.za>
+ * @license MIT
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+const noop = () => { };
+export function credsSnapshot(config) {
+    const { credsPath, snapshotDir = path.join(path.dirname(credsPath), '.snapshots'), keep = 3, logger = {}, } = config;
+    const log = {
+        info: logger.info || noop,
+        warn: logger.warn || noop,
+        error: logger.error || noop,
+    };
+    async function take() {
+        try {
+            // Check if creds file exists
+            try {
+                await fs.access(credsPath);
+            }
+            catch {
+                log.warn(`[credsSnapshot] Creds file not found: ${credsPath}`);
+                return null;
+            }
+            // Ensure snapshot dir exists
+            await fs.mkdir(snapshotDir, { recursive: true });
+            // Generate snapshot path
+            const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+            const snapshotPath = path.join(snapshotDir, `creds-${timestamp}.json`);
+            const tmpPath = `${snapshotPath}.tmp`;
+            // Atomic copy: write to .tmp, then rename
+            await fs.copyFile(credsPath, tmpPath);
+            await fs.rename(tmpPath, snapshotPath);
+            log.info(`[credsSnapshot] Snapshot taken: ${snapshotPath}`);
+            // Rotate old snapshots
+            await rotate();
+            return snapshotPath;
+        }
+        catch (err) {
+            log.error(`[credsSnapshot] Failed to take snapshot: ${err}`);
+            return null;
+        }
+    }
+    async function rotate() {
+        try {
+            const snapshots = await list();
+            const toDelete = snapshots.slice(keep);
+            for (const snap of toDelete) {
+                await fs.unlink(snap.path);
+                log.info(`[credsSnapshot] Rotated out: ${snap.path}`);
+            }
+        }
+        catch (err) {
+            log.error(`[credsSnapshot] Rotation failed: ${err}`);
+        }
+    }
+    async function list() {
+        try {
+            await fs.access(snapshotDir);
+        }
+        catch {
+            return [];
+        }
+        try {
+            const files = await fs.readdir(snapshotDir);
+            const snapshots = await Promise.all(files
+                .filter((f) => f.startsWith('creds-') && f.endsWith('.json'))
+                .map(async (f) => {
+                const fullPath = path.join(snapshotDir, f);
+                const stat = await fs.stat(fullPath);
+                // Use file mtime for timestamp (simpler than parsing filename)
+                return {
+                    path: fullPath,
+                    takenAt: stat.mtime,
+                    size: stat.size,
+                };
+            }));
+            // Sort newest first
+            return snapshots.sort((a, b) => b.takenAt.getTime() - a.takenAt.getTime());
+        }
+        catch (err) {
+            log.error(`[credsSnapshot] Failed to list snapshots: ${err}`);
+            return [];
+        }
+    }
+    async function restoreLatest() {
+        const snapshots = await list();
+        if (snapshots.length === 0) {
+            log.warn('[credsSnapshot] No snapshots available to restore');
+            return false;
+        }
+        return restore(snapshots[0].path);
+    }
+    async function restore(snapshotPath) {
+        try {
+            // Verify snapshot exists
+            await fs.access(snapshotPath);
+            // Atomic restore: copy to .tmp, then rename
+            const tmpPath = `${credsPath}.tmp`;
+            await fs.copyFile(snapshotPath, tmpPath);
+            await fs.rename(tmpPath, credsPath);
+            log.info(`[credsSnapshot] Restored from: ${snapshotPath}`);
+            return true;
+        }
+        catch (err) {
+            log.error(`[credsSnapshot] Failed to restore from ${snapshotPath}: ${err}`);
+            return false;
+        }
+    }
+    return {
+        take,
+        restoreLatest,
+        restore,
+        list,
+    };
+}

package/dist/deviceFingerprint.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Device Fingerprint Randomization
+ *
+ * Randomizes appVersion, osVersion, and deviceModel to prevent Meta's
+ * clientPayload fingerprinting. Addresses the #1 gap in anti-ban coverage.
+ *
+ * @author Kobus Wentzel <kobie@pop.co.za>
+ * @license MIT
+ */
+export interface DeviceFingerprintConfig {
+    /** Master switch */
+    enabled?: boolean;
+    /** Vary appVersion patch number within safe range */
+    randomizeAppVersion?: boolean;
+    /** Vary osVersion (Android build string) */
+    randomizeOsVersion?: boolean;
+    /** Pick random deviceModel from real-world device pool */
+    randomizeDeviceModel?: boolean;
+    /** Optional seed for deterministic randomization (testing) */
+    seed?: string;
+    /** User-supplied override pools */
+    appVersionPool?: number[][];
+    osVersionPool?: string[];
+    deviceModelPool?: string[];
+}
+export interface DeviceFingerprint {
+    appVersion: number[];
+    osVersion: string;
+    deviceModel: string;
+    /** Stable across same session, different per session-id */
+    sessionId: string;
+}
+/**
+ * Generate a randomized fingerprint for one session.
+ * Stable for the same sessionId — call once per socket init.
+ */
+export declare function generateFingerprint(config?: DeviceFingerprintConfig, sessionId?: string): DeviceFingerprint;
+/**
+ * Apply fingerprint to a Baileys SocketConfig before makeWASocket().
+ *
+ * Example:
+ *   const fp = generateFingerprint({});
+ *   const sock = makeWASocket(applyFingerprint(socketConfig, fp));
+ */
+export declare function applyFingerprint(socketConfig: any, fp: DeviceFingerprint): any;

package/dist/deviceFingerprint.js

@@ -0,0 +1,106 @@
+/**
+ * Device Fingerprint Randomization
+ *
+ * Randomizes appVersion, osVersion, and deviceModel to prevent Meta's
+ * clientPayload fingerprinting. Addresses the #1 gap in anti-ban coverage.
+ *
+ * @author Kobus Wentzel <kobie@pop.co.za>
+ * @license MIT
+ */
+// Default pools - real-world values observed in the wild
+const DEFAULT_APP_VERSION_POOL = [
+    [2, 24, 5, 18],
+    [2, 24, 5, 17],
+    [2, 24, 4, 77],
+    [2, 24, 5, 15],
+    [2, 24, 3, 91],
+    [2, 24, 5, 20],
+];
+const DEFAULT_OS_VERSION_POOL = ['10', '11', '12', '13', '14'];
+const DEFAULT_DEVICE_MODEL_POOL = [
+    'Pixel 6',
+    'Pixel 7',
+    'Galaxy S22',
+    'Galaxy S23',
+    'Xiaomi 13',
+    'Xiaomi 12',
+    'OnePlus 11',
+    'Moto G84',
+    'Moto G54',
+    'Realme 11',
+    'Vivo V29',
+    'Oppo Find X6',
+];
+/**
+ * Simple deterministic PRNG using mulberry32
+ * Seeded from string hash for consistent results per session
+ */
+class SeededRandom {
+    state;
+    constructor(seed) {
+        // Hash string to 32-bit seed
+        let hash = 0;
+        for (let i = 0; i < seed.length; i++) {
+            hash = (hash << 5) - hash + seed.charCodeAt(i);
+            hash = hash & hash; // Convert to 32-bit int
+        }
+        this.state = Math.abs(hash) || 1;
+    }
+    next() {
+        let t = (this.state += 0x6d2b79f5);
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    }
+    pick(array) {
+        return array[Math.floor(this.next() * array.length)];
+    }
+}
+/**
+ * Generate a randomized fingerprint for one session.
+ * Stable for the same sessionId — call once per socket init.
+ */
+export function generateFingerprint(config = {}, sessionId) {
+    const { enabled = true, randomizeAppVersion = true, randomizeOsVersion = true, randomizeDeviceModel = true, seed, appVersionPool = DEFAULT_APP_VERSION_POOL, osVersionPool = DEFAULT_OS_VERSION_POOL, deviceModelPool = DEFAULT_DEVICE_MODEL_POOL, } = config;
+    const finalSessionId = sessionId || `session-${Date.now()}-${Math.random()}`;
+    const rng = new SeededRandom(seed || finalSessionId);
+    // Pick random values if enabled, otherwise use first pool item
+    const appVersion = enabled && randomizeAppVersion
+        ? rng.pick(appVersionPool)
+        : appVersionPool[0];
+    const osVersion = enabled && randomizeOsVersion ? rng.pick(osVersionPool) : osVersionPool[0];
+    const deviceModel = enabled && randomizeDeviceModel
+        ? rng.pick(deviceModelPool)
+        : deviceModelPool[0];
+    return {
+        appVersion: [...appVersion], // Copy to avoid mutation
+        osVersion,
+        deviceModel,
+        sessionId: finalSessionId,
+    };
+}
+/**
+ * Apply fingerprint to a Baileys SocketConfig before makeWASocket().
+ *
+ * Example:
+ *   const fp = generateFingerprint({});
+ *   const sock = makeWASocket(applyFingerprint(socketConfig, fp));
+ */
+export function applyFingerprint(socketConfig, fp) {
+    // Create defensive copy
+    const config = { ...socketConfig };
+    // Apply version if field exists
+    if (config.version !== undefined || 'version' in config || true) {
+        config.version = fp.appVersion;
+    }
+    // Apply browser tuple if field exists
+    // Baileys browser format: [deviceName, osVersion, appVersion]
+    if (config.browser !== undefined || 'browser' in config || true) {
+        config.browser = [
+            fp.deviceModel,
+            fp.osVersion,
+            `WhatsApp/${fp.appVersion.join('.')}`,
+        ];
+    }
+    return config;
+}

package/dist/index.d.ts

@@ -32,3 +32,6 @@ export { resolveConfig, PRESETS, type AntiBanInput, type ResolvedConfig, type Pr
 export { StateManager, type PersistedState } from './persist.js';
 export { isGroup, isNewsletter, isBroadcast, shouldUseGroupProfile, applyGroupMultiplier, type RateLimits } from './profiles.js';
 export { messageRecovery, type MessageRecoveryConfig, type MessageRecoveryStats, type MessageRecoveryHandle } from './messageRecovery.js';
+export { generateFingerprint, applyFingerprint, type DeviceFingerprint, type DeviceFingerprintConfig, } from './deviceFingerprint.js';
+export { credsSnapshot, type CredsSnapshot, type CredsSnapshotConfig, } from './credsSnapshot.js';
+export { readReceiptVariance, type ReadReceiptVariance, type ReadReceiptVarianceConfig, } from './readReceiptVariance.js';

package/dist/index.js

@@ -43,3 +43,7 @@ export { StateManager } from './persist.js';
 export { isGroup, isNewsletter, isBroadcast, shouldUseGroupProfile, applyGroupMultiplier } from './profiles.js';
 // v3.1 new modules
 export { messageRecovery } from './messageRecovery.js';
+// v3.2 new modules
+export { generateFingerprint, applyFingerprint, } from './deviceFingerprint.js';
+export { credsSnapshot, } from './credsSnapshot.js';
+export { readReceiptVariance, } from './readReceiptVariance.js';

package/dist/readReceiptVariance.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Read Receipt Timing Variance
+ *
+ * Extends presence choreography to randomize read-receipt delay.
+ * Instant reads = bot signal. Gaussian jitter makes reads feel human.
+ *
+ * @author Kobus Wentzel <kobie@pop.co.za>
+ * @license MIT
+ */
+export interface ReadReceiptVarianceConfig {
+    /** Mean delay before sending read receipt, ms */
+    meanMs?: number;
+    /** Standard deviation, ms */
+    stdDevMs?: number;
+    /** Min clamp, ms */
+    minMs?: number;
+    /** Max clamp, ms */
+    maxMs?: number;
+    /** Skip variance for messages older than this (already-read backlog) */
+    skipIfOlderThanMs?: number;
+}
+export interface ReadReceiptVariance {
+    /** Wrap a sock — call sock.readMessages internally with jittered delay */
+    wrap<T extends {
+        readMessages: Function;
+    }>(sock: T): T;
+    /** Manually compute jittered delay (for users wiring their own receipt logic) */
+    delayMs(): number;
+    /** Stop pending timers */
+    stop(): void;
+}
+export declare function readReceiptVariance(config?: ReadReceiptVarianceConfig): ReadReceiptVariance;

package/dist/readReceiptVariance.js

@@ -0,0 +1,88 @@
+/**
+ * Read Receipt Timing Variance
+ *
+ * Extends presence choreography to randomize read-receipt delay.
+ * Instant reads = bot signal. Gaussian jitter makes reads feel human.
+ *
+ * @author Kobus Wentzel <kobie@pop.co.za>
+ * @license MIT
+ */
+/**
+ * Box-Muller transform for Gaussian random samples
+ * Returns a value from normal distribution (mean=0, stdDev=1)
+ */
+function gaussianRandom() {
+    let u = 0;
+    let v = 0;
+    while (u === 0)
+        u = Math.random(); // Avoid log(0)
+    while (v === 0)
+        v = Math.random();
+    return Math.sqrt(-2.0 * Math.log(u)) * Math.cos(2.0 * Math.PI * v);
+}
+export function readReceiptVariance(config = {}) {
+    const { meanMs = 1500, stdDevMs = 800, minMs = 200, maxMs = 8000, skipIfOlderThanMs = 60_000, } = config;
+    const pendingTimers = new Set();
+    function delayMs() {
+        // Generate Gaussian sample and scale to configured mean/stdDev
+        const gaussian = gaussianRandom();
+        const value = meanMs + gaussian * stdDevMs;
+        // Clamp to min/max
+        return Math.max(minMs, Math.min(maxMs, value));
+    }
+    function wrap(sock) {
+        const originalReadMessages = sock.readMessages.bind(sock);
+        // Proxy the readMessages method
+        const wrappedReadMessages = async (keys) => {
+            // Check if messages are too old (backlog)
+            const now = Date.now();
+            const oldMessages = keys.every((key) => {
+                if (!key.messageTimestamp)
+                    return false;
+                const msgTime = typeof key.messageTimestamp === 'number'
+                    ? key.messageTimestamp * 1000 // Baileys uses seconds
+                    : parseInt(key.messageTimestamp, 10) * 1000;
+                return now - msgTime > skipIfOlderThanMs;
+            });
+            if (oldMessages) {
+                // Skip delay for backlog messages
+                return originalReadMessages(keys);
+            }
+            // Apply jittered delay
+            const delay = delayMs();
+            return new Promise((resolve, reject) => {
+                const timer = setTimeout(async () => {
+                    pendingTimers.delete(timer);
+                    try {
+                        const result = await originalReadMessages(keys);
+                        resolve(result);
+                    }
+                    catch (err) {
+                        reject(err);
+                    }
+                }, delay);
+                pendingTimers.add(timer);
+            });
+        };
+        // Return proxy with wrapped readMessages
+        return new Proxy(sock, {
+            get(target, prop) {
+                if (prop === 'readMessages') {
+                    return wrappedReadMessages;
+                }
+                return target[prop];
+            },
+        });
+    }
+    function stop() {
+        for (const timer of pendingTimers) {
+            clearTimeout(timer);
+        }
+        pendingTimers.clear();
+    }
+    return {
+        wrap,
+        delayMs,
+        stop,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baileys-antiban",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Anti-ban middleware for Baileys WhatsApp bots. Rate limiting, warmup, health monitor, LID resolver, disconnect classifier. Free Whapi.Cloud alternative.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",