baileys-antiban 4.6.0 → 4.7.0

package/README.md

@@ -8,9 +8,9 @@
 
 **Drop-in anti-ban middleware for Baileys WhatsApp bots. Free, self-hosted, TypeScript-first. Whapi.Cloud alternative — zero monthly fees.**
 
-> Rate limiting with Gaussian jitter, 7-day warmup, session health monitoring, LID resolver, disconnect classification, contact graph enforcement — all in one `npm install`. Works with [Baileys](https://github.com/WhiskeySockets/Baileys) and [@oxidezap/baileyrs](https://github.com/oxidezap/baileyrs) (Rust/WASM).
+> Rate limiting with Gaussian jitter, 7-day warmup, session health monitoring, LID resolver, disconnect classification, contact graph enforcement, device fingerprinting, group operation guards, recovery orchestration, cross-instance coordination — all in one `npm install`. Works with [Baileys](https://github.com/WhiskeySockets/Baileys) and [@oxidezap/baileyrs](https://github.com/oxidezap/baileyrs) (Rust/WASM).
 
-> **New in v3.3:** [LID Migration Guide](./docs/lid-migration.md) — survive Baileys v7's @lid default with stable thread keys.
+> **New in v4.7:** HumanEntropyService — background human-like activity (typing indicators, delayed read receipts, presence cycles) to prevent "too perfect bot" detection. Works with WaSP and any session manager, no socket access needed.
 
 ## Why Trust This Package
 
@@ -27,6 +27,167 @@ The npm WhatsApp ecosystem has a malware problem. In April 2026, [`lotusbail`](h
 
 If you can't read the code yourself, lean on these signals: signed releases, public audit trail, no telemetry, and a real product behind it. That's the floor. Everything below is the feature set.
 
+## v4.x New Features — Production-Grade Ban Prevention
+
+v4.0–v4.7 ship seven major anti-ban modules. All are **auto-wired** by default via `wrapSocket()` or `wrapSocketWithFingerprint()`.
+
+### v4.0 — GroupOperationGuard
+
+Rate-limits group operations to prevent `account_reachout_restricted` errors. WA limits: ~3 adds/10min, 2 creates/10min.
+
+```typescript
+import { wrapSocket } from 'baileys-antiban';
+
+const sock = wrapSocket(makeWASocket({ ... }), {
+  groupOpGuard: { limits: { add: { max: 3, windowMs: 600_000 } } },
+});
+```
+
+Classify errors: `classifyGroupOpError(err)` returns `GROUP_OP_ERRORS.REACHOUT_RESTRICTED` | `RATE_OVERLIMIT` | `PRIVACY_BLOCK` | etc.  
+Disable: `groupOpGuard: false`
+
+### v4.1 — LegitimacySignalInjector
+
+Injects realistic imperfections: typos + corrections (2.5% of messages), read gaps, mid-typing pauses. WhatsApp's ML flags accounts that are "too perfect".
+
+```typescript
+const sock = wrapSocket(makeWASocket({ ... }), {
+  legitimacySignals: { typoProbability: 0.03 },
+});
+```
+
+Disable: `legitimacySignals: false`
+
+### v4.2 — BanRecoveryOrchestrator
+
+Structured recovery after ban events. Auto-triggers via HealthMonitor at critical risk.
+
+```typescript
+import { BanRecoveryOrchestrator } from 'baileys-antiban';
+
+const recovery = new BanRecoveryOrchestrator({
+  onPhaseChange: (phase, plan) => console.log(`Phase: ${phase}`),
+  onHardBan: () => { /* replace SIM */ },
+});
+
+recovery.triggerRecovery('timelock');
+const status = recovery.getStatus();
+console.log(status.rateMultiplier); // 0.1 = 10% speed
+```
+
+**Recovery plans:** timelock: 24h pause, 10% resume, 15%/week ramp | rate_overlimit: 4h, 25%, 25%/week | soft_ban: 48h, 5%, 10%/week | hard_ban: dead  
+Access via: `antiban.recoveryOrchestrator`
+
+### v4.3 — wrapSocketWithFingerprint
+
+One-call setup with device fingerprint randomization (appVersion, osVersion, deviceModel).
+
+```typescript
+import { wrapSocketWithFingerprint } from 'baileys-antiban';
+
+const sock = wrapSocketWithFingerprint(makeWASocket, { auth }, { preset: 'moderate' });
+```
+
+**Preset changes:** All presets default `groupProfiles: true`; `aggressive`/`high-volume` now `autoPauseAt: 'high'`
+
+### v4.4 — Per-Contact Risk Delays + DeliveryTracker
+
+Strangers get 2.5× delay, known contacts 1.0×. Active when `contactGraph.enabled: true`.
+
+```typescript
+const sock = wrapSocket(makeWASocket({ ... }), { contactGraph: { enabled: true } });
+// stranger: 2.5×, handshake_sent: 1.8×, handshake_complete: 1.3×, known: 1.0×
+```
+
+**DeliveryTracker** tracks double-tick receipts. <60% delivery = soft-ban signal.
+
+```typescript
+import { DeliveryTracker } from 'baileys-antiban';
+
+const tracker = new DeliveryTracker({
+  lowRateThreshold: 0.6,
+  onLowDeliveryRate: (rate) => console.error(`Delivery: ${rate * 100}%`),
+});
+
+sock.ev.on('messages.upsert', ({ messages }) => {
+  messages.forEach(m => m.key.fromMe && tracker.onMessageSent(m.key.id));
+});
+sock.ev.on('messages.update', (updates) => {
+  updates.forEach(({ key, update }) => {
+    if (update.status >= 3) tracker.onDeliveryReceipt(key.id);
+  });
+});
+```
+
+### v4.5 — Adaptive Rate Limiting
+
+Auto-adjusts rate based on delivery success: ≥85% → 100% speed, <55% → 25% speed. Auto-wired.
+
+```typescript
+import { RateLimiter } from 'baileys-antiban';
+
+const limiter = new RateLimiter({ maxPerMinute: 10 });
+limiter.adaptLimits(0.5); // manual throttle to 50%
+const factor = limiter.getCurrentFactor();
+```
+
+### v4.6 — Cross-Instance Coordination
+
+Shared token bucket across processes. Solves: 5 bots × 8/min = 40/min → flag.
+
+```typescript
+const sock = wrapSocket(makeWASocket({ ... }), {
+  instanceCoordinator: '/tmp/wa-pool.json',
+  instancePoolMaxPerMinute: 20,
+});
+```
+
+All instances share 20/min IP-level budget. Atomic writes via rename-swap.
+
+### v4.7 — HumanEntropyService
+
+Background noise generator that makes a WA session indistinguishable from a real human user during idle periods. Runs independently of your message flow — no socket access required, works with WaSP or any session manager.
+
+**The problem it solves:** WhatsApp's ML flags accounts with "too perfect" patterns — instant read receipts, zero typing activity, always-on presence. A listen-only bot that never idles looks like a bot.
+
+**What it does every 2-6 hours (randomized):**
+- Sends typing indicator to a recent contact for 3-8 seconds, then stops (mimics "started typing, changed mind")
+- Marks a received message as read with 10-60 min delay (mimics "opened notification, read later")
+- Toggles own presence available → unavailable over 30-120s (mimics "checked phone, put it down")
+
+**Safety:** Only contacts people who already messaged you first. Never cold-contacts strangers. All errors caught silently.
+
+```typescript
+import { createHumanEntropyService } from 'baileys-antiban';
+
+// Works with WaSP (no direct socket access needed)
+const entropy = createHumanEntropyService(wasp, sessionId, {
+  enabled: true,
+  minIntervalMs: 2 * 60 * 60 * 1000, // 2 hours
+  maxIntervalMs: 6 * 60 * 60 * 1000, // 6 hours
+});
+
+entropy.start(); // runs in background
+entropy.stop();  // call on shutdown
+
+// Or with direct Baileys socket
+import { HumanEntropyService } from 'baileys-antiban';
+const svc = new HumanEntropyService(socket, { enabled: true });
+svc.start();
+```
+
+**Tracking recent contacts:** Feed incoming messages so the service knows who to interact with:
+
+```typescript
+sock.ev.on('messages.upsert', ({ messages }) => {
+  messages.forEach(m => entropy.addRecentContact(m.key.remoteJid, m.key));
+});
+```
+
+Stats: `entropy.getStats()` returns `{ typingActions, readActions, presenceActions, cycles }`.
+
+---
+
 ## v2.0 New Features — Session Stability Module
 
 ### What's New in v2.0

package/dist/cjs/fleetEventStore.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * 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 });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFleetEventStore = createFleetEventStore;
+exports.createMySQLEventStoreBackend = createMySQLEventStoreBackend;
+exports.createInMemoryEventStoreBackend = createInMemoryEventStoreBackend;
+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 };
+}
+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
+// ===============================
+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/dist/cjs/humanEntropy.js

@@ -0,0 +1,342 @@
+"use strict";
+/**
+ * HumanEntropyService — Background noise for WA sessions
+ *
+ * Runs periodic human-like actions to make idle sessions appear more realistic:
+ * - Random typing presence to recent contacts
+ * - Delayed read receipts
+ * - Availability status toggles
+ *
+ * Design:
+ * - Works ONLY with WaSP's public API (no direct socket access)
+ * - Fail-silent (never crashes wa-pa)
+ * - Configurable intervals and probabilities
+ * - Only interacts with contacts who messaged first (never strangers)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HumanEntropyService = void 0;
+exports.createHumanEntropyService = createHumanEntropyService;
+const DEFAULT_CONFIG = {
+    enabled: true,
+    minIntervalMs: 2 * 60 * 60 * 1000, // 2 hours
+    maxIntervalMs: 6 * 60 * 60 * 1000, // 6 hours
+    maxRecentContacts: 30,
+    typingProbability: 0.3,
+    typingMinMs: 3000,
+    typingMaxMs: 8000,
+    readReceiptProbability: 0.2,
+    readReceiptMinDelayMs: 10 * 60 * 1000, // 10 min
+    readReceiptMaxDelayMs: 60 * 60 * 1000, // 60 min
+    presenceToggleProbability: 0.15,
+    presenceToggleMinMs: 30 * 1000, // 30 sec
+    presenceToggleMaxMs: 2 * 60 * 1000, // 2 min
+};
+/**
+ * Human entropy service
+ *
+ * Adds realistic background noise to WhatsApp sessions by performing
+ * random human-like actions periodically.
+ */
+class HumanEntropyService {
+    config;
+    wasp; // WaSP instance
+    sessionId;
+    recentContacts = [];
+    unreadMessages = [];
+    cycleTimer = null;
+    isRunning = false;
+    stats = {
+        cyclesExecuted: 0,
+        typingActionsPerformed: 0,
+        readReceiptsMarked: 0,
+        presenceToggles: 0,
+        errors: 0,
+        lastCycleAt: null,
+        nextCycleAt: null,
+    };
+    constructor(wasp, sessionId, config = {}) {
+        this.wasp = wasp;
+        this.sessionId = sessionId;
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        // Listen to MESSAGE_RECEIVED events to track recent contacts
+        this.wasp.on('MESSAGE_RECEIVED', (event) => {
+            if (event.sessionId === this.sessionId) {
+                this.trackIncomingMessage(event.data);
+            }
+        });
+        this.log('info', 'HumanEntropyService initialized', {
+            enabled: this.config.enabled,
+            minInterval: this.config.minIntervalMs,
+            maxInterval: this.config.maxIntervalMs,
+        });
+    }
+    /**
+     * Start the entropy service
+     */
+    start() {
+        if (!this.config.enabled) {
+            this.log('info', 'Entropy service disabled, not starting');
+            return;
+        }
+        if (this.isRunning) {
+            this.log('warn', 'Entropy service already running');
+            return;
+        }
+        this.isRunning = true;
+        this.scheduleNextCycle();
+        this.log('info', 'Entropy service started');
+    }
+    /**
+     * Stop the entropy service
+     */
+    stop() {
+        this.isRunning = false;
+        if (this.cycleTimer) {
+            clearTimeout(this.cycleTimer);
+            this.cycleTimer = null;
+        }
+        this.stats.nextCycleAt = null;
+        this.log('info', 'Entropy service stopped');
+    }
+    /**
+     * Get current statistics
+     */
+    getStats() {
+        return { ...this.stats };
+    }
+    /**
+     * Track incoming message to build recent contacts list
+     */
+    trackIncomingMessage(message) {
+        try {
+            // Skip outgoing messages
+            if (message.fromMe)
+                return;
+            const jid = message.from || message.chatId;
+            if (!jid)
+                return;
+            // Update or add to recent contacts
+            const existingIndex = this.recentContacts.findIndex(c => c.jid === jid);
+            if (existingIndex >= 0) {
+                this.recentContacts[existingIndex].lastMessageAt = new Date();
+            }
+            else {
+                this.recentContacts.push({
+                    jid,
+                    lastMessageAt: new Date(),
+                    isGroup: message.isGroup ?? false,
+                });
+            }
+            // Trim to max size (keep most recent)
+            if (this.recentContacts.length > this.config.maxRecentContacts) {
+                this.recentContacts.sort((a, b) => b.lastMessageAt.getTime() - a.lastMessageAt.getTime());
+                this.recentContacts = this.recentContacts.slice(0, this.config.maxRecentContacts);
+            }
+            // Track for potential read receipt
+            if (message.id && message.key) {
+                this.unreadMessages.push({
+                    jid,
+                    messageKey: message.key,
+                    receivedAt: new Date(),
+                });
+                // Trim old unread messages (keep last 50)
+                if (this.unreadMessages.length > 50) {
+                    this.unreadMessages = this.unreadMessages.slice(-50);
+                }
+            }
+        }
+        catch (error) {
+            this.log('error', 'Error tracking incoming message', { error: error.message });
+        }
+    }
+    /**
+     * Schedule next entropy cycle
+     */
+    scheduleNextCycle() {
+        if (!this.isRunning)
+            return;
+        const delay = this.randomBetween(this.config.minIntervalMs, this.config.maxIntervalMs);
+        this.stats.nextCycleAt = new Date(Date.now() + delay);
+        this.cycleTimer = setTimeout(() => {
+            this.executeCycle().catch(error => {
+                this.log('error', 'Entropy cycle failed', { error: error.message });
+                this.stats.errors++;
+            }).finally(() => {
+                this.scheduleNextCycle();
+            });
+        }, delay);
+        this.log('debug', `Next entropy cycle in ${Math.floor(delay / 1000)}s`);
+    }
+    /**
+     * Execute one entropy cycle
+     */
+    async executeCycle() {
+        if (!this.isRunning || this.recentContacts.length === 0) {
+            return;
+        }
+        this.log('info', 'Starting entropy cycle', {
+            recentContactsCount: this.recentContacts.length,
+            unreadMessagesCount: this.unreadMessages.length,
+        });
+        this.stats.cyclesExecuted++;
+        this.stats.lastCycleAt = new Date();
+        const actions = [];
+        // Action 1: Random typing presence
+        if (Math.random() < this.config.typingProbability) {
+            actions.push(this.performTypingPresence());
+        }
+        // Action 2: Mark random message as read
+        if (Math.random() < this.config.readReceiptProbability && this.unreadMessages.length > 0) {
+            actions.push(this.performReadReceipt());
+        }
+        // Action 3: Toggle presence status
+        if (Math.random() < this.config.presenceToggleProbability) {
+            actions.push(this.performPresenceToggle());
+        }
+        // Execute all actions in parallel
+        await Promise.allSettled(actions);
+    }
+    /**
+     * Send typing presence to a random recent contact
+     */
+    async performTypingPresence() {
+        try {
+            // Pick a random non-group contact
+            const eligibleContacts = this.recentContacts.filter(c => !c.isGroup);
+            if (eligibleContacts.length === 0) {
+                this.log('debug', 'No eligible contacts for typing presence');
+                return;
+            }
+            const contact = eligibleContacts[Math.floor(Math.random() * eligibleContacts.length)];
+            const duration = this.randomBetween(this.config.typingMinMs, this.config.typingMaxMs);
+            this.log('info', `Entropy action: typing to ${this.maskJid(contact.jid)} for ${duration}ms`);
+            // Get provider to access socket
+            const provider = this.wasp.getProvider(this.sessionId);
+            if (!provider || !provider.socket) {
+                throw new Error('Provider or socket not available');
+            }
+            // Send composing presence
+            await provider.socket.sendPresenceUpdate('composing', contact.jid);
+            // Wait for duration
+            await this.sleep(duration);
+            // Send paused presence
+            await provider.socket.sendPresenceUpdate('paused', contact.jid);
+            this.stats.typingActionsPerformed++;
+        }
+        catch (error) {
+            this.log('error', 'Error performing typing presence', { error: error.message });
+            this.stats.errors++;
+        }
+    }
+    /**
+     * Mark a random recent message as read with delay
+     */
+    async performReadReceipt() {
+        try {
+            const message = this.unreadMessages[Math.floor(Math.random() * this.unreadMessages.length)];
+            if (!message)
+                return;
+            const delay = this.randomBetween(this.config.readReceiptMinDelayMs, this.config.readReceiptMaxDelayMs);
+            this.log('info', `Entropy action: mark read ${this.maskJid(message.jid)} after ${Math.floor(delay / 1000)}s`);
+            // Wait for delay
+            await this.sleep(delay);
+            // Get provider to access socket
+            const provider = this.wasp.getProvider(this.sessionId);
+            if (!provider || !provider.socket) {
+                throw new Error('Provider or socket not available');
+            }
+            // Mark as read
+            await provider.socket.readMessages([message.messageKey]);
+            // Remove from unread list
+            this.unreadMessages = this.unreadMessages.filter(m => m !== message);
+            this.stats.readReceiptsMarked++;
+        }
+        catch (error) {
+            this.log('error', 'Error performing read receipt', { error: error.message });
+            this.stats.errors++;
+        }
+    }
+    /**
+     * Toggle presence status (available → unavailable)
+     */
+    async performPresenceToggle() {
+        try {
+            const duration = this.randomBetween(this.config.presenceToggleMinMs, this.config.presenceToggleMaxMs);
+            this.log('info', `Entropy action: presence toggle for ${Math.floor(duration / 1000)}s`);
+            // Get provider to access socket
+            const provider = this.wasp.getProvider(this.sessionId);
+            if (!provider || !provider.socket) {
+                throw new Error('Provider or socket not available');
+            }
+            // Set available
+            await provider.socket.sendPresenceUpdate('available');
+            // Wait for duration
+            await this.sleep(duration);
+            // Set unavailable
+            await provider.socket.sendPresenceUpdate('unavailable');
+            this.stats.presenceToggles++;
+        }
+        catch (error) {
+            this.log('error', 'Error performing presence toggle', { error: error.message });
+            this.stats.errors++;
+        }
+    }
+    /**
+     * Random value between min and max (inclusive)
+     */
+    randomBetween(min, max) {
+        return Math.floor(Math.random() * (max - min + 1)) + min;
+    }
+    /**
+     * Sleep for specified milliseconds
+     */
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    /**
+     * Mask JID for logging (privacy)
+     */
+    maskJid(jid) {
+        if (jid.length < 8)
+            return '***';
+        return jid.substring(0, 4) + '***' + jid.substring(jid.length - 4);
+    }
+    /**
+     * Log message
+     */
+    log(level, message, meta) {
+        const prefix = '[entropy]';
+        const logData = meta ? `${message} ${JSON.stringify(meta)}` : message;
+        switch (level) {
+            case 'info':
+                console.log(`${prefix} ${logData}`);
+                break;
+            case 'warn':
+                console.warn(`${prefix} ${logData}`);
+                break;
+            case 'error':
+                console.error(`${prefix} ${logData}`);
+                break;
+            case 'debug':
+                // Skip debug logs in production
+                break;
+        }
+    }
+}
+exports.HumanEntropyService = HumanEntropyService;
+/**
+ * Factory function to create HumanEntropyService
+ *
+ * @param wasp WaSP instance
+ * @param sessionId Session ID
+ * @param config Optional configuration
+ * @returns HumanEntropyService instance with start() and stop() methods
+ */
+function createHumanEntropyService(wasp, sessionId, config) {
+    const service = new HumanEntropyService(wasp, sessionId, config);
+    return {
+        start: () => service.start(),
+        stop: () => service.stop(),
+        getStats: () => service.getStats(),
+    };
+}