@prototypevip/baileys 0.0.5 → 0.0.7

package/lib/AntiBan/credsSnapshot.js

@@ -0,0 +1,121 @@
+/**
+ * Atomic Credentials Snapshot
+ *
+ * Pre-reconnect backup to kill code-500 corruption loop.
+ * Take snapshots before risky operations, restore on corruption.
+ *
+ * @author Kobus Wentzel <kobie@pop.co.za>
+ * @license MIT
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+const noop = () => { };
+export function credsSnapshot(config) {
+    const { credsPath, snapshotDir = path.join(path.dirname(credsPath), '.snapshots'), keep = 3, logger = {}, } = config;
+    const log = {
+        info: logger.info || noop,
+        warn: logger.warn || noop,
+        error: logger.error || noop,
+    };
+    async function take() {
+        try {
+            // Check if creds file exists
+            try {
+                await fs.access(credsPath);
+            }
+            catch {
+                log.warn(`[credsSnapshot] Creds file not found: ${credsPath}`);
+                return null;
+            }
+            // Ensure snapshot dir exists
+            await fs.mkdir(snapshotDir, { recursive: true });
+            // Generate snapshot path
+            const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+            const snapshotPath = path.join(snapshotDir, `creds-${timestamp}.json`);
+            const tmpPath = `${snapshotPath}.tmp`;
+            // Atomic copy: write to .tmp, then rename
+            await fs.copyFile(credsPath, tmpPath);
+            await fs.rename(tmpPath, snapshotPath);
+            log.info(`[credsSnapshot] Snapshot taken: ${snapshotPath}`);
+            // Rotate old snapshots
+            await rotate();
+            return snapshotPath;
+        }
+        catch (err) {
+            log.error(`[credsSnapshot] Failed to take snapshot: ${err}`);
+            return null;
+        }
+    }
+    async function rotate() {
+        try {
+            const snapshots = await list();
+            const toDelete = snapshots.slice(keep);
+            for (const snap of toDelete) {
+                await fs.unlink(snap.path);
+                log.info(`[credsSnapshot] Rotated out: ${snap.path}`);
+            }
+        }
+        catch (err) {
+            log.error(`[credsSnapshot] Rotation failed: ${err}`);
+        }
+    }
+    async function list() {
+        try {
+            await fs.access(snapshotDir);
+        }
+        catch {
+            return [];
+        }
+        try {
+            const files = await fs.readdir(snapshotDir);
+            const snapshots = await Promise.all(files
+                .filter((f) => f.startsWith('creds-') && f.endsWith('.json'))
+                .map(async (f) => {
+                const fullPath = path.join(snapshotDir, f);
+                const stat = await fs.stat(fullPath);
+                // Use file mtime for timestamp (simpler than parsing filename)
+                return {
+                    path: fullPath,
+                    takenAt: stat.mtime,
+                    size: stat.size,
+                };
+            }));
+            // Sort newest first
+            return snapshots.sort((a, b) => b.takenAt.getTime() - a.takenAt.getTime());
+        }
+        catch (err) {
+            log.error(`[credsSnapshot] Failed to list snapshots: ${err}`);
+            return [];
+        }
+    }
+    async function restoreLatest() {
+        const snapshots = await list();
+        if (snapshots.length === 0) {
+            log.warn('[credsSnapshot] No snapshots available to restore');
+            return false;
+        }
+        return restore(snapshots[0].path);
+    }
+    async function restore(snapshotPath) {
+        try {
+            // Verify snapshot exists
+            await fs.access(snapshotPath);
+            // Atomic restore: copy to .tmp, then rename
+            const tmpPath = `${credsPath}.tmp`;
+            await fs.copyFile(snapshotPath, tmpPath);
+            await fs.rename(tmpPath, credsPath);
+            log.info(`[credsSnapshot] Restored from: ${snapshotPath}`);
+            return true;
+        }
+        catch (err) {
+            log.error(`[credsSnapshot] Failed to restore from ${snapshotPath}: ${err}`);
+            return false;
+        }
+    }
+    return {
+        take,
+        restoreLatest,
+        restore,
+        list,
+    };
+}

package/lib/AntiBan/deliveryTracker.js

@@ -0,0 +1,107 @@
+/**
+ * DeliveryTracker — tracks actual delivery rate vs sent
+ *
+ * WhatsApp delivery receipts arrive via messages.update events as
+ * update.update.status = 3 (DELIVERY_ACK) or 4 (READ).
+ *
+ * Low delivery rate (< 60%) = strong soft-ban signal.
+ * Exposes deliveryRate for health monitoring and stats.
+ */
+const DEFAULT_CONFIG = {
+    windowMs: 3600000, // 1 hour
+    minSampleSize: 10,
+    onLowDeliveryRate: () => { },
+    lowRateThreshold: 0.6,
+};
+export class DeliveryTracker {
+    config;
+    messages = new Map();
+    lastLowRateAlert = 0;
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Register a sent message.
+     */
+    onMessageSent(msgId) {
+        this.messages.set(msgId, {
+            sentAt: Date.now(),
+            delivered: false,
+        });
+        this.pruneOldMessages();
+    }
+    /**
+     * Mark a message as delivered (status 3 or 4).
+     */
+    onDeliveryReceipt(msgId) {
+        const record = this.messages.get(msgId);
+        if (record) {
+            record.delivered = true;
+        }
+        this.pruneOldMessages();
+        this.checkDeliveryRate();
+    }
+    /**
+     * Get current delivery statistics.
+     */
+    getStats() {
+        this.pruneOldMessages();
+        const now = Date.now();
+        const cutoff = now - this.config.windowMs;
+        let sentInWindow = 0;
+        let deliveredInWindow = 0;
+        for (const record of this.messages.values()) {
+            if (record.sentAt >= cutoff) {
+                sentInWindow++;
+                if (record.delivered) {
+                    deliveredInWindow++;
+                }
+            }
+        }
+        const deliveryRate = sentInWindow >= this.config.minSampleSize
+            ? deliveredInWindow / sentInWindow
+            : null;
+        return {
+            sentInWindow,
+            deliveredInWindow,
+            deliveryRate,
+            windowMs: this.config.windowMs,
+        };
+    }
+    /**
+     * Prune messages older than the window.
+     */
+    pruneOldMessages() {
+        const now = Date.now();
+        const cutoff = now - this.config.windowMs;
+        for (const [msgId, record] of this.messages.entries()) {
+            if (record.sentAt < cutoff) {
+                this.messages.delete(msgId);
+            }
+        }
+    }
+    /**
+     * Check delivery rate and trigger callback if below threshold.
+     */
+    checkDeliveryRate() {
+        const stats = this.getStats();
+        // Only alert if we have enough samples
+        if (stats.deliveryRate === null)
+            return;
+        // Only alert once per hour to avoid spam
+        const now = Date.now();
+        if (now - this.lastLowRateAlert < 3600000)
+            return;
+        if (stats.deliveryRate < this.config.lowRateThreshold) {
+            this.lastLowRateAlert = now;
+            this.config.onLowDeliveryRate(stats.deliveryRate);
+        }
+    }
+    /**
+     * Reset all tracked messages.
+     */
+    reset() {
+        this.messages.clear();
+        this.lastLowRateAlert = 0;
+    }
+}

package/lib/AntiBan/deviceFingerprint.js

@@ -0,0 +1,106 @@
+/**
+ * Device Fingerprint Randomization
+ *
+ * Randomizes appVersion, osVersion, and deviceModel to prevent Meta's
+ * clientPayload fingerprinting. Addresses the #1 gap in anti-ban coverage.
+ *
+ * @author Kobus Wentzel <kobie@pop.co.za>
+ * @license MIT
+ */
+// Default pools - real-world values observed in the wild
+const DEFAULT_APP_VERSION_POOL = [
+    [2, 24, 5, 18],
+    [2, 24, 5, 17],
+    [2, 24, 4, 77],
+    [2, 24, 5, 15],
+    [2, 24, 3, 91],
+    [2, 24, 5, 20],
+];
+const DEFAULT_OS_VERSION_POOL = ['10', '11', '12', '13', '14'];
+const DEFAULT_DEVICE_MODEL_POOL = [
+    'Pixel 6',
+    'Pixel 7',
+    'Galaxy S22',
+    'Galaxy S23',
+    'Xiaomi 13',
+    'Xiaomi 12',
+    'OnePlus 11',
+    'Moto G84',
+    'Moto G54',
+    'Realme 11',
+    'Vivo V29',
+    'Oppo Find X6',
+];
+/**
+ * Simple deterministic PRNG using mulberry32
+ * Seeded from string hash for consistent results per session
+ */
+class SeededRandom {
+    state;
+    constructor(seed) {
+        // Hash string to 32-bit seed
+        let hash = 0;
+        for (let i = 0; i < seed.length; i++) {
+            hash = (hash << 5) - hash + seed.charCodeAt(i);
+            hash = hash & hash; // Convert to 32-bit int
+        }
+        this.state = Math.abs(hash) || 1;
+    }
+    next() {
+        let t = (this.state += 0x6d2b79f5);
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    }
+    pick(array) {
+        return array[Math.floor(this.next() * array.length)];
+    }
+}
+/**
+ * Generate a randomized fingerprint for one session.
+ * Stable for the same sessionId — call once per socket init.
+ */
+export function generateFingerprint(config = {}, sessionId) {
+    const { enabled = true, randomizeAppVersion = true, randomizeOsVersion = true, randomizeDeviceModel = true, seed, appVersionPool = DEFAULT_APP_VERSION_POOL, osVersionPool = DEFAULT_OS_VERSION_POOL, deviceModelPool = DEFAULT_DEVICE_MODEL_POOL, } = config;
+    const finalSessionId = sessionId || `session-${Date.now()}-${Math.random()}`;
+    const rng = new SeededRandom(seed || finalSessionId);
+    // Pick random values if enabled, otherwise use first pool item
+    const appVersion = enabled && randomizeAppVersion
+        ? rng.pick(appVersionPool)
+        : appVersionPool[0];
+    const osVersion = enabled && randomizeOsVersion ? rng.pick(osVersionPool) : osVersionPool[0];
+    const deviceModel = enabled && randomizeDeviceModel
+        ? rng.pick(deviceModelPool)
+        : deviceModelPool[0];
+    return {
+        appVersion: [...appVersion], // Copy to avoid mutation
+        osVersion,
+        deviceModel,
+        sessionId: finalSessionId,
+    };
+}
+/**
+ * Apply fingerprint to a Baileys SocketConfig before makeWASocket().
+ *
+ * Example:
+ *   const fp = generateFingerprint({});
+ *   const sock = makeWASocket(applyFingerprint(socketConfig, fp));
+ */
+export function applyFingerprint(socketConfig, fp) {
+    // Create defensive copy
+    const config = { ...socketConfig };
+    // Apply version if field exists
+    if (config.version !== undefined || 'version' in config || true) {
+        config.version = fp.appVersion;
+    }
+    // Apply browser tuple if field exists
+    // Baileys browser format: [deviceName, osVersion, appVersion]
+    if (config.browser !== undefined || 'browser' in config || true) {
+        config.browser = [
+            fp.deviceModel,
+            fp.osVersion,
+            `WhatsApp/${fp.appVersion.join('.')}`,
+        ];
+    }
+    return config;
+}

package/lib/AntiBan/fleetEventStore.js

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

package/lib/AntiBan/groupOperationGuard.js

@@ -0,0 +1,116 @@
+/**
+ * GroupOperationGuard — Rate limiting for WhatsApp group operations
+ *
+ * Prevents account_reachout_restricted and rate-overlimit errors
+ * by enforcing per-operation windows on group adds, removes, and creates.
+ *
+ * WA unofficial limits (observed):
+ *   - groupParticipantsUpdate (add): ~3 new contacts per 10 min
+ *   - groupCreate: ~2 per 10 min
+ *   - Rapid retries after 403: triggers account_reachout_restricted
+ */
+const DEFAULT_LIMITS = {
+    add: { max: 3, windowMs: 10 * 60 * 1000 }, // 3 adds / 10 min
+    remove: { max: 5, windowMs: 10 * 60 * 1000 }, // 5 removes / 10 min
+    create: { max: 2, windowMs: 10 * 60 * 1000 }, // 2 creates / 10 min
+    invite: { max: 10, windowMs: 10 * 60 * 1000 }, // 10 invite fetches / 10 min
+};
+/**
+ * Known WA error patterns for group operations.
+ * Use with classifyGroupOpError() to classify errors before retrying.
+ */
+export const GROUP_OP_ERRORS = {
+    REACHOUT_RESTRICTED: 'account_reachout_restricted',
+    RATE_OVERLIMIT: 'rate-overlimit',
+    PRIVACY_BLOCK: '403', // groupParticipantsUpdate returned status '403'
+    INVITE_EXPIRED: 'gone', // groupInviteCode returned 'gone' — code expired
+    GROUP_LOCKED: 'locked', // groupRevokeInvite returned 'locked'
+};
+/**
+ * Classify a caught error from a group operation.
+ */
+export function classifyGroupOpError(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes('account_reachout_restricted') || msg.includes('reachout'))
+        return GROUP_OP_ERRORS.REACHOUT_RESTRICTED;
+    if (msg.includes('rate-overlimit') || msg.includes('429'))
+        return GROUP_OP_ERRORS.RATE_OVERLIMIT;
+    if (msg.includes('locked'))
+        return GROUP_OP_ERRORS.GROUP_LOCKED;
+    if (msg.includes('gone'))
+        return GROUP_OP_ERRORS.INVITE_EXPIRED;
+    return null;
+}
+export function extractPrivacyBlock(result) {
+    if (!Array.isArray(result))
+        return { blocked: false };
+    for (const r of result) {
+        const entry = r;
+        if (entry.status !== '403')
+            continue;
+        // Traverse content to find add_request with code
+        const content = Array.isArray(entry.content) ? entry.content : [];
+        for (const c of content) {
+            if (c.tag === 'add_request' && typeof c.attrs === 'object') {
+                const attrs = c.attrs;
+                if (attrs.code) {
+                    return {
+                        blocked: true,
+                        inviteCode: attrs.code,
+                        inviteLink: `https://chat.whatsapp.com/${attrs.code}`,
+                    };
+                }
+            }
+        }
+        // 403 without invite code — privacy block but WA didn't provide link
+        return { blocked: true };
+    }
+    return { blocked: false };
+}
+export class GroupOperationGuard {
+    limits;
+    windows = new Map();
+    constructor(config = {}) {
+        this.limits = { ...DEFAULT_LIMITS, ...config.limits };
+    }
+    /**
+     * Check whether an operation is allowed under the current rate limits.
+     * @param op   Operation type
+     * @param key  Unique key scoping the limit (e.g. groupJid, clientId, or composite)
+     */
+    check(op, key) {
+        const limit = this.limits[op];
+        const windowKey = `${op}:${key}`;
+        const now = Date.now();
+        const entry = this.windows.get(windowKey);
+        if (!entry || now > entry.resetAt) {
+            this.windows.set(windowKey, { count: 1, resetAt: now + limit.windowMs });
+            return { allowed: true };
+        }
+        if (entry.count >= limit.max) {
+            const retryAfterSec = Math.ceil((entry.resetAt - now) / 1000);
+            return {
+                allowed: false,
+                reason: `Too many ${op} attempts. WhatsApp rate-limits group operations — wait ${Math.ceil(retryAfterSec / 60)} min before trying again.`,
+                retryAfterSec,
+            };
+        }
+        entry.count++;
+        return { allowed: true };
+    }
+    /**
+     * Reset the counter for a specific operation + key.
+     * Call this if you want to allow immediate retry after a successful operation.
+     */
+    reset(op, key) {
+        this.windows.delete(`${op}:${key}`);
+    }
+    /** Snapshot of all active windows (for observability). */
+    getStats() {
+        const stats = {};
+        for (const [key, val] of this.windows) {
+            stats[key] = { ...val };
+        }
+        return stats;
+    }
+}