baileys-antiban 3.8.11 → 4.6.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ 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.8.11] - 2026-05-19
+
+### Security
+- **persist.ts**: Resolve state file path to absolute (`path.resolve()`), reject null bytes. Add strict JSON shape validation (version, savedAt, knownChats types) before trusting loaded state — prevents type confusion from corrupt or tampered files.
+- **proxyRotator.ts**: Replace `(0, eval)('require')` and `(0, eval)('import.meta.url')` with `new Function()` on static literal strings in the ESM code path. Not user-controlled, but removes the indirect eval chain for static analysis and CSP compliance.
+
+### Fixed
+- **rateLimiter.ts**: Added LRU size cap (10,000 entries) to `identicalCount` Map. Time-window eviction alone allowed unbounded growth when sending many unique messages; oldest-by-lastSeen entries are now evicted when the cap is exceeded.
+- **antiban.ts**: Extend `mapLegacyToFlat()` to preserve `autoPauseAt`, `groupMultiplier`, `groupProfiles`, `persist` from flat top-level fields when legacy config detection fires — completing the coverage from 3.8.9.
+
+### Changed (3.8.10)
+- README: Expanded v3 flat config example with all `ResolvedConfig` fields; added correct `deafSession` wrapOptions (4th arg) example; marked nested Configuration section as deprecated.
+- Tests: 4 new v3 test cases covering `maxIdenticalMessages`/`burstAllowance` forwarding, mixed legacy+flat preservation, `getConfig()`.
+- CHANGELOG: Added missing 3.8.9 entry.
+
 ## [3.8.9] - 2026-05-19
 
 ### Fixed

package/dist/antiban.d.ts

@@ -25,7 +25,10 @@ import { PostReconnectThrottle, type ReconnectThrottleConfig, type ReconnectThro
 import { LidResolver, type LidResolverConfig, type LidResolverStats } from './lidResolver.js';
 import { JidCanonicalizer, type JidCanonicalizerConfig, type JidCanonicalizerStats } from './jidCanonicalizer.js';
 import { SessionHealthMonitor, type SessionHealthStats } from './sessionStability.js';
+import { BanRecoveryOrchestrator, type RecoveryStatus } from './banRecoveryOrchestrator.js';
 import { type AntiBanInput, type ResolvedConfig } from './presets.js';
+import { type DeliveryTrackerStats } from './deliveryTracker.js';
+import { type InstanceCoordinatorStats } from './instanceCoordinator.js';
 export interface AntiBanConfigLegacy {
     rateLimiter?: Partial<RateLimiterConfig>;
     warmUp?: Partial<WarmUpConfig>;
@@ -70,6 +73,9 @@ export interface AntiBanStats {
     lidResolver?: LidResolverStats | null;
     jidCanonicalizer?: JidCanonicalizerStats | null;
     sessionStability?: SessionHealthStats | null;
+    banRecovery?: RecoveryStatus | null;
+    deliveryTracker: DeliveryTrackerStats;
+    instanceCoordinator?: InstanceCoordinatorStats | null;
 }
 export declare class AntiBan {
     private rateLimiter;
@@ -84,6 +90,9 @@ export declare class AntiBan {
     private lidResolverModule;
     private jidCanonicalizerModule;
     private sessionStabilityMonitor;
+    private banRecovery;
+    private deliveryTracker;
+    private instanceCoordinator;
     private stateManager;
     private resolvedConfig;
     private logging;
@@ -98,7 +107,7 @@ export declare class AntiBan {
      * Record a successfully sent message.
      * Call this AFTER every successful sendMessage().
      */
-    afterSend(recipient: string, content: string): void;
+    afterSend(recipient: string, content: string, msgId?: string): void;
     /**
      * Record a failed message send
      */
@@ -119,6 +128,11 @@ export declare class AntiBan {
         shouldReply: boolean;
         suggestedText?: string;
     };
+    /**
+     * Record a delivery receipt (status 3 = DELIVERY_ACK, status 4 = READ).
+     * Call from messages.update handler when delivery status is received.
+     */
+    onDeliveryReceipt(msgId: string): void;
     /**
      * Get the resolved configuration
      */
@@ -145,6 +159,8 @@ export declare class AntiBan {
     get jidCanonicalizer(): JidCanonicalizer | null;
     /** Get the session stability monitor for direct access */
     get sessionStability(): SessionHealthMonitor | null;
+    /** Get the ban recovery orchestrator for direct access */
+    get recoveryOrchestrator(): BanRecoveryOrchestrator;
     /**
      * Export warm-up state for persistence between restarts
      */
@@ -161,6 +177,7 @@ export declare class AntiBan {
      * Reset everything (use after a ban period)
      */
     reset(): void;
+    private runAdaptiveCheck;
     private persistStateDebounced;
     private persistStateImmediate;
     /**

package/dist/antiban.js

@@ -25,9 +25,12 @@ import { PostReconnectThrottle } from './reconnectThrottle.js';
 import { LidResolver } from './lidResolver.js';
 import { JidCanonicalizer } from './jidCanonicalizer.js';
 import { SessionHealthMonitor } from './sessionStability.js';
+import { BanRecoveryOrchestrator } from './banRecoveryOrchestrator.js';
 import { resolveConfig } from './presets.js';
 import { StateManager } from './persist.js';
 import { shouldUseGroupProfile, applyGroupMultiplier } from './profiles.js';
+import { DeliveryTracker } from './deliveryTracker.js';
+import { InstanceCoordinator } from './instanceCoordinator.js';
 function isLegacyConfig(cfg) {
     if (typeof cfg !== 'object' || cfg === null)
         return false;
@@ -103,6 +106,9 @@ export class AntiBan {
     lidResolverModule = null;
     jidCanonicalizerModule = null;
     sessionStabilityMonitor = null;
+    banRecovery;
+    deliveryTracker;
+    instanceCoordinator = null;
     stateManager = null;
     resolvedConfig;
     logging;
@@ -170,23 +176,54 @@ export class AntiBan {
                     console.log(`[baileys-antiban] ${status.recommendation}`);
                     status.reasons.forEach(r => console.log(`[baileys-antiban]   → ${r}`));
                 }
-                // Call original callback if present
+                if ((status.risk === 'high' || status.risk === 'critical') && cfg.onAtRisk) {
+                    cfg.onAtRisk(status);
+                }
+                // Trigger recovery orchestrator on critical risk
+                if (status.risk === 'critical') {
+                    this.banRecovery.recordBanEvent('soft_ban');
+                }
+                cfg.onRiskChange?.(status);
                 legacyPassthrough?.health?.onRiskChange?.(status);
             },
         });
+        // Initialize ban recovery orchestrator
+        this.banRecovery = new BanRecoveryOrchestrator({
+            onPhaseChange: (phase, plan) => {
+                if (this.logging) {
+                    console.log(`[baileys-antiban] 🔄 Recovery phase: ${phase} — ${plan.description}`);
+                }
+            },
+            onHardBan: () => {
+                if (this.logging) {
+                    console.log(`[baileys-antiban] 💀 HARD BAN detected — account likely dead, replace SIM`);
+                }
+            },
+        });
+        // Initialize delivery tracker
+        this.deliveryTracker = new DeliveryTracker({
+            onLowDeliveryRate: (rate) => {
+                if (this.logging) {
+                    console.log(`[baileys-antiban] ⚠️  Low delivery rate detected: ${Math.round(rate * 100)}% — possible soft ban`);
+                }
+            },
+        });
         this.timelockGuard = new TimelockGuard({
             ...(legacyPassthrough?.timelock || {}),
             onTimelockDetected: (state) => {
                 this.health.recordReachoutTimelock(state.enforcementType);
+                this.banRecovery.recordBanEvent('timelock');
                 if (this.logging) {
                     console.log(`[baileys-antiban] REACHOUT TIMELOCKED — ${state.enforcementType || 'unknown'}, expires ${state.expiresAt?.toISOString() || 'unknown'}`);
                 }
+                cfg.onTimelockDetected?.(state);
                 legacyPassthrough?.timelock?.onTimelockDetected?.(state);
             },
             onTimelockLifted: (state) => {
                 if (this.logging) {
                     console.log(`[baileys-antiban] Timelock lifted — resuming new contact messages`);
                 }
+                cfg.onTimelockLifted?.(state);
                 legacyPassthrough?.timelock?.onTimelockLifted?.(state);
             },
         });
@@ -249,6 +286,17 @@ export class AntiBan {
             };
             this.sessionStabilityMonitor = new SessionHealthMonitor(healthConfig);
         }
+        // Initialize instance coordinator if configured
+        if (cfg.instanceCoordinator) {
+            this.instanceCoordinator = new InstanceCoordinator({
+                sharedFilePath: cfg.instanceCoordinator,
+                poolMaxPerMinute: cfg.instancePoolMaxPerMinute,
+                poolMaxPerHour: cfg.instancePoolMaxPerHour,
+            });
+            if (this.logging) {
+                console.log(`[baileys-antiban] 🌐 Instance coordination enabled: ${cfg.instanceCoordinator}`);
+            }
+        }
     }
     /**
      * Check if a message can be sent and get required delay.
@@ -269,6 +317,17 @@ export class AntiBan {
                 health: healthStatus,
             };
         }
+        // Recovery orchestrator rate multiplier
+        const recoveryStatus = this.banRecovery.getStatus();
+        if (recoveryStatus.phase === 'paused') {
+            this.stats.messagesBlocked++;
+            return {
+                allowed: false,
+                delayMs: recoveryStatus.pauseRemainingMs || 0,
+                reason: `Ban recovery: ${recoveryStatus.recommendation}`,
+                health: healthStatus,
+            };
+        }
         // Timelock guard (allows existing chats, blocks new contacts)
         const timelockDecision = this.timelockGuard.canSend(recipient);
         if (!timelockDecision.allowed) {
@@ -340,6 +399,22 @@ export class AntiBan {
                 health: healthStatus,
             };
         }
+        // Cross-instance coordination — check shared IP-level pool
+        if (this.instanceCoordinator) {
+            const slot = this.instanceCoordinator.tryAcquireSlot();
+            if (!slot.allowed) {
+                this.stats.messagesBlocked++;
+                if (this.logging) {
+                    console.log(`[baileys-antiban] 🌐 BLOCKED — instance pool exhausted (shared IP limit), retry in ${slot.retryAfterMs}ms`);
+                }
+                return {
+                    allowed: false,
+                    delayMs: slot.retryAfterMs || 5000,
+                    reason: 'Cross-instance rate pool exhausted',
+                    health: healthStatus,
+                };
+            }
+        }
         // Group profile rate check (runs before rateLimiter.getDelay for timing)
         if (this.resolvedConfig.groupProfiles && shouldUseGroupProfile(recipient)) {
             const groupLimits = applyGroupMultiplier({
@@ -379,6 +454,24 @@ export class AntiBan {
             const multiplier = Math.min(5, 1 / activityFactor);
             delay = Math.floor(delay * multiplier);
         }
+        // Per-contact risk multiplier — cold contacts need longer delays
+        // Only apply when contact graph is enabled, otherwise all contacts appear as 'stranger'
+        if (this.contactGraphWarmer['config']?.enabled) {
+            const contactState = this.contactGraphWarmer.getContactState(recipient);
+            const coldMultiplier = {
+                stranger: 2.5,
+                handshake_sent: 1.8,
+                handshake_complete: 1.3,
+                known: 1.0,
+            };
+            const contactRiskMult = coldMultiplier[contactState] ?? 1.0;
+            if (contactRiskMult > 1.0) {
+                delay = Math.floor(delay * contactRiskMult);
+                if (this.logging && contactRiskMult >= 2.0) {
+                    console.log(`[baileys-antiban] ⚠️  Cold contact ${recipient} — ${contactState}, delay ×${contactRiskMult}`);
+                }
+            }
+        }
         // Roll for distraction pause
         const distractionCheck = this.presenceChoreographer.shouldPauseForDistraction();
         if (distractionCheck.pause) {
@@ -406,11 +499,15 @@ export class AntiBan {
      * Record a successfully sent message.
      * Call this AFTER every successful sendMessage().
      */
-    afterSend(recipient, content) {
+    afterSend(recipient, content, msgId) {
         this.rateLimiter.record(recipient, content);
         this.warmUp.record();
         this.replyRatioGuard.recordSent(recipient);
         this.stats.messagesAllowed++;
+        if (msgId) {
+            this.deliveryTracker.onMessageSent(msgId);
+        }
+        this.runAdaptiveCheck();
         this.persistStateDebounced();
     }
     /**
@@ -436,6 +533,7 @@ export class AntiBan {
     onReconnect() {
         this.health.recordReconnect();
         this.reconnectThrottleModule.onReconnect();
+        this.rateLimiter.adaptLimits(1.0);
     }
     /**
      * Handle incoming message — record in reply ratio + contact graph.
@@ -446,6 +544,13 @@ export class AntiBan {
         this.contactGraphWarmer.onIncomingMessage(jid);
         return this.replyRatioGuard.suggestReply(jid, msgText);
     }
+    /**
+     * Record a delivery receipt (status 3 = DELIVERY_ACK, status 4 = READ).
+     * Call from messages.update handler when delivery status is received.
+     */
+    onDeliveryReceipt(msgId) {
+        this.deliveryTracker.onDeliveryReceipt(msgId);
+    }
     /**
      * Get the resolved configuration
      */
@@ -461,6 +566,8 @@ export class AntiBan {
             health: this.health.getStatus(),
             warmUp: this.warmUp.getStatus(),
             rateLimiter: this.rateLimiter.getStats(),
+            banRecovery: this.banRecovery.getStatus(),
+            deliveryTracker: this.deliveryTracker.getStats(),
         };
         // Only include new stats if enabled
         if (this.replyRatioGuard['config']?.enabled) {
@@ -487,6 +594,9 @@ export class AntiBan {
         if (this.sessionStabilityMonitor) {
             stats.sessionStability = this.sessionStabilityMonitor.getStats();
         }
+        if (this.instanceCoordinator) {
+            stats.instanceCoordinator = this.instanceCoordinator.getStats();
+        }
         return stats;
     }
     /** Get the timelock guard for direct access */
@@ -525,6 +635,10 @@ export class AntiBan {
     get sessionStability() {
         return this.sessionStabilityMonitor;
     }
+    /** Get the ban recovery orchestrator for direct access */
+    get recoveryOrchestrator() {
+        return this.banRecovery;
+    }
     /**
      * Export warm-up state for persistence between restarts
      */
@@ -566,6 +680,35 @@ export class AntiBan {
             console.log('[baileys-antiban] 🔄 Reset — starting fresh warm-up');
         }
     }
+    runAdaptiveCheck() {
+        const delivery = this.deliveryTracker.getStats();
+        // Need min sample to be meaningful
+        if (delivery.deliveryRate === null)
+            return;
+        const rate = delivery.deliveryRate;
+        let targetFactor;
+        if (rate >= 0.85) {
+            targetFactor = 1.0; // Excellent — full speed
+        }
+        else if (rate >= 0.70) {
+            targetFactor = 0.75; // Good — slight reduction
+        }
+        else if (rate >= 0.55) {
+            targetFactor = 0.50; // Poor — halve throughput
+        }
+        else {
+            targetFactor = 0.25; // Bad — severe throttle (soft ban likely)
+        }
+        const current = this.rateLimiter.getCurrentFactor();
+        // Only log + adjust when factor changes meaningfully (>5% delta)
+        if (Math.abs(targetFactor - current) > 0.05) {
+            if (this.logging) {
+                const dir = targetFactor > current ? '📈' : '📉';
+                console.log(`[baileys-antiban] ${dir} Adaptive rate: delivery=${(rate * 100).toFixed(0)}% → factor ${current.toFixed(2)}→${targetFactor.toFixed(2)}`);
+            }
+            this.rateLimiter.adaptLimits(targetFactor);
+        }
+    }
     persistStateDebounced() {
         if (!this.stateManager)
             return;

package/dist/banRecoveryOrchestrator.d.ts

@@ -0,0 +1,87 @@
+/**
+ * BanRecoveryOrchestrator — Structured recovery after ban/restriction events
+ *
+ * When WhatsApp restricts your account, the worst thing to do is immediately
+ * resume normal activity. This module provides a evidence-based recovery protocol:
+ *
+ * - Timelocked (reachout_restricted): 24h pause, resume at 10% rate, ramp 15%/week
+ * - Rate-overlimit (429): 4h pause, resume at 25% rate, ramp 25%/week
+ * - Soft-ban (repeated disconnects): 48h pause, resume at 5% rate, ramp 10%/week
+ * - Hard-ban (loggedOut): account is dead, signal for replacement
+ *
+ * Based on observed recovery times from community reports. Not guaranteed —
+ * WA's enforcement is non-deterministic. Treat as best-effort guidance.
+ */
+export type BanEventType = 'timelock' | 'rate_overlimit' | 'soft_ban' | 'hard_ban';
+export type RecoveryPhase = 'paused' | 'recovering' | 'ramping' | 'graduated' | 'dead';
+export interface RecoveryPlan {
+    eventType: BanEventType;
+    pauseDurationMs: number;
+    resumeRateMultiplier: number;
+    weeklyRampPercent: number;
+    estimatedRecoveryDays: number;
+    description: string;
+}
+export interface BanRecoveryConfig {
+    /** Custom recovery plans per event type (overrides defaults) */
+    plans?: Partial<Record<BanEventType, Partial<RecoveryPlan>>>;
+    /** Called when recovery phase changes */
+    onPhaseChange?: (phase: RecoveryPhase, plan: RecoveryPlan) => void;
+    /** Called when account appears dead (hard ban) — signal to replace SIM */
+    onHardBan?: () => void;
+    /** Max weeks before giving up on recovery and declaring dead (default: 8) */
+    maxRecoveryWeeks?: number;
+}
+export interface RecoveryState {
+    active: boolean;
+    eventType?: BanEventType;
+    phase: RecoveryPhase;
+    banDetectedAt?: number;
+    pauseUntil?: number;
+    currentRateMultiplier: number;
+    weeksSinceResume: number;
+    banCount30d: number;
+    lastBanAt?: number;
+}
+export interface RecoveryStatus {
+    phase: RecoveryPhase;
+    rateMultiplier: number;
+    pauseRemainingMs?: number;
+    estimatedFullRecoveryDate?: number;
+    recommendation: string;
+    shouldReplaceNumber: boolean;
+}
+export declare class BanRecoveryOrchestrator {
+    private config;
+    private state;
+    private plans;
+    constructor(config?: BanRecoveryConfig);
+    /**
+     * Record a ban event and start recovery protocol
+     */
+    recordBanEvent(eventType: BanEventType): RecoveryStatus;
+    /**
+     * Get current recovery status (call before sending to check rate)
+     */
+    getStatus(): RecoveryStatus;
+    /**
+     * Current rate multiplier — multiply your normal limits by this
+     */
+    getRateMultiplier(): number;
+    /**
+     * Should be called daily/weekly to advance the ramp
+     */
+    tick(): void;
+    /**
+     * Classify a raw error into a BanEventType
+     */
+    static classifyError(err: unknown): BanEventType | null;
+    /**
+     * Serializable state for persistence
+     */
+    getState(): RecoveryState;
+    /**
+     * Restore from persisted state
+     */
+    static fromState(state: RecoveryState, config?: BanRecoveryConfig): BanRecoveryOrchestrator;
+}