@prototypevip/baileys 0.0.8 → 0.1.0

package/lib/AntiBan/reputationVoucher.js

@@ -0,0 +1,373 @@
+/**
+ * ReputationVoucher — High-trust accounts vouch for new numbers
+ *
+ * Establishes genuine conversation history between trusted accounts and new numbers
+ * before those new numbers contact customers. Reduces warmup time and makes new
+ * accounts appear established with real bidirectional message history.
+ *
+ * Key design principles:
+ * - Dedicated sacrificial vouch accounts (separate from business accounts)
+ * - Max 5 vouches per week per vouching account (not per day)
+ * - Targets must complete 3 qualifying events before vouching
+ * - Strike system: 3 failed vouches = 90-day suspension for voucher
+ * - Blast radius containment: vouching accounts isolated from main business
+ *
+ * Usage:
+ *   const rv = new ReputationVoucher();
+ *
+ *   // Register a trusted account
+ *   rv.registerVoucher({
+ *     jid: '27123456789@s.whatsapp.net',
+ *     trustScore: 85,
+ *     accountAgeDays: 240
+ *   });
+ *
+ *   // Queue a new number for vouching
+ *   rv.queueTarget({ jid: '27987654321@s.whatsapp.net' });
+ *
+ *   // Record qualifying events (auction completion, payment, etc)
+ *   rv.recordQualifyingEvent('27987654321@s.whatsapp.net');
+ *   rv.recordQualifyingEvent('27987654321@s.whatsapp.net');
+ *   rv.recordQualifyingEvent('27987654321@s.whatsapp.net');
+ *
+ *   // Check if target qualifies
+ *   const check = rv.targetQualifies('27987654321@s.whatsapp.net');
+ *   if (check.qualified) {
+ *     const voucher = rv.getAvailableVoucher();
+ *     if (voucher) {
+ *       // Plan the conversation
+ *       const conversation = rv.planVouchConversation(voucher.jid, '27987654321@s.whatsapp.net');
+ *
+ *       // Execute sends (caller must have separate socket for voucher account)
+ *       // ... send conversation.messages ...
+ *
+ *       // After target replies
+ *       rv.recordVouchOutcome('27987654321@s.whatsapp.net', true);
+ *
+ *       // Calculate warmup credit
+ *       const daysCredit = rv.calculateWarmupCredit('27987654321@s.whatsapp.net');
+ *       // Skip daysCredit days of warmup for this target
+ *     }
+ *   }
+ */
+const DEFAULT_CONFIG = {
+    maxVouchesPerWeek: 5,
+    qualifyingEventsRequired: 3,
+    strikesForSuspension: 3,
+    suspensionDurationMs: 90 * 24 * 60 * 60 * 1000, // 90 days
+    minVoucherTrustScore: 60,
+    minVoucherAgeDays: 180, // 6 months
+    warmupMessages: [
+        "Hey, just checking this is the right number?",
+        "Hi! Got your details from the group",
+        "Morning! Are you available this week?",
+        "Hey there, hope this is a good time to connect",
+        "Hi, just wanted to reach out",
+    ],
+};
+export class ReputationVoucher {
+    config;
+    vouchers = new Map();
+    targets = new Map();
+    conversations = [];
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Register a vouching account (high-trust, established number)
+     */
+    registerVoucher(account) {
+        // Validate account meets minimum requirements
+        if (account.trustScore < this.config.minVoucherTrustScore) {
+            throw new Error(`Voucher trust score ${account.trustScore} below minimum ${this.config.minVoucherTrustScore}`);
+        }
+        if (account.accountAgeDays < this.config.minVoucherAgeDays) {
+            throw new Error(`Voucher account age ${account.accountAgeDays} days below minimum ${this.config.minVoucherAgeDays} days`);
+        }
+        const existing = this.vouchers.get(account.jid);
+        if (existing) {
+            // Update existing voucher (preserve counters)
+            this.vouchers.set(account.jid, {
+                ...account,
+                vouchesThisWeek: existing.vouchesThisWeek,
+                totalVouches: existing.totalVouches,
+                failedVouches: existing.failedVouches,
+                strikes: existing.strikes,
+                suspendedUntil: existing.suspendedUntil,
+                lastVouchAt: existing.lastVouchAt,
+            });
+        }
+        else {
+            // New voucher
+            this.vouchers.set(account.jid, {
+                ...account,
+                vouchesThisWeek: 0,
+                totalVouches: 0,
+                failedVouches: 0,
+                strikes: 0,
+            });
+        }
+    }
+    /**
+     * Queue a target for vouching
+     */
+    queueTarget(target) {
+        const existing = this.targets.get(target.jid);
+        if (existing && existing.status !== 'failed') {
+            // Already queued or in progress
+            return;
+        }
+        this.targets.set(target.jid, {
+            ...target,
+            qualifyingEvents: target.qualifyingEvents || 0,
+            requestedAt: Date.now(),
+            status: 'pending',
+        });
+    }
+    /**
+     * Check if a target qualifies for vouching
+     */
+    targetQualifies(jid) {
+        const target = this.targets.get(jid);
+        if (!target) {
+            return { qualified: false, reason: 'Target not queued', eventsNeeded: this.config.qualifyingEventsRequired };
+        }
+        const events = target.qualifyingEvents || 0;
+        if (events < this.config.qualifyingEventsRequired) {
+            return {
+                qualified: false,
+                reason: `Not enough qualifying events (${events}/${this.config.qualifyingEventsRequired})`,
+                eventsNeeded: this.config.qualifyingEventsRequired - events,
+            };
+        }
+        if (target.status === 'completed') {
+            return { qualified: false, reason: 'Already vouched' };
+        }
+        if (target.status === 'failed') {
+            return { qualified: false, reason: 'Previous vouch failed' };
+        }
+        return { qualified: true };
+    }
+    /**
+     * Record a qualifying event for a target (e.g., auction completion, payment cleared)
+     */
+    recordQualifyingEvent(jid) {
+        const target = this.targets.get(jid);
+        if (!target) {
+            // Auto-queue with first event
+            this.queueTarget({ jid, qualifyingEvents: 1 });
+            return;
+        }
+        target.qualifyingEvents = (target.qualifyingEvents || 0) + 1;
+    }
+    /**
+     * Get next available voucher for a target (respects limits + suspension)
+     */
+    getAvailableVoucher() {
+        const now = Date.now();
+        const weekMs = 7 * 24 * 60 * 60 * 1000;
+        // Find eligible vouchers
+        const eligible = [];
+        for (const voucher of this.vouchers.values()) {
+            // Check suspension
+            if (voucher.suspendedUntil && voucher.suspendedUntil > now) {
+                continue;
+            }
+            // Reset weekly counter if 7 days have passed since last vouch
+            if (voucher.lastVouchAt && now - voucher.lastVouchAt > weekMs) {
+                voucher.vouchesThisWeek = 0;
+            }
+            // Check weekly limit
+            if (voucher.vouchesThisWeek >= this.config.maxVouchesPerWeek) {
+                continue;
+            }
+            eligible.push(voucher);
+        }
+        if (eligible.length === 0) {
+            return null;
+        }
+        // Sort by:
+        // 1. Lowest vouchesThisWeek (spread load)
+        // 2. Highest trustScore (best vouchers first)
+        // 3. Lowest totalVouches (rotate usage)
+        eligible.sort((a, b) => {
+            if (a.vouchesThisWeek !== b.vouchesThisWeek) {
+                return a.vouchesThisWeek - b.vouchesThisWeek;
+            }
+            if (a.trustScore !== b.trustScore) {
+                return b.trustScore - a.trustScore;
+            }
+            return a.totalVouches - b.totalVouches;
+        });
+        return eligible[0];
+    }
+    /**
+     * Plan a vouch conversation.
+     * Returns a conversation plan — caller executes the sends.
+     */
+    planVouchConversation(voucherJid, targetJid) {
+        const voucher = this.vouchers.get(voucherJid);
+        if (!voucher) {
+            throw new Error(`Voucher ${voucherJid} not registered`);
+        }
+        const target = this.targets.get(targetJid);
+        if (!target) {
+            throw new Error(`Target ${targetJid} not queued`);
+        }
+        const check = this.targetQualifies(targetJid);
+        if (!check.qualified) {
+            throw new Error(`Target ${targetJid} not qualified: ${check.reason}`);
+        }
+        // Update voucher counters
+        voucher.vouchesThisWeek++;
+        voucher.totalVouches++;
+        voucher.lastVouchAt = Date.now();
+        // Update target status
+        target.status = 'active';
+        target.vouchedAt = Date.now();
+        target.vouchedBy = voucherJid;
+        // Pick 2-3 warmup messages randomly
+        const messageCount = 2 + Math.floor(Math.random() * 2); // 2-3 messages
+        const selectedMessages = [];
+        const pool = [...this.config.warmupMessages];
+        for (let i = 0; i < messageCount && pool.length > 0; i++) {
+            const idx = Math.floor(Math.random() * pool.length);
+            selectedMessages.push(pool[idx]);
+            pool.splice(idx, 1); // Remove to avoid duplicates
+        }
+        // Create conversation plan
+        const conversation = {
+            targetJid,
+            voucherJid,
+            messages: selectedMessages.map((text, idx) => ({
+                direction: 'outbound',
+                timestamp: Date.now() + idx * 5000, // Stagger by 5s
+                text,
+            })),
+            startedAt: Date.now(),
+            success: false, // Will be updated when recordVouchOutcome is called
+        };
+        this.conversations.push(conversation);
+        return conversation;
+    }
+    /**
+     * Record outcome of a vouch.
+     * success = true if target replied within reasonable time (e.g., 7 days)
+     * success = false if target got banned within 7 days of vouch
+     */
+    recordVouchOutcome(targetJid, success) {
+        const target = this.targets.get(targetJid);
+        if (!target || !target.vouchedBy) {
+            throw new Error(`Target ${targetJid} not vouched`);
+        }
+        const voucher = this.vouchers.get(target.vouchedBy);
+        if (!voucher) {
+            throw new Error(`Voucher ${target.vouchedBy} not found`);
+        }
+        // Find the conversation
+        const conversation = this.conversations.find((c) => c.targetJid === targetJid && c.voucherJid === target.vouchedBy);
+        if (conversation) {
+            conversation.success = success;
+            conversation.completedAt = Date.now();
+        }
+        if (success) {
+            target.status = 'completed';
+        }
+        else {
+            // Failed vouch — apply strike to voucher
+            target.status = 'failed';
+            voucher.failedVouches++;
+            voucher.strikes++;
+            // Check if suspension threshold reached
+            if (voucher.strikes >= this.config.strikesForSuspension) {
+                voucher.suspendedUntil = Date.now() + this.config.suspensionDurationMs;
+            }
+        }
+    }
+    /**
+     * Calculate warmup credit for a successfully vouched target.
+     * Returns number of warmup days that can be skipped (0-3).
+     *
+     * Credit logic:
+     * - 1 reply = 1 day credit
+     * - 2+ replies = 2 days credit
+     * - Reply + 3+ days elapsed = 3 days credit (max)
+     */
+    calculateWarmupCredit(targetJid) {
+        const target = this.targets.get(targetJid);
+        if (!target || target.status !== 'completed') {
+            return 0;
+        }
+        const conversation = this.conversations.find((c) => c.targetJid === targetJid && c.success);
+        if (!conversation) {
+            return 0;
+        }
+        // Count inbound messages (replies from target)
+        const inboundCount = conversation.messages.filter((m) => m.direction === 'inbound').length;
+        if (inboundCount === 0) {
+            return 0;
+        }
+        if (inboundCount === 1) {
+            return 1;
+        }
+        if (inboundCount >= 2) {
+            // Check if 3+ days elapsed
+            const daysElapsed = (Date.now() - conversation.startedAt) / (24 * 60 * 60 * 1000);
+            if (daysElapsed >= 3) {
+                return 3; // Max credit
+            }
+            return 2;
+        }
+        return 0;
+    }
+    /**
+     * Get stats for a specific voucher
+     */
+    getVoucherStats(jid) {
+        const voucher = this.vouchers.get(jid);
+        return voucher ? { ...voucher } : null;
+    }
+    /**
+     * Get all pending targets (awaiting vouching)
+     */
+    getPendingTargets() {
+        return Array.from(this.targets.values()).filter((t) => t.status === 'pending');
+    }
+    /**
+     * Get vouch history
+     */
+    getVouchHistory() {
+        return [...this.conversations];
+    }
+    /**
+     * Export state for persistence
+     */
+    exportState() {
+        return {
+            version: 1,
+            exportedAt: Date.now(),
+            vouchers: Array.from(this.vouchers.values()),
+            targets: Array.from(this.targets.values()),
+            conversations: [...this.conversations],
+        };
+    }
+    /**
+     * Import state from persistence
+     */
+    importState(state) {
+        // Clear existing state
+        this.vouchers.clear();
+        this.targets.clear();
+        this.conversations = [];
+        // Import vouchers
+        for (const voucher of state.vouchers) {
+            this.vouchers.set(voucher.jid, { ...voucher });
+        }
+        // Import targets
+        for (const target of state.targets) {
+            this.targets.set(target.jid, { ...target });
+        }
+        // Import conversations
+        this.conversations = [...state.conversations];
+    }
+}

package/lib/AntiBan/retryReason.js

@@ -0,0 +1,91 @@
+/**
+ * TypedMessageRetryReason — Typed enum for WhatsApp's retry reason codes
+ *
+ * Based on protocol research from whatsapp-rust and Baileys source.
+ * These codes appear in message retry events when encryption fails.
+ *
+ * Common scenarios:
+ * - SignalErrorBadMac (7) — Most common, indicates encryption session mismatch
+ * - SignalErrorNoSession (5) — Peer hasn't established session yet
+ * - SignalErrorInvalidKeyId (3) — Peer's prekey rotated
+ * - MessageExpired (8) — Message too old to decrypt
+ *
+ * @author Kobus Wentzel <kobie@pop.co.za>
+ * @license MIT
+ */
+/**
+ * WhatsApp message retry reason codes.
+ * Based on Signal protocol error codes + WhatsApp extensions.
+ */
+export var MessageRetryReason;
+(function (MessageRetryReason) {
+    MessageRetryReason[MessageRetryReason["UnknownError"] = 0] = "UnknownError";
+    MessageRetryReason[MessageRetryReason["GenericError"] = 1] = "GenericError";
+    MessageRetryReason[MessageRetryReason["SignalErrorInvalidKeyId"] = 3] = "SignalErrorInvalidKeyId";
+    MessageRetryReason[MessageRetryReason["SignalErrorInvalidMessage"] = 4] = "SignalErrorInvalidMessage";
+    MessageRetryReason[MessageRetryReason["SignalErrorNoSession"] = 5] = "SignalErrorNoSession";
+    MessageRetryReason[MessageRetryReason["SignalErrorBadMac"] = 7] = "SignalErrorBadMac";
+    MessageRetryReason[MessageRetryReason["MessageExpired"] = 8] = "MessageExpired";
+    MessageRetryReason[MessageRetryReason["DecryptionError"] = 9] = "DecryptionError";
+})(MessageRetryReason || (MessageRetryReason = {}));
+/**
+ * Set of retry reasons that indicate MAC verification failure.
+ * These are the most common causes of "Bad MAC" errors in Baileys.
+ */
+export const MAC_ERROR_CODES = new Set([
+    MessageRetryReason.SignalErrorBadMac,
+    MessageRetryReason.SignalErrorInvalidMessage,
+    MessageRetryReason.SignalErrorNoSession,
+    MessageRetryReason.SignalErrorInvalidKeyId,
+]);
+/**
+ * Parse a retry reason code from various input formats.
+ * Returns UnknownError if code is not recognized.
+ */
+export function parseRetryReason(code) {
+    if (code === undefined || code === null) {
+        return MessageRetryReason.UnknownError;
+    }
+    const n = typeof code === 'string' ? parseInt(code, 10) : code;
+    if (isNaN(n)) {
+        return MessageRetryReason.UnknownError;
+    }
+    // Check if the number is a valid enum value
+    if (Object.values(MessageRetryReason).includes(n)) {
+        return n;
+    }
+    return MessageRetryReason.UnknownError;
+}
+/**
+ * Check if a retry reason indicates a MAC error.
+ * MAC errors are typically caused by encryption session mismatches,
+ * often due to LID/PN race conditions.
+ */
+export function isMacError(reason) {
+    return MAC_ERROR_CODES.has(reason);
+}
+/**
+ * Get a human-readable description of a retry reason.
+ */
+export function getRetryReasonDescription(reason) {
+    switch (reason) {
+        case MessageRetryReason.UnknownError:
+            return 'Unknown error';
+        case MessageRetryReason.GenericError:
+            return 'Generic error';
+        case MessageRetryReason.SignalErrorInvalidKeyId:
+            return 'Invalid key ID — peer prekey rotated';
+        case MessageRetryReason.SignalErrorInvalidMessage:
+            return 'Invalid message format';
+        case MessageRetryReason.SignalErrorNoSession:
+            return 'No session — peer not initialized';
+        case MessageRetryReason.SignalErrorBadMac:
+            return 'Bad MAC — encryption session mismatch';
+        case MessageRetryReason.MessageExpired:
+            return 'Message expired — too old to decrypt';
+        case MessageRetryReason.DecryptionError:
+            return 'Decryption failed';
+        default:
+            return `Unknown reason code ${reason}`;
+    }
+}

package/lib/AntiBan/retryTracker.js

@@ -0,0 +1,172 @@
+/**
+ * RetryReasonTracker — Track message retry reasons and detect retry spirals
+ *
+ * Inspired by whatsapp-rust's protocol/retry.rs module which defines 13 typed
+ * RetryReason codes with MAX_RETRY=5 and optimized key-include behavior.
+ *
+ * In the middleware layer, we can't control key inclusion (that's transport-level),
+ * but we CAN observe retry patterns from messages.update events and classify them.
+ * High retry rates per reason = ban signal precursor.
+ *
+ * Usage:
+ *   const tracker = new RetryReasonTracker({ enabled: true, maxRetries: 5 });
+ *
+ *   // In messages.update handler:
+ *   tracker.onMessageUpdate(update);
+ *
+ *   // Check for spirals:
+ *   if (tracker.isSpiraling(msgId)) {
+ *     console.warn('Message stuck in retry spiral, dropping');
+ *   }
+ *
+ *   // On successful send:
+ *   tracker.clear(msgId);
+ *
+ *   // Get stats:
+ *   const stats = tracker.getStats();
+ */
+const DEFAULT_CONFIG = {
+    enabled: false,
+    maxRetries: 5,
+    spiralThreshold: 3,
+    onSpiral: () => { },
+};
+export class RetryReasonTracker {
+    config;
+    retries = new Map();
+    totalRetries = 0;
+    reasonCounts = {
+        no_session: 0,
+        invalid_key: 0,
+        bad_mac: 0,
+        decryption_failure: 0,
+        server_error_463: 0,
+        server_error_429: 0,
+        timeout: 0,
+        no_route: 0,
+        node_malformed: 0,
+        unknown: 0,
+    };
+    spiralsDetected = 0;
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Call when a messages.update event arrives with a status/error.
+     * Classifies and records the retry.
+     */
+    onMessageUpdate(update) {
+        if (!this.config.enabled)
+            return;
+        const msgId = update.key?.id;
+        if (!msgId)
+            return;
+        // Only track error statuses (status 0 = error in Baileys WAMessageStatus)
+        if (update.status !== 0 && !update.error)
+            return;
+        // rc10 may surface error info in update.update (wrapped message); check all forms
+        const reason = this.classify(update.error || update.update || update);
+        this.recordRetry(msgId, reason);
+    }
+    /**
+     * Classify an arbitrary error object into a RetryReason
+     */
+    classify(err) {
+        if (!err)
+            return 'unknown';
+        // Check for HTTP status codes
+        const statusCode = err.output?.statusCode || err.statusCode || err.status;
+        if (statusCode === 463)
+            return 'server_error_463';
+        if (statusCode === 429)
+            return 'server_error_429';
+        // Extract error message/text for pattern matching
+        const errorMsg = (err.message || err.text || String(err)).toLowerCase();
+        // Pattern matching for known errors
+        if (errorMsg.includes('bad mac'))
+            return 'bad_mac';
+        if (errorMsg.includes('no session') || errorMsg.includes('session not found'))
+            return 'no_session';
+        if (errorMsg.includes('invalid key') || errorMsg.includes('key error'))
+            return 'invalid_key';
+        if (errorMsg.includes('decryption') || errorMsg.includes('decrypt'))
+            return 'decryption_failure';
+        if (errorMsg.includes('timeout') || errorMsg.includes('timed out'))
+            return 'timeout';
+        if (errorMsg.includes('no route') || errorMsg.includes('unreachable') || errorMsg.includes('offline'))
+            return 'no_route';
+        if (errorMsg.includes('malformed') || errorMsg.includes('invalid node'))
+            return 'node_malformed';
+        return 'unknown';
+    }
+    /**
+     * Record a retry for a message
+     */
+    recordRetry(msgId, reason) {
+        const now = Date.now();
+        let record = this.retries.get(msgId);
+        if (!record) {
+            record = {
+                msgId,
+                count: 0,
+                reasons: [],
+                firstRetry: now,
+                lastRetry: now,
+            };
+            this.retries.set(msgId, record);
+        }
+        record.count++;
+        record.reasons.push(reason);
+        record.lastRetry = now;
+        this.totalRetries++;
+        this.reasonCounts[reason]++;
+        // Check for spiral
+        if (record.count >= this.config.spiralThreshold) {
+            this.spiralsDetected++;
+            this.config.onSpiral(msgId, reason);
+        }
+    }
+    /**
+     * Should we warn the user this message is spiraling?
+     */
+    isSpiraling(msgId) {
+        const record = this.retries.get(msgId);
+        return record ? record.count >= this.config.spiralThreshold : false;
+    }
+    /**
+     * Reset counters for a specific message (call on successful delivery)
+     */
+    clear(msgId) {
+        this.retries.delete(msgId);
+    }
+    /**
+     * Get current stats
+     */
+    getStats() {
+        return {
+            totalRetries: this.totalRetries,
+            byReason: { ...this.reasonCounts },
+            spiralsDetected: this.spiralsDetected,
+            activeRetries: this.retries.size,
+        };
+    }
+    /**
+     * Clean up old retry records (>5 minutes old)
+     */
+    cleanup() {
+        const now = Date.now();
+        const maxAge = 5 * 60 * 1000; // 5 minutes
+        for (const [msgId, record] of this.retries.entries()) {
+            if (now - record.lastRetry > maxAge) {
+                this.retries.delete(msgId);
+            }
+        }
+    }
+    /**
+     * Destroy and clean up
+     */
+    destroy() {
+        this.retries.clear();
+        this.cleanup();
+    }
+}