baileys-antiban 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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

package/README.md

@@ -61,6 +61,58 @@ 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

package/dist/antiban.d.ts

@@ -22,6 +22,8 @@ import { ContactGraphWarmer, type ContactGraphConfig, type ContactGraphStats } f
 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>;
@@ -32,6 +34,8 @@ export interface AntiBanConfig {
     presence?: Partial<PresenceChoreographerConfig>;
     retryTracker?: Partial<RetryTrackerConfig>;
     reconnectThrottle?: Partial<ReconnectThrottleConfig>;
+    lidResolver?: LidResolverConfig;
+    jidCanonicalizer?: JidCanonicalizerConfig;
     /** Log warnings and blocks to console (default: true) */
     logging?: boolean;
 }
@@ -54,6 +58,8 @@ export interface AntiBanStats {
     presence?: PresenceChoreographerStats;
     retryTracker?: RetryStats | null;
     reconnectThrottle?: ReconnectThrottleStats | null;
+    lidResolver?: LidResolverStats | null;
+    jidCanonicalizer?: JidCanonicalizerStats | null;
 }
 export declare class AntiBan {
     private rateLimiter;
@@ -65,6 +71,8 @@ export declare class AntiBan {
     private presenceChoreographer;
     private retryTrackerModule;
     private reconnectThrottleModule;
+    private lidResolverModule;
+    private jidCanonicalizerModule;
     private logging;
     private stats;
     constructor(config?: AntiBanConfig, warmUpState?: WarmUpState);
@@ -114,6 +122,10 @@ export declare class AntiBan {
     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

@@ -22,6 +22,8 @@ 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;
@@ -32,6 +34,8 @@ export class AntiBan {
     presenceChoreographer;
     retryTrackerModule;
     reconnectThrottleModule;
+    lidResolverModule = null;
+    jidCanonicalizerModule = null;
     logging;
     stats = {
         messagesAllowed: 0,
@@ -86,6 +90,30 @@ export class AntiBan {
             ...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.
@@ -286,6 +314,12 @@ export class AntiBan {
         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 */
@@ -312,6 +346,14 @@ export class AntiBan {
     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
      */
@@ -364,6 +406,8 @@ export class AntiBan {
         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

@@ -17,6 +17,8 @@ export { ContactGraphWarmer, type ContactGraphConfig, type ContactGraphStats, ty
 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

@@ -20,6 +20,9 @@ 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;
+}

package/dist/jidCanonicalizer.js

@@ -0,0 +1,172 @@
+/**
+ * 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 } from './lidResolver.js';
+const DEFAULT_CONFIG = {
+    enabled: false,
+    canonicalizeOutbound: true,
+    learnFromEvents: true,
+};
+export class JidCanonicalizer {
+    config;
+    lidResolver;
+    ownsResolver; // Track if we created the resolver (for destroy)
+    stats = {
+        outboundCanonicalized: 0,
+        outboundPassthrough: 0,
+        inboundLearned: 0,
+    };
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        // Use provided resolver or create new one
+        if (config.resolver) {
+            this.lidResolver = config.resolver;
+            this.ownsResolver = false;
+        }
+        else {
+            this.lidResolver = new LidResolver(config.resolverConfig);
+            this.ownsResolver = true;
+        }
+    }
+    /**
+     * Access the underlying resolver (for cross-module sharing)
+     */
+    get resolver() {
+        return this.lidResolver;
+    }
+    /**
+     * Called by wrapper on every outbound send. Returns canonical JID.
+     */
+    canonicalizeTarget(jid) {
+        if (!this.config.enabled || !this.config.canonicalizeOutbound) {
+            return jid;
+        }
+        const canonical = this.lidResolver.resolveCanonical(jid);
+        if (canonical !== jid) {
+            this.stats.outboundCanonicalized++;
+        }
+        else {
+            this.stats.outboundPassthrough++;
+        }
+        return canonical;
+    }
+    /**
+     * Called by wrapper on messages.upsert event. Learns mappings.
+     */
+    onIncomingEvent(upsert) {
+        if (!this.config.enabled || !this.config.learnFromEvents) {
+            return;
+        }
+        for (const msg of upsert.messages || []) {
+            this.learnFromMessage(msg);
+        }
+    }
+    /**
+     * Called by wrapper on messages.update event. Learns from sent-message refs.
+     */
+    onMessageUpdate(updates) {
+        if (!this.config.enabled || !this.config.learnFromEvents) {
+            return;
+        }
+        for (const update of updates) {
+            // messages.update doesn't typically carry LID info — mostly for retry tracking
+            // But handle edge case where update.key has participant/participantPn
+            if (update.key) {
+                this.learnFromMessageKey(update.key);
+            }
+        }
+    }
+    getStats() {
+        return {
+            resolver: this.lidResolver.getStats(),
+            outboundCanonicalized: this.stats.outboundCanonicalized,
+            outboundPassthrough: this.stats.outboundPassthrough,
+            inboundLearned: this.stats.inboundLearned,
+        };
+    }
+    destroy() {
+        // Only destroy resolver if we created it
+        if (this.ownsResolver) {
+            this.lidResolver.destroy();
+        }
+    }
+    // Private helpers
+    /**
+     * Extract LID↔PN mappings from a message object
+     */
+    learnFromMessage(msg) {
+        if (!msg.key)
+            return;
+        // Extract from message key
+        this.learnFromMessageKey(msg.key);
+        // Additional extraction from message envelope (if present)
+        // Some Baileys forks/versions expose participantPn at the message level
+        if (msg.participantPn && msg.key.participant) {
+            this.lidResolver.learn({
+                lid: msg.key.participant.endsWith('@lid') ? msg.key.participant : undefined,
+                pn: msg.participantPn,
+            });
+            this.stats.inboundLearned++;
+        }
+    }
+    /**
+     * Extract mappings from message.key
+     */
+    learnFromMessageKey(key) {
+        if (!key)
+            return;
+        // Case 1: participant (LID) + participantPn (PN)
+        // This appears in group messages where sender uses LID
+        if (key.participant && key.participantPn) {
+            if (key.participant.endsWith('@lid')) {
+                this.lidResolver.learn({
+                    lid: key.participant,
+                    pn: key.participantPn,
+                });
+                this.stats.inboundLearned++;
+            }
+        }
+        // Case 2: remoteJid (LID) + senderPn (PN)
+        // This appears in 1:1 messages from LID senders
+        if (key.remoteJid && key.senderPn) {
+            if (key.remoteJid.endsWith('@lid')) {
+                this.lidResolver.learn({
+                    lid: key.remoteJid,
+                    pn: key.senderPn,
+                });
+                this.stats.inboundLearned++;
+            }
+        }
+        // Case 3: participant (PN) exists but we have remoteJid (LID)
+        // Inverse case where participant is PN form
+        if (key.participant && key.remoteJid) {
+            if (key.participant.endsWith('@s.whatsapp.net') && key.remoteJid.endsWith('@lid')) {
+                this.lidResolver.learn({
+                    lid: key.remoteJid,
+                    pn: key.participant,
+                });
+                this.stats.inboundLearned++;
+            }
+        }
+    }
+}

package/dist/lidResolver.d.ts

@@ -0,0 +1,96 @@
+/**
+ * LID Resolver — Maintains bidirectional LID↔PN mapping for contacts
+ *
+ * WhatsApp migrated to LID (Linked Identity) in 2024. A contact now has two JIDs:
+ * - Phone number form: "27825651069@s.whatsapp.net"
+ * - LID form: "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".
+ *
+ * This utility:
+ * - Learns LID↔PN mappings from message events
+ * - Normalizes JIDs to a canonical form (phone number by default)
+ * - Provides lookup for cross-form resolution
+ * - Optionally persists state across restarts
+ *
+ * This is a standalone utility — can be used independently or via JidCanonicalizer.
+ */
+export interface LidResolverConfig {
+    /** Canonical form to normalize to. Default: 'pn' (phone-number) */
+    canonical?: 'pn' | 'lid';
+    /** Optional persistence hooks — if provided, map survives restarts */
+    persistence?: {
+        load?: () => Promise<Record<string, any>> | Record<string, any>;
+        save?: (map: Record<string, any>) => Promise<void> | void;
+    };
+    /** Max entries to hold in memory (LRU). Default 10_000 */
+    maxEntries?: number;
+}
+export interface LidMapping {
+    lid: string;
+    pn: string;
+    phone?: string;
+    learnedAt: number;
+    seenCount: number;
+}
+export interface LidResolverStats {
+    totalMappings: number;
+    learnedFromEvents: number;
+    lookupsServed: number;
+    lookupMisses: number;
+    canonicalForm: 'pn' | 'lid';
+}
+export declare class LidResolver {
+    private config;
+    private persistence?;
+    private lidToPn;
+    private pnToLid;
+    private stats;
+    constructor(config?: LidResolverConfig);
+    /**
+     * Learn from a message event. Idempotent.
+     * Accepts partial mappings — will use whatever fields are available.
+     */
+    learn(mapping: {
+        lid?: string;
+        pn?: string;
+        phone?: string;
+    }): void;
+    /**
+     * Given any form (LID or PN), return the canonical form.
+     * Falls back to input if unknown (no throw).
+     */
+    resolveCanonical(jid: string): string;
+    /**
+     * Lookup partner form. Returns null if unknown.
+     */
+    getLid(pn: string): string | null;
+    getPn(lid: string): string | null;
+    /**
+     * Full mapping for inspection
+     */
+    getMapping(jid: string): LidMapping | null;
+    /**
+     * Seed from persistence (called automatically in constructor if persistence provided)
+     */
+    hydrate(): Promise<void>;
+    /**
+     * Flush current map to persistence
+     */
+    flush(): Promise<void>;
+    getStats(): LidResolverStats;
+    /**
+     * Clear everything
+     */
+    reset(): void;
+    destroy(): void;
+    /**
+     * Normalize JID: strip device suffix `:N`
+     */
+    private normalizeJid;
+    /**
+     * Evict least recently accessed mapping (LRU)
+     */
+    private evictLRU;
+}

package/dist/lidResolver.js

@@ -0,0 +1,292 @@
+/**
+ * LID Resolver — Maintains bidirectional LID↔PN mapping for contacts
+ *
+ * WhatsApp migrated to LID (Linked Identity) in 2024. A contact now has two JIDs:
+ * - Phone number form: "27825651069@s.whatsapp.net"
+ * - LID form: "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".
+ *
+ * This utility:
+ * - Learns LID↔PN mappings from message events
+ * - Normalizes JIDs to a canonical form (phone number by default)
+ * - Provides lookup for cross-form resolution
+ * - Optionally persists state across restarts
+ *
+ * This is a standalone utility — can be used independently or via JidCanonicalizer.
+ */
+const DEFAULT_CONFIG = {
+    canonical: 'pn',
+    maxEntries: 10_000,
+};
+export class LidResolver {
+    config;
+    persistence;
+    // Bidirectional maps: lid→pn and pn→lid
+    lidToPn = new Map();
+    pnToLid = new Map(); // pn → lid (for quick reverse lookup)
+    stats = {
+        learnedFromEvents: 0,
+        lookupsServed: 0,
+        lookupMisses: 0,
+    };
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.persistence = config.persistence;
+        // Auto-hydrate if persistence provided
+        if (this.persistence?.load) {
+            void this.hydrate();
+        }
+    }
+    /**
+     * Learn from a message event. Idempotent.
+     * Accepts partial mappings — will use whatever fields are available.
+     */
+    learn(mapping) {
+        let lid = mapping.lid ? this.normalizeJid(mapping.lid) : undefined;
+        let pn = mapping.pn ? this.normalizeJid(mapping.pn) : undefined;
+        const phone = mapping.phone;
+        // Validate we have both lid and pn (or can derive pn from phone)
+        if (!lid || (!pn && !phone)) {
+            return; // Insufficient data
+        }
+        // Derive pn from phone if not provided
+        if (!pn && phone) {
+            pn = `${phone}@s.whatsapp.net`;
+        }
+        // Validate forms
+        if (!lid || !pn)
+            return;
+        if (!lid.endsWith('@lid'))
+            return;
+        if (!pn.endsWith('@s.whatsapp.net'))
+            return;
+        // Check if we already know this mapping
+        const existing = this.lidToPn.get(lid);
+        if (existing) {
+            // Already learned — just increment seen count
+            existing.seenCount++;
+            existing.learnedAt = Date.now(); // Update access time for LRU
+            return;
+        }
+        // Learn new mapping
+        const extractedPhone = phone || pn.split('@')[0];
+        const newMapping = {
+            lid,
+            pn,
+            phone: extractedPhone,
+            learnedAt: Date.now(),
+            seenCount: 1,
+        };
+        // Check if we need to evict (LRU)
+        if (this.lidToPn.size >= this.config.maxEntries) {
+            this.evictLRU();
+        }
+        this.lidToPn.set(lid, newMapping);
+        this.pnToLid.set(pn, lid);
+        this.stats.learnedFromEvents++;
+        // Async flush to persistence (don't await)
+        if (this.persistence?.save) {
+            void this.flush();
+        }
+    }
+    /**
+     * Given any form (LID or PN), return the canonical form.
+     * Falls back to input if unknown (no throw).
+     */
+    resolveCanonical(jid) {
+        const normalized = this.normalizeJid(jid);
+        if (this.config.canonical === 'pn') {
+            // Want PN form
+            if (normalized.endsWith('@lid')) {
+                const mapping = this.lidToPn.get(normalized);
+                if (mapping) {
+                    this.stats.lookupsServed++;
+                    mapping.learnedAt = Date.now(); // Update LRU access time
+                    return mapping.pn;
+                }
+                this.stats.lookupMisses++;
+                return jid; // Fallback to original input
+            }
+            // Already PN form
+            this.stats.lookupsServed++;
+            return normalized;
+        }
+        else {
+            // Want LID form
+            if (normalized.endsWith('@s.whatsapp.net')) {
+                const lid = this.pnToLid.get(normalized);
+                if (lid) {
+                    this.stats.lookupsServed++;
+                    const mapping = this.lidToPn.get(lid);
+                    if (mapping) {
+                        mapping.learnedAt = Date.now(); // Update LRU access time
+                    }
+                    return lid;
+                }
+                this.stats.lookupMisses++;
+                return jid; // Fallback to original input
+            }
+            // Already LID form
+            this.stats.lookupsServed++;
+            return normalized;
+        }
+    }
+    /**
+     * Lookup partner form. Returns null if unknown.
+     */
+    getLid(pn) {
+        const normalized = this.normalizeJid(pn);
+        const lid = this.pnToLid.get(normalized);
+        if (lid) {
+            const mapping = this.lidToPn.get(lid);
+            if (mapping) {
+                mapping.learnedAt = Date.now(); // Update LRU access time
+            }
+        }
+        return lid || null;
+    }
+    getPn(lid) {
+        const normalized = this.normalizeJid(lid);
+        const mapping = this.lidToPn.get(normalized);
+        if (mapping) {
+            mapping.learnedAt = Date.now(); // Update LRU access time
+            return mapping.pn;
+        }
+        return null;
+    }
+    /**
+     * Full mapping for inspection
+     */
+    getMapping(jid) {
+        const normalized = this.normalizeJid(jid);
+        // Try as LID first
+        const byLid = this.lidToPn.get(normalized);
+        if (byLid) {
+            byLid.learnedAt = Date.now(); // Update LRU access time
+            return byLid;
+        }
+        // Try as PN
+        const lid = this.pnToLid.get(normalized);
+        if (lid) {
+            const mapping = this.lidToPn.get(lid);
+            if (mapping) {
+                mapping.learnedAt = Date.now(); // Update LRU access time
+                return mapping;
+            }
+        }
+        return null;
+    }
+    /**
+     * Seed from persistence (called automatically in constructor if persistence provided)
+     */
+    async hydrate() {
+        if (!this.persistence?.load)
+            return;
+        try {
+            const stored = await this.persistence.load();
+            if (!stored || typeof stored !== 'object')
+                return;
+            // Restore mappings
+            for (const [lid, serialized] of Object.entries(stored)) {
+                if (typeof serialized === 'string') {
+                    // Old format: lid → pn string
+                    const pn = serialized;
+                    const phone = pn.split('@')[0];
+                    const mapping = {
+                        lid,
+                        pn,
+                        phone,
+                        learnedAt: Date.now(),
+                        seenCount: 1,
+                    };
+                    this.lidToPn.set(lid, mapping);
+                    this.pnToLid.set(pn, lid);
+                }
+                else if (typeof serialized === 'object' && serialized !== null) {
+                    // New format: lid → LidMapping object
+                    const mapping = serialized;
+                    this.lidToPn.set(lid, mapping);
+                    this.pnToLid.set(mapping.pn, lid);
+                }
+            }
+        }
+        catch (error) {
+            // Silently fail hydration — don't crash on corrupt persistence
+        }
+    }
+    /**
+     * Flush current map to persistence
+     */
+    async flush() {
+        if (!this.persistence?.save)
+            return;
+        try {
+            const toStore = {};
+            for (const [lid, mapping] of this.lidToPn.entries()) {
+                toStore[lid] = mapping;
+            }
+            await this.persistence.save(toStore);
+        }
+        catch (error) {
+            // Silently fail flush — don't crash
+        }
+    }
+    getStats() {
+        return {
+            totalMappings: this.lidToPn.size,
+            learnedFromEvents: this.stats.learnedFromEvents,
+            lookupsServed: this.stats.lookupsServed,
+            lookupMisses: this.stats.lookupMisses,
+            canonicalForm: this.config.canonical,
+        };
+    }
+    /**
+     * Clear everything
+     */
+    reset() {
+        this.lidToPn.clear();
+        this.pnToLid.clear();
+        this.stats = {
+            learnedFromEvents: 0,
+            lookupsServed: 0,
+            lookupMisses: 0,
+        };
+    }
+    destroy() {
+        this.reset();
+        // Flush one final time
+        if (this.persistence?.save) {
+            void this.flush();
+        }
+    }
+    // Private helpers
+    /**
+     * Normalize JID: strip device suffix `:N`
+     */
+    normalizeJid(jid) {
+        // Strip device suffix e.g. "123:45@s.whatsapp.net" → "123@s.whatsapp.net"
+        return jid.replace(/:\d+@/, '@');
+    }
+    /**
+     * Evict least recently accessed mapping (LRU)
+     */
+    evictLRU() {
+        let oldestLid = null;
+        let oldestTime = Infinity;
+        for (const [lid, mapping] of this.lidToPn.entries()) {
+            if (mapping.learnedAt < oldestTime) {
+                oldestTime = mapping.learnedAt;
+                oldestLid = lid;
+            }
+        }
+        if (oldestLid) {
+            const mapping = this.lidToPn.get(oldestLid);
+            if (mapping) {
+                this.pnToLid.delete(mapping.pn);
+            }
+            this.lidToPn.delete(oldestLid);
+        }
+    }
+}

package/dist/wrapper.js

@@ -63,7 +63,7 @@ export function wrapSocket(sock, config, warmUpState, wrapOptions) {
                     });
                 }
             }
-            // Catch 463 errors from message updates + track retries
+            // Catch 463 errors from message updates + track retries + learn LID mappings
             if (events['messages.update']) {
                 const updates = events['messages.update'];
                 for (const update of updates) {
@@ -77,10 +77,14 @@ export function wrapSocket(sock, config, warmUpState, wrapOptions) {
                     // Retry tracking
                     antiban.retryTracker.onMessageUpdate(update);
                 }
+                // LID canonicalizer learning
+                antiban.jidCanonicalizer?.onMessageUpdate(updates);
             }
-            // Register known chats from incoming messages + handle reply suggestions
+            // Register known chats from incoming messages + handle reply suggestions + learn LID mappings
             if (events['messages.upsert']) {
                 const { messages } = events['messages.upsert'];
+                // Learn LID mappings FIRST (before any other processing)
+                antiban.jidCanonicalizer?.onIncomingEvent(events['messages.upsert']);
                 for (const msg of messages || []) {
                     const jid = msg.key?.remoteJid;
                     if (!jid)
@@ -136,7 +140,7 @@ export function wrapSocket(sock, config, warmUpState, wrapOptions) {
                 });
             }
         });
-        // Catch 463 errors from message updates + track retries
+        // Catch 463 errors from message updates + track retries + learn LID mappings
         sock.ev.on('messages.update', (updates) => {
             for (const update of updates) {
                 // 463 error detection
@@ -149,9 +153,14 @@ export function wrapSocket(sock, config, warmUpState, wrapOptions) {
                 // Retry tracking
                 antiban.retryTracker.onMessageUpdate(update);
             }
+            // LID canonicalizer learning
+            antiban.jidCanonicalizer?.onMessageUpdate(updates);
         });
-        // Register known chats from incoming messages + handle reply suggestions
-        sock.ev.on('messages.upsert', ({ messages }) => {
+        // Register known chats from incoming messages + handle reply suggestions + learn LID mappings
+        sock.ev.on('messages.upsert', (upsert) => {
+            const { messages } = upsert;
+            // Learn LID mappings FIRST (before any other processing)
+            antiban.jidCanonicalizer?.onIncomingEvent(upsert);
             for (const msg of messages || []) {
                 const jid = msg.key?.remoteJid;
                 if (!jid)
@@ -189,9 +198,20 @@ export function wrapSocket(sock, config, warmUpState, wrapOptions) {
     // Create proxy that intercepts sendMessage
     const originalSendMessage = sock.sendMessage.bind(sock);
     const wrappedSendMessage = async (jid, content, options) => {
+        /**
+         * LID/PN Canonicalization — Normalize JID to canonical form
+         *
+         * This mitigates the LID/PN race that causes "Bad MAC / No Session / Invalid PreKey"
+         * errors (Baileys #1769, our PR #2372). When a message event arrives under one form
+         * (e.g. LID) but the crypto session was established under another (e.g. PN), decryption
+         * fails. By normalizing all outbound targets to a single form, we reduce this race.
+         *
+         * This is middleware-layer mitigation only. Root fix requires PR #2372 merged upstream.
+         */
+        const canonicalJid = antiban.jidCanonicalizer?.canonicalizeTarget(jid) || jid;
         // Extract text content for rate limiter analysis
         const text = content?.text || content?.caption || content?.image?.caption || '';
-        const decision = await antiban.beforeSend(jid, text);
+        const decision = await antiban.beforeSend(canonicalJid, text);
         if (!decision.allowed) {
             throw new Error(`[baileys-antiban] Message blocked: ${decision.reason}`);
         }
@@ -199,11 +219,11 @@ export function wrapSocket(sock, config, warmUpState, wrapOptions) {
         if (decision.delayMs > 0) {
             await new Promise(resolve => setTimeout(resolve, decision.delayMs));
         }
-        // Send message
+        // Send message (using canonical JID)
         try {
-            const result = await originalSendMessage(jid, content, options);
-            antiban.afterSend(jid, text);
-            antiban.timelock.registerKnownChat(jid);
+            const result = await originalSendMessage(canonicalJid, content, options);
+            antiban.afterSend(canonicalJid, text);
+            antiban.timelock.registerKnownChat(canonicalJid);
             // Clear retry tracking on successful send
             if (result?.key?.id) {
                 antiban.retryTracker.clear(result.key.id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baileys-antiban",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Transport-agnostic anti-ban middleware for Baileys and baileyrs — human-like messaging patterns to protect your WhatsApp number",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",