baileys-antiban 4.6.0 → 4.8.0

package/README.md

@@ -8,9 +8,9 @@
 
 **Drop-in anti-ban middleware for Baileys WhatsApp bots. Free, self-hosted, TypeScript-first. Whapi.Cloud alternative — zero monthly fees.**
 
-> Rate limiting with Gaussian jitter, 7-day warmup, session health monitoring, LID resolver, disconnect classification, contact graph enforcement — all in one `npm install`. Works with [Baileys](https://github.com/WhiskeySockets/Baileys) and [@oxidezap/baileyrs](https://github.com/oxidezap/baileyrs) (Rust/WASM).
+> Rate limiting with Gaussian jitter, 7-day warmup, session health monitoring, LID resolver, disconnect classification, contact graph enforcement, device fingerprinting, group operation guards, recovery orchestration, cross-instance coordination — all in one `npm install`. Works with [Baileys](https://github.com/WhiskeySockets/Baileys) and [@oxidezap/baileyrs](https://github.com/oxidezap/baileyrs) (Rust/WASM).
 
-> **New in v3.3:** [LID Migration Guide](./docs/lid-migration.md) — survive Baileys v7's @lid default with stable thread keys.
+> **New in v4.7:** HumanEntropyService — background human-like activity (typing indicators, delayed read receipts, presence cycles) to prevent "too perfect bot" detection. Works with WaSP and any session manager, no socket access needed.
 
 ## Why Trust This Package
 
@@ -27,6 +27,167 @@ The npm WhatsApp ecosystem has a malware problem. In April 2026, [`lotusbail`](h
 
 If you can't read the code yourself, lean on these signals: signed releases, public audit trail, no telemetry, and a real product behind it. That's the floor. Everything below is the feature set.
 
+## v4.x New Features — Production-Grade Ban Prevention
+
+v4.0–v4.7 ship seven major anti-ban modules. All are **auto-wired** by default via `wrapSocket()` or `wrapSocketWithFingerprint()`.
+
+### v4.0 — GroupOperationGuard
+
+Rate-limits group operations to prevent `account_reachout_restricted` errors. WA limits: ~3 adds/10min, 2 creates/10min.
+
+```typescript
+import { wrapSocket } from 'baileys-antiban';
+
+const sock = wrapSocket(makeWASocket({ ... }), {
+  groupOpGuard: { limits: { add: { max: 3, windowMs: 600_000 } } },
+});
+```
+
+Classify errors: `classifyGroupOpError(err)` returns `GROUP_OP_ERRORS.REACHOUT_RESTRICTED` | `RATE_OVERLIMIT` | `PRIVACY_BLOCK` | etc.  
+Disable: `groupOpGuard: false`
+
+### v4.1 — LegitimacySignalInjector
+
+Injects realistic imperfections: typos + corrections (2.5% of messages), read gaps, mid-typing pauses. WhatsApp's ML flags accounts that are "too perfect".
+
+```typescript
+const sock = wrapSocket(makeWASocket({ ... }), {
+  legitimacySignals: { typoProbability: 0.03 },
+});
+```
+
+Disable: `legitimacySignals: false`
+
+### v4.2 — BanRecoveryOrchestrator
+
+Structured recovery after ban events. Auto-triggers via HealthMonitor at critical risk.
+
+```typescript
+import { BanRecoveryOrchestrator } from 'baileys-antiban';
+
+const recovery = new BanRecoveryOrchestrator({
+  onPhaseChange: (phase, plan) => console.log(`Phase: ${phase}`),
+  onHardBan: () => { /* replace SIM */ },
+});
+
+recovery.triggerRecovery('timelock');
+const status = recovery.getStatus();
+console.log(status.rateMultiplier); // 0.1 = 10% speed
+```
+
+**Recovery plans:** timelock: 24h pause, 10% resume, 15%/week ramp | rate_overlimit: 4h, 25%, 25%/week | soft_ban: 48h, 5%, 10%/week | hard_ban: dead  
+Access via: `antiban.recoveryOrchestrator`
+
+### v4.3 — wrapSocketWithFingerprint
+
+One-call setup with device fingerprint randomization (appVersion, osVersion, deviceModel).
+
+```typescript
+import { wrapSocketWithFingerprint } from 'baileys-antiban';
+
+const sock = wrapSocketWithFingerprint(makeWASocket, { auth }, { preset: 'moderate' });
+```
+
+**Preset changes:** All presets default `groupProfiles: true`; `aggressive`/`high-volume` now `autoPauseAt: 'high'`
+
+### v4.4 — Per-Contact Risk Delays + DeliveryTracker
+
+Strangers get 2.5× delay, known contacts 1.0×. Active when `contactGraph.enabled: true`.
+
+```typescript
+const sock = wrapSocket(makeWASocket({ ... }), { contactGraph: { enabled: true } });
+// stranger: 2.5×, handshake_sent: 1.8×, handshake_complete: 1.3×, known: 1.0×
+```
+
+**DeliveryTracker** tracks double-tick receipts. <60% delivery = soft-ban signal.
+
+```typescript
+import { DeliveryTracker } from 'baileys-antiban';
+
+const tracker = new DeliveryTracker({
+  lowRateThreshold: 0.6,
+  onLowDeliveryRate: (rate) => console.error(`Delivery: ${rate * 100}%`),
+});
+
+sock.ev.on('messages.upsert', ({ messages }) => {
+  messages.forEach(m => m.key.fromMe && tracker.onMessageSent(m.key.id));
+});
+sock.ev.on('messages.update', (updates) => {
+  updates.forEach(({ key, update }) => {
+    if (update.status >= 3) tracker.onDeliveryReceipt(key.id);
+  });
+});
+```
+
+### v4.5 — Adaptive Rate Limiting
+
+Auto-adjusts rate based on delivery success: ≥85% → 100% speed, <55% → 25% speed. Auto-wired.
+
+```typescript
+import { RateLimiter } from 'baileys-antiban';
+
+const limiter = new RateLimiter({ maxPerMinute: 10 });
+limiter.adaptLimits(0.5); // manual throttle to 50%
+const factor = limiter.getCurrentFactor();
+```
+
+### v4.6 — Cross-Instance Coordination
+
+Shared token bucket across processes. Solves: 5 bots × 8/min = 40/min → flag.
+
+```typescript
+const sock = wrapSocket(makeWASocket({ ... }), {
+  instanceCoordinator: '/tmp/wa-pool.json',
+  instancePoolMaxPerMinute: 20,
+});
+```
+
+All instances share 20/min IP-level budget. Atomic writes via rename-swap.
+
+### v4.7 — HumanEntropyService
+
+Background noise generator that makes a WA session indistinguishable from a real human user during idle periods. Runs independently of your message flow — no socket access required, works with WaSP or any session manager.
+
+**The problem it solves:** WhatsApp's ML flags accounts with "too perfect" patterns — instant read receipts, zero typing activity, always-on presence. A listen-only bot that never idles looks like a bot.
+
+**What it does every 2-6 hours (randomized):**
+- Sends typing indicator to a recent contact for 3-8 seconds, then stops (mimics "started typing, changed mind")
+- Marks a received message as read with 10-60 min delay (mimics "opened notification, read later")
+- Toggles own presence available → unavailable over 30-120s (mimics "checked phone, put it down")
+
+**Safety:** Only contacts people who already messaged you first. Never cold-contacts strangers. All errors caught silently.
+
+```typescript
+import { createHumanEntropyService } from 'baileys-antiban';
+
+// Works with WaSP (no direct socket access needed)
+const entropy = createHumanEntropyService(wasp, sessionId, {
+  enabled: true,
+  minIntervalMs: 2 * 60 * 60 * 1000, // 2 hours
+  maxIntervalMs: 6 * 60 * 60 * 1000, // 6 hours
+});
+
+entropy.start(); // runs in background
+entropy.stop();  // call on shutdown
+
+// Or with direct Baileys socket
+import { HumanEntropyService } from 'baileys-antiban';
+const svc = new HumanEntropyService(socket, { enabled: true });
+svc.start();
+```
+
+**Tracking recent contacts:** Feed incoming messages so the service knows who to interact with:
+
+```typescript
+sock.ev.on('messages.upsert', ({ messages }) => {
+  messages.forEach(m => entropy.addRecentContact(m.key.remoteJid, m.key));
+});
+```
+
+Stats: `entropy.getStats()` returns `{ typingActions, readActions, presenceActions, cycles }`.
+
+---
+
 ## v2.0 New Features — Session Stability Module
 
 ### What's New in v2.0

package/dist/antiban.d.ts

@@ -29,6 +29,8 @@ import { BanRecoveryOrchestrator, type RecoveryStatus } from './banRecoveryOrche
 import { type AntiBanInput, type ResolvedConfig } from './presets.js';
 import { type DeliveryTrackerStats } from './deliveryTracker.js';
 import { type InstanceCoordinatorStats } from './instanceCoordinator.js';
+import { MessageTypeRegistry } from './messageTypeRegistry.js';
+import { type AntibanSnapshot } from './stateExport.js';
 export interface AntiBanConfigLegacy {
     rateLimiter?: Partial<RateLimiterConfig>;
     warmUp?: Partial<WarmUpConfig>;
@@ -76,6 +78,10 @@ export interface AntiBanStats {
     banRecovery?: RecoveryStatus | null;
     deliveryTracker: DeliveryTrackerStats;
     instanceCoordinator?: InstanceCoordinatorStats | null;
+    messageRegistry?: {
+        typeCount: number;
+        warningCount: number;
+    } | null;
 }
 export declare class AntiBan {
     private rateLimiter;
@@ -93,6 +99,7 @@ export declare class AntiBan {
     private banRecovery;
     private deliveryTracker;
     private instanceCoordinator;
+    private messageTypeRegistry;
     private stateManager;
     private resolvedConfig;
     private logging;
@@ -161,6 +168,8 @@ export declare class AntiBan {
     get sessionStability(): SessionHealthMonitor | null;
     /** Get the ban recovery orchestrator for direct access */
     get recoveryOrchestrator(): BanRecoveryOrchestrator;
+    /** Get the message type registry for direct access */
+    get messageRegistry(): MessageTypeRegistry | null;
     /**
      * Export warm-up state for persistence between restarts
      */
@@ -180,6 +189,16 @@ export declare class AntiBan {
     private runAdaptiveCheck;
     private persistStateDebounced;
     private persistStateImmediate;
+    /**
+     * Export unified state snapshot for Redis failover or cross-instance migration.
+     * Returns snapshot of all module states (warmup, health, rate limiter, circuits, etc.)
+     */
+    exportState(): AntibanSnapshot;
+    /**
+     * Import unified state snapshot.
+     * CRDT-safe for rate limiters (never overwrites higher counts).
+     */
+    importState(snapshot: AntibanSnapshot): void;
     /**
      * Clean up all timers and resources.
      * Call this when disposing of the AntiBan instance or when the socket closes.

package/dist/antiban.js

@@ -31,6 +31,8 @@ import { StateManager } from './persist.js';
 import { shouldUseGroupProfile, applyGroupMultiplier } from './profiles.js';
 import { DeliveryTracker } from './deliveryTracker.js';
 import { InstanceCoordinator } from './instanceCoordinator.js';
+import { MessageTypeRegistry } from './messageTypeRegistry.js';
+import { exportAntibanState, importAntibanState } from './stateExport.js';
 function isLegacyConfig(cfg) {
     if (typeof cfg !== 'object' || cfg === null)
         return false;
@@ -109,6 +111,7 @@ export class AntiBan {
     banRecovery;
     deliveryTracker;
     instanceCoordinator = null;
+    messageTypeRegistry = null;
     stateManager = null;
     resolvedConfig;
     logging;
@@ -297,6 +300,13 @@ export class AntiBan {
                 console.log(`[baileys-antiban] 🌐 Instance coordination enabled: ${cfg.instanceCoordinator}`);
             }
         }
+        // Initialize message type registry if configured
+        if (cfg.messageTypeRegistry) {
+            this.messageTypeRegistry = new MessageTypeRegistry();
+            if (this.logging) {
+                console.log(`[baileys-antiban] 📝 Message type registry enabled`);
+            }
+        }
     }
     /**
      * Check if a message can be sent and get required delay.
@@ -597,6 +607,13 @@ export class AntiBan {
         if (this.instanceCoordinator) {
             stats.instanceCoordinator = this.instanceCoordinator.getStats();
         }
+        if (this.messageTypeRegistry) {
+            const warnings = this.messageTypeRegistry.getWarnings();
+            stats.messageRegistry = {
+                typeCount: Array.from(this.messageTypeRegistry.types.keys()).length,
+                warningCount: warnings.length,
+            };
+        }
         return stats;
     }
     /** Get the timelock guard for direct access */
@@ -639,6 +656,10 @@ export class AntiBan {
     get recoveryOrchestrator() {
         return this.banRecovery;
     }
+    /** Get the message type registry for direct access */
+    get messageRegistry() {
+        return this.messageTypeRegistry;
+    }
     /**
      * Export warm-up state for persistence between restarts
      */
@@ -731,6 +752,33 @@ export class AntiBan {
         };
         this.stateManager.saveImmediate(state);
     }
+    /**
+     * Export unified state snapshot for Redis failover or cross-instance migration.
+     * Returns snapshot of all module states (warmup, health, rate limiter, circuits, etc.)
+     */
+    exportState() {
+        return exportAntibanState({
+            warmup: this.warmUp,
+            health: this.health,
+            rateLimiter: this.rateLimiter,
+            timelockGuard: this.timelockGuard,
+            messageRegistry: this.messageTypeRegistry || undefined,
+            instanceId: this.resolvedConfig.instanceId,
+        });
+    }
+    /**
+     * Import unified state snapshot.
+     * CRDT-safe for rate limiters (never overwrites higher counts).
+     */
+    importState(snapshot) {
+        importAntibanState(snapshot, {
+            warmup: this.warmUp,
+            health: this.health,
+            rateLimiter: this.rateLimiter,
+            timelockGuard: this.timelockGuard,
+            messageRegistry: this.messageTypeRegistry || undefined,
+        });
+    }
     /**
      * Clean up all timers and resources.
      * Call this when disposing of the AntiBan instance or when the socket closes.
@@ -746,6 +794,7 @@ export class AntiBan {
         this.jidCanonicalizerModule?.destroy();
         this.lidResolverModule?.destroy();
         this.sessionStabilityMonitor?.reset();
+        this.messageTypeRegistry?.cleanup();
         if (this.logging) {
             console.log('[baileys-antiban] 🧹 Destroyed — all timers cleared');
         }

package/dist/cjs/antiban.js

@@ -34,6 +34,8 @@ const persist_js_1 = require("./persist.js");
 const profiles_js_1 = require("./profiles.js");
 const deliveryTracker_js_1 = require("./deliveryTracker.js");
 const instanceCoordinator_js_1 = require("./instanceCoordinator.js");
+const messageTypeRegistry_js_1 = require("./messageTypeRegistry.js");
+const stateExport_js_1 = require("./stateExport.js");
 function isLegacyConfig(cfg) {
     if (typeof cfg !== 'object' || cfg === null)
         return false;
@@ -112,6 +114,7 @@ class AntiBan {
     banRecovery;
     deliveryTracker;
     instanceCoordinator = null;
+    messageTypeRegistry = null;
     stateManager = null;
     resolvedConfig;
     logging;
@@ -300,6 +303,13 @@ class AntiBan {
                 console.log(`[baileys-antiban] 🌐 Instance coordination enabled: ${cfg.instanceCoordinator}`);
             }
         }
+        // Initialize message type registry if configured
+        if (cfg.messageTypeRegistry) {
+            this.messageTypeRegistry = new messageTypeRegistry_js_1.MessageTypeRegistry();
+            if (this.logging) {
+                console.log(`[baileys-antiban] 📝 Message type registry enabled`);
+            }
+        }
     }
     /**
      * Check if a message can be sent and get required delay.
@@ -600,6 +610,13 @@ class AntiBan {
         if (this.instanceCoordinator) {
             stats.instanceCoordinator = this.instanceCoordinator.getStats();
         }
+        if (this.messageTypeRegistry) {
+            const warnings = this.messageTypeRegistry.getWarnings();
+            stats.messageRegistry = {
+                typeCount: Array.from(this.messageTypeRegistry.types.keys()).length,
+                warningCount: warnings.length,
+            };
+        }
         return stats;
     }
     /** Get the timelock guard for direct access */
@@ -642,6 +659,10 @@ class AntiBan {
     get recoveryOrchestrator() {
         return this.banRecovery;
     }
+    /** Get the message type registry for direct access */
+    get messageRegistry() {
+        return this.messageTypeRegistry;
+    }
     /**
      * Export warm-up state for persistence between restarts
      */
@@ -734,6 +755,33 @@ class AntiBan {
         };
         this.stateManager.saveImmediate(state);
     }
+    /**
+     * Export unified state snapshot for Redis failover or cross-instance migration.
+     * Returns snapshot of all module states (warmup, health, rate limiter, circuits, etc.)
+     */
+    exportState() {
+        return (0, stateExport_js_1.exportAntibanState)({
+            warmup: this.warmUp,
+            health: this.health,
+            rateLimiter: this.rateLimiter,
+            timelockGuard: this.timelockGuard,
+            messageRegistry: this.messageTypeRegistry || undefined,
+            instanceId: this.resolvedConfig.instanceId,
+        });
+    }
+    /**
+     * Import unified state snapshot.
+     * CRDT-safe for rate limiters (never overwrites higher counts).
+     */
+    importState(snapshot) {
+        (0, stateExport_js_1.importAntibanState)(snapshot, {
+            warmup: this.warmUp,
+            health: this.health,
+            rateLimiter: this.rateLimiter,
+            timelockGuard: this.timelockGuard,
+            messageRegistry: this.messageTypeRegistry || undefined,
+        });
+    }
     /**
      * Clean up all timers and resources.
      * Call this when disposing of the AntiBan instance or when the socket closes.
@@ -749,6 +797,7 @@ class AntiBan {
         this.jidCanonicalizerModule?.destroy();
         this.lidResolverModule?.destroy();
         this.sessionStabilityMonitor?.reset();
+        this.messageTypeRegistry?.cleanup();
         if (this.logging) {
             console.log('[baileys-antiban] 🧹 Destroyed — all timers cleared');
         }

package/dist/cjs/fleetEventStore.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * Fleet Event Store — Multi-instance coordination via shared event log
+ *
+ * Enables multiple WhatsApp instances to share ban/warn/recovery signals
+ * via a pluggable backend (MySQL, in-memory, etc).
+ *
+ * Architecture:
+ * - EventStoreBackend interface — caller provides storage
+ * - Two built-in backends:
+ *   1. MySQLEventStoreBackend — persistent, multi-instance (peer dep)
+ *   2. InMemoryEventStoreBackend — ephemeral, single-instance, testing
+ *
+ * Usage with MySQL:
+ *   import mysql from 'mysql2/promise';
+ *   const pool = mysql.createPool({ ... });
+ *   const backend = createMySQLEventStoreBackend(pool);
+ *   const store = createFleetEventStore({
+ *     connectionId: 'wa-instance-1',
+ *     backend,
+ *     pollIntervalMs: 10_000
+ *   });
+ *   store.emit('warn', { risk: 'medium' });
+ *   store.startPolling((events) => console.log('New events:', events));
+ *
+ * Usage in-memory (testing):
+ *   const backend = createInMemoryEventStoreBackend();
+ *   const store = createFleetEventStore({ connectionId: 'test', backend });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFleetEventStore = createFleetEventStore;
+exports.createMySQLEventStoreBackend = createMySQLEventStoreBackend;
+exports.createInMemoryEventStoreBackend = createInMemoryEventStoreBackend;
+function createFleetEventStore(config) {
+    const { connectionId, backend, logger } = config;
+    const pollIntervalMs = config.pollIntervalMs ?? 10_000;
+    let lastSeenEpoch = Date.now();
+    let pollTimer = null;
+    const emit = async (eventType, payload) => {
+        const epoch = Date.now();
+        await backend.emit(connectionId, eventType, epoch, payload);
+        logger?.info('[fleet-events] emitted', { connectionId, eventType, epoch });
+    };
+    const startPolling = (onNewEvents) => {
+        if (pollTimer)
+            return;
+        pollTimer = setInterval(() => {
+            void (async () => {
+                try {
+                    const events = await backend.poll(connectionId, lastSeenEpoch);
+                    if (events.length > 0) {
+                        // Update cursor
+                        const maxEpoch = Math.max(...events.map((e) => e.epoch));
+                        lastSeenEpoch = maxEpoch;
+                        onNewEvents(events);
+                    }
+                }
+                catch (error) {
+                    logger?.warn('[fleet-events] poll failed', { connectionId, err: error });
+                }
+            })();
+        }, pollIntervalMs);
+        // @ts-ignore — unref exists on NodeJS.Timeout
+        pollTimer.unref?.();
+        logger?.info('[fleet-events] polling started', { connectionId, pollIntervalMs });
+    };
+    const stop = () => {
+        if (pollTimer) {
+            clearInterval(pollTimer);
+            pollTimer = null;
+            logger?.info('[fleet-events] polling stopped', { connectionId });
+        }
+    };
+    return { emit, startPolling, stop };
+}
+function createMySQLEventStoreBackend(pool) {
+    // Ensure table exists on first emit (idempotent)
+    let tableEnsured = false;
+    const ensureTable = async () => {
+        if (tableEnsured)
+            return;
+        const createTableSQL = `
+      CREATE TABLE IF NOT EXISTS antiban_events (
+        id BIGINT AUTO_INCREMENT PRIMARY KEY,
+        connection_id VARCHAR(255) NOT NULL,
+        event_type VARCHAR(50) NOT NULL,
+        epoch BIGINT NOT NULL,
+        payload JSON,
+        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+        INDEX idx_conn (connection_id),
+        INDEX idx_epoch (epoch)
+      ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
+    `;
+        try {
+            await pool.query(createTableSQL);
+            tableEnsured = true;
+        }
+        catch (error) {
+            // Log but don't throw — table might already exist
+            console.warn('[mysql-backend] table creation failed (may already exist)', error);
+            tableEnsured = true; // Assume it exists
+        }
+    };
+    const emit = async (connectionId, eventType, epoch, payload) => {
+        try {
+            await ensureTable();
+            await pool.execute('INSERT INTO antiban_events (connection_id, event_type, epoch, payload) VALUES (?, ?, ?, ?)', [connectionId, eventType, epoch, payload ? JSON.stringify(payload) : null]);
+        }
+        catch (error) {
+            // Never throw — event emission is non-critical
+            console.warn('[mysql-backend] emit failed', { connectionId, eventType, error });
+        }
+    };
+    const poll = async (connectionId, sinceEpoch) => {
+        try {
+            await ensureTable();
+            const [rows] = (await pool.execute('SELECT id, connection_id, event_type, epoch, payload, created_at FROM antiban_events WHERE connection_id = ? AND epoch > ? ORDER BY epoch ASC LIMIT 50', [connectionId, sinceEpoch]));
+            return rows.map((row) => ({
+                id: row.id,
+                connectionId: row.connection_id,
+                eventType: row.event_type,
+                epoch: row.epoch,
+                payload: row.payload ? JSON.parse(row.payload) : null,
+                createdAt: row.created_at,
+            }));
+        }
+        catch (error) {
+            console.warn('[mysql-backend] poll failed', { connectionId, error });
+            return [];
+        }
+    };
+    return { emit, poll };
+}
+// ===============================
+// Built-in Backend: In-Memory
+// ===============================
+function createInMemoryEventStoreBackend() {
+    const events = [];
+    let nextId = 1;
+    const emit = async (connectionId, eventType, epoch, payload) => {
+        const event = {
+            id: nextId++,
+            connectionId,
+            eventType,
+            epoch,
+            payload: payload || null,
+            createdAt: new Date(),
+        };
+        events.push(event);
+        // Evict oldest if over 1000 entries
+        if (events.length > 1000) {
+            events.shift();
+        }
+    };
+    const poll = async (connectionId, sinceEpoch) => {
+        return events
+            .filter((e) => e.connectionId === connectionId && e.epoch > sinceEpoch)
+            .sort((a, b) => a.epoch - b.epoch)
+            .slice(0, 50);
+    };
+    return { emit, poll };
+}