baileys-antiban 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -5,6 +5,53 @@ 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).
 
+## [1.6.0] - 2026-04-18
+
+### Added
+- **LID/PN Race Condition Mitigation** — New modules to address the #1 reported Baileys bug: "Bad MAC / No Session / Invalid PreKey" errors caused by WhatsApp's Linked Identity (LID) migration
+  - `LidResolver` — Standalone utility for maintaining bidirectional LID↔PN mappings learned from message events
+  - `JidCanonicalizer` — Opt-in middleware that auto-learns from incoming events and canonicalizes outbound send targets to a single form (phone number by default)
+  - Both modules default to **disabled** — backward compatible, zero behavior change for existing users
+  - Middleware-layer mitigation only — root fix still requires [PR #2372](https://github.com/WhiskeySockets/Baileys/pull/2372) merged upstream
+  - Comprehensive test coverage: 56 new tests (29 LidResolver + 18 JidCanonicalizer + 9 integration)
+
+### Changed
+- `AntiBan` class now exposes `lidResolver` and `jidCanonicalizer` getters for direct access
+- `AntiBanConfig` extended with `lidResolver` and `jidCanonicalizer` config options
+- `AntiBanStats` includes `lidResolver` and `jidCanonicalizer` stats when enabled
+- Wrapper's `sendMessage` now canonicalizes JID before all rate-limit/timelock/graph checks
+- `messages.upsert` and `messages.update` handlers now auto-learn LID mappings when canonicalizer enabled
+
+### Technical Details
+- LRU eviction at configurable `maxEntries` (default 10,000)
+- Optional persistence hooks for cross-restart state survival
+- Device suffix stripping (`:N` in JIDs) for robust matching
+- Supports both `canonical: 'pn'` (phone number) and `canonical: 'lid'` modes
+- Shared resolver mode allows multiple canonicalizers to reference same mapping state
+
+## [1.5.0] - 2026-04-18
+
+### Added
+- **RetryReasonTracker** module: Track message retry reasons and detect retry spirals
+  - Classifies 10 retry reason types (no_session, invalid_key, bad_mac, decryption_failure, server_error_463, server_error_429, timeout, no_route, node_malformed, unknown)
+  - Detects retry spirals when same message retries exceed threshold (default: 3)
+  - Provides stats on total retries, retries by reason, spirals detected, and active retries
+  - Auto-integrates with messages.update events in wrapper
+  - Inspired by whatsapp-rust's protocol/retry.rs module
+- **PostReconnectThrottle** module: Throttle outbound messages after reconnection
+  - Prevents burst-floods on reconnect that trigger WhatsApp rate limits
+  - Configurable ramp-up from initial rate multiplier (default: 10%) to full rate over ramp duration (default: 60s)
+  - Linear ramp with configurable steps (default: 6 steps)
+  - Auto-integrates with connection.update events
+  - Inspired by whatsapp-rust's client/sessions.rs semaphore swap pattern
+- Both modules are opt-in (enabled: false by default) for backward compatibility
+
+### Changed
+- `AntiBan.beforeSend()` now also consults reconnect throttle
+- `AntiBan.onReconnect()` triggers reconnect throttle window
+- `AntiBan.getStats()` includes retry tracker and reconnect throttle stats when enabled
+- Wrapper now tracks message updates for retry classification and clears on successful send
+
 ## [1.4.0] - 2026-04-18
 
 ### Added

package/README.md

@@ -6,7 +6,114 @@
 
 **Transport-agnostic** anti-ban middleware — protect your WhatsApp number with human-like messaging patterns. Works with both [Baileys](https://github.com/WhiskeySockets/Baileys) and [@oxidezap/baileyrs](https://github.com/oxidezap/baileyrs) (Rust/WASM).
 
-## v1.3 New Features
+## v1.5 New Features
+
+### RetryReasonTracker
+Tracks message retry reasons and detects retry spirals (when the same message keeps failing). Inspired by whatsapp-rust's protocol/retry.rs module.
+
+```typescript
+import { AntiBan } from 'baileys-antiban';
+
+const antiban = new AntiBan({
+  retryTracker: {
+    enabled: true,
+    maxRetries: 5,           // Max retries before considering a message failed
+    spiralThreshold: 3,      // Retries before warning about retry spiral
+    onSpiral: (msgId, reason) => {
+      console.warn(`Message ${msgId} stuck in retry spiral: ${reason}`);
+    },
+  },
+});
+
+// Stats show retry patterns
+const stats = antiban.getStats().retryTracker;
+console.log(stats.totalRetries);         // Total retries across all messages
+console.log(stats.byReason.timeout);     // Retries due to timeout
+console.log(stats.spiralsDetected);      // Messages stuck in retry loops
+console.log(stats.activeRetries);        // Messages currently retrying
+```
+
+**Retry reasons tracked**: no_session, invalid_key, bad_mac, decryption_failure, server_error_463, server_error_429, timeout, no_route, node_malformed, unknown
+
+### PostReconnectThrottle
+Throttles outbound messages after reconnection to prevent burst-floods that trigger rate limits. Inspired by whatsapp-rust's client/sessions.rs semaphore swap pattern.
+
+```typescript
+const antiban = new AntiBan({
+  reconnectThrottle: {
+    enabled: true,
+    rampDurationMs: 60_000,       // 60s ramp-up to full rate
+    initialRateMultiplier: 0.1,   // Start at 10% of normal rate
+    rampSteps: 6,                 // 10% → 25% → 50% → 75% → 90% → 100%
+  },
+});
+
+// After reconnect, sends are automatically throttled for 60 seconds
+// Ramps from 10% rate to 100% rate linearly over 6 steps
+
+// Stats show throttle state
+const stats = antiban.getStats().reconnectThrottle;
+console.log(stats.isThrottled);          // Currently throttled?
+console.log(stats.currentMultiplier);    // 0.1 to 1.0
+console.log(stats.remainingMs);          // Time until full rate
+console.log(stats.throttledSendCount);   // Sends gated since reconnect
+```
+
+**Why?** When WhatsApp reconnects after a disconnection, sending messages at full rate immediately can trigger rate limit alarms. The reconnect throttle gradually ramps up sending rate over 60 seconds, mimicking how a human would resume messaging after their internet came back.
+
+## LID / Phone Number Canonicalization
+
+WhatsApp migrated to **Linked Identity (LID)** in 2024. A contact now has two JID forms:
+- Phone number: `27825651069@s.whatsapp.net`
+- LID: `123456789@lid`
+
+Messages can arrive under either form. If an encryption session was established under one form and a message arrives under the other, decryption fails → **"Bad MAC / No Session / Invalid PreKey"** errors (the #1 reported Baileys bug).
+
+baileys-antiban v1.6+ provides **middleware-layer mitigation** via two new modules:
+
+```typescript
+import { wrapSocket } from 'baileys-antiban';
+
+const sock = makeWASocket({ ... });
+const safeSock = wrapSocket(sock, {
+  jidCanonicalizer: {
+    enabled: true,  // Enable LID/PN canonicalization
+    canonical: 'pn', // Normalize to phone-number form (default)
+  },
+});
+
+// That's it! Incoming events auto-learn LID↔PN mappings.
+// Outbound sends are auto-canonicalized to phone-number form.
+```
+
+**Advanced: Standalone Resolver**
+
+```typescript
+import { LidResolver } from 'baileys-antiban';
+
+const resolver = new LidResolver({
+  canonical: 'pn',
+  maxEntries: 10_000, // LRU cache size
+  persistence: {
+    load: async () => JSON.parse(await fs.readFile('lid-map.json', 'utf8')),
+    save: async (map) => fs.writeFile('lid-map.json', JSON.stringify(map)),
+  },
+});
+
+// Learn from message events
+resolver.learn({
+  lid: '123456789@lid',
+  pn: '27825651069@s.whatsapp.net',
+});
+
+// Resolve canonical form
+const canonical = resolver.resolveCanonical('123456789@lid');
+// → '27825651069@s.whatsapp.net'
+```
+
+**Note:** This is a middleware-layer workaround. The root fix lives inside Baileys' crypto pipeline ([PR #2372](https://github.com/WhiskeySockets/Baileys/pull/2372)).
+
+## v1.3 Features
 
 ### ReplyRatioGuard
 Tracks outbound:inbound message ratio per contact. Blocks sends to non-responsive contacts to avoid "spray-and-pray" ban patterns. Optionally suggests auto-replies to maintain healthy engagement.
@@ -92,6 +199,8 @@ WhatsApp bans numbers that behave like bots. This library makes your Baileys bot
 - **Reply ratio tracking** (v1.3) — blocks sends to non-responsive contacts
 - **Contact graph enforcement** (v1.3) — requires handshakes before bulk/group sends
 - **Circadian rhythm** (v1.3) — realistic time-of-day activity patterns
+- **Retry tracking** (v1.5) — detect retry spirals and classify retry reasons
+- **Reconnect throttle** (v1.5) — prevent burst-floods after reconnection
 
 ## Supported Transports
 
@@ -223,6 +332,17 @@ const antiban = new AntiBan({
       console.log('Timelock lifted — resuming normal operation');
     },
   },
+  retryTracker: {
+    enabled: false,                  // Opt-in (default: false)
+    maxRetries: 5,
+    spiralThreshold: 3,
+  },
+  reconnectThrottle: {
+    enabled: false,                  // Opt-in (default: false)
+    rampDurationMs: 60_000,
+    initialRateMultiplier: 0.1,
+    rampSteps: 6,
+  },
   logging: true, // Console logging (default: true)
 });
 ```

package/dist/antiban.d.ts

@@ -20,6 +20,10 @@ import { TimelockGuard, type TimelockGuardConfig } from './timelockGuard.js';
 import { ReplyRatioGuard, type ReplyRatioConfig, type ReplyRatioStats } from './replyRatio.js';
 import { ContactGraphWarmer, type ContactGraphConfig, type ContactGraphStats } from './contactGraph.js';
 import { PresenceChoreographer, type PresenceChoreographerConfig, type PresenceChoreographerStats } from './presenceChoreographer.js';
+import { RetryReasonTracker, type RetryTrackerConfig, type RetryStats } from './retryTracker.js';
+import { PostReconnectThrottle, type ReconnectThrottleConfig, type ReconnectThrottleStats } from './reconnectThrottle.js';
+import { LidResolver, type LidResolverConfig, type LidResolverStats } from './lidResolver.js';
+import { JidCanonicalizer, type JidCanonicalizerConfig, type JidCanonicalizerStats } from './jidCanonicalizer.js';
 export interface AntiBanConfig {
     rateLimiter?: Partial<RateLimiterConfig>;
     warmUp?: Partial<WarmUpConfig>;
@@ -28,6 +32,10 @@ export interface AntiBanConfig {
     replyRatio?: Partial<ReplyRatioConfig>;
     contactGraph?: Partial<ContactGraphConfig>;
     presence?: Partial<PresenceChoreographerConfig>;
+    retryTracker?: Partial<RetryTrackerConfig>;
+    reconnectThrottle?: Partial<ReconnectThrottleConfig>;
+    lidResolver?: LidResolverConfig;
+    jidCanonicalizer?: JidCanonicalizerConfig;
     /** Log warnings and blocks to console (default: true) */
     logging?: boolean;
 }
@@ -48,6 +56,10 @@ export interface AntiBanStats {
     replyRatio?: ReplyRatioStats;
     contactGraph?: ContactGraphStats;
     presence?: PresenceChoreographerStats;
+    retryTracker?: RetryStats | null;
+    reconnectThrottle?: ReconnectThrottleStats | null;
+    lidResolver?: LidResolverStats | null;
+    jidCanonicalizer?: JidCanonicalizerStats | null;
 }
 export declare class AntiBan {
     private rateLimiter;
@@ -57,6 +69,10 @@ export declare class AntiBan {
     private replyRatioGuard;
     private contactGraphWarmer;
     private presenceChoreographer;
+    private retryTrackerModule;
+    private reconnectThrottleModule;
+    private lidResolverModule;
+    private jidCanonicalizerModule;
     private logging;
     private stats;
     constructor(config?: AntiBanConfig, warmUpState?: WarmUpState);
@@ -102,6 +118,14 @@ export declare class AntiBan {
     get contactGraph(): ContactGraphWarmer;
     /** Get the presence choreographer for direct access */
     get presence(): PresenceChoreographer;
+    /** Get the retry tracker for direct access */
+    get retryTracker(): RetryReasonTracker;
+    /** Get the reconnect throttle for direct access */
+    get reconnectThrottle(): PostReconnectThrottle;
+    /** Get the LID resolver for direct access */
+    get lidResolver(): LidResolver | null;
+    /** Get the JID canonicalizer for direct access */
+    get jidCanonicalizer(): JidCanonicalizer | null;
     /**
      * Export warm-up state for persistence between restarts
      */

package/dist/antiban.js

@@ -20,6 +20,10 @@ import { TimelockGuard } from './timelockGuard.js';
 import { ReplyRatioGuard } from './replyRatio.js';
 import { ContactGraphWarmer } from './contactGraph.js';
 import { PresenceChoreographer } from './presenceChoreographer.js';
+import { RetryReasonTracker } from './retryTracker.js';
+import { PostReconnectThrottle } from './reconnectThrottle.js';
+import { LidResolver } from './lidResolver.js';
+import { JidCanonicalizer } from './jidCanonicalizer.js';
 export class AntiBan {
     rateLimiter;
     warmUp;
@@ -28,6 +32,10 @@ export class AntiBan {
     replyRatioGuard;
     contactGraphWarmer;
     presenceChoreographer;
+    retryTrackerModule;
+    reconnectThrottleModule;
+    lidResolverModule = null;
+    jidCanonicalizerModule = null;
     logging;
     stats = {
         messagesAllowed: 0,
@@ -69,6 +77,43 @@ export class AntiBan {
         this.replyRatioGuard = new ReplyRatioGuard(config.replyRatio);
         this.contactGraphWarmer = new ContactGraphWarmer(config.contactGraph);
         this.presenceChoreographer = new PresenceChoreographer(config.presence);
+        this.retryTrackerModule = new RetryReasonTracker({
+            ...config.retryTracker,
+            onSpiral: (msgId, reason) => {
+                if (this.logging) {
+                    console.log(`[baileys-antiban] ⚠️  Message ${msgId} stuck in retry spiral (${reason})`);
+                }
+                config.retryTracker?.onSpiral?.(msgId, reason);
+            },
+        });
+        this.reconnectThrottleModule = new PostReconnectThrottle({
+            ...config.reconnectThrottle,
+            baselineRatePerMinute: () => this.rateLimiter.getStats().limits.perMinute,
+        });
+        // Initialize LID resolver and canonicalizer if configured
+        // If jidCanonicalizer is enabled but no resolver provided, create standalone resolver
+        if (config.jidCanonicalizer?.enabled) {
+            // Create or use provided resolver
+            if (config.jidCanonicalizer.resolver) {
+                // User provided their own resolver
+                this.jidCanonicalizerModule = new JidCanonicalizer(config.jidCanonicalizer);
+                this.lidResolverModule = config.jidCanonicalizer.resolver;
+            }
+            else {
+                // Create new resolver using lidResolver config if provided
+                const resolverConfig = config.lidResolver || config.jidCanonicalizer.resolverConfig;
+                const resolver = new LidResolver(resolverConfig);
+                this.lidResolverModule = resolver;
+                this.jidCanonicalizerModule = new JidCanonicalizer({
+                    ...config.jidCanonicalizer,
+                    resolver,
+                });
+            }
+        }
+        else if (config.lidResolver) {
+            // Standalone resolver without canonicalizer
+            this.lidResolverModule = new LidResolver(config.lidResolver);
+        }
     }
     /**
      * Check if a message can be sent and get required delay.
@@ -146,6 +191,20 @@ export class AntiBan {
                 health: healthStatus,
             };
         }
+        // Reconnect throttle check
+        const reconnectThrottleDecision = this.reconnectThrottleModule.beforeSend();
+        if (!reconnectThrottleDecision.allowed) {
+            this.stats.messagesBlocked++;
+            if (this.logging) {
+                console.log(`[baileys-antiban] 🔄 BLOCKED — reconnect throttle: ${reconnectThrottleDecision.reason}`);
+            }
+            return {
+                allowed: false,
+                delayMs: reconnectThrottleDecision.retryAfterMs || 0,
+                reason: reconnectThrottleDecision.reason || 'Post-reconnect throttle',
+                health: healthStatus,
+            };
+        }
         // Rate limiter delay
         let delay = await this.rateLimiter.getDelay(recipient, content);
         if (delay === -1) {
@@ -211,12 +270,14 @@ export class AntiBan {
      */
     onDisconnect(reason) {
         this.health.recordDisconnect(reason);
+        this.reconnectThrottleModule.onDisconnect();
     }
     /**
      * Record a successful reconnection
      */
     onReconnect() {
         this.health.recordReconnect();
+        this.reconnectThrottleModule.onReconnect();
     }
     /**
      * Handle incoming message — record in reply ratio + contact graph.
@@ -247,6 +308,18 @@ export class AntiBan {
         if (this.presenceChoreographer['config']?.enabled) {
             stats.presence = this.presenceChoreographer.getStats();
         }
+        if (this.retryTrackerModule['config']?.enabled) {
+            stats.retryTracker = this.retryTrackerModule.getStats();
+        }
+        if (this.reconnectThrottleModule['config']?.enabled) {
+            stats.reconnectThrottle = this.reconnectThrottleModule.getStats();
+        }
+        if (this.lidResolverModule) {
+            stats.lidResolver = this.lidResolverModule.getStats();
+        }
+        if (this.jidCanonicalizerModule) {
+            stats.jidCanonicalizer = this.jidCanonicalizerModule.getStats();
+        }
         return stats;
     }
     /** Get the timelock guard for direct access */
@@ -265,6 +338,22 @@ export class AntiBan {
     get presence() {
         return this.presenceChoreographer;
     }
+    /** Get the retry tracker for direct access */
+    get retryTracker() {
+        return this.retryTrackerModule;
+    }
+    /** Get the reconnect throttle for direct access */
+    get reconnectThrottle() {
+        return this.reconnectThrottleModule;
+    }
+    /** Get the LID resolver for direct access */
+    get lidResolver() {
+        return this.lidResolverModule;
+    }
+    /** Get the JID canonicalizer for direct access */
+    get jidCanonicalizer() {
+        return this.jidCanonicalizerModule;
+    }
     /**
      * Export warm-up state for persistence between restarts
      */
@@ -299,6 +388,8 @@ export class AntiBan {
         this.replyRatioGuard.reset();
         this.contactGraphWarmer.reset();
         this.presenceChoreographer.reset();
+        this.retryTrackerModule.destroy();
+        this.reconnectThrottleModule.destroy();
         this.stats = { messagesAllowed: 0, messagesBlocked: 0, totalDelayMs: 0 };
         if (this.logging) {
             console.log('[baileys-antiban] 🔄 Reset — starting fresh warm-up');
@@ -313,6 +404,10 @@ export class AntiBan {
         this.replyRatioGuard.reset();
         this.contactGraphWarmer.reset();
         this.presenceChoreographer.reset();
+        this.retryTrackerModule.destroy();
+        this.reconnectThrottleModule.destroy();
+        this.jidCanonicalizerModule?.destroy();
+        this.lidResolverModule?.destroy();
         if (this.logging) {
             console.log('[baileys-antiban] 🧹 Destroyed — all timers cleared');
         }

package/dist/index.d.ts

@@ -15,6 +15,10 @@ export { TimelockGuard, type TimelockGuardConfig, type TimelockState } from './t
 export { ReplyRatioGuard, type ReplyRatioConfig, type ReplyRatioStats } from './replyRatio.js';
 export { ContactGraphWarmer, type ContactGraphConfig, type ContactGraphStats, type ContactState } from './contactGraph.js';
 export { PresenceChoreographer, type PresenceChoreographerConfig, type PresenceChoreographerStats } from './presenceChoreographer.js';
+export { RetryReasonTracker, type RetryTrackerConfig, type RetryStats, type RetryReason } from './retryTracker.js';
+export { PostReconnectThrottle, type ReconnectThrottleConfig, type ReconnectThrottleStats } from './reconnectThrottle.js';
+export { LidResolver, type LidResolverConfig, type LidResolverStats, type LidMapping } from './lidResolver.js';
+export { JidCanonicalizer, type JidCanonicalizerConfig, type JidCanonicalizerStats } from './jidCanonicalizer.js';
 export { wrapSocket, type WrappedSocket, type WrapSocketOptions } from './wrapper.js';
 export { MessageQueue, type QueuedMessage, type MessageQueueConfig } from './messageQueue.js';
 export { ContentVariator, type VariatorConfig } from './contentVariator.js';

package/dist/index.js

@@ -17,6 +17,12 @@ export { TimelockGuard } from './timelockGuard.js';
 export { ReplyRatioGuard } from './replyRatio.js';
 export { ContactGraphWarmer } from './contactGraph.js';
 export { PresenceChoreographer } from './presenceChoreographer.js';
+// v1.5 new modules
+export { RetryReasonTracker } from './retryTracker.js';
+export { PostReconnectThrottle } from './reconnectThrottle.js';
+// v1.6 new modules
+export { LidResolver } from './lidResolver.js';
+export { JidCanonicalizer } from './jidCanonicalizer.js';
 // Socket wrapper
 export { wrapSocket } from './wrapper.js';
 // Optional features

package/dist/jidCanonicalizer.d.ts

@@ -0,0 +1,78 @@
+/**
+ * JID Canonicalizer — Opt-in middleware for LID/PN normalization
+ *
+ * Wraps LidResolver to provide automatic:
+ * 1. Learning from incoming message events
+ * 2. Canonicalization of outbound send targets
+ *
+ * This mitigates the LID/PN race condition that causes "Bad MAC / No Session /
+ * Invalid PreKey" errors (Baileys issue #1769, our PR #2372).
+ *
+ * Usage:
+ *   const canonicalizer = new JidCanonicalizer({ enabled: true });
+ *
+ *   // On incoming event
+ *   canonicalizer.onIncomingEvent({ messages: [...] });
+ *
+ *   // On outbound send
+ *   const canonicalJid = canonicalizer.canonicalizeTarget(jid);
+ *   await sock.sendMessage(canonicalJid, content);
+ *
+ * Note: This is a middleware-layer mitigation. The root fix requires merging
+ * PR #2372 into Baileys' crypto pipeline.
+ */
+import { LidResolver, type LidResolverConfig, type LidResolverStats } from './lidResolver.js';
+export interface JidCanonicalizerConfig {
+    /** Enable canonicalization (default: false — opt-in) */
+    enabled?: boolean;
+    /** Provide your own resolver to share across modules. Otherwise one is created. */
+    resolver?: LidResolver;
+    /** Config for creating a new resolver (ignored if resolver provided) */
+    resolverConfig?: LidResolverConfig;
+    /** Canonicalize outbound sendMessage targets. Default true. */
+    canonicalizeOutbound?: boolean;
+    /** Learn from inbound events. Default true. */
+    learnFromEvents?: boolean;
+}
+export interface JidCanonicalizerStats {
+    resolver: LidResolverStats;
+    outboundCanonicalized: number;
+    outboundPassthrough: number;
+    inboundLearned: number;
+}
+export declare class JidCanonicalizer {
+    private config;
+    private lidResolver;
+    private ownsResolver;
+    private stats;
+    constructor(config?: JidCanonicalizerConfig);
+    /**
+     * Access the underlying resolver (for cross-module sharing)
+     */
+    get resolver(): LidResolver;
+    /**
+     * Called by wrapper on every outbound send. Returns canonical JID.
+     */
+    canonicalizeTarget(jid: string): string;
+    /**
+     * Called by wrapper on messages.upsert event. Learns mappings.
+     */
+    onIncomingEvent(upsert: {
+        messages: Array<any>;
+        type?: string;
+    }): void;
+    /**
+     * Called by wrapper on messages.update event. Learns from sent-message refs.
+     */
+    onMessageUpdate(updates: Array<any>): void;
+    getStats(): JidCanonicalizerStats;
+    destroy(): void;
+    /**
+     * Extract LID↔PN mappings from a message object
+     */
+    private learnFromMessage;
+    /**
+     * Extract mappings from message.key
+     */
+    private learnFromMessageKey;
+}